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
  version: number                            // the bundle format version
  generatedAt?: string                       // optional — absent by default, see below
  tokens: {
    primitive: DesignToken[]
    semantic:  DesignToken[]
    component: DesignToken[]
  }
  layoutPrinciples: { shells; layouts; overlays; navigation }
  components: ComponentDoc[]                 // rules + snippet per component
  patterns: PatternRecord[]                  // one per pattern, and one per variant
}

interface PatternRecord {
  id: string
  name: string
  variant?: string                           // present when the record is a variant
  kind: 'ux' | 'layout' | 'journey'
  problem: string
  do: string[]
  dont: string[]
  steps: string[]
  components: string[]                       // component names from your library
  code: { language: string; stack?: string; snippet: string; caption?: string }[]
  noCodeReference: boolean                   // says so when there is nothing to adapt
}

• Tokens are split into arrays by tier.
• Layout principles are serialized as-is using the types in Reference → Schemas.
• patterns is the compact form of every pattern — the base set Tostada ships and your own. The full reasoning is in patterns.md; the lossless object is in tostada.json. Images are never included: they would name storage you cannot reach.
• No internal-only fields (no undo stack, no history, no React state).

patterns.md

Every pattern, base set first: its problem, do and don't rules, steps if it has an order, the components it composes, the reasoning behind the rules, and any reference code — which says to adapt it to your codebase rather than paste it. Written for a developer and a coding agent alike; AGENTS.md points agents at it.

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.