diff --git a/_data/navigation.yml b/_data/navigation.yml index 55df359..ddbc791 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -16,28 +16,31 @@ secondary: external: true css: - - text: Architecture + - text: CSS architecture href: /css/architecture/ - - text: Documentation - href: /css/documentation/ - - text: Frameworks + - text: Choosing a framework href: /css/frameworks/ - - text: Formatting - href: /css/formatting/ - - text: Inheritance - href: /css/inheritance/ - - text: Linting - href: /css/linting/ - - text: Naming - href: /css/naming/ - - text: Preprocessors + - text: Documenting your code + href: /css/documentation/ + - text: Using CSS preprocessors href: /css/preprocessors/ - - text: Specificity - href: /css/specificity/ - - text: Units - href: /css/units/ - - text: Variables - href: /css/variables/ + - text: Recommended linting techniques + href: /css/linting/ + - text: Inheritance in Sass + href: /css/inheritance/ + - text: 18F CSS style guide + href: /css/styleguide/ + links: + - text: Formatting + href: /css/styleguide/formatting/ + - text: Naming + href: /css/styleguide/naming/ + - text: Specificity + href: /css/styleguide/specificity/ + - text: Units + href: /css/styleguide/units/ + - text: Variables + href: /css/styleguide/variables/ js: - text: Dependencies diff --git a/_includes/sidenav.html b/_includes/sidenav.html new file mode 100644 index 0000000..f602400 --- /dev/null +++ b/_includes/sidenav.html @@ -0,0 +1,28 @@ + diff --git a/pages/css/architecture.md b/pages/css/architecture.md index eebe9ea..4425d98 100644 --- a/pages/css/architecture.md +++ b/pages/css/architecture.md @@ -8,6 +8,10 @@ A site's architecture should be based on its goals and purposes. This means the guidance here should be adapted to different sites and situations. ## Modular or component architecture +Modular CSS (not to be confused with +[CSS Modules](https://css-tricks.com/css-modules-part-1-need/)) is the +recommended default at 18F. + When using a modular or component architecture, every page is broken into a series of modular components. There are two sets of these components: `components` and `modules`. The architecture starts out with basic HTML element @@ -15,9 +19,11 @@ rules: HTML, p, a, form, etc tags that than have components and modules written on top of them. Components are very basic structure such as buttons, blurbs, navs, and positioning structures like insets, island, and enclosure. From here, modules are built with these components. This architecture also attempts -to keep the specificity trend in an upwards curve as you move down in the file -(more on this to come). +to keep the specificity trend in an upwards curve as you move down in the file. + +[Here is a good overview of how to think about and apply modular CSS.](https://spaceninja.com/2018/09/17/what-is-modular-css/) +### Best practices for implementing modular CSS - Start with an elements file for all tag rules (a, h1-h5, p, \*, html, body). - Create component files for each structural element, such as buttons, navs, etc. These are mainly class-based and use [BEM] or another [naming @@ -32,7 +38,10 @@ to keep the specificity trend in an upwards curve as you move down in the file - A good thing to put here are breakpoint-specific rules, such as hiding something at small breakpoints. -### File structure +### Example file structure + +Here's how you might see a modular system organized: + ```sh _elements.scss _mixins.scss @@ -67,11 +76,13 @@ util/_clearfix.scss ``` -## Importing +### Using Sass imports for modular architecture As you likely know, CSS rules that are later in the file override earlier rules. This means Sass imports can be used to control inheritance and specificity. +#### Best practices for imports + - Start with base elements. - Move to single nested classes and utils. - Move next to more specific classes, often with nesting. @@ -79,6 +90,8 @@ specificity. - Import alphabetically. - Only modify import order for groups of files, not specific files. +#### Example structures + ```scss // Bad @import 'module/logo'; diff --git a/pages/css/documentation.md b/pages/css/documentation.md index d0fe6ac..84bb024 100644 --- a/pages/css/documentation.md +++ b/pages/css/documentation.md @@ -4,15 +4,33 @@ permalink: /css/documentation/ sidenav: css --- # Documentation + +You should always document: +- Magic numbers (when you absolutely cannot avoid using them) +- Overrides of imported frameworks like USWDS +- Rules that must be used in conjunction with one another +(using BEM naming conventions is somewhat self-documenting in this regard) + +We also recommend maintaining a project style guide of your choice. +Add examples of how to use classes that make up complex modules +when used in conjunction with one another. + ## Sass Comments Be intentional when you use `//` (silent comments) versus `/* */` (which are preserved in the CSS output). When in doubt, use `//`. ## KSS -Use KSS for documentation. More information on KSS can be found on the -[official site](http://warpspire.com/kss/). +KSS is the most common CSS documentation method to date. It relies +on comments that follow a specific format to generate documentation +for you. The generated documentation can be modified through templates. +More information on KSS can be found on the +[official KSS site](http://warpspire.com/kss/). -### Example +The original KSS repo is not maintained. There are numerous forks that are +maintained, the [Node.js KSS fork](https://github.com/kss-node/kss-node) being +one of the more active ones. + +### Example of KSS documentation ```scss // Button @@ -34,7 +52,3 @@ Use KSS for documentation. More information on KSS can be found on the .button-modified { } ``` - -### Rationale -KSS is the most common CSS documentation method to date. While it’s not perfect, -the generated documentation can be modified through templates. diff --git a/pages/css/frameworks.md b/pages/css/frameworks.md index 208824b..4580b3d 100644 --- a/pages/css/frameworks.md +++ b/pages/css/frameworks.md @@ -9,17 +9,30 @@ sidenav: css Sometimes, projects utilize other CSS frameworks such as: -1. [Bourbon](https://www.bourbon.io/) -2. [BassCSS](https://www.basscss.com/) +- [Bourbon](https://www.bourbon.io/) (particularly well-suited to working with Sass) +- [BassCSS](https://www.basscss.com/) (atomic CSS framework) These frameworks were chosen because they're relatively unopinionated about design decisions while still providing the helpers that make frameworks -essential to fast and accurate frontend work, for example, solutions for -responsive design, grids, and common design patterns. In addition, both +essential to fast and accurate front-end work (for example, solutions for +responsive design, grids, and common design patterns). In addition, both frameworks, through modular design and excellent documentation, make it easy for the designer or developer to only use the parts that they need, rather than including a hefty library. +## Considerations for choosing a CSS framework + +When choosing a framework for your project, the following questions may be helpful in assessing your options: + +- What does it offer that the U.S. Web Design System doesn't? +- How does it support responsive design? +- Are patterns for more complex interactions (accordions, tabs, menus) accessible? +- Does it allow for straightforward customization? +- Is it mature and currently supported? +- Does it support older browsers and provide fallbacks for newer techniques when necessary? +- Is the library size reasonable? +- Do other developers and designers on your team know how to work with this framework? + ## Do not use Bootstrap 18F specifically does not recommend using [Bootstrap](http://getbootstrap.com/) for production work because it can be difficult to adapt its opinionated styles to bespoke design work. diff --git a/pages/css/inheritance.md b/pages/css/inheritance.md index ef07f15..e2cd71e 100644 --- a/pages/css/inheritance.md +++ b/pages/css/inheritance.md @@ -3,10 +3,17 @@ title: Inheritance permalink: /css/inheritance/ sidenav: css --- -# Inheritance +# Working with inheritance in Sass + +Two commonly used Sass features are [mixins and inheritance](https://sass-lang.com/guide) +(the @extend directive). These are very powerful if used correctly; however, +@extend in particular can bloat your stylesheets if used too liberally. + ## Mixins -- Use mixins for groups of properties that appear together intentionally and - are used multiple times. + +Mixins are helpful for decreasing the amount of repetitive code you need to write. +For instance, if you want to create a clearfix that can be added to other classes +easily, you could create a clearfix mixin: ```scss @mixin clearfix { @@ -18,8 +25,23 @@ sidenav: css } ``` +You can then use the mixin in other classes, without having to rewrite the rules: + ```scss + .media-block { + @include clearfix; + ... + } + ``` + +Mixins can also take parameters. + +For further guidance, see the [Sass documentation](https://sass-lang.com/guide). + +### When to use mixins + +- Use mixins for groups of properties that appear together intentionally and are used multiple times. - Use mixins for components to change size. -- Use mixins when something requires parameters. +- Use mixins when a repeatable pattern requires parameters. For example: ```scss @mixin size($width, $height: $width) { @@ -28,20 +50,18 @@ sidenav: css } ``` -- Do not use mixins for browser prefixes. Use [Autoprefixer](https://github.com/postcss/autoprefixer). - - ```scss - // Bad - @mixin transform($value) { - -webkit-transform: $value; - -moz-transform: $value; - transform: $value; - } - ``` +### When not to use mixins +Do not use mixins for browser prefixes. Use [Autoprefixer](https://github.com/postcss/autoprefixer). ## Extend -Be very careful with using `@extend`. It's a powerful tool that can have +Any Sass selector can be extended. However, because `@extend` copies all of +the rules from one selector to another, it can cause a great deal of unintentional +CSS bloat when the CSS is compiled. Sass has the concept of [placeholder classes], +which help reduce unforeseen side effects. The Sass documentation has +[helpful information about using `@extend`](http://sass-lang.com/guide). + +Be very careful and deliberate when using `@extend`. It's a powerful tool that can have disastrous side-effects. Before using please consider: - Where is my current selector going to be appended? @@ -52,12 +72,12 @@ If you're unsure of using `@extend`, follow these rules to avoid running into trouble: - Use `@extend` from within a module, not across different modules. -- Use `@extend` on [placeholders] exclusively, not on actual selectors. -- Make sure the placeholder you extend is present as little as possible in the +- Use `@extend` on placeholder classes exclusively, not on actual selectors. +- Make sure the placeholder class you extend is present as little as possible in the stylesheet. You can use [mixins] in place of selectors. While mixins will copy more code, the difference will often be negligible once the output file has been gzipped. [mixins]: http://sass-lang.com/guide#mixins -[placeholders]: http://thesassway.com/intermediate/understanding-placeholder-selectors +[placeholder classes]: http://thesassway.com/intermediate/understanding-placeholder-selectors diff --git a/pages/css/linting.md b/pages/css/linting.md index 1cd04f4..c271128 100644 --- a/pages/css/linting.md +++ b/pages/css/linting.md @@ -4,15 +4,15 @@ permalink: /css/linting/ sidenav: css --- # Linting -The styleguide provides a method of linting [Sass] code to ensure it conforms -to the rules in the styleguide. This linting tool will go through all Sass code -and issue warnings wherever the code differs from the styleguide. We've created +The style guide provides a method of linting [Sass] code to ensure it conforms +to the rules in the style guide. This linting tool will go through all Sass code +and issue warnings wherever the code differs from the style guide. We've created a specific [`.scss-lint.yml` file][scss-lint yaml] that's configured to work -with the css coding styleguide. There are three ways to setup linting: +with the specifications of the CSS style guide. There are three ways to set up linting: * on GitHub with Hound -* locally with ruby -* locally with node +* locally with Ruby +* locally with Node ## On GitHub with Hound 1. Go to [Hound](https://houndci.com/). @@ -21,19 +21,19 @@ with the css coding styleguide. There are three ways to setup linting: 4. Add the [`.scss-lint.yml` file][scss-lint yaml] to the base of your repository. -## Locally with ruby +## Locally with Ruby 1. Add the [`.scss-lint.yml` file][scss-lint yaml] to the base of your repository. 2. Install the [scss-lint] gem with `gem install scss_lint` 3. Run scss-lint: `scss-lint app/assets/stylesheets/` -## Locally with node (experimental!) +## Locally with Node (experimental!) 1. Run `npm install --save-dev @18f/stylelint-rules` to download the package and save it to your package.json 2. The package provides both a gulp task and a cli interface. Detailed usage instructions can be found in the [README](https://github.com/18F/stylelint-rules) ## Shortcomings -### scss-lint +### [scss-lint](https://github.com/brigade/scss-lint) The scss-lint tool currently lacks the functionality to check these rules in the CSS coding styleguide: @@ -52,7 +52,7 @@ a bit more feature rich. The following rules are currently not supported: - PropertySpelling - UnecessaryParentReference -That being said, if you want to avoid a dependency on ruby in your project and +That being said, if you want to avoid a dependency on Ruby in your project and still benefit from reliable SCSS linting, please test out this tool! diff --git a/pages/css/styleguide.md b/pages/css/styleguide.md new file mode 100644 index 0000000..485eeba --- /dev/null +++ b/pages/css/styleguide.md @@ -0,0 +1,11 @@ +--- +title: 18F CSS style guide +permalink: /css/styleguide/ +sidenav: css +--- + +# CSS style guide + +The purpose of the CSS coding style guide is to create consistent CSS or +preprocessor CSS code across 18F. The style guide should be treated as a guide +— rules can be modified according to project needs. diff --git a/pages/css/formatting.md b/pages/css/styleguide/formatting.md similarity index 100% rename from pages/css/formatting.md rename to pages/css/styleguide/formatting.md diff --git a/pages/css/naming.md b/pages/css/styleguide/naming.md similarity index 100% rename from pages/css/naming.md rename to pages/css/styleguide/naming.md diff --git a/pages/css/specificity.md b/pages/css/styleguide/specificity.md similarity index 100% rename from pages/css/specificity.md rename to pages/css/styleguide/specificity.md diff --git a/pages/css/units.md b/pages/css/styleguide/units.md similarity index 100% rename from pages/css/units.md rename to pages/css/styleguide/units.md diff --git a/pages/css/variables.md b/pages/css/styleguide/variables.md similarity index 100% rename from pages/css/variables.md rename to pages/css/styleguide/variables.md diff --git a/pages/index.md b/pages/index.md index 1042e97..be684c2 100644 --- a/pages/index.md +++ b/pages/index.md @@ -5,14 +5,38 @@ permalink: / Welcome to the 18F Front-End Guide! This is where we keep all of our guidelines for front-end design and development. -## What is front end? - -The Front-End Guild did a series of exercises to determine the -fundamental differences between the front-end design and front-end -developer roles at 18F. Using [some of our own research -methods](https://methods.18f.gov), the Front-End Guild came up with -the following recommendations on knowing the difference between the -two disciplines: +## Why this guide? + +18F strives for a level of consistency across projects and code bases. +This guide serves as a canonical reference for guidelines that the +Front-End Guild has researched internally and decided to elevate as +organizational best practices. It's a good starting point for new 18F +developers and designers, as well as anyone seeking to know more about +how and why we build the way we do. + +### What's not in this guide + +Because front-end work touches so many different realms, this guide links +out heavily to other work that deals with related topics. Some resources of note: + +- [18F's guide to best practices for building software](https://github.com/18F/development-guide) +- [18F's project launch, security and ATO guidelines](https://before-you-ship.18f.gov/) +- [TTS' accessibility best practice guidelines for front-end developers](https://accessibility.digital.gov/front-end/getting-started/) (link also guides for designers, PMs, and other teammates) +- [The 18F Accessibility Guide](https://accessibility.18f.gov/) + + +## Front-end design vs. front-end development + +Originally, 18F hired for two distinct varieties of front-end work: design and +development. 18F no longer separates the two to diminish administrative +repetition, rather, all front-end work is now called front-end development. + +There are subtle but significant differences between front-end design +and development, however. The Front-End Guild did a series of exercises +to determine the fundamental differences between the roles at 18F. +Using [some of our own research methods](https://methods.18f.gov), the +Front-End Guild came up with the following recommendations on knowing the +difference between the two disciplines: **Front-end designers** design, write, and implement the presentational code base for websites and applications. They should