Tostada
Try Tostada Join Slack

Application rules

Tokens tell the AI how a button looks. Application rules tell it when to use one.

Every component in Tostada has a Do / Don't / Notes panel. The text you write there is what makes a generic primitive into your team's button.

The shape

A ComponentRuleSet has three fields:

  • do: string[] — short imperative statements. "Use Primary for the single most important action on the page."
  • dont: string[] — what to avoid. "Don't stack two Primary buttons in the same view."
  • notes: string — free-form context, edge cases, links.

Component-level vs per-variant

Rules cascade in two tiers:

  • base — rules that apply to every variant of the component.
  • perVariant — overrides keyed by ${axis}:${value} (e.g. variant:outline). When a variant has its own rule set, it replaces the base for that variant — it doesn't merge.

The editor surfaces this clearly: a variant with custom rules shows an override badge, and a Reset button restores the base.

Practical rule of thumb: write base rules for the whole component, then add per-variant overrides only where a variant has genuinely different guidance.

Imperative voice for AI ingestion

design-system.md renders your rules as bullet lists under the component's section. AI agents (Claude Code, Cursor, v0) parse this and apply it during code generation. Two things matter:

  1. Active voice. "Use Primary for the most important action" reads as a rule. "Primary buttons are typically used for the most important action" reads as trivia.
  2. One rule per bullet. A bullet that says three things is a paragraph; it won't be applied as a rule.

Examples

Button (base)

  • ✅ Do: Use the most prominent variant available for the single most important action on the page.
  • ✅ Do: Place destructive buttons (delete, remove) at the bottom-right of confirmation dialogs.
  • ❌ Don't: Stack two Primary buttons in the same view.
  • ❌ Don't: Use icon-only buttons without a title or visible label nearby.

Button.destructive (override)

  • ✅ Do: Pair destructive buttons with a confirmation dialog explaining the consequence.
  • ❌ Don't: Use destructive buttons for actions that can be undone — use a regular variant with a toast undo instead.

Why this is the artifact

Most "design system docs" rot because they're prose in a place nobody reads. Application rules in Tostada live next to the component they apply to, render into the same export your AI agents read, and ship as part of the artifact your developers consume. The rule and the component never drift.

Where this lives in code