# Capital Style
This package contains several resources that can be used for building applications with the visual style of Capital Design System.

## Installing the package
You can add this package to your application by running:
`yarn add @opengov/capital-style`

## Tokens
[Token Documentation](https://opengov.design/capital/styles/tokens)

Tokens are individual variables that can be used to build styles, such as colors, fonts, or size units. We build in JSON under the `/tokens` folder. From there they are exported to `scss`. A few mixins are added to these tokens as well to build more complex styles (such as focus).

To import just the tokens into your `scss` file, place this line at the top of every file you want to use your tokens:
`@import “~@opengov/capital-style/scss/tokens;`
If your SCSS is compiled all together, this should only be needed once. If you are using CSS Modules in React, this will be needed for every `scss` file you need to use the tokens in.

### Using Tokens & Mixins
Tokens should be used just like any other variable within your scss, for example:
`color: $color-primary-selection;`

To reference a token within a function:
`width: calc(100vw - #{$unit-20});`

To use media queries:
`@media #{$mq-small} { ... }`

To use mixins:
`@include focus-wrap;`

Tokens are not currently available in JS.

## Stylesheets
We offer a few base stylesheets that you can use for your application. We recommend using these only once in your application.

`@import “~@opengov/capital-style/scss/tokens;`
* Token and mixin definitions

`@import “~@opengov/capital-style/scss/font;`
* Font definitions

`@import “~@opengov/capital-style/scss/base;`
* Imports tokens, mixins and fonts
* Imports normalize.css
* A few base styles for your application: setting the font, basic focus, and bold font weight

`@import “~@opengov/capital-style/scss/components;`
* Styles for basic components: [Component Stylesheet Documentation](https://opengov.design/capital/styles/stylesheet)

`@import “~@opengov/capital-style/scss/capital;`
* Everything

The capital stylesheet is also compiled as CSS and can be pointed to with:
`<link rel="stylesheet" type="text/css" href="[relative file path]/@opengov/capital-style/css/capital.css">`

### Using Component Styles
Component styles are written with the namespace `.cds-` to avoid conflicts with any existing styles. All children styles will only be affective with the correct parent style.

Styles are written with BEM. Children objects are prefixed with `__` and modifiers are prefixed with `--`. Modifiers should state what is being modified and then the modification. For example:
```
.cds-button {

  &.cds-button--variantPrimary {}

  &.cds-button--sizeDefault {}

  svg.cds-button__icon {}
}
```

## Fonts
Font files are available under `/fonts` and can be imported with:
`@import “~@opengov/capital-style/scss/font;`

## Visualization Colors

You can see all of the token on this Github Page:

https://opengov.github.io/Capital-Style/

```
import { vizColors } from '@opengov/capital-style/js';
import { getVizColors } from '@opengov/capital-style/js';
```

## Adding Tokens, Mixins or Styles
### Tokens
Tokens should be added within the `/tokens` folder to the appropriate `json` file. Update the `docs/index.html` to list any new tokens added.

### Mixins
Mixins should be added to the `/scss/tokens/mixins` file. Update the `docs/index.html` to list any new mixins added.

### Component Styles
Component Styles are maintained under `/scss/components`.

#### Style Namespacing
Please see the above notes on how classes are named and follow this pattern.

#### Targeting HTML elements
*NEVER* target an HTML element directly without a class used as an identifier.

#### Nesting Styles
Styles should always be nested under one parent style for the component.
