tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-22 14:05:37 +02:00
Code Issues Projects Releases Wiki Activity
5f7b13ee49
silverstripe-framework/docs/en/05_Contributing/13_CSS_Coding_Conventions.md
Sam Minnee 1b527fca3f 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-09-15 22:19:09 +12:00

3.7 KiB
Raw Blame History

CSS and SCSS Coding Conventions

Overview

This document provides guidelines for code formatting to developers contributing to SilverStripe. It applies to all CSS/Sass files in the framework/ and cms/ modules.

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

Tools and libraries

Styles are written in the SCSS language. We use Bootstrap 4 styles where possible.

Conventions

We follow the AirBnB CSS Conventions and the BEM methodology (block-element-modifier). File naming and style include ordering is inspired by ITCSS.

Linting

We use SCSSLint to ensure all new SCSS written complies with the rules below. Please consider installing it in your development environment (you'll need Ruby). There's also quite a few SCSSLint IDE integrations which highlight any linting errors right in your code.

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. Naming and conventions in this folder follow ITCSS.

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 service. If you need new icons to be added, please ping us on Github.

Legacy conventions

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:

  • 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 to highlight a specific component. See the jQuery UI Theming API for a full list.

Related