Velvet Runtime Notes

Semantic tokens keep your UI stable while the brand evolves.

Instead of hard-coding one-off colors in components, shape a small set of variables and map all surfaces to those variables.

Why this matters

• You can restyle the app in minutes instead of days
• Light and dark themes stay behaviorally consistent
• Add-on pages inherit your visual identity by default

Token-to-component mapping

Token	Typical usage
--surface	Card backgrounds
--line	Borders and separators
--lagoon-deep	Links and active nav

Keep the mapping documented and your team will make fewer ad-hoc styling calls.

Example: deriving UI from semantic tokens

const button = {
  color: 'var(--sea-ink)',
  background: 'var(--surface)',
  borderColor: 'var(--line)',
}

MDX is useful here because you can interleave narrative, tables, code blocks, and custom JSX components in one authoring surface.