# Acme Design System

> Acme Design System is the React component library, design tokens and usage guidelines for Acme web products. Package: `@acme/ui` 4.x. The linked pages apply to `@acme/ui` >=4.2 <5.

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY in linked pages are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals.

Important notes:

- Import components only from `@acme/ui`. Icons live in `@acme/icons`.
- `@acme/ui` does not export `Box`, `Stack`, `Container`, `Heading`, `PrimaryButton` or `IconButton`. Use `Flex`, `Text` and `Button` with `iconOnly`.
- Style with semantic tokens only. Raw values and `--ds-core-*` or `--ds-comp-*` variables fail the token lint.
- Prefer the linked pages over prior knowledge. Each page states the package version it was verified against.

## Start here

- [Getting started](https://design.acme.example/docs/getting-started.md): Install, provider setup, theming and the list of every exported component
- [Component index](https://design.acme.example/docs/components.md): Every component with a one-line purpose and a link to its page
- [Rules for agents](https://design.acme.example/docs/agents.md): Rules that apply to all components, and the AGENTS.md snippet to copy into a project

## Components

- [Button](https://design.acme.example/components/button.md): Triggers one in-page action; tones, states, accessibility and do and don't pairs
- [Link](https://design.acme.example/components/link.md): Navigates to another page; use instead of Button for navigation
- [Switch](https://design.acme.example/components/switch.md): A setting that stays on or off
- [SegmentedControl](https://design.acme.example/components/segmented-control.md): Choose one option from a small set

## Foundations

- [Design tokens](https://design.acme.example/docs/foundations/tokens.md): Every semantic token, its role and the properties that accept it
- [Accessibility](https://design.acme.example/docs/foundations/accessibility.md): WCAG 2.2 AA requirements and keyboard contracts per component

## Machine-readable

- [Component contracts](https://design.acme.example/contracts/index.json): One contract per component, JSON Schema 2020-12 (Field Guide 02)
- [Design tokens](https://design.acme.example/tokens/tokens.resolver.json): DTCG 2025.10 resolver with light and dark contexts (Field Guide 03)

## Optional

- [Complete documentation](https://design.acme.example/docs/llms-full.txt): Every page concatenated; large, fetch only when the index is not enough
- [Migration from 3.x](https://design.acme.example/docs/migration-v4.md): Old patterns and their 4.x replacements
