Agent-consumable brand guide

VLLNT UI Design Guide

The canonical rules for brand, tokens, layout, motion, accessibility, and component composition across the library.

DESIGN.md

Single source of truth for VLLNT UI's brand and design conventions. Humans read this file. Agents read it too — every UI suggestion must follow it.

This is the canonical brand & design guideline for the library. Read it on the web at three public surfaces, all generated from this one file:

  • /DESIGN.md — this file as raw markdown (canonical for agents).
  • /design — human-browsable rendering with a contents nav.
  • /r/design.json — machine-readable token set.

The full token set lives in packages/design/tokens.json and is documented in packages/design/README.md.


1. Brand

AttributeValue
NameVLLNT UI (always two words, both capitalised)
VoiceDirect. No marketing fluff. Short sentences.
MissionAgent-first React components — copy-paste, you own them.
ToneConfident, technical, honest about tradeoffs.

Voice rules

  • Sentence case for headings, button labels, tooltips. Title Case only for proper nouns.
  • Avoid superlatives ("the best", "blazingly fast"). State facts.
  • Avoid em-dash chains. One per sentence max.
  • Use … (ellipsis glyph), not ....
  • No emoji in shipped UI. Lucide icons handle anything visual.

Banned phrases

  • "Click here"
  • "Submit" as a button label (use the verb of the action)
  • "Loading…" without a context noun ("Loading components…")
  • "Sign up to learn more"

VLLNT UI set in the system font stack at the brand weight. There is no standalone wordmark file; the type itself is the mark.

Clear space — at minimum, height of the cap-height of the logotype. Min size — 14px equivalent. Below that, omit "UI" and show only "VLLNT". Misuse — never stretch, recolor, italicise, or add a tagline beneath.


3. Color

Tokens live as CSS variables in packages/ui/themes/default.css. Components always consume tokens — never raw hex. The token set is versioned with the library.

Machine clients use packages/design/tokens.json. The JSON schema is documented in packages/design/tokens.schema.json and groups tokens by color, typography, spacing, radius, elevation, motion, and iconography.

Semantic tokens (consumer-facing)

Values are OKLCH channels; the sRGB hex is what renders on an sRGB display.

TokenRoleLightDark
--backgroundPage surface1 0 0 (#ffffff)0 0 0 (#000000)
--foregroundPrimary text0.1445 0 0 (#0a0a0a)0.9848 0 0 (#fafafa)
--card / --popoverContained / floating surface1 0 0 (#ffffff)0.1445 0 0 (#0a0a0a)
--mutedSubtle surface (--secondary and --accent share it)0.9703 0 0 (#f5f5f5)0.2686 0 0 (#262626)
--muted-foregroundSecondary text0.525 0 0 (#6a6a6a)0.7153 0 0 (#a3a3a3)
--destructiveDanger fill and danger text0.55 0.2078 25.326 (#cf1f29)0.7 0.18 25.721 (#fa6961)
--destructive-foregroundText on a destructive fill0.9848 0 0 (#fafafa)0.2044 0 0 (#171717)
--successSuccess fill and success text0.5 0.11 155 (#1e7546)0.78 0.16 155 (#4ed589)
--warningCaution fill and caution text0.5 0.085 70 (#825a27)0.82 0.15 85 (#f0bb3b)
--infoInformational fill and text0.5 0.15 255 (#1762b6)0.74 0.12 245 (#65b2f1)
--success-foreground / --warning-foreground / --info-foregroundText on that fill (same pairing as destructive)0.9848 0 0 (#fafafa)0.2044 0 0 (#171717)
--diff-added / --diff-removedAdded / removed line surfaces; --foreground is the text on them0.94 0.04 150 (#d9f3dd) / 0.94 0.03 25 (#ffe4e1)0.26 0.05 150 (#102b17) / 0.26 0.055 25 (#3b1816)
--borderDecorative hairline (cards, separators, tables)0.9219 0 0 (#e5e5e5)0.2686 0 0 (#262626)
--inputForm-control boundary0.66 0 0 (#929292)0.49 0 0 (#606060)
--ringFocus ring0.1445 0 0 (#0a0a0a)0.8697 0 0 (#d4d4d4)

In dark mode --destructive is a light red paired with a dark --destructive-foreground (the shadcn v4 pairing). One dark red cannot be both readable text on a near-black surface and a fill behind white text.

Anti-patterns

  • Never use bg-black / text-white / bg-white. Use bg-background / bg-foreground / text-foreground so dark mode works.
  • Never use bg-gray-500 / Tailwind palette literals. Pick a semantic token.
  • Pure black (#000) is banned for backgrounds — use --background.

Contrast

WCAG 2.2 AA minimum: text ≥ 4.5:1 (large text ≥ 3:1), non-text UI such as control boundaries and focus rings ≥ 3:1. The token contract below holds for the default theme, every preset in themes/presets.css and the product themes in themes/products.css, in light and dark. The status and diff rows hold for the default theme and the product themes, which own those roles. Tests enforce it and fail on any regression: packages/ui/src/lib/theme-contrast.test.ts (web CSS) and packages/ui-core/src/theme.test.ts (native theme and product themes).

RulePairsMinimum
On-surface textX-foreground on X for background, card, popover, primary, secondary, accent, destructive, success, warning, info4.5:1
Secondary text--muted-foreground on background, card, popover, muted4.5:1
Danger text--destructive on background, card, popover, muted, and on its own 10% tint (bg-destructive/10)4.5:1
Status text--success, --warning, --info on background, card, popover, muted, and on their own 10% tint4.5:1
Diff text--foreground on --diff-added and --diff-removed4.5:1
Control boundary--input against background, card, popover3:1
Focus ring--ring against background3:1

Default theme ratios: muted-foreground 5.41 (light, on background) / 4.96 (light, on muted), 6.00 (dark, on muted); destructive text 5.41 / 4.96 (light), 7.26 / 5.23 (dark, on background / muted); destructive-foreground on destructive 5.18 (light), 6.20 (dark); input 3.11 (light), 3.34 (dark, on background); success / warning / info text on muted 5.22 / 5.60 / 5.57 (light), 8.07 / 8.56 / 6.62 (dark), and on their 10% tint 4.95 / 5.33 / 5.24 (light); success / warning / info foreground on its fill 5.46 / 5.85 / 5.82 (light), 9.56 / 10.14 / 7.85 (dark); foreground on diff-added / diff-removed 16.80 / 16.44 (light), 14.58 / 15.15 (dark).

Rules

  • Draw form-control boundaries (input, textarea, select trigger, checkbox, switch off-track, composers) with border-input, never border / border-border. --border is decorative and stays low contrast.
  • Text on bg-primary / bg-secondary / bg-accent / bg-destructive / bg-success / bg-warning / bg-info uses that surface's *-foreground. --muted-foreground is only guaranteed on background, card, popover, and muted.
  • Put light text on a destructive fill with text-destructive-foreground, never text-white: dark mode pairs a light red with dark text.
  • New themes and presets must pass the contract test before merging. Keep new values inside the sRGB gamut so the measured ratio matches what renders.
  • Hand-written presets in themes/presets.css do not define the status or diff roles; they inherit the default theme's. On five presets (dracula, synthwave, nord, claude, dusk) those inherited tones fall below 4.5:1 on some preset surfaces, so use the status roles with a preset only after checking the pair (tracked in #579). Product themes define every role. The theme switcher and useThemePreset do not know the product themes yet (also #579).

Product themes

A product theme is a named override layer on the core tokens, authored in the themes block of packages/design/tokens.json. It overrides existing roles (colors per mode, fonts, type steps, --radius); it never adds product-specific role names to the core. Apply one with data-theme on <html>; the dark class still picks the mode. themes/products.css is generated, so edit tokens.json and run pnpm tokens:generate.

Themedata-themeIdentity
MaiamaiaPink --primary (#BE148B light, #F46CBF dark) on white / black, Figtree + JetBrains Mono, tighter scale, radius sm 6 / md 8 / lg 12 / xl 16
PaaSpaasCore neutrals and status tones, JetBrains Mono for sans, display and mono. Dark is the design default; light works too. No accent: --primary stays the core neutral

Maia's palette comes from a Penpot export kept for review in packages/design/sources/ (the generator never reads it). Its product-specific names map onto core roles:

Maia tokenCore role
accent--primary (and --primary-foreground from accent-foreground)
muted--muted; core --accent is the same subtle surface
muted-foreground, status.planned, state.idle--muted-foreground
surface-raised--card and --popover
status.implemented, state.done--success
status.candidate, state.running--info
status.deprecated, state.attention--warning
status.unsupported, state.failed--destructive
diff.added, diff.removed--diff-added, --diff-removed
background, foreground, border, inputsame-named roles

Status foregrounds are not in the export: Maia uses white on its light fills and black on its dark fills. --secondary, --secondary-foreground and --ring inherit the core values.

On the web, --radius carries a theme's md step only, because Tailwind derives rounded-sm and rounded-lg from it (--radius minus 4px / 2px). Maia's full radius scale ships in the @vllnt/ui-core outputs (productThemes, tamaguiTokens) and the Penpot token sets.

Other outputs from the same source, drift-checked by pnpm tokens:check:

OutputPathFor
Product theme CSSpackages/ui/themes/products.cssWeb (@vllnt/ui/themes/products.css)
Theme objectsproductThemes, tamaguiTokens, tamaguiThemes in @vllnt/ui-coreNative; plain objects, no Tamagui dependency: tamaguiTokens is the input for createTokens, tamaguiThemes (keyed maia_dark, paas_light) the themes input for createTamagui({ themes })
Penpot token setspackages/design/generated/penpot-tokens.jsonPenpot import: sets vllnt/core, vllnt/<theme>/<mode>, plus themes and set order

4. Typography

Font families — theme-overridable CSS variables. A brand adopts a different type identity by overriding these on a theme scope; nothing in the library is edited.

FamilyCSS variableDefaultRole
Sans--font-sansInter, then the system sans stackBody + UI text (Text, Prose)
Display--font-displayvar(--font-sans)Headings + hero (Heading, Display) — set a serif/display face here for a brand identity
Mono--font-monoJetBrains Mono, then the system mono stackCode, tabular

Type scale — each step is a token (--font-size-*); heading/display weight is a token too (--font-weight-heading, --font-weight-display). Overriding any of these restyles the foundation primitives.

TokenCSS variableSizeWeightLine height
Display--font-size-display3.75rem (60px)600 (--font-weight-display)1.05
H1--font-size-h13rem (48px)600 (--font-weight-heading)1.1
H2--font-size-h22.25rem (36px)6001.2
H3--font-size-h31.875rem (30px)6001.25
H4--font-size-h41.5rem (24px)6001.3
H5--font-size-h51.25rem (20px)6001.4
H6--font-size-h61.125rem (18px)6001.5
Body large--font-size-body-lg1.125rem (18px)4001.7
Body--font-size-body1rem (16px)4001.6
Body small--font-size-body-sm0.875rem (14px)4001.5
Caption--font-size-caption0.75rem (12px)5001.4
Label--font-size-label0.75rem (12px)600 (--font-weight-label)1.4
Codeinheritinherit400 mono1.5

Product themes override these steps. Maia sets Display 28/700, H5 20/600, H6 15/600, Body 14/400, Body small 13/400, Caption 12/500 and Label 11/700; its Mono 12/400 is font-mono at the Caption size with the body weight. Maia's Display weight (700) and Label weight (700) are theme-level exceptions to the rule below; core stays at 600. Maia's Label is set in capitals in the design; the tokens carry no text-transform role (a theme cannot add roles), so add uppercase where the Label step is used. Steps a theme does not set (H1 to H4, Body large) keep the core size.

Rules

  • The Text / Heading / Display / Prose foundation primitives consume the tokens above — style them by overriding tokens, not by forking the components.
  • Headings use font-semibold (600), never font-bold (700+) at display sizes — letter shapes crush. The heading weight token defaults to 600.
  • Code uses the core mono stack (JetBrains Mono, then the system mono stack) via font-mono.
  • Tabular numerals for data tables, charts, transactions: font-variant-numeric: tabular-nums.

5. Spacing

4-pt scale. Tailwind classes map 1:1.

TokenValueUse
space-14pxIcon padding
space-28pxTight stack, inline gap
space-312pxComfortable inline gap
space-416pxDefault block stack
space-520pxRoomy inline gap, dense card padding
space-624pxSection break
space-832pxMajor section
space-1040pxLarge control height, loose section break
space-1248pxPage section
space-1664pxHero / landing block

Rules

  • Stay on the scale. Never gap-[7px] etc.
  • One axis at a time on flex children — use gap-y-N or gap-x-N, not gap-N when only one axis is needed.

6. Radius

TokenValue
radius-none0
radius-sm4px
radius-md8px (default)
radius-lg12px
radius-xl16px
radius-full9999px

Cards, popovers, dialogs use radius-md. Pills, avatars use radius-full. Long surfaces (panels, sheets) use radius-lg.


7. Elevation

Use sparingly. Most components are flat with border + bg-background.

TokenValue
shadow-nonenone
shadow-sm0 1px 2px rgba(0,0,0,0.05)
shadow-md0 4px 6px -1px rgba(0,0,0,0.1)
shadow-lg0 10px 15px -3px rgba(0,0,0,0.1) (popovers, dialogs)

No coloured shadows. No multi-layered glow effects.


8. Motion

Principles

  1. Purposeful — every animation must explain a state change. No decoration.
  2. Fast — under 200ms unless the motion communicates distance or volume.
  3. Subtle — translate < 8px, scale ±2%. No bounces (spring easings strip fidelity at small distances).
TokenDurationEasingUse
duration-fast100msease-outMicro-interactions (button press)
duration-base200msease-outOpen / close, hover, focus
duration-slow300msease-in-outLayout shifts, modal entry

prefers-reduced-motion — when reduce, durations collapse to 1ms or motion is skipped entirely.

Banned

  • Bounce easings (cubic-bezier(0.68, -0.55, 0.265, 1.55)).
  • Auto-playing entrance animations on initial page load (jarring).
  • animation: spin on anything except a true loading spinner.

9. Iconography

  • Library: lucide-react (only). Match its line-art aesthetic.
  • Default size: 16px (h-4 w-4).
  • Stroke: 2px (lucide default).
  • Color: inherits currentColor. Don't hardcode.
  • Spacing: 8px (gap-2) between icon and adjacent text.

10. Component patterns

UsePattern
Inline actionButton
Single binary choiceSwitch
One of NSelect (≤ 8 options) or Combobox (> 8 / searchable)
Many of NMultiSelect
Free textInput (single line) or Textarea
ConfirmationAlertDialog (destructive) or Dialog (informational)
Side panelSheet
Hover helpTooltip (≤ 80 chars)
Stepper / wizardStepper + MultiStepForm
Tabular dataDataTable
Hierarchical dataTreeView
Status chipBadge
Notification (transient)Toast
Notification (persistent)Banner
Empty stateEmptyState

Anti-patterns

  • <div onClick> — always use Button for click semantics.
  • Tooltips on disabled buttons — wrap in a <span> with aria-disabled instead, since browsers swallow events on disabled elements.
  • Modal-on-modal — restructure the flow.
  • Polymorphic children + items props on the same component — pick one.

11. Accessibility (WCAG AA minimum)

  • Every interactive element is keyboard-reachable.
  • Focus rings visible (--ring token), never outline-none without a replacement.
  • Form inputs always labelled (<label> or aria-label).
  • Live regions for async state changes (aria-live="polite" for toasts, assertive for errors).
  • Color is never the only signal — pair with icon, text, or pattern.
  • Animations respect prefers-reduced-motion.
  • Components shipping a defined ARIA pattern (combobox, dialog, menu, tabs) declare their full keyboard map in meta.json per #255.

12. Voice & writing

  • Buttons: name the action. "Save changes" not "Submit", "Send invite" not "OK".
  • Errors: state what happened + what to do. "Couldn't reach the API. Check your connection and retry."
  • Empty states: explain why empty + what unblocks the user. "No components match. Try a different filter or request a component."
  • Inputs: placeholder = example, label = field meaning. They are not interchangeable.
  • Don't hide failures. If something fails silently, you have a bug.

13. Anti-patterns (banned)

PatternWhy banned
font-bold on display headingsCrushes letter shapes; use font-semibold
bg-black / bg-whiteBreaks dark mode; use bg-background / bg-foreground
Tailwind palette literals (bg-zinc-500)Bypasses tokens; breaks theming
Bounce easingsVisual noise; doesn't scale to small distances
<div> with onClickLoses keyboard + a11y semantics; use Button
Em-dash chains in copy (3+ in a row)Unreadable
Submit / OK / Click here button labelsDon't name the action
Pure black backgroundsEye strain in dark mode
Auto-play hero videoPerformance + motion sensitivity
Modal on modalRestructure the flow
eslint-disable to bypass a ruleFix the root cause

14. Surfaces and roadmap

This document is the v1 brand baseline for VLLNT UI. It ships on these surfaces today:

  • /DESIGN.md — this file as raw markdown.
  • /design — human-browsable rendering with a contents nav.
  • /r/design.json — JSON token set, mirroring packages/design/tokens.json.

Still planned:

  • Live token previews inline on the /design page.
  • meta.json a11y schemas per component (#255) — keyboard / ARIA / focus rules surfaced via the registry.

15. References