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

Getting Started

UDS (Urban Design System) ships in two layers: tokens (semantic CSS custom properties) and components (framework-agnostic web components in Storybook). Tokens drop into any stack via uds.css; components register once and work in React, Vue, Svelte, Angular, or vanilla. The doc site is the design specification — all code shown is example-only.

How it works

download 1. Get the files

Import the UDS CSS bundle for tokens, then register the Web Components package once at app startup.

link 2. Add to your project

Use @uds/web-components in any framework, or @uds/react when your app is React.

content_copy 3. Copy & paste

Use the Web Component tags as the public API. Current class-based examples stay in place only until cutover.

Download

The current bundle contains the token CSS and legacy component payload. The Web Components package is being built beside it for the public API cutover.

Or, if your team uses a shared repo, copy the uds/ folder directly into your project.

npm

Install the Web Component package for framework-agnostic components, or add the React wrapper package when your app is React.

shell
# Once the package is published
npm install @uds/web-components @uds/react
js
// In your entry file (main.jsx, main.js, etc.)
import './uds/uds.css';
import { registerUdsComponents } from '@uds/web-components';

registerUdsComponents();

The Web Component package is being built beside the current docs examples. Every documented component now has an initial tag and React wrapper; the current component pages stay on the existing examples until examples, playgrounds, and deeper complex-component behavior are ready for the full cutover.

CDN

Add the UDS token CSS to any page. Component registration will move to the Web Components bundle at cutover.

html
<!-- Tokens (themes + spacing + typography) -->
<link rel="stylesheet" href="https://udsdocs.com/uds/uds.css" />

<!-- Web Components bundle (defines <udc-*> custom elements) -->
<script type="module" src="https://udsdocs.com/web-components.js"></script>

Pin to a specific version:

html
<link rel="stylesheet" href="https://udsdocs.com/versions/0.2/uds/uds.css" />

AI Assist

Using Cursor or another AI coding tool? Download the UDS rule file and drop it in your project.

text
your-project/.cursor/rules/uds-design-system.mdc
The rule tells your AI to use UDS tokens and components automatically. See the AI Assist page for details and downloads.

File Structure

You can import uds.css for the full bundle, or cherry-pick individual token and component files.

text
uds/
├── uds.css              ← token entrypoint (imports tokens/*.css)
├── tokens/
│   ├── primitives.css   ← raw color palette
│   ├── semantic.css     ← themed color, spacing, font tokens
│   ├── layers.css       ← z-index + elevation tokens
│   └── text-styles.css  ← typography utility classes
└── components/
    ├── button/
    │   ├── spec.json               ← Guidelines data
    │   ├── impl.json               ← Code-tab reference data
    │   ├── playground.js           ← interactive playground config
    │   └── examples/*.html         ← example markup
    └── ...

web-components.js        ← defines every <udc-*> custom element
                           (component CSS lives inside shadow DOM)

Two Layers

UDS ships in two layers. Use both, or just the tokens layer when you only need foundations.

1. Tokens (CSS only)

Semantic CSS custom properties for colors, spacing, type, borders, and shadows. Drop the stylesheet in any project — the icon font is a separate link.

html
<head>
  <!-- Material Symbols icon font (required for icons) -->
  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200" />

  <!-- UDS tokens + base styles -->
  <link rel="stylesheet" href="uds/uds.css" />
</head>

2. Components — Web Components

The replacement component API is framework-agnostic Web Components. Register them once at app entry, then use the tags in any framework — React, Vue, Svelte, Angular, or plain HTML.

js
// app entry (any framework)
import './uds/uds.css';
import { registerUdsComponents } from '@uds/web-components';

registerUdsComponents();
html
<!-- Then in any framework's template -->
<udc-button variant="primary">Save</udc-button>
<udc-text-input label="Full name" helper-text="First and last name required"></udc-text-input>

This package is landing in parallel with the current docs. Wait for the public cutover before replacing every class-based example in product guidance.

2b. React wrappers

React apps should use the wrapper package. It renders the same Web Components and provides React-friendly prop and event names.

tsx
import { UdsButton, UdsTextInput } from '@uds/react';

export function ProfileForm() {
  return (
    <>
      <UdsTextInput label="Full name" helperText="First and last name required" />
      <UdsButton variant="primary">Save</UdsButton>
    </>
  );
}

2c. Current docs examples

Component pages still show the current class-based examples while the Web Component set is incomplete. Those examples remain useful for design review, but they are no longer the target public API.

html
<link rel="stylesheet" href="uds/uds.css" />
<script type="module" src="path/to/register-uds-components.js"></script>

<udc-button variant="primary">Save changes</udc-button>

Using the Docs

Each component page in the sidebar has everything you need to spec the component:

TabWhat you'll find
ExamplesLive previews with a "Show code" toggle. Data-consuming components (Data Table, List, Dropdown, Search, Breadcrumb) include realistic data examples (tiny / large / long-content / empty / loading)
CodeCurrent HTML/CSS examples showing the design intent. For production framework code, use the Web Component package once the matching component has landed.
GuidelinesFull handoff spec: when to use, acceptance criteria, props, events, slots, states, accessibility, ownership. Auto-rendered from uds/components/<component>/spec.json
ChangelogPer-component release history
PlaygroundInteractive sandbox — configure variants and states to see the markup the spec implies

Hit / or ⌘K anywhere to open the global token search.

Theming

UDS supports multiple themes via data-* attributes on the <html> element. Set them to switch color schemes, brands, fonts, and density at runtime — no rebuild needed.

html
<!-- Light mode (default — no attributes needed) -->
<html>

<!-- Dark mode -->
<html data-color-scheme="dark">

<!-- Brand override -->
<html data-theme="resman">

<!-- Combine multiple -->
<html data-color-scheme="dark" data-theme="anyonehome" data-font="poppins">

Available theme attributes

AttributeValuesEffect
data-color-schemedarkDark mode (light is default)
data-themeresman, anyonehome, inhabitBrand accent colors
data-fontpoppins, roboto, lexendFont family override
data-font-scalesmaller, largerGlobal font size scale
data-densitycomfortableRelaxed spacing

Try these live using the appearance bar at the top of this site.