@opengov/capital-style

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

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

@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.