From 0eb2ca7cf29b07e494721cfa9844ff8bb72eb3a1 Mon Sep 17 00:00:00 2001 From: Josh Barr Date: Thu, 16 Apr 2015 17:09:13 +1200 Subject: [PATCH] added css guidelines --- .gitignore | 1 + .scss-lint.yml | 154 ++++++++++++++++++++++++++++++ docs/reference/css_guidelines.rst | 151 +++++++++++++++++++++++++++++ docs/reference/index.rst | 1 + 4 files changed, 307 insertions(+) create mode 100644 .scss-lint.yml create mode 100644 docs/reference/css_guidelines.rst diff --git a/.gitignore b/.gitignore index c8ceb2743..d98495eec 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,4 @@ /docs/_build/ /.tox/ /venv +/node_modules/ diff --git a/.scss-lint.yml b/.scss-lint.yml new file mode 100644 index 000000000..5589b866c --- /dev/null +++ b/.scss-lint.yml @@ -0,0 +1,154 @@ + +scss_files: 'wagtail/*/static/**/*.scss' +exclude: 'wagtail/**/static/**/vendor/*.scss' + +linters: + BorderZero: + enabled: true + + Indentation: + severity: warning + width: 4 + allow_non_nested_indentation: true + character: space + + ColorKeyword: + enabled: true + + ColorVariable: + enabled: true + + BangFormat: + space_before_bang: true + space_after_bang: false + + Comment: + enabled: true + + DeclarationOrder: + enabled: true + + DuplicateProperty: + enabled: false + + ElsePlacement: + enabled: true + + EmptyLineBetweenBlocks: + enabled: true + + EmptyRule: + enabled: true + + FinalNewline: + present: true + + HexLength: + style: short + + HexNotation: + style: lowercase + + HexValidation: + enabled: true + + IdSelector: + enabled: true + + ImportantRule: + enabled: true + + ImportPath: + enabled: true + + LeadingZero: + style: exclude_zero + + MergeableSelector: + enabled: false + + NameFormat: + allow_leading_underscore: true + + NestingDepth: + max_depth: 4 + + SelectorDepth: + max_depth: 3 + + SelectorFormat: + convention: hyphenated_lowercase + ignored_names: + - js_class + ignored_types: + - element + + PlaceholderInExtend: + enabled: true + + PropertyCount: + enabled: false + + QualifyingElement: + allow_element_with_attribute: false + allow_element_with_class: false + allow_element_with_id: false + + Shorthand: + enabled: true + + SingleLinePerProperty: + enabled: true + allow_single_line_rule_sets: true + + SingleLinePerSelector: + enabled: true + + SpaceAfterComma: + enabled: true + + SpaceAfterPropertyColon: + style: at_least_one_space + + SpaceAfterPropertyName: + enabled: true + + SpaceBeforeBrace: + enabled: true + allow_single_line_padding: true + style: space + + SpaceBetweenParens: + enabled: true + + StringQuotes: + style: single_quotes + + TrailingSemicolon: + enabled: true + + TrailingZero: + enabled: true + + UnnecessaryMantissa: + enabled: true + + UnnecessaryParentReference: + enbabled: true + + UrlFormat: + enabled: true + + UrlQuotes: + enabled: true + + VariableForProperty: + enabled: false + + VendorPrefix: + enabled: false + + ZeroUnit: + enabled: true + + diff --git a/docs/reference/css_guidelines.rst b/docs/reference/css_guidelines.rst new file mode 100644 index 000000000..b15aa0379 --- /dev/null +++ b/docs/reference/css_guidelines.rst @@ -0,0 +1,151 @@ +Contributing CSS to Wagtail +=========================== + +Our CSS is written in Sass, using the SCSS syntax. + +Spacing +~~~~~~~ + +- Use soft-tabs with a four space indent. Spaces are the only way to + guarantee code renders the same in any person's environment. +- Put spaces after ``:`` in property declarations. +- Put spaces before ``{`` in rule declarations. +- Put line breaks between rulesets. +- When grouping selectors, keep individual selectors to a single line. +- Place closing braces of declaration blocks on a new line. +- Each declaration should appear on its own line for more accurate + error reporting. +- Add a newline at the end of your ``.scss`` files. +- Strip trailing whitespace from your rules. + +Formatting +~~~~~~~~~~ + +- Use hex color codes ``#000`` unless using ``rgba()`` in raw CSS + (SCSS' ``rgba()`` function is overloaded to accept hex colors as a + param, e.g., ``rgba(#000, .5)``). +- Use ``//`` for comment blocks (instead of ``/* */``). +- Use single quotes for string values + ``background: url('my/image.png')`` or ``content: 'moose'`` +- Avoid specifying units for zero values, e.g., ``margin: 0;`` instead + of ``margin: 0px;``. +- Strive to limit use of shorthand declarations to instances where you + must explicitly set all the available values. + +Sass imports +~~~~~~~~~~~~ + +Leave off underscores and file extensions in includes: + +.. code-block:: scss + + // Bad + @import 'components/_widget.scss' + + // Better + @import 'components/widget' + +Pixels vs. ems +~~~~~~~~~~~~~~ + +Use ``rems`` for ``font-size`` with a ``px`` fallback, because it offers +absolute control over text. Additionally, unit-less ``line-height`` is +preferred because it does not inherit a percentage value of its parent +element, but instead is based on a multiplier of the ``font-size``. + +Specificity (classes vs. ids) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Prefer classes over IDs in CSS code. IDs can be overly specific and lead +to duplication of CSS. When in doubt, use a class name. + +When styling a component, start with an element + class namespace, +prefer direct descendant selectors by default, and use as little +specificity as possible. Here is a good example: + +.. code-block:: html + + + +.. code-block:: scss + + .category-list { // element + class namespace + + // Direct descendant selector > for list items + > li { + list-style-type: disc; + } + + // Minimal specificity for all links + a { + color: #f00; + } + } + +Class naming conventions +~~~~~~~~~~~~~~~~~~~~~~~~ + +Never reference ``js-`` prefixed class names from CSS files. ``js-`` are +used exclusively from JS files. + +Use the SMACSS ``is-`` `prefix `__ +for state rules that are shared between CSS and JS. + +Misc +~~~~ + +As a rule of thumb, avoid unnecessary nesting in SCSS. At most, aim for +three levels. If you cannot help it, step back and rethink your overall +strategy (either the specificity needed, or the layout of the nesting). + +Examples +~~~~~~~~ + +Here are some good examples that apply the above guidelines: + +.. code-block:: scss + + // Example of good basic formatting practices + .styleguide-format { + color: #000; + background-color: rgba(0, 0, 0, .5); + border: 1px solid #0f0; + } + + // Example of individual selectors getting their own lines (for error reporting) + .multiple, + .classes, + .get-new-lines { + display: block; + } + + // Avoid unnecessary shorthand declarations + .not-so-good { + margin: 0 0 20px; + } + .good { + margin-bottom: 20px; + } + +Vendor prefixes +~~~~~~~~~~~~~~~ + +Where possible, use the autoprefixer + +Linting SCSS +~~~~~~~~~~~~ + +The guidelines are included in a ``.scss-lint.yml`` file so that you can +check that your code conforms to the style guide. + +Run the linter from the wagtail project root with ``scss-lint .``. +You'll need to have the linter installed to do this. You can get it by +running + +.. code-block:: bash + + gem install scss-lint diff --git a/docs/reference/index.rst b/docs/reference/index.rst index af7227ec2..06789a47a 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -9,3 +9,4 @@ Reference hooks project_template page + css_guidelines