Export formats

The Documentation page emits three files from the same library state. All three are deterministic — the same state produces the same bytes.

Generator: src/lib/docs.ts.

tokens.css

A CSS file with two blocks.

Structure

/* Tostada export — <library-name>
   Generated YYYY-MM-DD HH:mm:ss */

:root {
  /* Primitives */
  --color-blue-500: #1B19FF;
  …

  /* Semantic */
  --bg-accent: var(--color-blue-500);
  …

  /* shadcn */
  --primary: var(--bg-accent);
  …
}

.dark {
  /* Only tokens whose dark resolution differs from light */
  --bg-base: var(--color-gray-950);
  --primary: var(--bg-accent-dark);
  …
}

Rules

• Section order inside :root: primitives → semantic → component.
• A token's CSS variable name is its id directly (primitives) or the literal name including dashes (component — e.g. --primary).
• Reference chains compile to nested var(--…) expressions so the browser handles the lookup.
• .dark block emits ONLY tokens whose dark resolution differs from light. Tokens that look the same in both modes are omitted from .dark.
• File starts with a comment header carrying the library name and generation timestamp.

design-system.md

A Markdown file in this section order:

# <Library name>

> Generated YYYY-MM-DD HH:mm:ss

## Tokens

### Primitives
(table grouped by `token.group`)

### Semantic aliases
(table grouped by ID prefix: Background, Foreground, Border, Other)

### Component variable bindings
(table grouped: Surface, Action, Neutral, Status, Form, Chart, Sidebar, Geometry)

## Layout principles

### Page shells
(one sub-section per shell principle — name, fields, notes)

### Page layouts
(one sub-section per layout principle — name, fields, notes)

## Navigation hierarchy
(DesignRules fields as a bullet list; notes as blockquote)

Conventions

• Tokens render as tables with columns: ID · Name · Value (or Reference) · Dark.
• Principle fields render as - key: value bullet lists with units appended.
• Notes render as a > Notes — … blockquote.
• Stable section anchors — agents and humans can link to #tokens, #layout-principles, etc.

design-system.json

interface DesignSystemJson {
  name: string
  generatedAt: string                       // ISO timestamp
  tokens: {
    primitive: DesignToken[]
    semantic:  DesignToken[]
    shadcn:    DesignToken[]
  }
  principles: LayoutPrinciple[]
  designRules: DesignRules
}

• Tokens are split into three arrays by tier.
• Other shapes (principles, designRules) are serialized as-is using the types in Reference → Schemas.
• No internal-only fields (no undo stack, no history, no React state).

Determinism guarantees

• Same library state → identical bytes across all three files.
• Section ordering is stable across versions.
• Whitespace is stable (no Date.now() interpolation outside the timestamp header).
• Token ordering inside each section is stable (sorted by group, then by ID).

This means diffs across exports reflect real design system changes — useful for code review and Git history.

Versioning

Today there's no version field in any of the three files. The roadmap will introduce one before the schemas change in a breaking way; until then, the rules are: existing fields don't change meaning, new fields are additive.