Tailwind CSS

This is a boilerplate MadeByShape use internally for projects.

It utilises the [Tailwind CSS] (https://tailwindcss.com) framework, to enable rapid development using utility / helper classes, with a mixture of BEM.

Installing
Compiling
JS/CSS Dependencies
Framework
Framework Plugins
Colours
CSS Blocks
CSS Helpers
CSS Utilities
JS Components
JS Naming
Favicons

Installing

@TODO

Compiling

Use Gulp to run tasks within the project. See the gulpfile.js file for a list of available individual tasks. The build tasks are:

gulp dev
gulp production

All Gulp settings are stored in the package.json file, e.g. If you need to change the public folder from web/ then edit paths > public in this file.

All assets should be placed in the root folder assets, seperated in to subfolders (E.g. scss, js etc). Use the web/dist folder to store any public files.

Any files placed inside assets will be compiled, minified and optimised and then moved to the dist folder.

NOTE: Never place files directly into the web/dist folder, as these can be overwritten sometimes via build commands.

JS/CSS Dependencies

Install all plugins and library dependencies using npm. Use the cssDependencies and jsDependencies arrays in package.json to add dependency files straight from the node_modules folder.

For example, if the JS file required for the project is located in path/to/the/node_modules/jquery/dist/jquery.js add this path to the jsDependencies array without the node_modules folder (jquery/dist/jquery.js) and compile.

Framework

[Tailwind CSS] (https://tailwindcss.com) is used as the core framework - Read the docs to use this framework https://tailwindcss.com/docs

Edit the tailwind.config.js whenever you need to modify / add new CSS utility classes.

Use the @apply in custom CSS components where possible.

For a grid, use Flex box mixed with width utilities as specified in the Tailwind CSS docs (https://tailwindcss.com/components/grids)

Framework Plugins

Aspect Ratio (https://github.com/webdna/tailwindcss-aspect-ratio)
Transitions (https://github.com/benface/tailwindcss-transitions)
Transforms (https://github.com/benface/tailwindcss-transforms)

Colours

Although we're English, use the word color where possible (Over colour).

All brand colours are specified using primary, secondary etc hierarchy. 500 is the base colour, with numbers lower (E.g. 300) being lighter colours, and numbers (E.g. 800) higher being darker colours.

CSS Blocks

Use BEM (http://getbem.com) style of naming when creating bespoke blocks But try to use @apply where possible to use existing CSS rules generated by Tailwind.

Example:

.card
.card__content
.card__content--large

CSS Components

CSS Components are styles that are used for repeat elements throughout a project. They are created in a separate component file in assets/scss/components. Try to avoid creating components where possible and use utility classes.

Name	Base Class	File	Description
Button	`.button`	`button.scss`	Applies bases styles for buttons such as hovers and transition.
Form	`.form`	`form.scss`	Applies base styles for form elements (Fields, Labels etc)
Heading	`.heading`	`headings.scss`	Used to apply base styles to headings (Especially used with `.rich-text`).
Link	`.link`	`links.scss`	Used to apply base styles to links.
Rich Text	`.rich-text`	`rich-text.scss`	Applies base styles to tags used inside redactor (Rich text) fields.
Section	`.section`	`section.scss`	Used to limit the max width of a site, and adds a site gutter.
Transition	`.transition`	`transitions.scss`	Applies transitions classes to be used on links etc.

CSS Helpers

CSS Helpers are usually SCSS mixins or functions that can be used within components or blocks. They are created in separate helper files in assets/scss/helpers. If a new helper is created, or a helper is modified for a project consider submitting as a pull request to be used in future projects.

Name	Property	File	Description
Font Face	`font-face($family, $filename, $weight, $style)`	`font-face.scss`	Allows use of custom fonts within CSS. Ideally place this within `base.scss` when being used.
Hover	`hover()`	`hover.scss`	Used to detect if a browser supports `:hover`
REM	`rem($size)`	`rem.scss`	Converts pixels (px) to REM values

JS Components

JS Components are chunks of functionality that do a specific function. E.g. You could have a component for creating a slideshow which includes when the slideshow loads, when it's resized etc. They are created in a separate a component file in assets/js/components using the following syntax:

var component = {
   var: {
      object: '.js-component'
   },
   scroll: function(){},
   resize: function(){},
   load: function(){}
}

When a component is required to be run add this to the assets/js/app.js file in the appropriate method (load, resize, scroll) by calling the correct method on the component e.g. component.load(); or component.resize().

JS Naming

Try to avoid linking any JS to any CSS classes or utilities to avoid any conflict.

Name your JS classes the same as your components in kebab case and prefix your component classes with .js- so developers know this relates to a specific JS function.

Favicons

Place a file named favicon.png in assets/images to generate a favicon. Running gulp favicon will generate this and put the appropriate files in the dist/images folder. Use gulp images to optimise these files.

dazeign/tailwind-css