@boostdev/design-system-components 0.1.18 → 1.0.1

package/src/stories/DesignSystem/Borders.mdx

@@ -0,0 +1,158 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Design System/Borders" />
+
+export const BorderDemo = ({ label, token, color = 'currentcolor', offset = '-1px', width = '1px' }) => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: '0.75rem', alignItems: 'center' }}>
+    <div style={{
+      width: '8rem',
+      height: '5rem',
+      background: 'var(--bds-bg)',
+      borderRadius: '0.5rem',
+      outline: `${width} solid ${color}`,
+      outlineOffset: offset,
+    }} />
+    <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 TokenRow = ({ token, type, defaultValue, description }) => (
+  <tr>
+    <td><code>{token}</code></td>
+    <td style={{ fontFamily: 'monospace' }}>{type}</td>
+    <td style={{ fontFamily: 'monospace' }}>{defaultValue}</td>
+    <td>{description}</td>
+  </tr>
+);
+
+# Borders
+
+The `bdc` system unifies all component borders behind five registered CSS custom properties. Every form control, card, and interactive surface draws its border from these tokens — ensuring consistent visual weight, smooth animated state transitions, and a single override point for theming.
+
+## Why outline, not border?
+
+Components use `outline` rather than `border` for their decorative edge. The reasons:
+
+- **Zero layout impact** — `outline` lives outside the box model, so changing width or color never shifts surrounding elements.
+- **Inset appearance** — `outline-offset: -1px` pulls the ring inside the element, making it visually indistinguishable from a traditional border.
+- **Animatable colour** — `@property --bdc_color { syntax: '<color>'; }` registers the token as a typed custom property, which lets the browser interpolate it directly. A single `transition: --bdc_color 150ms ease-out` handles focus, hover, and error state changes without JavaScript.
+
+## Tokens
+
+<table>
+  <thead>
+    <tr>
+      <th>Token</th>
+      <th>Type</th>
+      <th>Default</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <TokenRow token="--bdc_color"  type="<color>"              defaultValue="currentcolor" description="Border colour — transitions smoothly between states" />
+    <TokenRow token="--bdc-outline_width"  type="<length>"             defaultValue="1px"          description="Border width" />
+    <TokenRow token="--bdc-outline_offset" type="<length>"             defaultValue="-1px"         description="Negative = inset (border-like); positive = outer halo" />
+    <TokenRow token="--bdc-outline_radius" type="<length-percentage>"  defaultValue="0"            description="Border radius, synced with the element's own radius" />
+    <TokenRow token="--bdc-outline_shadow" type="*"                    defaultValue="none"         description="Box shadow — opt-in accent, e.g. focus glow" />
+  </tbody>
+</table>
+
+---
+
+## Visual examples
+
+<div style={{ display: 'flex', gap: '2.5rem', flexWrap: 'wrap', padding: '2rem', background: 'var(--bds-bg--subtle)', borderRadius: '0.75rem', marginBottom: '2rem' }}>
+  <BorderDemo label="Default" token="currentcolor" color="currentcolor" />
+  <BorderDemo label="Focus" token="--bdc_color--focus" color="var(--bds-interactive)" />
+  <BorderDemo label="Error" token="--bdc_color--error" color="var(--bds-error)" />
+  <BorderDemo label="Outer halo" token="--bdc-outline_offset: 2px" color="var(--bds-interactive)" offset="2px" width="2px" />
+</div>
+
+| State | `--bdc_color` resolves to | Trigger |
+|-------|--------------------------|---------|
+| Default | `currentcolor` | — |
+| Focus | `var(--bdc_color--focus)` → `--bds-interactive` | `:focus` |
+| Error | `var(--bdc_color--error)` → `--bds-error` | `[aria-invalid="true"]` |
+| Keyboard ring | `var(--bds-outline_default)` | `:focus-visible` |
+
+---
+
+## Component pattern
+
+Every component that renders a bordered element follows this CSS pattern:
+
+```css
+.element {
+  /* Suppress any browser default border — consumer can re-enable
+     via the --component_border custom property if needed. */
+  border: none;
+
+  /* bdc defaults */
+  --bdc_color: currentcolor;
+
+  /* Rendered border (zero layout impact) */
+  outline: var(--bdc-outline_width) solid var(--bdc_color);
+  outline-offset: var(--bdc-outline_offset);
+  border-radius: var(--bdc-outline_radius);
+  box-shadow: var(--bdc-outline_shadow);
+
+  /* Smooth colour transitions via registered @property */
+  transition: --bdc_color 150ms ease-out;
+}
+
+/* State overrides — only the colour token changes */
+.element:focus              { --bdc_color: var(--bdc_color--focus); }
+.element[aria-invalid="true"] { --bdc_color: var(--bdc_color--error); }
+
+/* Keyboard accessibility ring — replaces outline on focus-visible */
+.element:focus-visible {
+  outline: var(--bds-outline_default);
+  outline-offset: var(--bds-outline_offset);
+}
+```
+
+---
+
+## Consumer overrides
+
+Override a component's border colour for a specific context by reassigning `--bdc_color`:
+
+```css
+/* Scoped to a single component instance */
+.my-context .my-input {
+  --bdc_color: var(--bds-warning);
+}
+
+/* Override globally via the token layer */
+@layer tokens.override {
+  :root {
+    --bdc_color: var(--bds-brand);
+  }
+}
+```
+
+To change width or radius independently:
+
+```css
+.my-card {
+  --bdc-outline_width: 2px;
+  --bdc-outline_radius: var(--bds-border_radius--m);
+}
+```
+
+---
+
+## Import
+
+The `bdc` tokens are included automatically when you import the component stylesheet:
+
+```css
+/* Included automatically with the full component CSS */
+@import '@boostdev/components/css';
+
+/* Or load the token layer standalone */
+@import '@boostdev/components/css/bdc';
+```

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