Design Tokens using CSS custom properties

You are free to structure your CSS custom properties any way you like.

Our recommendation is to to separate them in different packages and document each Design Token family separately.

~/typography/src/_typography.scss

:root {
  --acme-typo-family-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI',
    Roboto, Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji',
    'Segoe UI Symbol';
  --acme-typo-family-serif: Georgia, 'Times New Roman', serif;
  --acme-typo-family-mono: Menlo, Monaco, 'Courier New', monospace;

  --acme-typo-size-small: 0.875rem;
  --acme-typo-size-medium: 1rem;
  --acme-typo-size-large: 1.25rem;
  --acme-typo-size-xlarge: 1.5rem;

  --acme-typo-weight-light: 300;
  --acme-typo-weight-normal: 400;
  --acme-typo-weight-semibold: 500;
  --acme-typo-weight-bold: 700;

  --acme-typo-letterspacing-dense: -0.015em;
  --acme-typo-letterspacing-normal: normal;
  --acme-typo-letterspacing-loose: 0.075em;

  --acme-typo-lineheight-dense: 1.4;
  --acme-typo-lineheight-normal: 1.8;
  --acme-typo-lineheight-loose: 2.2;
}

~/colors/src/_colors.scss

:root {
  --acme-color-white: #ffffff;
  --acme-color-primary: #3082ce;
  --acme-color-gray300: #cbd5e0;
  --acme-color-focusoutline: #4299e14c;
}

You can then combine all Design Tokens together using Sass imports.

~/all/src/all.scss

@import '../../colors/src/colors';
@import '../../typography/src/typography';
@import '../../spacing/src/spacing';
@import '../../elevation/src/elevation';
@import '../../border-radius/src/border-radius';
@import '../../transition/src/transition';
@import '../../z-index/src/z-index';
See starter-react-aria ▶

Documentation of Design Tokens using CSS custom properties

We provide a set of open-source components that you can drop in the documentation pages to illustrate Design Tokens automatically.

@divriots/dockit-react

Dockit-react is a React component to showcase different types of Design Tokens. Ideally used in documentation written using MDX technology.

<StyleShowcases
  prefix="--acme-color"
  styleKey="backgroundColor"
  componentProps={{ className: 'box' }}
/>

This showcases all CSS custom properties starting with --acme-color in a set of colored boxes.

See @divriots/dockit-react documentation for more details.

See starter-react-aria ▶

@divriots/dockit-core

Dockit-core is a Web Component to showcase different types of CSS custom properties. Used in documentation written using mdjs technology.

<dockit-css-showcases
  css-props-prefix="--acme-color"
  component-class="box"
  style-key="background-color"
>
</dockit-css-showcases>

This showcases all CSS custom properties starting with --acme-color in a set of colored boxes.

See starter-open-props ▶