Design rules schema

Two related types live in src/principles/types.ts and src/principles/componentRules.ts.

DesignRules — the navigation hierarchy

interface DesignRules {
  primaryNav:         'left-rail' | 'top-bar' | 'hybrid'
  navCollapseBelow:   'mobile' | 'tablet' | 'desktop' | 'never'
  bottomNavOnMobile:  boolean
  mobileBreakpoint:   number              // px
  tabletBreakpoint:   number              // px
  desktopBreakpoint:  number              // px
  showBreadcrumbsOn:  string              // CSV of layout kinds (e.g. 'detail,docs')
  focusOrder:         'logical-dom' | 'visual'
  notes:              string              // free-form Markdown
}

One DesignRules object exists per library. All fields are required (defaults are applied on first run); editing happens in Library → Properties → Navigation hierarchy.

showBreadcrumbsOn format

A comma-separated list of layout variant names. Spaces around commas are stripped on commit. Example:

detail, docs, settings

means breadcrumbs are visible on detail, docs, and settings layouts only.

ComponentRules — per-component application rules

interface ComponentRuleSet {
  do:    string[]
  dont:  string[]
  notes: string
}

interface ComponentRules {
  base?:        ComponentRuleSet                        // applied to all variants
  perVariant?:  Record<string, ComponentRuleSet>        // keyed by `${axis}:${value}`
}

The library stores a Record<string, ComponentRules> keyed by component name (e.g. "button", "alert", "badge"). Authoring happens in Library → Components → Application Rules.

perVariant keys

The key is axis:value, where the axis is the CVA variant axis (typically variant or size):

{
  base: { do: [...], dont: [...], notes: '...' },
  perVariant: {
    'variant:destructive': { do: [...], dont: [...], notes: '...' },
    'variant:outline':     { do: [...], dont: [...], notes: '...' },
  }
}

When a variant has its own ruleset, it replaces the base for that variant — no merge.

Defaults

Seeded for 43 components in src/principles/defaultComponentRules.ts. The editor surfaces defaults the same way as user-authored rules.

How they ship in the export

design-system.md includes a ## Navigation hierarchy section that renders the DesignRules object, and a ### <Component> sub-section per component under a ## Components section that renders the application rules.

design-system.json includes both objects under their respective keys (designRules and componentRules).