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.

Contents

• 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.

Roadmap