Tostada
Try Tostada Join Slack

The orchestrator model

Tostada is a design system orchestrator. It sits on top of an existing component library — today, the component library — and adds the layer your team actually argues about: which tokens, which layouts, which navigation pattern, which Do / Don't for each component.

This page explains the model, why it exists, and what flows downstream from it.

The gap an orchestrator fills

Most teams have:

  • A component library — the component library, Material, Chakra, Radix themes, or something homegrown. Ships primitives.
  • A design file — Figma, Penpot, Sketch. Ships visuals.
  • A doc — Notion, a Google Doc, a README. Ships rules.

These three sources of truth agree for about a month and then start whispering different things. A new hire ships a Card where everyone else uses a Banner. The brand color in the Figma file is #1B19FF; in the codebase it's #1A1AFF. The Notion doc says "use Primary buttons sparingly" but nobody reads it.

The orchestrator is one place that is all three of those things at once:

  • It applies the visual tokens to the real components, so the preview is the production output.
  • It captures the rules alongside the components they apply to.
  • It exports the same content as the code your devs ship and the prose your AI agents read.

What Tostada orchestrates today (and tomorrow)

Today: the component library (56 components, 27 blocks vendored).

Tomorrow (roadmap): Material, Chakra, Radix themes, headless UI primitives, your homegrown library. The orchestration layer doesn't care about the underlying library — it cares about the tokens flowing in, the rules flowing alongside, and the export flowing out.

The contract

Tostada captures four things:

  1. Tokens — primitive → semantic → component binding (three-tier tokens)
  2. Layout principles — page shells (app · marketing · docs · auth) and layouts (dashboard · article · list · detail · settings · empty-state · split), each with structured fields (layout principles)
  3. Navigation rules — primary nav placement, breakpoint behavior, breadcrumb policy, focus order
  4. Application rules — per-component and per-variant Do / Don't / Notes (application rules)

These four together are your design system. Tostada doesn't ship one for you — it gives you the authoring surface and the live preview.

What flows downstream

When you click Documentation, Tostada generates three files from the same source:

  • tokens.css — drop-in stylesheet your developers paste into any app. Defines every CSS variable for light and dark.
  • design-system.md — human- and AI-readable Markdown reference. Token tables, principles, rules in imperative voice. This is the file you feed Claude Code, Cursor, v0, or Claude Project memory.
  • design-system.json — structured JSON for tooling that needs to parse the system programmatically (custom linters, future Figma sync, etc.).

All three are generated from the same internal state. Edit a token; all three update.

Why an orchestrator and not a library

A component library is a tool. An orchestrator is a contract. The orchestrator is the layer where your team's opinions live — and opinions are what make a design system, not primitives.

The corollary: when you swap component for Material in three years, the orchestrator survives. Your tokens, your rules, your principles all port over. Only the bindings to the new library's variables change.

Further reading