Docs: Add Guidelines (#68)

* Nested Guidelines pages * Fix sort order of generated nav items * Update Getting Started page * Update Code conventions page * Add naming convention image * Update BEM syntax copy * Add credit links * Build documentation * Add Internationalization docs * Add Grid guidance Resolves https://jira.cms.gov/browse/HDSG-70 * Build docs
CMSgov · Jun 4, 2017 · a0774cf · a0774cf
1 parent 87f00ca
commit a0774cf
Show file tree

Hide file tree

Showing 69 changed files with 1,071 additions and 627 deletions.
diff --git a/docs/base/index.html b/docs/base/index.html
diff --git a/docs/base/typography/index.html b/docs/base/typography/index.html
diff --git a/docs/components/alert/index.html b/docs/components/alert/index.html
diff --git a/docs/components/badge/index.html b/docs/components/badge/index.html
diff --git a/docs/components/button/index.html b/docs/components/button/index.html
diff --git a/docs/components/choice/index.html b/docs/components/choice/index.html
diff --git a/docs/components/index.html b/docs/components/index.html
diff --git a/docs/components/list/index.html b/docs/components/list/index.html
diff --git a/docs/components/select/index.html b/docs/components/select/index.html
diff --git a/docs/components/table/index.html b/docs/components/table/index.html
diff --git a/docs/components/tabs/index.html b/docs/components/tabs/index.html
diff --git a/docs/components/text-field/index.html b/docs/components/text-field/index.html
diff --git a/docs/components/vertical-nav/index.html b/docs/components/vertical-nav/index.html
diff --git a/docs/core-concepts/index.html b/docs/core-concepts/index.html
diff --git a/docs/guidelines/code-conventions/index.html b/docs/guidelines/code-conventions/index.html
diff --git a/docs/guidelines/grid/index.html b/docs/guidelines/grid/index.html
diff --git a/docs/guidelines/i18n/index.html b/docs/guidelines/i18n/index.html
diff --git a/docs/guidelines/responsive/index.html b/docs/guidelines/responsive/index.html
diff --git a/docs/index.html b/docs/index.html
diff --git a/docs/public/images/naming-convention.svg b/docs/public/images/naming-convention.svg
diff --git a/docs/public/scripts/index.js b/docs/public/scripts/index.js
diff --git a/docs/public/styles/docs.css b/docs/public/styles/docs.css
diff --git a/docs/responsive/index.html b/docs/responsive/index.html
diff --git a/docs/utilities/background-color/index.html b/docs/utilities/background-color/index.html
diff --git a/docs/utilities/border-radius/index.html b/docs/utilities/border-radius/index.html
diff --git a/docs/utilities/border/index.html b/docs/utilities/border/index.html
diff --git a/docs/utilities/clearfix/index.html b/docs/utilities/clearfix/index.html
diff --git a/docs/utilities/color/index.html b/docs/utilities/color/index.html
diff --git a/docs/utilities/float/index.html b/docs/utilities/float/index.html
diff --git a/docs/utilities/font-family/index.html b/docs/utilities/font-family/index.html
diff --git a/docs/utilities/font-size/index.html b/docs/utilities/font-size/index.html
diff --git a/docs/utilities/font-style/index.html b/docs/utilities/font-style/index.html
diff --git a/docs/utilities/font-weight/index.html b/docs/utilities/font-weight/index.html
diff --git a/docs/utilities/index.html b/docs/utilities/index.html
diff --git a/docs/utilities/line-height/index.html b/docs/utilities/line-height/index.html
diff --git a/docs/utilities/margin/index.html b/docs/utilities/margin/index.html
diff --git a/docs/utilities/measure/index.html b/docs/utilities/measure/index.html
diff --git a/docs/utilities/overflow/index.html b/docs/utilities/overflow/index.html
diff --git a/docs/utilities/padding/index.html b/docs/utilities/padding/index.html
diff --git a/docs/utilities/text-align/index.html b/docs/utilities/text-align/index.html
diff --git a/docs/utilities/text-decoration/index.html b/docs/utilities/text-decoration/index.html
diff --git a/docs/utilities/text-transform/index.html b/docs/utilities/text-transform/index.html
diff --git a/docs/utilities/truncate/index.html b/docs/utilities/truncate/index.html
diff --git a/docs/utilities/vertical-align/index.html b/docs/utilities/vertical-align/index.html
diff --git a/docs/utilities/visibility/index.html b/docs/utilities/visibility/index.html
diff --git a/packages/core/dist/components/Alert/Alert.css b/packages/core/dist/components/Alert/Alert.css
diff --git a/packages/core/dist/components/Button/Button.css b/packages/core/dist/components/Button/Button.css
diff --git a/packages/core/dist/components/ChoiceList/Choice.css b/packages/core/dist/components/ChoiceList/Choice.css
diff --git a/packages/core/dist/index.css b/packages/core/dist/index.css
diff --git a/packages/core/dist/utilities/color.css b/packages/core/dist/utilities/color.css
diff --git a/packages/core/dist/utilities/index.css b/packages/core/dist/utilities/index.css
diff --git a/packages/core/dist/utilities/text-decoration.css b/packages/core/dist/utilities/text-decoration.css
diff --git a/packages/docs/src/images/naming-convention.svg b/packages/docs/src/images/naming-convention.svg
diff --git a/packages/docs/src/pages/core-concepts.md b/packages/docs/src/pages/core-concepts.md
diff --git a/packages/docs/src/pages/guidelines/code-conventions.md b/packages/docs/src/pages/guidelines/code-conventions.md
@@ -0,0 +1,46 @@
+---
+title: Code conventions
+---
+
+<p class="ds-text--lead">
+  The design system favors clarity over succinctness. This means the design system may be verbose, but it should deliver clarity and resilience in exchange. Keeping CSS legible and scalable means sacrificing a shorter syntax.
+</p>
+
+## CSS naming convention
+
+<img src="{{root}}/public/images/naming-convention.svg" class="ds-u-border--1" />
+
+### Namespace
+
+To avoid conflicting with other libraries and existing code, the design system namespaces its CSS class names with `ds-`.
+
+### Prefix
+
+Prefixes are added to class names to make it more apparent what job the class is doing.
+
+| Prefix | Description |
+| ------ | ----------- |
+| `l-`  | Indicates layout-related styles. These classes may be used in any number of unrelated contexts. Example: `.ds-l-container` |
+| `c-` | Indicates a component. Example: `.ds-c-button`
+| `u-` | Indicates a utility. Example: `.ds-u-color--base` |
+| `is-`, `has-` | Indicates state. |
+
+### BEM syntax
+
+Following the namespace and prefix is a name conforming to [BEM syntax](http://getbem.com/introduction/).
+
+Put all together, a CSS class can be broken down to these key parts: `[NAMESPACE]-[PREFIX]-[BLOCK]__[ELEMENT]--[MODIFIER]`
+
+- **Block** is a standalone entity that is meaningful on its own. For example: `.ds-c-card`, `.ds-c-button`
+- **Element** is a part of a block that has no standalone meaning and is semantically tied to its block, such as `.ds-c-card__title`
+- **Modifier** is a flag on a block or element and is used to change appearance or behavior. For example: `.ds-c-button--primary`, `ds-u-color--primary`, `ds-u-margin--3`
+
+[BEM’s strict naming rules can be found here](http://getbem.com/naming/).
+
+## Credits
+
+The CSS naming convention outlined here was heavily influenced by:
+
+- [CSS Architecture for Design Systems](http://bradfrost.com/blog/post/css-architecture-for-design-systems/), by Brad Frost
+- [Thoughtful CSS Architecture](https://seesparkbox.com/foundry/thoughtful_css_architecture), by Nathan Rambeck
+- [More Transparent UI Code with Namespaces](https://csswizardry.com/2015/03/more-transparent-ui-code-with-namespaces/), by Harry Roberts
diff --git a/packages/docs/src/pages/guidelines/grid.md b/packages/docs/src/pages/guidelines/grid.md
@@ -0,0 +1,17 @@
+---
+title: Grid layout
+---
+
+Choosing a suitable grid framework is dependent on several factors. Some of these factors are browser support, if and which CSS preprocessor is being used, degree of customizability, and [layout mode](https://developer.mozilla.org/en-US/docs/Web/CSS/Layout_mode) preference.
+
+As a result, the design system doesn't currently include its own grid framework and instead suggests that you pick from existing solutions, based on what works best for your project and preferences.
+
+Below is a non-exhaustive list of existing grid solutions:
+
+- [Neat](http://neat.bourbon.io/)
+- [Flexbox Grid](http://flexboxgrid.com/)
+- [Susy](http://susy.oddbird.net/)
+- [Unsemantic](https://unsemantic.com/)
+- [Bootstrap grid](http://getbootstrap.com/css/#grid)
+
+If you have more suggestions, feel free to [open a ticket](https://github.com/CMSgov/design-system/issues/new).
diff --git a/packages/docs/src/pages/guidelines/i18n.md b/packages/docs/src/pages/guidelines/i18n.md
@@ -0,0 +1,21 @@
+---
+title: Internationalization
+---
+
+The design system's React components accepts all text as `props`, and it is the app's responsibility to provide the internationalized strings.
+
+For example:
+
+```jsx
+import {Alert} from '@cmsgov/design-system-core';
+import i18n from 'i18n';
+
+export default function() {
+  return (
+    <Alert heading={i18n('success')}>
+      {i18n('account.created')}
+    </Alert>
+  );
+}
+
+```
diff --git a/packages/docs/src/pages/responsive.md → ...s/docs/src/pages/guidelines/responsive.md b/packages/docs/src/pages/responsive.md → ...s/docs/src/pages/guidelines/responsive.md