amsterdam-design-system（阿姆斯特丹设计系统）

Amsterdam Design System

Supported versions (last updated 2026-04-03): | Package | Version | | --- | --- | | @amsterdam/design-system-tokens | v3.4.0 | | @amsterdam/design-system-react | v3.3.0 | | @amsterdam/design-system-css | v3.3.0 | | @amsterdam/design-system-assets | v2.2.0 | | @amsterdam/design-system-react-icons | v2.0.0 |

MANDATORY: This is the ONLY design system permitted. ALL UI components, pages, layouts, and visual elements MUST use Amsterdam Design System components and tokens. Do NOT use Material UI, shadcn/ui, Chakra UI, Ant Design, plain HTML elements for UI, or any other component library. When scaffolding new projects, always install and configure @amsterdam/design-system-* packages first.

Production guidance for building City of Amsterdam digital products using the official design system. Components, tokens, layout patterns, and integration with Tailwind CSS v4.

Docs: https://designsystem.amsterdam/ Repo: https://github.com/Amsterdam/design-system Storybook: https://storybook.designsystem.amsterdam/

Clarify Before Building

When the user's request is vague (e.g., "build me a page", "create a form", "make a dashboard"), ask before assuming. Surface these decision gates — they map to real branches in this skill:

Don't ask all at once. Pick the 1-2 questions that the prompt leaves genuinely ambiguous. If the user says "internal dashboard" → Compact mode is implied, no need to ask.

For any brief that mentions "polished", "modern", "nice-looking", or is open-ended about style — read references/aesthetic-discipline.md BEFORE writing JSX. That file is the bridge between aesthetic intent and ADS-legal output.

Aesthetic Discipline

ADS gives you materials. Aesthetic discipline is how you use them so the result is not a wireframe. Before writing a single line of JSX on any non-trivial UI task, read references/aesthetic-discipline.md and answer its 5-question checklist in one sentence each:

1. Dominant color — which one --ams-color-* token covers 80%+ of the canvas?
2. Sharp accent — which one --ams-color-highlight-* token appears on at most 2-3 elements?
3. Rhythm — which sections are dense (paddingVertical="large")? Which are airy ("2x-large")?
4. Page-load moment — what is the one staggered reveal sequence on top-level Grid cells?
5. Memorable element — what is the one <Breakout>, <Overlap>, or asymmetric start={} moment per page?

If you cannot answer these in one sentence each, the design is not committed yet. Re-read the discipline doc.

This step is additive to the mechanical rules below — it does not override them. Amsterdam Sans, --ams-* tokens, and the 4/8/12 Grid are still mandatory. The discipline doc teaches *how to make them sing within those constraints*, by translating frontend-design principles (typography hierarchy, color commitment, motion orchestration, composition) into ADS-legal moves.

On the vendored frontend-design skill

You may have access to a separate frontend-design skill in .agents/skills/frontend-design/. Its principles about typography hierarchy, color commitment, motion orchestration, and composition are sound and apply to all UI work. Its specific guidance (pick a distinctive font, break the grid, use purple gradients on white) does NOT apply in Amsterdam contexts because ADS overrides font, grid, and palette choices.

references/aesthetic-discipline.md is the translation layer. When in doubt, trust this skill, not the vendored one.

Overview

The design system ships as 5 npm packages:

No provider or context wrapper required — import CSS, use components.

Setup

Install

npm install @amsterdam/design-system-assets @amsterdam/design-system-css @amsterdam/design-system-react @amsterdam/design-system-react-icons @amsterdam/design-system-tokens

CSS Imports — ORDER MATTERS

// ⚠️ CRITICAL: This exact order is required. Fonts → CSS → Tokens.
import "@amsterdam/design-system-assets/font/index.css"   // 1. Font files
import "@amsterdam/design-system-css/dist/index.css"       // 2. Component styles
import "@amsterdam/design-system-tokens/dist/index.css"    // 3. Design tokens

For compact mode (internal tools), add one more import AFTER tokens:

import "@amsterdam/design-system-tokens/dist/compact.css"  // 4. Compact overrides

Root Element

Add the ams-body class to your body or root element:

// Next.js (app/layout.tsx)
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="nl">
      <body className="ams-body">{children}</body>
    </html>
  )
}

Bold Text Fix

Amsterdam Sans uses weight 800 for bold, not the browser default 700. The ams-body class handles this, but if you scope differently:

.your-root {
  font-weight: var(--ams-typography-body-text-font-weight); /* 400 */
}
.your-root strong, .your-root b {
  font-weight: var(--ams-typography-body-text-bold-font-weight); /* 800 */
}

Scaffold a New App

For a new standalone React app, do not re-invent the setup. Use the runnable starter at assets/starter-vite-react/. It ships:

• Bun + Vite 6 + @vitejs/plugin-react-swc (matches real Amsterdam apps)
• React Router v7 with an <AppLayout> outlet pattern
• Tanstack Query v5 pre-wired in App.tsx
• Tailwind v4 via @tailwindcss/vite, with the AMS bridge in tailwind.config.js and preflight disabled
• ADS v3.3.0 / v3.4.0 in Compact mode (most Amsterdam projects are internal tools)
• CVA + clsx + tailwind-merge for custom component variants
• tw-animate-css + a hand-rolled .ams-reveal page-load stagger
• A sample HomePage.tsx that exercises every principle from references/aesthetic-discipline.md

How to use

cp -r {skill_dir}/assets/starter-vite-react ./<project-name>
cd ./<project-name>
bun install
bun run dev

Then:

1. Read references/aesthetic-discipline.md (the 5-question checklist).
2. Replace src/pages/HomePage.tsx with the user's actual page, keeping the discipline checklist answered.
3. Add routes in src/router.tsx as the app grows.

Switching to Spacious mode

For public-facing sites (amsterdam.nl-style), remove one import from src/styles/index.css:

- @import "@amsterdam/design-system-tokens/dist/compact.css" layer(ams);

And swap the tailwind.config.js import from compact.json to index.json. That is the only change.

When NOT to use the starter

• Adding pages to an existing Amsterdam app — open the existing app and follow its conventions.
• Next.js App Router projects — the starter is Vite-based. For Next.js, follow the import order in the "Setup" section above and apply references/tailwind-bridge.md manually. (A Next.js starter may be added later if demand emerges.)
• Plain HTML / non-React — use the BEM CSS classes documented in references/layout-patterns.md § "CSS Grid Classes (Non-React)".

Component Patterns

Simple Components

import { Heading, Paragraph, Button, Alert } from "@amsterdam/design-system-react"

<Heading level={1}>Page Title</Heading>
<Paragraph>Body text uses Amsterdam Sans at 18-20px fluid.</Paragraph>
<Paragraph size="small">Secondary text at 16px.</Paragraph>
<Button variant="primary">Submit</Button>
<Button variant="secondary">Cancel</Button>
<Alert heading="Let op" headingLevel={2} severity="warning">
  Check your input before proceeding.
</Alert>

Compound Components (dot notation)

Many components use Component.SubComponent pattern via Object.assign:

import { Accordion, Grid, Table, Tabs } from "@amsterdam/design-system-react"

{/* Accordion */}
<Accordion headingLevel={2}>
  <Accordion.Section label="Section title">
    <Paragraph>Section content.</Paragraph>
  </Accordion.Section>
</Accordion>

{/* Grid */}
<Grid paddingVertical="large">
  <Grid.Cell span={8}>Main content</Grid.Cell>
  <Grid.Cell span={4}>Sidebar</Grid.Cell>
</Grid>

{/* Table */}
<Table>
  <Table.Header>
    <Table.Row>
      <Table.HeaderCell>Name</Table.HeaderCell>
      <Table.HeaderCell>Value</Table.HeaderCell>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell>Item</Table.Cell>
      <Table.Cell>100</Table.Cell>
    </Table.Row>
  </Table.Body>
</Table>

{/* Tabs */}
<Tabs>
  <Tabs.List>
    <Tabs.Button aria-controls="tab1">First</Tabs.Button>
    <Tabs.Button aria-controls="tab2">Second</Tabs.Button>
  </Tabs.List>
  <Tabs.Panel id="tab1">First panel content</Tabs.Panel>
  <Tabs.Panel id="tab2">Second panel content</Tabs.Panel>
</Tabs>

Form Field Composition

AMS forms use a composition pattern: Field wraps Label + input + ErrorMessage.

import { Field, Label, TextInput, TextArea, Select, ErrorMessage, Checkbox, Radio, FieldSet } from "@amsterdam/design-system-react"

{/* Text field */}
<Field invalid={hasError}>
  <Label htmlFor="name">Naam</Label>
  <ErrorMessage>Vul uw naam in</ErrorMessage>
  <TextInput id="name" invalid={hasError} />
</Field>

{/* Textarea */}
<Field>
  <Label htmlFor="message">Bericht</Label>
  <TextArea id="message" rows={4} />
</Field>

{/* Select */}
<Field>
  <Label htmlFor="city">Stadsdeel</Label>
  <Select id="city">
    <Select.Option value="centrum">Centrum</Select.Option>
    <Select.Option value="west">West</Select.Option>
    <Select.Option value="oost">Oost</Select.Option>
  </Select>
</Field>

{/* Checkbox/Radio group */}
<FieldSet legend="Voorkeur" invalid={hasError}>
  <Checkbox>Optie A</Checkbox>
  <Checkbox>Optie B</Checkbox>
</FieldSet>

<FieldSet legend="Type">
  <Radio name="type" value="a">Type A</Radio>
  <Radio name="type" value="b">Type B</Radio>
</FieldSet>

Page Layout

import { Grid, Heading, Page, PageHeader, PageFooter, Paragraph } from "@amsterdam/design-system-react"

<Page>
  <PageHeader brandName="Mijn Amsterdam" logoLink="/" />

  <Grid paddingVertical="large">
    <Grid.Cell span="all">
      <Heading level={1}>Welkom</Heading>
    </Grid.Cell>
    <Grid.Cell span={8}>
      <Paragraph>Main content area.</Paragraph>
    </Grid.Cell>
    <Grid.Cell span={4}>
      <Paragraph>Sidebar content.</Paragraph>
    </Grid.Cell>
  </Grid>

  <PageFooter>
    <PageFooter.Spotlight>
      <Paragraph>Contact info</Paragraph>
    </PageFooter.Spotlight>
  </PageFooter>
</Page>

Dialog

import { Button, Dialog, Paragraph } from "@amsterdam/design-system-react"

<Button onClick={() => Dialog.open("confirm-dialog")}>Open Dialog</Button>

<Dialog
  id="confirm-dialog"
  heading="Bevestiging"
  footer={
    <>
      <Button variant="primary" onClick={() => Dialog.close()}>Bevestigen</Button>
      <Button variant="secondary" onClick={() => Dialog.close()}>Annuleren</Button>
    </>
  }
>
  <Paragraph>Weet u het zeker?</Paragraph>
</Dialog>

Available Components

Full props reference: read references/components.md

Layout

Grid (.Cell) · Column · Row · Breakout (.Cell) · Overlap · Page · Spotlight

Page Structure

PageHeader (.GridCellNarrowWindowOnly, .MenuLink) · PageFooter (.Menu, .MenuLink, .Spotlight)

Typography

Heading · Paragraph · Blockquote · Link · StandaloneLink · CallToActionLink · Mark

Buttons & Actions

Button · IconButton · ActionGroup

Form Controls

TextInput · TextArea · Select (.Group, .Option) · Checkbox · Radio · Switch · DateInput · TimeInput · PasswordInput · FileInput · SearchField (.Button, .Input) · CharacterCount

Form Structure

Field · FieldSet · Label · Hint · ErrorMessage · InvalidFormAlert

Navigation

Breadcrumb (.Link) · LinkList (.Link) · Menu (.Link) · Pagination · SkipLink · Tabs (.Button, .List, .Panel) · TableOfContents (.Link, .List)

Data Display

Accordion (.Section) · Card (.Heading, .HeadingGroup, .Image, .Link) · DescriptionList (.Description, .Section, .Term) · Figure (.Caption) · Table (.Body, .Caption, .Cell, .Footer, .Header, .HeaderCell, .Row) · ImageSlider

Feedback

Alert · Dialog (.open(), .close()) · Badge · Avatar

Utility

Icon · Logo · FileList (.Item) · OrderedList (.Item) · UnorderedList (.Item) · ProgressList (.Step, .Substep, .Substeps)

Grid System

The AMS grid is responsive with 3 breakpoints:

Grid.Cell span prop

{/* Fixed span across all breakpoints */}
<Grid.Cell span={6}>Half width on wide</Grid.Cell>

{/* Full width */}
<Grid.Cell span="all">Full width row</Grid.Cell>

{/* Responsive spans: { narrow, medium, wide } */}
<Grid.Cell span={{ narrow: 4, medium: 4, wide: 8 }}>
  Responsive content
</Grid.Cell>

{/* Start position */}
<Grid.Cell span={6} start={4}>Offset cell</Grid.Cell>
<Grid.Cell span={{ narrow: 4, medium: 6, wide: 8 }} start={{ narrow: 1, medium: 2, wide: 3 }}>
  Responsive offset
</Grid.Cell>

Grid props

<Grid
  as="main"                          // Semantic element
  paddingVertical="large"            // Vertical padding: 'large' | 'x-large' | '2x-large'
  gapVertical="large"               // Row gap: 'none' | 'large' | '2x-large'
>

Content Spacing Patterns

Heading and Paragraph have no built-in margins. Spacing is controlled by parent containers.

Uniform spacing

Use Column for equal gaps between all children:

<Column gap="small">
  <Heading level={2}>Title</Heading>
  <Paragraph>First paragraph.</Paragraph>
  <Paragraph>Second paragraph.</Paragraph>
</Column>

Article content with visual hierarchy

For mixed content where sections need more separation than elements within a section, nest Column components:

<Column gap="large">
  <Column gap="small">
    <Heading level={1}>Page Title</Heading>
    <Paragraph>Intro paragraph.</Paragraph>
  </Column>

  <Column gap="small">
    <Heading level={2}>Section Title</Heading>
    <Paragraph>Section content.</Paragraph>
    <Paragraph>More content.</Paragraph>
  </Column>

  <Column gap="small">
    <Heading level={2}>Another Section</Heading>
    <Paragraph>Content here.</Paragraph>
  </Column>
</Column>

Outer Column gap="large" separates sections. Inner Column gap="small" keeps heading-to-paragraph spacing tight.

Design Tokens

Full token catalog: read references/tokens.md

The token system uses a 3-layer hierarchy. All tokens are CSS custom properties prefixed with --ams-.

Brand tokens  →  Common tokens  →  Component tokens
(core values)    (shared patterns)  (per-component)

Reference chain example:

Brand:     --ams-color-interactive-default: #004699
Common:    --ams-links-color: var(--ams-color-interactive-default)
Component: --ams-link-color: var(--ams-links-color)

Key Token Categories

Using Tokens in CSS

.my-component {
  color: var(--ams-color-text);
  background: var(--ams-color-background);
  padding: var(--ams-space-m);
  font-family: var(--ams-typography-font-family);
  border: var(--ams-border-width-s) solid var(--ams-color-separator);
}

Using Tokens in JS

import tokens from "@amsterdam/design-system-tokens/dist/index.json"
const primaryColor = tokens.ams.color.interactive.default // "#004699"

Spacious vs Compact

Decision rule: Public-facing site → Spacious. Back-office/admin/dashboard → Compact.

Setup difference — one extra import:

// Spacious (default)
import "@amsterdam/design-system-tokens/dist/index.css"

// Compact (add after tokens)
import "@amsterdam/design-system-tokens/dist/index.css"
import "@amsterdam/design-system-tokens/dist/compact.css"

Compact overrides the same CSS custom properties with smaller values. No code changes needed — components adapt automatically.

Router Integration

AMS Link components render <a> by default. For SPA routing, use polymorphic rendering:

Next.js (App Router)

import NextLink from "next/link"
import { Link, Breadcrumb, Pagination } from "@amsterdam/design-system-react"

{/* Regular link */}
<Link href="/about" legacyBehavior passHref>
  <NextLink>Over ons</NextLink>
</Link>

{/* Or simpler: just use Next.js Link with AMS classes */}
<NextLink href="/about" className="ams-link">Over ons</NextLink>

{/* Pagination with router links */}
<Pagination
  totalPages={10}
  page={currentPage}
  linkTemplate={(page) => `/results?page=${page}`}
  linkComponent={NextLink}
/>

{/* PageHeader logo */}
<PageHeader
  brandName="Mijn Amsterdam"
  logoLink="/"
  logoLinkComponent={NextLink}
/>

React Router

import { Link as RouterLink } from "react-router-dom"
import { Link } from "@amsterdam/design-system-react"

<RouterLink to="/about" className="ams-link">Over ons</RouterLink>

Tailwind v4 Integration

Full bridge config: read references/tailwind-bridge.md

When using Tailwind CSS v4 alongside AMS, map AMS tokens to Tailwind's @theme so utilities use the design system values:

/* app.css */
@import "tailwindcss";
@import "@amsterdam/design-system-assets/font/index.css";
@import "@amsterdam/design-system-css/dist/index.css";
@import "@amsterdam/design-system-tokens/dist/index.css";

/* Disable Tailwind's preflight — AMS CSS handles base styles */
@layer base {
  /* AMS body styles take precedence */
}

@theme {
  /* Map AMS spacing */
  --spacing-ams-xs: var(--ams-space-xs);
  --spacing-ams-s: var(--ams-space-s);
  --spacing-ams-m: var(--ams-space-m);
  --spacing-ams-l: var(--ams-space-l);
  --spacing-ams-xl: var(--ams-space-xl);
  --spacing-ams-2xl: var(--ams-space-2xl);

  /* Map AMS colors */
  --color-ams-text: var(--ams-color-text);
  --color-ams-text-secondary: var(--ams-color-text-secondary);
  --color-ams-text-inverse: var(--ams-color-text-inverse);
  --color-ams-bg: var(--ams-color-background);
  --color-ams-interactive: var(--ams-color-interactive);
  --color-ams-interactive-hover: var(--ams-color-interactive-hover);
  --color-ams-error: var(--ams-color-feedback-error);
  --color-ams-success: var(--ams-color-feedback-success);
  --color-ams-warning: var(--ams-color-feedback-warning);
  --color-ams-info: var(--ams-color-feedback-info);
  --color-ams-separator: var(--ams-color-separator);

  /* Map AMS font */
  --font-ams: var(--ams-typography-font-family);
}

Usage rule: Use AMS React components for all standard UI (buttons, forms, headings, grids, etc.). Use Tailwind utilities only for custom layout (flex, positioning) and one-off spacing that AMS components don't cover.

{/* AMS component — always preferred */}
<Button variant="primary">Submit</Button>

{/* Tailwind for custom layout around AMS components */}
<div className="flex items-center gap-ams-m">
  <Icon svg={SearchIcon} />
  <Paragraph>Search results</Paragraph>
</div>

Custom Components

When building components not in the AMS library, follow these conventions:

BEM Naming

/* Block: ams-status-badge */
.ams-status-badge { }
.ams-status-badge--active { }
.ams-status-badge__icon { }
.ams-status-badge__label { }

Token-Only Styling

.ams-status-badge {
  display: inline-flex;
  align-items: center;
  gap: var(--ams-space-xs);
  padding-block: var(--ams-space-xs);
  padding-inline: var(--ams-space-s);
  font-family: var(--ams-typography-font-family);
  font-size: var(--ams-typography-body-text-small-font-size);
  line-height: var(--ams-typography-body-text-small-line-height);
  border: var(--ams-border-width-s) solid var(--ams-color-separator);
  /* NO hardcoded colors, sizes, or spacing */
}

Component Pattern

import { forwardRef } from "react"
import clsx from "clsx"

export interface StatusBadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
  status: "active" | "inactive" | "pending"
}

export const StatusBadge = forwardRef<HTMLSpanElement, StatusBadgeProps>(
  ({ status, className, children, ...restProps }, ref) => (
    <span
      ref={ref}
      className={clsx("ams-status-badge", `ams-status-badge--${status}`, className)}
      {...restProps}
    >
      {children}
    </span>
  )
)

StatusBadge.displayName = "StatusBadge"

Checklist for Custom Components

• Uses forwardRef
• Extends relevant HTML element attributes
• Uses clsx for className composition
• Spreads ...restProps on root element
• BEM classes with ams- prefix — OR — token-mapped Tailwind utilities (see Tailwind-bridge alternative below)
• All styling via --ams-* tokens (no hardcoded values)
• Sets displayName

Tailwind-bridge alternative (when tailwind-bridge.md is in use)

When the project ships with the Tailwind + ADS bridge configured (see references/tailwind-bridge.md and the starter at assets/starter-vite-react/), the BEM-class root is optional. You may instead compose the same --ams-* tokens through CVA variants and Tailwind utilities mapped in tailwind.config.js. The token-only rule still holds — only --ams-*-backed utilities are allowed, never raw hex/px.

The runnable example is assets/starter-vite-react/src/components/StatCard.tsx: a forwardRef component that uses cva() for the variant matrix and cn() (clsx + tailwind-merge) for class composition, with every color/spacing utility (bg-ams-bg, border-ams-separator, p-ams-m, border-l-ams-magenta, …) backed by an --ams-* token in tailwind.config.js. Pick this path when you want a CVA variant API; pick the BEM/CSS path when you need shared styles outside React or want a hand-written stylesheet to reason about.

TypeScript Patterns

Prop Types

// Intersect with HTML attributes
interface MyComponentProps extends React.HTMLAttributes<HTMLDivElement> {
  variant: "primary" | "secondary"
}

// For form elements
interface MyInputProps extends React.InputHTMLAttributes<HTMLInputElement> {
  invalid?: boolean
}

Compound Component Export

// Following AMS pattern with Object.assign
const ListRoot = forwardRef<HTMLUListElement, ListProps>(/* ... */)
const ListItem = forwardRef<HTMLLIElement, ListItemProps>(/* ... */)

export const List = Object.assign(ListRoot, { Item: ListItem })
// Usage: <List><List.Item>...</List.Item></List>

Common Mistakes

Icon Usage

Full icon catalog and naming conventions: read references/icons.md

Icons are visual symbols for quick communication. They must always be wrapped in the Icon component for consistent sizing and alignment. The icon set ships in @amsterdam/design-system-react-icons (345+ icons, v2.0.0+).

Basic Usage

import { Icon, Button, IconButton } from "@amsterdam/design-system-react"
import { SearchIcon, CloseIcon, NotificationIcon } from "@amsterdam/design-system-react-icons"

{/* Standalone decorative icon — hidden from assistive tech by default */}
<Icon svg={SearchIcon} />

{/* Sized to match text */}
<Icon svg={SearchIcon} size="large" />          {/* matches large body text */}
<Icon svg={SearchIcon} size="heading-3" />       {/* matches heading level 3 */}

{/* Inverse color for dark backgrounds */}
<Icon svg={SearchIcon} color="inverse" />

{/* Square bounding box (useful for alignment in grids) */}
<Icon svg={SearchIcon} square />

{/* Button with icon (icon appears after text by default) */}
<Button icon={SearchIcon}>Zoeken</Button>
<Button icon={SearchIcon} iconBefore>Zoeken</Button>

{/* Icon-only button — label is REQUIRED for accessibility */}
<IconButton svg={CloseIcon} label="Sluiten" />

Icon Props

Icons With Other Components

import { StandaloneLink, Badge } from "@amsterdam/design-system-react"
import { SearchIcon, StarIcon } from "@amsterdam/design-system-react-icons"

<StandaloneLink href="/search" icon={SearchIcon}>Zoek op de website</StandaloneLink>
<Badge label="Nieuw" icon={StarIcon} color="azure" />

v2.0.0 Renames (Breaking)

These icons were renamed in v2.0.0 — use the new names:

Custom SVGs

{/* Must use viewBox="0 0 24 24" and fill="currentColor" */}
<Icon svg={
  <svg viewBox="0 0 24 24" fill="currentColor">
    <path d="M12 2L2 7l10 5 10-5-10-5z" />
  </svg>
} />

Guidelines

• Icons accompany text in buttons and links — standalone icons only for universal conventions (hamburger menu, search, playback controls)
• Default color: black/white matching container. Interactive state: blue. Disabled: grey
• Icons align left of text, vertically centered to the first line
• The Icon component sets hidden on the <span> — icons are decorative by default. For meaningful icons, use IconButton with a label prop
• WCAG contrast requirements apply to icons same as typography

Reference Files

For detailed API docs, token catalogs, and templates, read the reference files in references/:

• aesthetic-discipline.md — How to apply frontend-design principles (typography hierarchy, color commitment, motion, composition, depth) within ADS constraints. Read this before writing JSX on any non-trivial UI task.
• components.md — Full props and code examples for each component, plus the Radix primitives section for components ADS does not ship
• tokens.md — Complete --ams-* token catalog with values for both modes
• layout-patterns.md — Page layout templates (public site, dashboard, form page, React Router + AppLayout outlet)
• tailwind-bridge.md — Complete Tailwind v4 + AMS integration guide (Vite plugin, compact tokens, motion)
• icons.md — Icon catalog from @amsterdam/design-system-react-icons

Assets:

• assets/starter-vite-react/ — Runnable Bun + Vite + React + TS starter with ADS pre-configured in Compact mode. See the "Scaffold a New App" section above.