2016-04-26 04:21:08 +02:00
|
|
|
# CSS and SCSS Coding Conventions
|
|
|
|
|
|
|
|
|
|
## Overview
|
|
|
|
|
|
|
|
|
|
This document provides guidelines for code formatting to developers contributing
|
2017-12-15 04:28:50 +01:00
|
|
|
to SilverStripe. It applies to all CSS/Sass files in the SilverStripe core modules.
|
2016-04-26 04:21:08 +02:00
|
|
|
|
|
|
|
|
In 2016, SilverStripe started a rewrite of the styles of the CMS interface.
|
|
|
|
|
This rewrite is work-in-progress so code written prior to this
|
|
|
|
|
rewrite might not follow these conventions, and is placed in a `legacy/` folder structure.
|
|
|
|
|
|
|
|
|
|
## Browser support
|
|
|
|
|
|
|
|
|
|
Check our [requirements](/getting_started/server_requirements) documentation.
|
|
|
|
|
|
|
|
|
|
## Tools and libraries
|
|
|
|
|
|
|
|
|
|
Styles are written in the [SCSS language](http://sass-lang.com/).
|
2017-12-15 04:28:50 +01:00
|
|
|
We use [Bootstrap 4](https://getbootstrap.com/) styles where possible.
|
2016-04-26 04:21:08 +02:00
|
|
|
|
|
|
|
|
## Conventions
|
|
|
|
|
|
|
|
|
|
We follow the [AirBnB CSS Conventions](https://github.com/airbnb/css)
|
|
|
|
|
and the [BEM](http://getbem.com/) methodology (block-element-modifier).
|
2017-12-15 04:28:50 +01:00
|
|
|
|
|
|
|
|
Because we use [Bootstrap 4](https://getbootstrap.com/) which
|
|
|
|
|
does not follow [BEM](http://getbem.com/) naming convention there will be
|
|
|
|
|
a lot of places where class names voilate BEM.
|
|
|
|
|
However, please note that they are not a indicator of how to name classes.
|
|
|
|
|
Use BEM conventions where possible.
|
2016-04-26 04:21:08 +02:00
|
|
|
|
2016-05-05 10:44:38 +02:00
|
|
|
## Linting
|
|
|
|
|
|
2019-02-21 15:32:45 +01:00
|
|
|
We use [sass-lint](https://github.com/sasstools/sass-lint) to ensure all new SCSS
|
2016-09-17 05:30:30 +02:00
|
|
|
written complies with the rules below. It will be provided as an npm dev dependency.
|
2019-02-21 15:32:45 +01:00
|
|
|
There are also quite a few [sass-lint IDE integrations](https://github.com/sasstools/sass-lint#ide-integration)
|
2016-09-18 06:25:16 +02:00
|
|
|
which highlight any linting errors right in your code.
|
|
|
|
|
|
2016-09-17 05:30:30 +02:00
|
|
|
We strongly recommend installing one of these into the editor of your choice, to
|
2016-09-18 06:25:16 +02:00
|
|
|
avoid the frustration of failed pull requests. You can run the checks on console
|
2017-03-09 23:59:38 +01:00
|
|
|
via `yarn run lint`.
|
2016-04-26 04:21:08 +02:00
|
|
|
|
|
|
|
|
## File and Folder Naming
|
|
|
|
|
|
|
|
|
|
- All frontend files (CSS, JavaScript, images) should be placed in
|
|
|
|
|
a `client/` folder on the top level of the module
|
|
|
|
|
- Frontend files relating to the `framework` CMS UI should be placed in `admin/client`
|
|
|
|
|
- The `client/src/components` folder should contain only reusable components
|
|
|
|
|
(e.g. Button, Accordion). Presentation of these components should not rely on
|
|
|
|
|
the markup context they're embedded in.
|
|
|
|
|
- The `client/src/containers` folder should contain use-case dependent styles only
|
|
|
|
|
(e.g. CampaignAdmin). Styles in here should be kept at a minimum.
|
|
|
|
|
- The file name of styles nested within components and containers should inherit their
|
|
|
|
|
respective folder name for easy reference.
|
|
|
|
|
For example, a `components/FormAction` component has styles named `FormAction.scss`).
|
|
|
|
|
- The `client/src/styles` folder contains base styles (reset, typography, variables)
|
|
|
|
|
as well as layout-related styles which arranges components together.
|
|
|
|
|
|
FIX Webpack handles images & fonts.
Responsibility for finding and referencing images and fonts is now
given to webpack. All the url references are now relative to the
component scss file, and point to font & images files in src/, rather
than assuming someone else will place them in dist.
This makes the source more modular, and makes it easier to, for
example, inline images are data URIs, or create a new build script that
builds several modules for a project in a single pass.
Workaround for bad font path in bundle.css:
ExtactTextPlugin didn’t work as well with a subfolder reference in the
filename. This is just a short-term fix and could probably be improved
to put bundle.css back in the styles subfolder.
Webpack handles images & fonts:
Responsibility for finding and referencing images and fonts is now
given to webpack. All the url references are now relative to the
component scss file, and point to font & images files in src/, rather
than assuming someone else will place them in dist.
This makes the source more modular, and makes it easier to, for
example, inline images are data URIs, or create a new build script that
builds several modules for a project in a single pass.
Clarify docs on spriting and webfonts:
We've decided to remove sprity since it comes with hundreds of dependencies,
and needs compilation within the "npm install" - dragging out the already overweight
install process, and making the resulting node_modules/ folder less portable between systems.
2016-08-26 05:37:43 +02:00
|
|
|
## Icons and Graphics
|
|
|
|
|
|
|
|
|
|
Most graphics used in the CMS are vector based, and stored as generated
|
|
|
|
|
webfonts in `admin/client/src/font`, which also contains a HTML reference.
|
|
|
|
|
The webfonts are generated through the [Fontastic](http://app.fontastic.me) service.
|
|
|
|
|
If you need new icons to be added, please ping us on Github.
|
|
|
|
|
|
2016-04-26 04:21:08 +02:00
|
|
|
## Legacy conventions
|
|
|
|
|
|
2016-04-26 22:00:44 +02:00
|
|
|
CSS written prior to SilverStripe 4.0 is not following the conventions outlined above.
|
|
|
|
|
It is contained in a `legacy/` folder structure. If modifying these styles,
|
|
|
|
|
consider porting them over into the new structure. Otherwise, follow these conventions:
|
2016-04-26 04:21:08 +02:00
|
|
|
|
|
|
|
|
- Class naming: Use the `cms-` class prefix for major components in the cms interface,
|
|
|
|
|
and the `ss-ui-` prefix for extensions to jQuery UI. Don't use the `ui-` class prefix, its reserved for jQuery UI built-in styles.
|
|
|
|
|
- Use jQuery UI's built-in styles where possible, e.g. `ui-widget` for a generic container, or `ui-state-highlight`
|
2019-02-21 15:32:45 +01:00
|
|
|
to highlight a specific component. See the [jQuery UI Theming API](https://api.jqueryui.com/category/theming/) for a full list.
|
2016-04-26 04:21:08 +02:00
|
|
|
|
|
|
|
|
## Related
|
|
|
|
|
|
2016-06-03 00:53:35 +02:00
|
|
|
* [PHP Coding Conventions](/contributing/php_coding_conventions)
|
|
|
|
|
* [JavaScript Coding Conventions](/contributing/javascript_coding_conventions)
|
2016-04-26 04:21:08 +02:00
|
|
|
* [Browser support](/getting_started/server_requirements/)
|
