atomic-design-poc/libs/shared/docs/design-tokens.mdx

import { Meta } from '@storybook/addon-docs/blocks';
import { useState, useLayoutEffect, useRef } from 'react';

<Meta title="Foundations/Design Tokens" />

# Design tokens

We do not hand-write colours or spacing. `src/styles.scss` defines a semantic `--rhc-*` token
vocabulary and redefines every one of those tokens onto the vendored **CIBG Huisstijl**
(Bootstrap 5.2) values — `--bs-*`/`--ro-*` custom properties where one exists, CIBG palette hex
otherwise (that one file is exempt from `npm run check:tokens`, which fails the build on any
_other_ hardcoded hex colour in atoms/molecules/chrome). The `--rhc-*` names are an internal
alias set now; the values are CIBG's.

**Prefer a CIBG class over a token where one exists** — `.btn`, `.form-control`, `.card`,
`.stepper`, `.confirmation`, `.applications`, … are already themed by the vendored CSS (see
`public/cibg-huisstijl/`). Reach for a `--rhc-*` token only where CIBG has no ready-made class
(an `alert` surface, a skeleton loader, a status badge — see ADR-0003).

> Resolved values below are read live from the running theme via `getComputedStyle`, so they
> can't drift from what ships. `body.brand--cibg` (set in `index.html` and Storybook's
> `preview.ts`) activates CIBG's robijn/lintblauw palette; no extra wrapper class is needed.

export const Resolved = ({ token }) => {
  const ref = useRef(null);
  const [val, setVal] = useState('');
  useLayoutEffect(() => {
    if (ref.current) setVal(getComputedStyle(ref.current).getPropertyValue(token).trim());
  }, [token]);
  return (
    <span ref={ref} style={{ fontFamily: 'monospace', fontSize: '0.75rem', color: '#666' }}>
      {val || '…'}
    </span>
  );
};

## When to use which token

- **CIBG class first** (see above) — a token is for the gaps a CIBG class doesn't cover.
- **Semantic first** — reach for a role token (`--rhc-color-foreground-default`,
  `--rhc-color-border-default`, `--rhc-color-foreground-link`) before a raw palette step
  (`--rhc-color-lintblauw-500`). Roles survive a theme swap; palette steps don't.
- **`--rhc-space-max-*`** for all spacing/gaps — never a raw `rem`.
- **`--app-*`** (in `src/styles.scss`) only for app measures CIBG has no token for
  (`--app-content-max`, `--app-form-narrow`). If you're tempted to add one, check CIBG first.

## Spacing scale — `--rhc-space-max-*`

<div style={{ display: 'grid', gap: '0.4rem', margin: '1rem 0' }}>
  {['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl', '4xl', '5xl'].map((step) => {
    const token = `--rhc-space-max-${step}`;
    return (
      <div key={step} style={{ display: 'flex', alignItems: 'center', gap: '1rem' }}>
        <code style={{ width: '12rem', fontSize: '0.78rem' }}>{token}</code>
        <div
          style={{
            height: '1rem',
            width: `var(${token})`,
            background: 'var(--rhc-color-lintblauw-500)',
            borderRadius: '2px',
          }}
        />
        <Resolved token={token} />
      </div>
    );
  })}
</div>

## Semantic colours

<div
  style={{
    display: 'grid',
    gridTemplateColumns: 'repeat(auto-fill, minmax(14rem, 1fr))',
    gap: '0.75rem',
    margin: '1rem 0',
  }}
>
  {[
    '--rhc-color-foreground-default',
    '--rhc-color-foreground-subtle',
    '--rhc-color-foreground-link',
    '--rhc-color-layout',
    '--rhc-color-lintblauw-500',
    '--rhc-color-lintblauw-700',
    '--rhc-color-border-default',
    '--rhc-color-border-strong',
    '--rhc-color-cool-grey-100',
  ].map((token) => (
    <div key={token} style={{ border: '1px solid #ddd', borderRadius: '6px', overflow: 'hidden' }}>
      <div style={{ height: '3rem', background: `var(${token})` }} />
      <div style={{ padding: '0.4rem 0.5rem' }}>
        <div style={{ fontFamily: 'monospace', fontSize: '0.72rem', wordBreak: 'break-all' }}>
          {token}
        </div>
        <Resolved token={token} />
      </div>
    </div>
  ))}
</div>