NO-TICKET Guide/Core doc cleanup (#1722)

* removing all guides

* updates to core docs to reflect recent changes with loki and guide removal

* 'adding guiding principles to contributing'

* Update CONTRIBUTING.md

Co-authored-by: Patrick Wolfert <[email protected]>

* updating governance, moving to root

Co-authored-by: Patrick Wolfert <[email protected]>

Author: Forrest Baer

CONTRIBUTING.md

@@ -9,12 +9,6 @@ Please take a look at our [Code of Conduct](CODE_OF_CONDUCT.md) to learn more.
 
 If you are interested in running this site locally, please take a look at [setting up your local development environment](/README.md#running-locally).
 
-Use [our guides](https://github.com/CMSgov/design-system/tree/master/guides) to find additional information like:
-
-- Guiding principles
-- Coding guidelines
-- How to write documentation
-
 ## Submitting a pull request
 
 - [Fork the design system](https://guides.github.com/activities/forking/) into your GitHub account
@@ -23,12 +17,54 @@ Use [our guides](https://github.com/CMSgov/design-system/tree/master/guides) to
 
 **Note:** more information on the [GitHub flow](https://guides.github.com/introduction/flow/)
 
+## Guiding development principles
+
+As we're building the design system it helps to have some guiding principles in place to refer back to when we reach forks in the road. Forks in the road can be the different ways something could be named, whether a certain component belongs in the design system, etc. These guiding principles aren't set in stone and should evolve as opinions are evolved.
+
+_If you'd like to provide feedback on these principles, please [open a GitHub issue for discussion](https://github.com/CMSgov/design-system/issues/new)._
+
+### Compatible with existing codebases
+
+A developer should be able to import the design system into an existing codebase without causing unintended visual changes. Implementing the design system should be a deliberate process and developers should be able to incrementally add the design system to an existing site.
+
+For example, the design system avoids styling base HTML elements (`body`, `h1`) because an existing codebase likely already has CSS rulesets for those elements and we can't predict the intentions of those rulesets. Our solution then is to only use namespaced class selectors (`.ds-base`, `.ds-h1`, `.ds-c-button`) which allows a developer to choose where the design system's styles are applied.
+
+### Favor clarity over succinctness
+
+The design system should favor 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, and reducing cognitive load, means sacrificing a shorter syntax.
+
+Some other design systems user abstract and condensed naming conventions (ie. "`mr1`"). However, this naming convention can be intimidating, difficult to understand at a glance, has a steep learning curve, and results in a lot of back and forth between project code and the system's documentation.
+
+Here are a few examples of how the design system favors clarity over succinctness with its CSS class names:
+
+| Design system (Good)      | Abstract names (Bad) | Description                                                     |
+| ------------------------- | -------------------- | --------------------------------------------------------------- |
+| 👍 `ds-u-margin-right--1` | 🙅 `mr1`             | A utility class, applies a right margin that is 1x the baseline |
+| 👍 `ds-c-button`          | 🙅 `btn`             | A button component                                              |
+
+### Favor generalized names
+
+Avoid naming that indicates a specific use-case or styling, e.g. `snippet` rather than `search-snippet`.
+
+The names and phrasing of the design system's parts should also still make sense when a different theme is applied, e.g. `primary` rather than `blue`.
+
+### Variations exist only when they can't be achieved with a utility class
+
+The design system includes utility classes for modifying the most common visual traits, like spacing, size, and color. You may want to offer variations of a component that involves changing one of these traits. When you do, you should first see if users of the design can accomplish the variation by applying one of the utility classes to your component.
+
+This accomplishes a few things: Most importantly it reduces the total amount of CSS, and secondly it teaches people how to use the utility classes.
+
+### Support improvisation, but steer direction.
+
+The design system should be opinionated about the visual design, accessibility, and voice, but it should also provide the tools and necessary parts for developers and designers to create components and more complex patterns that are unique to their project.
+
+What does this mean in practice? One example is: Utility classes allow new ideas and patterns to form, while the components and base styling establish a voice and visual direction.
+
 ## Proposing new patterns
 
 When considering what to do with a proposed pattern, there are several questions to answer first. The decision tree below outlines those questions to be answered and the various outcomes:
 
 ![CMS Design System component decision workflow](https://raw.githubusercontent.com/CMSgov/design-system/master/.github/images/CMS-Design-System-component-decision-workflow.jpg)
-
 When a new pattern is created, it’s worth asking if it's a one-off use case or something that can be used on other sites. New patterns come at a cost in terms of additional code, maintenance, documentation, and increased cognitive load on users. Care should therefore be taken when adding patterns to the design system.
 
 Our pattern proposal process is largely based on those by the [US Web Design System](https://github.com/uswds/uswds/wiki/Contribution-Guidelines%3A-Design).

GOVERNANCE.md

@@ -0,0 +1,2 @@
+See our governance process in Confluence
+https://confluence.cms.gov/x/LYWbGQ

LICENSE.md

@@ -8,12 +8,10 @@ The Open Sans font files are from [Google Web Fonts](https://fonts.google.com/sp
 
 The Bitter font files are from [Google Web Fonts](https://fonts.google.com/specimen/Bitter), licensed under the [SIL Open Font License](http://scripts.sil.org/cms/scripts/page.php?item_id=OFL), and copyright [Sol Matas](www.huertatipografica.com.ar), with Reserved Font Name "Bitter"
 
-The icons in `core/src/images` are from [Font Awesome](http://fontawesome.io/) by Dave Gandy under the [SIL Open Font License 1.1](http://scripts.sil.org/OFL).
+Svg icons are from [Font Awesome](http://fontawesome.io/) by Dave Gandy under the [SIL Open Font License 1.1](http://scripts.sil.org/OFL).
 
 ### Files licensed under the MIT license
 
-- [Bourbon](http://bourbon.io/), copyright [thoughtbot](https://thoughtbot.com/), inc., under the [MIT license](https://github.com/thoughtbot/neat/blob/master/LICENSE.md).
-- [kss-node](https://github.com/kss-node/kss-node), copyright Hugh Kennedy, John Albin Wilkins, et. al.
 - [ev-emitter](https://github.com/metafizzy/ev-emitter)
 
 #### Full license text for the MIT licensed files:

README.md

@@ -74,22 +74,22 @@ These scripts can all be run from the root level of the repo:
   - Updates [Jest snapshots](http://facebook.github.io/jest/docs/en/snapshot-testing.html)
 - `yarn loki test`
   - Runs visual regression tests using [loki](https://storybook.js.org/addons/loki). See [Visual regression testing](#visual-regression-testing) section below for details.
-  - Must be running Storybook simultaneously to use this command in development
   - `yarn loki update` updates reference screenshots used for visual regression testing. Update these only when we expect the visual changes
+  - `yarn loki:healthcare test` to run the Healthcare.gov visual regression tests
+  - `yarn loki:medicare test` to run the Medicare.gov visual regression tests
 - `yarn lint`
-  - Runs just the linting portion of the tests
+  - Runs just the linting portion of the tests, eslint and stylelint
 - `yarn release`
   - Bumps package versions and tags a release commit. Read our [Release Process guide](/guides/RELEASE-PROCESS.md) for more info.
 
 ### Visual regression testing
 
 We use [loki](https://storybook.js.org/addons/loki) to test our components for visual regressions. It uses our existing Storybook stories, taking screenshots of them within a docker container and comparing those screenshots with ones previously taken and committed to version control.
 
-Running loki tests locally require two things: you must be signed into Docker and you must have an instance of Storybook running locally.
+Running loki tests locally requires that you be signed into Docker.
 
 1. Open the Docker app, and make sure you're signed in (Docker Desktop requires a license now)
-2. In your terminal window, start Storybook by running `yarn storybook`
-3. In another terminal window, run `yarn loki test` to begin comparing component images
+2. Run `yarn loki test` to begin comparing component images
    1. If differences are detected and unexpected, evaluate your changes - we only want to update and commit references when we expect the visual changes detected
    2. If differences are detected and expected, run `yarn loki update`