# Token Contract Audit Use when adding a new component, modifying an existing component's CSS, or investigating why a component misrenders under a theme. --- ## The Component Token Contract (mandatory) Spec: `.claude/docs/specs/component-token-contract.md` (live source of truth, if this doc contradicts that one, the spec wins; patch this skill). Every component's `.css` file must follow the **two-block @scope** pattern: ```css /* Block 1: token declarations on :where(:scope), zero specificity */ @scope (my-component-ui) { :where(:scope) { --my-bg: var(--a-bg); --my-text: var(--a-fg); --my-radius: var(--a-radius-md); } } /* Block 2: styles using those tokens on :scope */ @scope (my-component-ui) { :scope { background: var(--my-bg); color: var(--my-text); border-radius: var(--my-radius); } /* Variants override TOKENS, not base styles */ :scope[variant="danger"] { --my-bg: var(--a-danger-bg); --my-text: var(--a-danger-fg); } } ``` ### `@scope` donor selectors must be tag-independent when a component can swap its own rendered tag (ADR-0102, 2026-09-01) A `@scope (my-component-ui)` donor selector matches by **literal tag name**. That's a live gap for any component whose own contract lets it render as a different tag than its own custom-element name, `text-ui` already did this coincidentally (`variant="body"` → `

`, `variant="caption"` → ``), relying on ambient/bare-tag styling rather than the component's own `[variant]` rules. ADR-0102 (`text-ui`'s `level` prop, promoting the element to a real `

`-`
`) made this a first-class case, requiring the donor selector to stay tag-independent, e.g. `@scope (text-ui, [data-text])` with the renderer stamping a stable marker attribute on every such element regardless of the resolved tag, so a promoted `

` keeps its component styling instead of silently falling back to bare-tag `:where(hN)` defaults elsewhere in the cascade. Any component that can render under a tag other than its own name needs the same tag-independent scope check. ## Hard rules 1. **Zero raw color values** anywhere in component CSS - No `#fff`, `rgb(...)`, `oklch(...)` literals - All colors must reference `--a-chrome-*`, `--a-data-0..9`, `--a-fg*`, `--a-bg-*`, or family tokens (`--a-brand-*`, `--a-primary-*`, etc.) 2. **Two-block pattern**, token declarations separate from style rules 3. **Variants override tokens**, never rewrite base styles inside `[variant]` selectors. Change token values; the base styles absorb the change. 4. **`:where(:scope)`** for token defaults, zero specificity lets consumers override tokens from outside ## Audit procedure 1. **Find raw colors** ```bash grep -nE "#[0-9a-fA-F]{3,8}\b|rgb\(|rgba\(|oklch\(" \ packages/web-components/components//*.css ``` Any hit is a violation unless explicitly exempted (see below). 2. **Check for single-block @scope** ```bash grep -c "@scope" packages/web-components/components//*.css ``` Should be `2` (or `0` for layout-only components). 3. **Check for variant rewrites of base properties** ```bash grep -nE ":scope\[variant.*\] \{" packages/web-components/components//*.css ``` Inspect each match. If it sets `background`, `color`, `border` directly instead of `--my-bg`, `--my-text`, etc., it violates the variant rule. 4. **Check token usage in parent stylesheet** ```bash grep -n -- "--a-chrome\|--a-data\|--a-fg\|--a-bg" \ packages/web-components/components//*.css ``` Should have references; absence often indicates raw-value regressions. ## Documented exemptions (do not "fix") - `chart.css` data slots reference `--a-data-0..9` (tokens, not raw) - `card.css` mask uses `--a-chrome-light` (mask is opacity-only; value is semantic) - Drawer/modal scrims use `--a-scrim-dialog` (aliases.css, gh#373: routes to `--a-chrome-scrim-dialog`, 80% black, not `--a-chrome-backdrop`) If you find a raw value elsewhere, either: - Fix it by adding a proper token in the owning `styles/` dimension×layer file (see "Where foundation styles live" below, `tokens.css` is a compat barrel, not a home) - Or document the exemption in `.claude/docs/specs/component-token-contract.md` ## Chrome token palette Added in v0.5.0, use these for UI chrome: - `--a-chrome-light`, light scrim / overlay - `--a-chrome-dark`, dark scrim - `--a-chrome-border`, subtle hairline borders - `--a-chrome-ring-subtle`, focus rings, outlines - `--a-chrome-shadow-soft`, elevation shadows - `--a-chrome-backdrop` - generic 50% chrome overlay, reserved for non-dialog UI chrome; no current consumers. Modal/drawer backdrops use `--a-scrim-dialog` instead (80% black, gh#373, see `--a-chrome-scrim-dialog` in features.css' CHROME block) ## Data palette For charts, stat colors, category markers, use `--a-data-0` through `--a-data-9`. Do NOT hardcode chart colors. ## Where foundation styles live, dimension × layer Every file under `packages/web-components/styles/` answers two questions, which *dimension* (color · type · space · size · radius · motion · elevation) and which *layer* (primitive → semantic → role → element → attribute-API → context → reset), and declares its cell with a machine-readable header tag `adia:/`. When adding or moving a declaration: - Spatial / size / radius / motion / elevation primitives → `styles/foundation/` (one file per dimension) - Type scale (L1/L2), roles (L3), native-element defaults → `styles/type/` - Color layers → `styles/colors/` (parameters · primitives-* · surfaces · scrims · semantics/*) - The global attribute API (`[size]` `[density]` `[gap]` `[padding]` `[margin]` …) → `styles/api/{sizing,text,layout}.css`, the ONLY home for global `[attr]` selectors (governed by the grammar spec below) - `tokens.css`, `typography.css`, `colors/semantics.css`, etc. remain **compat barrels** at their public paths, they only `@import`; never add declarations to them Enforced by `scripts/release/check-foundation-layer-placement.mjs` (wired into `npm run check`): header tags present, primitive files free of attribute selectors, the attribute API confined to `api/`, no orphan files. Import order inside `colors/semantics/` is load-bearing (`aliases.css` last) and asserted in file headers. Source: ADR-0035. ## The global attribute grammar, read the spec before naming an attribute The global attribute API is a *designed system* with its own spec: `.claude/docs/specs/attribute-api-system.md` (companion audit: `.claude/docs/specs/attribute-api-audit.md`). That spec, not this checklist, owns the grammar. Two rules an author must know exist (read the spec for the mechanics; never work from this summary alone): - **Explicit vs ambient** (spec §5.2): `[gap]`/`[padding]`/`[margin]` are *explicit* per-element overrides (non-inheriting), while `[size]`/`[density]` are *ambient* context-setters (inheriting by design). Which axis an attribute sits on decides its `@property` registration and how components read it. - **No shadowing** (`docs/ops/adr/adr-0053-no-shadowing-global-attributes.md`): a component-local attribute may not share a name with any global attribute: the global name always means the global thing. Before minting any attribute in a component yaml, check it against the spec's attribute inventory; the only sanctioned collisions live in the spec's §11 Global-Attribute Exemption List (first entries: `swatch-ui[color]` / `noodles-ui[color]`, ADR-0054; granted since: `qr-code-ui[color]` / `icon-ui[weight]`, ADR-0070; `badge-ui[weight]` → `icon-ui[weight]`, ADR-0100). Beyond the global grammar, ADR-0063 (`docs/ops/adr/adr-0063-attribute-grammar-addendum.md`) ratifies seven CROSS-SIBLING conventions for component-local attribute naming, the axis ADR-0053/0054 don't cover. Any new attribute follows these: - **`no-*` is the canonical negation prefix**, `hide-*` retires (`chart[hideAverage|hideGrid|hideValues]` → `no*`, `stream[hide-cursor]` → `[no-cursor]`). - **Interactivity is opt-in by a positively-named boolean, default `false`** (the `stepper-item[interactive]` / `swatch[selectable]` shape), never opt-out. `chart-legend[static]` retires to `[interactive]` (inverted default). Applies to single-purpose toggles only, `noodles`'s `editable`/`readonly` pair is two orthogonal booleans and stays. - **One spelling survives a documented alias; the alias retires everywhere it appeared**, never a deprecation window. `alert[dismissible]` retired (`[closable]` survives, the implemented prop); `card`'s style enum's duplicate `outline` member retired (`outlined` survives, the ADR-0044 style-axis token). - **Two sanctioned multi-value encodings, never a hand-rolled delimited string:** (a) `multiple` boolean + a structured option model (`select`'s `options`/`