[WIP] CSS section style/language overhaul

_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: Using @mixin and @extend 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

_includes/sidenav.html

@@ -0,0 +1,28 @@
+<nav>
+  <ul class="usa-sidenav-list">
+    {% for link in include.links %}
+      {% assign _href = link.href %}
+      {% assign _current = false %}
+      {% if link.href == page.url or link.href == page.permalink %}
+        {% assign _current = true %}
+      {% endif %}
+    <li>
+      <a href="{% if link.external == true %}{{ link.href }}{% else %}{{ link.href | relative_url }}{% endif %}"
+         {% if _current %} class="usa-current" {% endif %}
+         {% if link.class %}class="{{ link.class }}" {% endif %} >
+         {{ link.text }}
+      </a>
+      {% if _current and page.subnav %}
+      <ul class="usa-sidenav-sub_list">
+        {% include subnav.html links=page.subnav %}
+      </ul>
+      {% endif %}
+       {% if link.links %}
+        <ul class="usa-sidenav-sub_list">
+           {% include subnav.html links=link.links %}
+        </ul>
+      {% endif %}
+    </li>
+    {% endfor %}
+  </ul>
+</nav>

pages/css/architecture.md

@@ -8,16 +8,22 @@ 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
 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,18 +76,22 @@ 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.
 - Move next to overrides, possibly with !important rules.
 - Import alphabetically.
 - Only modify import order for groups of files, not specific files.
 
+#### Example structures
+
 ```scss
 // Bad
 @import 'module/logo';

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.

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.

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

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 CSS style guide. There are three ways to setup 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,13 +21,13 @@ 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)
 
@@ -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!