Design principles

The token and class names are the design intent — match the meaning of the content to the name instead of picking by how something looks. success = positive/confirmation, warning = caution, error/danger = failure or destructive, info = neutral notice and focus, accents-brand = the product’s own accent. mains steps primary → quaternary from most to least important; surfaces name elevation; typography classes name role. The rules below are the guardrails; choosing the semantically-correct token is the goal.

If a component exists for the element, use its classes — never rebuild it from utilities, and never override a component’s size or colors with utilities (pick the proper variant instead). Utilities are for layout only: flex, grid, gap, spacing, max-width.

Nothing renders below the xs token (12px) — even Overline is 12px; there is no 11px in the scale. At 12px, prefer the semantic class over a raw size: vt-caption for fine print, vt-text-overline for uppercase eyebrows, vt-section-label for group labels.

Paddings, margins, gaps and sizes come from the spacing scale only. No arbitrary pixel values — if a step feels missing, snap to the nearest one. Rhythm: mt-8 between page sections, gap-4–6 between cards, gap-2–3 inside groups.

No hex, no rgb, no inline styles. Interactive and accent elements use accents-brand; blue info-* is reserved for informational states and focus. Surfaces follow the hierarchy (background → surface → subtle → moderate) so dark mode works automatically. Text steps down mains-primary → secondary → tertiary → quaternary; intent colors only mean their state.

Corner radii come from the radius scale. When a rounded element sits inside a rounded container, prefer inner radius = parent radius − padding so the corners run parallel (vt-rounded-concentric-3 inside a p-3 card). An aesthetic guideline, not a law — skip it when it fights the layout.

Full screens start from a pattern, the way a designer starts from a known layout: content column max-w-5xl px-6 py-8, app header h-16, sidebar with section labels. The examples gallery is the pattern library — the MCP server serves the same skeletons to AI via list_patterns / get_pattern.

Every list, table and board gets an empty state (icon, one line, primary action). Loading is a skeleton shaped like the content. Long text truncates. Destructive actions confirm via dialog. One primary button per view.

Sentence case everywhere — buttons, labels, headings. No lorem ipsum: realistic names, dates, sizes and trends. Labels are one to three words. No exclamation marks.

Focus states stay. Icon-only controls carry an aria-label. Images get meaningful alt text. Text/surface pairs from the color hierarchy keep contrast at AA.