@boostdev/design-system-components 0.1.18 → 1.0.0

package/src/stories/DesignSystem/Colors.mdx

@@ -0,0 +1,196 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Design System/Colors" />
+
+export const Swatch = ({ label, bg, text, token }) => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem', minWidth: '9rem' }}>
+    <div style={{
+      background: bg,
+      color: text,
+      height: '4rem',
+      borderRadius: '0.5rem',
+      border: '1px solid rgba(0,0,0,0.08)',
+      display: 'flex',
+      alignItems: 'flex-end',
+      padding: '0.375rem 0.5rem',
+      fontSize: '0.7rem',
+      fontFamily: 'monospace',
+      gap: '0.25rem',
+    }}>
+      {text && <span style={{ opacity: 0.8 }}>Aa</span>}
+    </div>
+    <div style={{ fontSize: '0.75rem', lineHeight: 1.3 }}>
+      <div style={{ fontWeight: 600 }}>{label}</div>
+      <div style={{ fontFamily: 'monospace', opacity: 0.65, fontSize: '0.7rem' }}>{token}</div>
+    </div>
+  </div>
+);
+
+export const SwatchRow = ({ children }) => (
+  <div style={{ display: 'flex', flexWrap: 'wrap', gap: '1rem', marginBottom: '2rem' }}>
+    {children}
+  </div>
+);
+
+export const TokenRow = ({ token, description }) => (
+  <tr>
+    <td><code>{token}</code></td>
+    <td>
+      <div style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
+        <div style={{ width: '1.5rem', height: '1.5rem', background: `var(${token})`, borderRadius: '0.25rem', border: '1px solid rgba(0,0,0,0.1)', flexShrink: 0 }} />
+        {description}
+      </div>
+    </td>
+  </tr>
+);
+
+# Colours
+
+Colours are the most visible part of the design system.
+Every colour token comes in surface–content pairs: for every `--bds-*` there is a `--bds-on-*` that guarantees WCAG AA contrast.
+
+```css
+.badge {
+  background-color: var(--bds-success--subtle);
+  color:            var(--bds-on-success--subtle); /* always legible */
+}
+```
+
+## Semantic colours
+
+These are the tokens you should use in component CSS. They adapt automatically to light and dark mode.
+
+### Brand & intent
+
+<SwatchRow>
+  <Swatch label="CTA / Active" token="--bds-cta" bg="var(--bds-cta)" text="var(--bds-on-cta)" />
+  <Swatch label="Interactive" token="--bds-interactive" bg="var(--bds-interactive)" text="var(--bds-on-interactive)" />
+  <Swatch label="Brand" token="--bds-brand" bg="var(--bds-brand)" text="var(--bds-on-brand)" />
+</SwatchRow>
+
+### Status
+
+<SwatchRow>
+  <Swatch label="Success" token="--bds-success" bg="var(--bds-success)" text="var(--bds-on-success)" />
+  <Swatch label="Warning" token="--bds-warning" bg="var(--bds-warning)" text="var(--bds-on-warning)" />
+  <Swatch label="Error" token="--bds-error" bg="var(--bds-error)" text="var(--bds-on-error)" />
+  <Swatch label="Important" token="--bds-important" bg="var(--bds-important)" text="var(--bds-on-important)" />
+</SwatchRow>
+
+### Surface
+
+<SwatchRow>
+  <Swatch label="Background" token="--bds-bg" bg="var(--bds-bg)" text="var(--bds-on-bg)" />
+  <Swatch label="Subtle background" token="--bds-bg--subtle" bg="var(--bds-bg--subtle)" text="var(--bds-on-bg--subtle)" />
+</SwatchRow>
+
+### Neutral grey scale
+
+<SwatchRow>
+  <Swatch label="Grey subtle" token="--bds-grey--subtle" bg="var(--bds-grey--subtle)" text="var(--bds-on-grey--subtle)" />
+  <Swatch label="Grey" token="--bds-grey" bg="var(--bds-grey)" text="var(--bds-on-grey)" />
+  <Swatch label="Grey strong" token="--bds-grey--strong" bg="var(--bds-grey--strong)" text="var(--bds-on-grey--strong)" />
+</SwatchRow>
+
+### Green scale
+
+<SwatchRow>
+  <Swatch label="Green subtle" token="--bds-green--subtle" bg="var(--bds-green--subtle)" text="var(--bds-on-green--subtle)" />
+  <Swatch label="Green" token="--bds-green" bg="var(--bds-green)" text="var(--bds-on-green)" />
+  <Swatch label="Green strong" token="--bds-green--strong" bg="var(--bds-green--strong)" text="var(--bds-on-green--strong)" />
+</SwatchRow>
+
+### Blue scale
+
+<SwatchRow>
+  <Swatch label="Blue subtle" token="--bds-blue--subtle" bg="var(--bds-blue--subtle)" text="var(--bds-on-blue--subtle)" />
+  <Swatch label="Blue" token="--bds-blue" bg="var(--bds-blue)" text="var(--bds-on-blue)" />
+  <Swatch label="Blue strong" token="--bds-blue--strong" bg="var(--bds-blue--strong)" text="var(--bds-on-blue--strong)" />
+</SwatchRow>
+
+### Orange scale
+
+<SwatchRow>
+  <Swatch label="Orange subtle" token="--bds-orange--subtle" bg="var(--bds-orange--subtle)" text="var(--bds-on-orange--subtle)" />
+  <Swatch label="Orange" token="--bds-orange" bg="var(--bds-orange)" text="var(--bds-on-orange)" />
+  <Swatch label="Orange strong" token="--bds-orange--strong" bg="var(--bds-orange--strong)" text="var(--bds-on-orange--strong)" />
+</SwatchRow>
+
+---
+
+## Base palette
+
+These `--bds-BASE__color--*` tokens are the primitive values. **Do not use them directly** in component CSS — always use semantic tokens so themes work correctly.
+
+### Grey
+
+<SwatchRow>
+  <Swatch label="grey-100" token="--bds-BASE__color--grey--100" bg="var(--bds-BASE__color--grey--100)" />
+  <Swatch label="grey-200" token="--bds-BASE__color--grey--200" bg="var(--bds-BASE__color--grey--200)" />
+  <Swatch label="grey-300" token="--bds-BASE__color--grey--300" bg="var(--bds-BASE__color--grey--300)" />
+  <Swatch label="grey-400" token="--bds-BASE__color--grey--400" bg="var(--bds-BASE__color--grey--400)" />
+  <Swatch label="grey-500" token="--bds-BASE__color--grey" bg="var(--bds-BASE__color--grey)" text="white" />
+  <Swatch label="grey-600" token="--bds-BASE__color--grey--600" bg="var(--bds-BASE__color--grey--600)" text="white" />
+  <Swatch label="grey-700" token="--bds-BASE__color--grey--700" bg="var(--bds-BASE__color--grey--700)" text="white" />
+  <Swatch label="grey-800" token="--bds-BASE__color--grey--800" bg="var(--bds-BASE__color--grey--800)" text="white" />
+  <Swatch label="grey-900" token="--bds-BASE__color--grey--900" bg="var(--bds-BASE__color--grey--900)" text="white" />
+</SwatchRow>
+
+### Green
+
+<SwatchRow>
+  <Swatch label="green-100" token="--bds-BASE__color--green--100" bg="var(--bds-BASE__color--green--100)" />
+  <Swatch label="green-200" token="--bds-BASE__color--green--200" bg="var(--bds-BASE__color--green--200)" />
+  <Swatch label="green-300" token="--bds-BASE__color--green--300" bg="var(--bds-BASE__color--green--300)" />
+  <Swatch label="green-400" token="--bds-BASE__color--green--400" bg="var(--bds-BASE__color--green--400)" />
+  <Swatch label="green-500" token="--bds-BASE__color--green" bg="var(--bds-BASE__color--green)" />
+  <Swatch label="green-600" token="--bds-BASE__color--green--600" bg="var(--bds-BASE__color--green--600)" />
+  <Swatch label="green-700" token="--bds-BASE__color--green--700" bg="var(--bds-BASE__color--green--700)" text="white" />
+  <Swatch label="green-800" token="--bds-BASE__color--green--800" bg="var(--bds-BASE__color--green--800)" text="white" />
+  <Swatch label="green-900" token="--bds-BASE__color--green--900" bg="var(--bds-BASE__color--green--900)" text="white" />
+</SwatchRow>
+
+### Blue
+
+<SwatchRow>
+  <Swatch label="blue-100" token="--bds-BASE__color--blue--100" bg="var(--bds-BASE__color--blue--100)" />
+  <Swatch label="blue-200" token="--bds-BASE__color--blue--200" bg="var(--bds-BASE__color--blue--200)" />
+  <Swatch label="blue-300" token="--bds-BASE__color--blue--300" bg="var(--bds-BASE__color--blue--300)" />
+  <Swatch label="blue-400" token="--bds-BASE__color--blue--400" bg="var(--bds-BASE__color--blue--400)" />
+  <Swatch label="blue-500" token="--bds-BASE__color--blue" bg="var(--bds-BASE__color--blue)" text="white" />
+  <Swatch label="blue-600" token="--bds-BASE__color--blue--600" bg="var(--bds-BASE__color--blue--600)" text="white" />
+  <Swatch label="blue-700" token="--bds-BASE__color--blue--700" bg="var(--bds-BASE__color--blue--700)" text="white" />
+  <Swatch label="blue-800" token="--bds-BASE__color--blue--800" bg="var(--bds-BASE__color--blue--800)" text="white" />
+  <Swatch label="blue-900" token="--bds-BASE__color--blue--900" bg="var(--bds-BASE__color--blue--900)" text="white" />
+</SwatchRow>
+
+### Orange
+
+<SwatchRow>
+  <Swatch label="orange-100" token="--bds-BASE__color--orange--100" bg="var(--bds-BASE__color--orange--100)" />
+  <Swatch label="orange-200" token="--bds-BASE__color--orange--200" bg="var(--bds-BASE__color--orange--200)" />
+  <Swatch label="orange-300" token="--bds-BASE__color--orange--300" bg="var(--bds-BASE__color--orange--300)" />
+  <Swatch label="orange-400" token="--bds-BASE__color--orange--400" bg="var(--bds-BASE__color--orange--400)" />
+  <Swatch label="orange-500" token="--bds-BASE__color--orange" bg="var(--bds-BASE__color--orange)" />
+  <Swatch label="orange-600" token="--bds-BASE__color--orange--600" bg="var(--bds-BASE__color--orange--600)" text="white" />
+  <Swatch label="orange-700" token="--bds-BASE__color--orange--700" bg="var(--bds-BASE__color--orange--700)" text="white" />
+  <Swatch label="orange-800" token="--bds-BASE__color--orange--800" bg="var(--bds-BASE__color--orange--800)" text="white" />
+  <Swatch label="orange-900" token="--bds-BASE__color--orange--900" bg="var(--bds-BASE__color--orange--900)" text="white" />
+</SwatchRow>
+
+---
+
+## Theming
+
+Override `--bds-cta` (and its `on-` pair) to change the primary action colour globally:
+
+```css
+@layer tokens.override {
+  :root {
+    --bds-cta:            var(--bds-BASE__color--blue);
+    --bds-on-cta:         var(--bds-BASE__color--white);
+    --bds-interactive:    var(--bds-BASE__color--blue);
+    --bds-on-interactive: var(--bds-BASE__color--white);
+  }
+}
+```

package/src/stories/DesignSystem/Elevation.mdx

@@ -0,0 +1,127 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Design System/Elevation" />
+
+export const ShadowCard = ({ token, label }) => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: '0.75rem', alignItems: 'center' }}>
+    <div style={{
+      width: '8rem',
+      height: '5rem',
+      background: 'var(--bds-bg)',
+      borderRadius: '0.75rem',
+      boxShadow: `var(${token})`,
+    }} />
+    <div style={{ textAlign: 'center' }}>
+      <div style={{ fontSize: '0.8rem', fontWeight: 600 }}>{label}</div>
+      <div style={{ fontSize: '0.7rem', fontFamily: 'monospace', opacity: 0.6, marginTop: '0.1rem' }}>{token}</div>
+    </div>
+  </div>
+);
+
+export const RadiusBox = ({ token, label, value }) => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: '0.75rem', alignItems: 'center' }}>
+    <div style={{
+      width: '4rem',
+      height: '4rem',
+      background: 'var(--bds-interactive)',
+      borderRadius: `var(${token})`,
+      opacity: 0.8,
+    }} />
+    <div style={{ textAlign: 'center' }}>
+      <div style={{ fontSize: '0.8rem', fontWeight: 600 }}>{label}</div>
+      <div style={{ fontSize: '0.7rem', fontFamily: 'monospace', opacity: 0.6 }}>{token}</div>
+      <div style={{ fontSize: '0.7rem', opacity: 0.5 }}>{value}</div>
+    </div>
+  </div>
+);
+
+export const ZRow = ({ token, value, description }) => (
+  <tr>
+    <td><code>{token}</code></td>
+    <td style={{ fontFamily: 'monospace' }}>{value}</td>
+    <td>{description}</td>
+  </tr>
+);
+
+# Elevation
+
+## Shadows
+
+Five shadow levels from subtle to dramatic. All values adapt to dark mode (higher opacity for visibility against dark surfaces).
+
+<div style={{ display: 'flex', gap: '2.5rem', flexWrap: 'wrap', padding: '2rem', background: 'var(--bds-bg--subtle)', borderRadius: '0.75rem', marginBottom: '2rem' }}>
+  <ShadowCard token="--bds-shadow_s" label="Small" />
+  <ShadowCard token="--bds-shadow_m" label="Medium" />
+  <ShadowCard token="--bds-shadow_l" label="Large" />
+  <ShadowCard token="--bds-shadow_xl" label="X-Large" />
+  <ShadowCard token="--bds-shadow_2xl" label="2X-Large" />
+</div>
+
+| Token | Light mode | Dark mode |
+|-------|-----------|-----------|
+| `--bds-shadow_s` | `0 1px 3px rgba(0,0,0,0.05)` | `0 2px 12px rgba(0,0,0,0.40)` |
+| `--bds-shadow_m` | `0 2px 8px rgba(0,0,0,0.10)` | `0 4px 20px rgba(0,0,0,0.50)` |
+| `--bds-shadow_l` | `0 4px 16px rgba(0,0,0,0.12)` | `0 8px 36px rgba(0,0,0,0.60)` |
+| `--bds-shadow_xl` | `0 8px 24px rgba(0,0,0,0.15)` | `0 8px 28px rgba(0,0,0,0.50)` |
+| `--bds-shadow_2xl` | `0 8px 32px rgba(0,0,0,0.16)` | `0 8px 32px rgba(0,0,0,0.65)` |
+
+---
+
+## Border radius
+
+<div style={{ display: 'flex', gap: '2rem', flexWrap: 'wrap', padding: '2rem', background: 'var(--bds-bg--subtle)', borderRadius: '0.75rem', marginBottom: '2rem' }}>
+  <RadiusBox token="--bds-border_radius--xs" label="X-Small" value="0.25rem / 4px" />
+  <RadiusBox token="--bds-border_radius--s" label="Small" value="0.75rem / 12px" />
+  <RadiusBox token="--bds-border_radius--m" label="Medium" value="1rem / 16px" />
+</div>
+
+---
+
+## Outline
+
+Used for focus rings on interactive elements.
+
+| Token | Value |
+|-------|-------|
+| `--bds-outline_default` | `2px dotted var(--bds-outline_color)` |
+| `--bds-outline_color` | grey-600 (light) / grey-400 (dark) |
+| `--bds-outline_offset` | `2px` |
+
+```css
+.my-button:focus-visible {
+  outline: var(--bds-outline_default);
+  outline-offset: var(--bds-outline_offset);
+}
+```
+
+---
+
+## Z-index
+
+<table>
+  <thead>
+    <tr>
+      <th>Token</th>
+      <th>Value</th>
+      <th>Purpose</th>
+    </tr>
+  </thead>
+  <tbody>
+    <ZRow token="--bds-z-index_below"    value="-1"  description="Visually behind the page" />
+    <ZRow token="--bds-z-index_base"     value="0"   description="Default stacking context" />
+    <ZRow token="--bds-z-index_above"    value="1"   description="One step above base" />
+    <ZRow token="--bds-z-index_s"        value="20"  description="Sticky headers, minor overlays" />
+    <ZRow token="--bds-z-index_m"        value="50"  description="Dropdowns, popovers" />
+    <ZRow token="--bds-z-index_l"        value="100" description="Navigation, drawers" />
+    <ZRow token="--bds-z-index_xl"       value="200" description="Toasts, critical overlays" />
+    <ZRow token="--bds-z-index_dropdown" value="50"  description="Role alias → m" />
+    <ZRow token="--bds-z-index_popover"  value="50"  description="Role alias → m" />
+    <ZRow token="--bds-z-index_nav"      value="100" description="Role alias → l" />
+    <ZRow token="--bds-z-index_toast"    value="200" description="Role alias → xl" />
+  </tbody>
+</table>
+
+```css
+.dropdown { z-index: var(--bds-z-index_dropdown); }
+.toast    { z-index: var(--bds-z-index_toast); }
+```

package/src/stories/DesignSystem/Grid.mdx

@@ -0,0 +1,140 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Design System/Grid" />
+
+export const GridCell = ({ span, label, color = 'var(--bds-interactive)' }) => (
+  <div style={{
+    gridColumn: span,
+    background: color,
+    color: 'var(--bds-on-interactive)',
+    borderRadius: '0.25rem',
+    padding: '0.5rem 0.75rem',
+    fontSize: '0.75rem',
+    fontFamily: 'monospace',
+    opacity: 0.85,
+  }}>
+    {label}
+  </div>
+);
+
+export const GridDemo = ({ children }) => (
+  <div style={{
+    display: 'grid',
+    gridTemplateColumns: 'repeat(12, 1fr)',
+    gap: '0.5rem',
+    padding: '1rem',
+    background: 'var(--bds-bg--subtle)',
+    borderRadius: '0.5rem',
+    marginBottom: '1.5rem',
+  }}>
+    {children}
+  </div>
+);
+
+# Grid
+
+The grid system is responsive and built entirely on CSS custom properties. It adapts from 4 columns on mobile to 12 columns on large screens.
+
+## Breakpoints
+
+| Breakpoint | Columns | Gap |
+|------------|---------|-----|
+| `< 48rem` (mobile) | 4 | 1rem |
+| `48rem+` (tablet) | 8 | 1.5rem |
+| `64rem+` (desktop) | 12 | 2rem |
+
+## Tokens
+
+| Token | Description |
+|-------|-------------|
+| `--bds-grid_columns` | Current column count (4 / 8 / 12) |
+| `--bds-grid_gap` | Current gap (1rem / 1.5rem / 2rem) |
+| `--bds-grid_template-columns` | `repeat(var(--bds-grid_columns), minmax(1rem, 1fr))` |
+| `--bds-grid_span-100` | `1 / -1` — full width |
+| `--bds-grid_span-75` | Approx. 75% — 3 of 4, 6 of 8, 9 of 12 columns |
+| `--bds-grid_span-66` | Approx. 66% — 2 of 4 / 5 of 8 / 8 of 12 |
+| `--bds-grid_span-50` | Approx. 50% — 2 / 4 / 6 columns |
+| `--bds-grid_span-33` | Approx. 33% — 1 / 3 / 4 columns |
+| `--bds-grid_span-25` | Approx. 25% — 1 / 2 / 3 columns |
+
+## Visual examples (shown at 12-column scale)
+
+### Full width — `--bds-grid_span-100`
+
+<GridDemo>
+  <GridCell span="1 / -1" label="span 100%" />
+</GridDemo>
+
+### 75% — `--bds-grid_span-75`
+
+<GridDemo>
+  <GridCell span="span 9" label="span 75%" />
+  <GridCell span="span 3" label="25%" color="var(--bds-grey)" />
+</GridDemo>
+
+### Two thirds — `--bds-grid_span-66`
+
+<GridDemo>
+  <GridCell span="span 8" label="span 66%" />
+  <GridCell span="span 4" label="33%" color="var(--bds-grey)" />
+</GridDemo>
+
+### Half and half — `--bds-grid_span-50`
+
+<GridDemo>
+  <GridCell span="span 6" label="span 50%" />
+  <GridCell span="span 6" label="span 50%" />
+</GridDemo>
+
+### Thirds — `--bds-grid_span-33`
+
+<GridDemo>
+  <GridCell span="span 4" label="33%" />
+  <GridCell span="span 4" label="33%" />
+  <GridCell span="span 4" label="33%" />
+</GridDemo>
+
+### Quarters — `--bds-grid_span-25`
+
+<GridDemo>
+  <GridCell span="span 3" label="25%" />
+  <GridCell span="span 3" label="25%" />
+  <GridCell span="span 3" label="25%" />
+  <GridCell span="span 3" label="25%" />
+</GridDemo>
+
+---
+
+## Utility classes
+
+Apply the built-in layout utilities to use the grid system without writing CSS:
+
+```html
+<div class="utl-page-grid">       <!-- full-width stacked outer layout -->
+  <main class="utl-main-grid">   <!-- responsive CSS grid with padding + max-width -->
+    <div class="utl-column" style="--size: var(--bds-grid_span-66)">
+      Two thirds content
+    </div>
+    <aside class="utl-column" style="--size: var(--bds-grid_span-33)">
+      One third sidebar
+    </aside>
+  </main>
+</div>
+```
+
+## Custom grid usage
+
+```css
+.my-layout {
+  display: grid;
+  grid-template-columns: var(--bds-grid_template-columns);
+  gap: var(--bds-grid_gap);
+}
+
+.sidebar { grid-column: var(--bds-grid_span-25); }
+.main    { grid-column: var(--bds-grid_span-75); }
+```
+
+## Sticky position
+
+`--bds-sticky_inset-start: 5rem` — the default top offset for sticky elements (accounts for a fixed nav bar).

package/src/stories/DesignSystem/Motion.mdx

@@ -0,0 +1,96 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Design System/Motion" />
+
+export const AnimDemo = ({ label, token, animationStyle }) => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: '0.75rem', alignItems: 'center' }}>
+    <div style={{
+      width: '3rem',
+      height: '3rem',
+      background: 'var(--bds-interactive)',
+      borderRadius: '0.5rem',
+      animation: animationStyle,
+      opacity: 0.9,
+    }} />
+    <div style={{ textAlign: 'center' }}>
+      <div style={{ fontSize: '0.8rem', fontWeight: 600 }}>{label}</div>
+      {token && <div style={{ fontSize: '0.7rem', fontFamily: 'monospace', opacity: 0.6 }}>{token}</div>}
+    </div>
+  </div>
+);
+
+# Motion
+
+## Timing tokens
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `--bds-animation_easing` | `ease-out` | Default easing for transitions |
+| `--bds-animation_duration--fast` | `150ms` | Micro-interactions, hover states |
+| `--bds-animation_duration--normal` | `350ms` | Panel opens, page transitions |
+| `--bds-animation_transition-duration` | `150ms` | Shorthand duration alias |
+| `--bds-animation_transition` | `all 150ms ease-out` | Single-line transition shorthand |
+
+```css
+.button {
+  transition: var(--bds-animation_transition);
+}
+
+.panel {
+  transition: transform var(--bds-animation_duration--normal) var(--bds-animation_easing);
+}
+```
+
+---
+
+## Keyframe animations
+
+The foundation ships six named keyframes.
+
+<div style={{ display: 'flex', gap: '3rem', flexWrap: 'wrap', padding: '2rem', background: 'var(--bds-bg--subtle)', borderRadius: '0.75rem', marginBottom: '2rem' }}>
+  <AnimDemo label="bounce" animationStyle="bounce 1s ease-out infinite" />
+  <AnimDemo label="rotate" animationStyle="rotate 2s linear infinite" />
+  <AnimDemo label="fade-zoom" animationStyle="fade-zoom 2s ease-in-out infinite" />
+  <AnimDemo label="slide-to-start" animationStyle="slide-to-start 1.5s ease-in-out infinite alternate" />
+  <AnimDemo label="slide-to-end" animationStyle="slide-to-end 1.5s ease-in-out infinite alternate" />
+</div>
+
+| Keyframe | Description |
+|----------|-------------|
+| `bounce` | Scale 1 → 0.75 → 1 — attention pulse |
+| `rotate` | 0 → 360deg — continuous spin |
+| `fade-zoom` | Opacity + scale pulse (1,1) → (0.4,1.25) → (1,1) |
+| `slide-to-start` | translateX 0 → -20% |
+| `slide-to-end` | translateX 0 → 20% |
+
+---
+
+## Reduced motion
+
+All animations in the library respect `prefers-reduced-motion`. When building custom animations, always add this override:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .my-animated-element {
+    animation: none;
+    transition: none;
+  }
+}
+```
+
+---
+
+## Chevron rotation
+
+`--bds-animation_chevron-rotate--end: x 180deg`
+
+Convenience token for animating a chevron/caret icon into its open/closed state:
+
+```css
+.chevron {
+  transition: rotate var(--bds-animation_transition);
+}
+.chevron[data-open="true"] {
+  rotate: var(--bds-animation_chevron-rotate--end);
+}
+```

package/src/stories/DesignSystem/Overview.mdx

@@ -0,0 +1,99 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Design System/Overview" />
+
+# Design System Foundation
+
+`@boostdev/design-system-foundation` is the token layer that every component in this library is built on.
+It provides a complete set of CSS custom properties for colour, spacing, typography, grid, elevation, and motion —
+all responsive and theme-aware out of the box.
+
+## Installation
+
+```bash
+pnpm add @boostdev/design-system-foundation
+```
+
+## Setup
+
+Import the CSS once at your app root. Components rely on these custom properties being present in the document.
+
+```css
+/* app.css */
+@import "@boostdev/design-system-foundation/css";
+```
+
+Or via a JS bundler (Vite, Next.js, etc.):
+
+```ts
+// main.ts / layout.tsx
+import '@boostdev/design-system-foundation/css';
+```
+
+## What's included
+
+| Import | Contents |
+|--------|----------|
+| `/css` | Everything below, bundled |
+| `/css/tokens/color` | Colour palette + semantic colour tokens |
+| `/css/tokens/space` | Spacing scale + container tokens |
+| `/css/tokens/font` | Typography — family, size, weight, line-height, tracking |
+| `/css/tokens/grid` | Responsive grid columns + span helpers |
+| `/css/tokens/border` | Border radius + outline tokens |
+| `/css/tokens/shadow` | Elevation scale (s → 2xl) |
+| `/css/tokens/animations` | Easing, duration, transition shorthand, keyframes |
+| `/css/tokens/z-index` | Z-index scale + named role aliases |
+| `/css/reset` | Minimal CSS reset |
+| `/css/base` | Base element styles (headings, links, body) |
+| `/css/utilities` | Utility classes (grid layout, visually-hidden, etc.) |
+
+## Layer architecture
+
+All tokens live inside `@layer` declarations. The cascade order, from lowest to highest, is:
+
+```
+tokens.base → tokens.semantic → tokens.override → reset → base → utilities → component
+```
+
+`@layer component` — used by every component in this library — sits above the token layers,
+so you can override any component from `@layer my-overrides` without specificity fights.
+
+## Theming
+
+Tokens adapt automatically to light and dark mode via `data-theme` attribute or `prefers-color-scheme`:
+
+```html
+<!-- explicit themes -->
+<html data-theme="light">
+<html data-theme="dark">
+```
+
+```css
+/* or CSS-only, no attribute needed */
+@media (prefers-color-scheme: dark) { … }
+```
+
+Override any token in your own layer to retheme:
+
+```css
+@import "@boostdev/design-system-foundation/css";
+
+@layer tokens.override {
+  :root {
+    --bds-cta:    var(--bds-BASE__color--blue);
+    --bds-on-cta: var(--bds-BASE__color--white);
+  }
+}
+```
+
+## Naming convention
+
+```
+--bds-{group}_{name}--{variant}
+```
+
+- `bds-` prefix = all foundation tokens
+- `_` separates group from name
+- `--` separates name from scale variant
+- `BASE__` prefix = primitive palette (never use directly in component CSS)
+- All semantic tokens are prefixed with `bds-` (e.g. `--bds-bg`, `--bds-interactive`)