From 0eb2ca7cf29b07e494721cfa9844ff8bb72eb3a1 Mon Sep 17 00:00:00 2001 From: Josh Barr Date: Thu, 16 Apr 2015 17:09:13 +1200 Subject: [PATCH 1/2] 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 c8ceb27434..d98495eec9 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 0000000000..5589b866c9 --- /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 0000000000..b15aa0379d --- /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 af7227ec21..06789a47aa 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -9,3 +9,4 @@ Reference hooks project_template page + css_guidelines From b7ef25d8e0e65ea75d1f16da22ff733e64c7e5ac Mon Sep 17 00:00:00 2001 From: Josh Barr Date: Sat, 18 Apr 2015 08:34:54 +1200 Subject: [PATCH 2/2] created contrib section in docs, made amends to css styleguide --- .../css_guidelines.rst | 65 ++++++++++++------- .../developing.rst} | 2 +- docs/contributing/index.rst | 9 +++ docs/howto/index.rst | 1 - docs/index.rst | 1 + docs/reference/index.rst | 1 - 6 files changed, 52 insertions(+), 27 deletions(-) rename docs/{reference => contributing}/css_guidelines.rst (71%) rename docs/{howto/contributing.rst => contributing/developing.rst} (99%) create mode 100644 docs/contributing/index.rst diff --git a/docs/reference/css_guidelines.rst b/docs/contributing/css_guidelines.rst similarity index 71% rename from docs/reference/css_guidelines.rst rename to docs/contributing/css_guidelines.rst index b15aa0379d..26d1e5e123 100644 --- a/docs/reference/css_guidelines.rst +++ b/docs/contributing/css_guidelines.rst @@ -1,4 +1,4 @@ -Contributing CSS to Wagtail +CSS coding guidelines =========================== Our CSS is written in Sass, using the SCSS syntax. @@ -48,7 +48,7 @@ Leave off underscores and file extensions in includes: Pixels vs. ems ~~~~~~~~~~~~~~ -Use ``rems`` for ``font-size`` with a ``px`` fallback, because it offers +Use ``rems`` for ``font-size``, because they offer 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``. @@ -56,8 +56,8 @@ 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. +Always use classes instead of IDs in CSS code. IDs are overly specific and lead +to duplication of CSS. When styling a component, start with an element + class namespace, prefer direct descendant selectors by default, and use as little @@ -66,24 +66,24 @@ specificity as possible. Here is a good example: .. code-block:: html
    -
  • Category 1
    • -
  • Category 2
    • -
  • Category 3
    • +
  • Category 1
    • +
  • Category 2
    • +
  • Category 3
.. code-block:: scss .category-list { // element + class namespace - // Direct descendant selector > for list items - > li { - list-style-type: disc; - } + // Direct descendant selector > for list items + > li { + list-style-type: disc; + } - // Minimal specificity for all links - a { - color: #f00; - } + // Minimal specificity for all links + a { + color: #f00; + } } Class naming conventions @@ -111,30 +111,47 @@ Here are some good examples that apply the above guidelines: // Example of good basic formatting practices .styleguide-format { - color: #000; - background-color: rgba(0, 0, 0, .5); - border: 1px solid #0f0; + 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; + display: block; } // Avoid unnecessary shorthand declarations .not-so-good { - margin: 0 0 20px; + margin: 0 0 20px; } .good { - margin-bottom: 20px; + margin-bottom: 20px; } Vendor prefixes ~~~~~~~~~~~~~~~ -Where possible, use the autoprefixer +Line up your vendor prefixes. + +.. code-block:: scss + + // Example of good prefix formatting practices + .styleguide-format { + -webkit-transition: opacity 0.2s ease-out; + -moz-transition: opacity 0.2s ease-out; + -ms-transition: opacity 0.2s ease-out; + -o-transition: opacity 0.2s ease-out; + transition: opacity 0.2s ease-out; + } + +Don't write vendor prefixes for ``border-radius``, it's pretty well supported. + +If you're unsure, you can always check support at +`caniuse `_ + Linting SCSS ~~~~~~~~~~~~ @@ -142,9 +159,9 @@ 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 .``. +Run the linter with ``scss-lint .`` from the wagtail project root. You'll need to have the linter installed to do this. You can get it by -running +running: .. code-block:: bash diff --git a/docs/howto/contributing.rst b/docs/contributing/developing.rst similarity index 99% rename from docs/howto/contributing.rst rename to docs/contributing/developing.rst index f43c63d46d..cff5426737 100644 --- a/docs/howto/contributing.rst +++ b/docs/contributing/developing.rst @@ -1,4 +1,4 @@ -Contributing to Wagtail +Developing Wagtail ----------------------- Issues diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst new file mode 100644 index 0000000000..e5324a2bf4 --- /dev/null +++ b/docs/contributing/index.rst @@ -0,0 +1,9 @@ +Contributing to Wagtail +====== + + +.. toctree:: + :maxdepth: 2 + + developing + css_guidelines diff --git a/docs/howto/index.rst b/docs/howto/index.rst index 2271642aa6..4d630f03f2 100644 --- a/docs/howto/index.rst +++ b/docs/howto/index.rst @@ -10,5 +10,4 @@ How to performance multilingual_sites custom_branding - contributing third_party_tutorials diff --git a/docs/index.rst b/docs/index.rst index e730e6d8ad..9df312c697 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -43,4 +43,5 @@ Index reference/index support editor_manual/index + contributing/index releases/index diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 06789a47aa..af7227ec21 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -9,4 +9,3 @@ Reference hooks project_template page - css_guidelines