> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equa.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Design System Foundations

> Token, theme, typography, spacing, radius, shadow, and export conventions for the Equa design system

# Design System Foundations

> **Last Verified:** 2026-05-20 | **Sources:** `equa-patternlib-nextjs/src/tokens/design-tokens.json`, `equa-patternlib-nextjs/src/tokens/design-tokens.css`, `equa-patternlib-nextjs/stories/DesignTokens.mdx`

## Source Of Truth

The design-token source is `equa-patternlib-nextjs/src/tokens/design-tokens.json`. The generated CSS and TypeScript exports are consumed by Storybook, equa-web, and gateway-aligned Lit/CSS surfaces.

<img src="https://mintcdn.com/equainc/6_JjxW8WIY8CWUQQ/images/design-system/foundations/design-tokens.png?fit=max&auto=format&n=6_JjxW8WIY8CWUQQ&q=85&s=aafacbb995bc80acea4b38493d56f150" alt="Design tokens visual reference" width="1280" height="720" data-path="images/design-system/foundations/design-tokens.png" />

## Token Groups

| Group       | Source               | Notes                                                      |
| ----------- | -------------------- | ---------------------------------------------------------- |
| \$schema    | `design-tokens.json` | Token group exported through CSS and TypeScript generation |
| meta        | `design-tokens.json` | Token group exported through CSS and TypeScript generation |
| colors      | `design-tokens.json` | Token group exported through CSS and TypeScript generation |
| spacing     | `design-tokens.json` | Token group exported through CSS and TypeScript generation |
| typography  | `design-tokens.json` | Token group exported through CSS and TypeScript generation |
| radii       | `design-tokens.json` | Token group exported through CSS and TypeScript generation |
| shadows     | `design-tokens.json` | Token group exported through CSS and TypeScript generation |
| breakpoints | `design-tokens.json` | Token group exported through CSS and TypeScript generation |
| animation   | `design-tokens.json` | Token group exported through CSS and TypeScript generation |

## Theme Contract

| Theme     | Scope                                           | Notes                                                   |
| --------- | ----------------------------------------------- | ------------------------------------------------------- |
| Equa dark | Storybook, equa-web, gateway-aligned components | Default dark teal product theme                         |
| Light     | Storybook, equa-web, gateway-aligned components | Light product theme for screenshots and contrast checks |
| Midnight  | Storybook and equa-web                          | Product-only dark navy theme, not a gateway requirement |

## Export Convention

* Keep generated token assets in the owning product repo until copied into this docs repo as visual references.
* Store rendered token visuals under `/images/design-system/foundations/`.
* Store synced Figma exports under `/images/design-system/figma-exports/`.

## Update Workflow

1. Edit `equa-patternlib-nextjs/src/tokens/design-tokens.json`.
2. Run `npm run tokens` and `npm run tokens:check` in `equa-patternlib-nextjs`.
3. Refresh this page and any affected component screenshots.
4. Run `npm run build:search`, `npm run validate`, `npm run broken-links`, and `npm run a11y` in `equa-docs`.