Skip to main content
UDSUrban Design SystemBuild a multi-component HTML demoSITE 2026.06.10.1
Color
Brand
Font
Scale
Density

About UDS

What UDS is, what this site is for, how a component goes from idea to production, and the terminology you'll encounter along the way.

Purpose

paletteThe design system

Urban Design System (UDS)

A coherent, themable design system shared across our products. UDS ships in two layers: tokens (semantic CSS custom properties for colors, spacing, type, borders, shadows) and components (framework-agnostic web components in Storybook). One codebase, one design language, multiple brands (Base, ResMan, AnyoneHome, Inhabit) and color schemes (light, dark) — adapted automatically via data-* attributes.

  • Designers get a consistent visual language, locked-in tokens, and ready-made components — no more bespoke buttons per project.
  • Developers get framework-agnostic web components and a stable token API. Use them in React, Vue, Svelte, Angular, or vanilla.
  • Product / brand teams get cross-brand consistency with single-attribute theming.
menu_bookThis site

UDS Documentation Site

The design specification layer of UDS — where designers author the contract that developers implement. Every component has a structured JSON spec (uds/components/<id>/spec.json) that defines props, events, slots, states, accessibility, and acceptance criteria. The doc site renders that spec as Guidelines, plus visual examples and an interactive playground.

  • Designers author specs here and confirm visual examples match Figma.
  • Developers read specs here and ship 1:1 implementations to Storybook.
  • PMs / stakeholders track component status, spec completeness, and changelog history.
Example code only
Production framework code lives in the UDS Storybook — see Getting Started.

Component Lifecycle

From "we need a thing" to "an app uses it in production". Every UDS component flows through these six phases.

  1. 1

    Propose

    personAnyone

    A need is identified — designer, developer, or PM starts a Figma page for the component with the red Exploration prefix and notes what problem it solves. See the Design Process page for the full stoplight flow.

    design_servicesFigma — UDS Components (Red)Proposed
  2. 2

    Design

    brushDesigner

    Designer builds variants and states in the UDS Components Figma file. Page name gets the orange dot prefix while in progress.

    design_servicesFigma — UDS ComponentsIn Progress
  3. 3

    Spec

    brushDesigner

    Designer writes the structured spec in uds/components/<id>/spec.json — description, when-to-use, props, events, slots, states, accessibility. The Guidelines tab on the doc site auto-renders from this file. Use the new-component skill to scaffold.

    data_objectuds/components/<id>/spec.jsonSpec building
  4. 4

    Build

    codeDeveloper

    Developer implements the spec 1:1 as a framework-agnostic web component in Storybook. Acceptance criteria from the JSON drive the work.

    auto_awesomeStorybookIn Review
  5. 5

    Ship

    groupsDesigner + Developer

    Spec audit (run the spec-audit subagent), accessibility review, visual review against Figma. Status moves to Production Ready, doc site bumps the UDS version, Figma release notes are updated.

    verifiedDoc site + Figma + StorybookProduction Ready
  6. 6

    Use

    codeProduct teams

    Product apps import the UDS CSS bundle for tokens and register the Web Components. The component appears in real products. Bug reports and enhancement requests flow back via the Report Issue button on each component page.

    rocket_launchProduction appsLive
Three sources of truth
Figma is the visual source. This doc site (specifically the uds/components/<id>/spec.json files) is the design spec. Storybook is the implementation. They stay in sync via the release workflow.

Glossary

UDS terminology. Use this when you encounter a term and aren't sure what it means.

Primitive token
A raw token value (e.g. --uds-primitive-color-blue-500: #1f6df0). Never used directly in component code — primitives feed into semantic tokens.
Semantic token
A purpose-named token (e.g. --uds-color-text-primary). These are what you use in components. Their values change with theme/mode.
Variant
A distinct visual or behavioral type of a component (e.g. primary / secondary / ghost button variants). Defined as data-* attributes or modifier classes.
State
An interactive condition (default, hover, active, focus, disabled, error, loading, empty). Different from variants — a button can be in any state regardless of variant.
Mode
A token-set switch (e.g. light vs dark color scheme). Controlled by data-color-scheme on <html>.
Theme
A brand-level token override (Base, ResMan, AnyoneHome, Inhabit). Controlled by data-theme on <html>.
Density
Compactness of UI (compact vs comfortable). Controlled by data-density.
Font scale
Global type-size multiplier (smaller / default / larger). Controlled by data-font-scale.
Text style
A predefined typographic role (e.g. uds-text-heading-xl, uds-text-paragraph-base). Composes font-size + line-height + weight in one class.
Surface
A semantic background-color token (page, main, subtle, alt, etc.). Controls the depth/hierarchy of stacked panels.
Slot
A named content region inside a component (e.g. Dialog has header / body / footer slots). The Storybook web component must support these.
Prop / Attribute
An input value the Storybook web component should accept (e.g. variant="primary", disabled).
Event
A custom event the Storybook web component should dispatch (e.g. change, dismiss, select).
Stoplight status
The component readiness indicator: Placeholder → Blocked → In Progress → In Review → Production Ready → Deprecated.
Spec completeness
How filled-in this component's uds/components/<id>/spec.json file is. Different from production status — a Production-Ready component might still have an incomplete written spec.