@pnx-mixtape/mxds 0.1.0-rc.4 → 0.1.0-rc.6

package/DESIGN.md

@@ -0,0 +1,595 @@
+# Mixtape Design System — Design Reference
+
+> This file is a structured reference for AI Design based tool onboarding (eg. Claude Design). It maps the design system's
+> tokens, components, conventions, and rules so the Agent can accurately generate designs and prototypes
+> using this system without ambiguity.
+>
+> **Read this as instruction, not advice.** Every "read X" below is a directive, not a suggestion — if a
+> section says to read a file or use a specific class, do that; do not infer an alternative from context.
+> When in doubt, prefer an existing class or token over inventing one.
+>
+> **When linking this repo to an AI Design tool:**
+>
+> - ✅ Include `dist/build/` — Browser-ready CSS with all tokens resolved, for accurate design generation
+> - ✅ Include `src/` — source files for reference on component structure, token definitions, and CSS architecture
+> - ✅ Include `docs/` — how-to guides, component architecture, CSS conventions
+> - ✅ Include `mockups/` — full page composition examples showing how components assemble together
+> - ❌ Exclude `notes/` — internal development notes, not relevant to design generation
+> - ❌ Exclude build/config files (`pnpm-lock.yaml`, `vite.config.js`, `docker-compose*.yml`, `vitest.config.js`) — these add noise without design value
+
+---
+
+## Package
+
+```
+@pnx-mixtape/mxds
+```
+
+- Storybook: https://mxds.pnx.io/
+- npm: https://www.npmjs.com/package/@pnx-mixtape/mxds
+
+---
+
+## Reference materials
+
+**For full-page composition examples, read [`mockups/HomePage.stories.ts`](./mockups/HomePage.stories.ts) first.** It shows how Atoms, Components, and Layouts assemble into a complete page using real classes — before generating anything, read at least one mockup end-to-end.
+
+**Mockups are Storybook stories; the `args` field is the source HTML.** Ignore the `meta`, decorators, and Storybook boilerplate — the composition you want lives in each story's `args`. Other full-page examples in [`mockups/`](./mockups/): `ArticlePage`, `ArticleListingPage`, `BasicPage`, `ContactPage`, `EventPage`, `EventListingPage`, `LandingPage`, `SearchResultPage`, `SidebarPage`.
+
+Each component README ends with a `→ Used in context:` footer pointing at the mockup line where it's composed — follow it to see the component in a real page.
+
+---
+
+## Design Tokens
+
+Tokens are defined in **`src/tokens.js`** and compiled into CSS custom properties via `postcss-design-tokens`.
+
+The resolved custom properties live in **`src/constants.css`** inside `@layer design-system.defaults`.
+
+### Colours
+
+| Token path              | CSS custom property           | Value                             |
+| ----------------------- | ----------------------------- | --------------------------------- |
+| `colour.primary.colour` | `--colour-primary`            | `hsl(223 100% 50%)` — vivid blue  |
+| `colour.accent.colour`  | `--colour-accent`             | `hsl(60, 94%, 68%)` — warm yellow |
+| `colour.main.fg`        | `--colour-foreground`         | `hsl(60 30% 6%)` — near-black     |
+| `colour.main.bg`        | `--colour-background`         | `hsl(60 0% 100%)` — white         |
+| `colour.main.fgAlt`     | `--colour-foreground-alt`     | `hsl(60 30% 20%)`                 |
+| `colour.main.bgAlt`     | `--colour-background-alt`     | `hsl(60 30% 95%)`                 |
+| `colour.main.border`    | `--colour-border`             | `hsl(60 5% 85%)`                  |
+| `colour.reverse.fg`     | `--colour-foreground-reverse` | `hsl(60 0% 100%)`                 |
+| `colour.reverse.bg`     | `--colour-background-reverse` | `hsl(60 30% 6%)`                  |
+| `colour.error`          | `--colour-error`              | `hsl(348 100% 33%)` — red         |
+| `colour.success`        | `--colour-success`            | `hsl(120 100% 26%)` — green       |
+| `colour.warning`        | `--colour-warning`            | `hsl(35 100% 32%)` — amber        |
+| `colour.info`           | `--colour-info`               | `hsl(223 100% 50%)` — blue        |
+
+Light/dark mode: colours use `light-dark()` CSS function. The scheme is controlled by `--scheme` (`light | dark`).
+
+Tints are derived automatically via `color-mix()`:
+
+- `--colour-primary-light` — primary + 90% white
+- `--colour-primary-lighter` — primary + 20% white
+- `--colour-primary-darker` — primary + 10% black
+
+### Typography
+
+The size scale is generated from a single ratio (`--type-ratio`, default `1.414` — augmentedFourth) using `pow()`, so each step is `base × ratio^n`.
+The ratio comes from `font.size.ratio` in `src/tokens.js`; on `--medium-down` viewports it is replaced with `font.size.ratioSmall` (default `1.2` — minorThird) so the scale tightens automatically on mobile.
+Both values index into a `global.typeScales` table of named scales (`minorSecond` 1.067 → `goldenRatio` 1.618) — swap either token to apply a different musical scale across the whole system.
+
+| CSS custom property    | Value / formula                                           |
+| ---------------------- | --------------------------------------------------------- |
+| `--font-family`        | `system-ui, sans-serif`                                   |
+| `--base-font-size`     | `max(1rem, 16px)`                                         |
+| `--type-ratio`         | `1.414` desktop / `1.2` mobile (`--medium-down` override) |
+| `--font-size`          | base (1rem) — used as the inherited default               |
+| `--font-size-xs`       | base × `pow(--type-ratio, -0.5)`                          |
+| `--font-size-s`        | base × `pow(--type-ratio, -0.25)`                         |
+| `--font-size-m`        | `1rem` (anchor — equal to base)                           |
+| `--font-size-ml`       | base × `pow(--type-ratio, 0.5)`                           |
+| `--font-size-l`        | base × `pow(--type-ratio, 1)`                             |
+| `--font-size-xl`       | base × `pow(--type-ratio, 2)`                             |
+| `--font-size-xxl`      | base × `pow(--type-ratio, 3)`                             |
+| `--font-size-xxxl`     | base × `pow(--type-ratio, 4)`                             |
+| `--font-size-diff`     | `0.3` — fluid-clamp drop, used by `clamp()` text sizing   |
+| `--font-weight-normal` | 400                                                       |
+| `--font-weight-bold`   | 700                                                       |
+| `--line-height`        | 1.6 (body)                                                |
+| `--line-height-h`      | 1.2 (headings)                                            |
+| `--line-height-ui`     | `0.9rem` (form controls)                                  |
+
+Because `--type-ratio` swaps on the breakpoint, every `--font-size-*` (other than `m`) recalculates fluidly — there is no separate mobile size scale to maintain.
+
+> See [`docs/CSSGuidelines.md → Swapping the type scale`](./docs/CSSGuidelines.md#swapping-the-type-scale) for a worked example of overriding to a different musical scale (perfect fourth, golden ratio, etc.).
+
+### Spacing
+
+Scale is `em`-based. All values map to `--spacing-{size}`:
+
+| Size    | Value   |
+| ------- | ------- |
+| `xxxxs` | 0.25em  |
+| `xxxs`  | 0.5em   |
+| `xxs`   | 0.75em  |
+| `xs`    | 0.875em |
+| `s`     | 1em     |
+| `m`     | 1.5em   |
+| `l`     | 2em     |
+| `xl`    | 2.5em   |
+| `xxl`   | 3em     |
+| `xxxl`  | 3.5em   |
+| `xxxxl` | 4em     |
+| `ul`    | 4.5em   |
+| `uul`   | 5em     |
+| `uuul`  | 5.5em   |
+
+Gap shortcuts: `--gap-s` (1em), `--gap` (1.5em), `--gap-l` (2em), `--gap-xl` (2.5em)
+
+### Breakpoints
+
+| Name  | Value  | Custom media                      |
+| ----- | ------ | --------------------------------- |
+| `xxs` | 320px  | —                                 |
+| `xs`  | 420px  | `--x-small-up` / `--x-small-down` |
+| `s`   | 540px  | `--small-up` / `--small-down`     |
+| `m`   | 720px  | `--medium-up` / `--medium-down`   |
+| `l`   | 946px  | `--large-up` / `--large-down`     |
+| `xl`  | 1100px | `--x-large-up` / `--x-large-down` |
+
+Additional utility media queries available: `--touch`, `--mouse`, `--dark`, `--light`, `--use-motion`, `--reduce-motion`, `--high-contrast`, `--portrait`, `--landscape`.
+
+This system is **mobile-first** — use `--medium-up` etc. to progressively enhance.
+
+### Layout
+
+| CSS custom property            | Value                             |
+| ------------------------------ | --------------------------------- |
+| `--container-max-width`        | `76ch` (aligned)                  |
+| `--container-max-width-narrow` | `58ch` (narrow)                   |
+| `--gutter-min`                 | `1em`                             |
+| `--gutter-max`                 | `2em`                             |
+| `--border-radius`              | `4px`                             |
+| `--border-radius-l`            | `2em` (pill)                      |
+| `--border-radius-round`        | `50%` (circle)                    |
+| `--box-shadow`                 | `0 0 0.875em hsl(0 0% 13% / 15%)` |
+
+---
+
+## CSS Architecture
+
+→ See [`docs/CSSGuidelines.md`](./docs/CSSGuidelines.md) for full details on PostCSS pipeline, BEM naming, cascade layers, custom media, logical properties, and override patterns.
+
+**Key facts for quick reference:**
+
+- All styles are in named `@layer` sub-layers (`design-system.defaults` → `.atoms` → `.layout` → `.components` → `.utilities`)
+- Class prefix: `mx-` — modifiers are BEM-style `mx-component--modifier`
+- Each component has `component.css` (full), `_component.css` (structure), `_component-styles.css` (colour variants)
+- Any **unlayered CSS wins** over all design system styles — no specificity battles
+
+---
+
+## Canonical class inventory
+
+> **This is the complete list of public `mx-*` classes that exist in the CSS.** Generated from `src/**/*.css`.
+> To regenerate: `grep -rhoE '\.mx-[a-z0-9][a-zA-Z0-9-]*' src --include="*.css" | sort -u`
+>
+> **Nothing else exists — do not invent classes.** If a class you want is not in this list, it is not part of
+> the system. Use an existing class, a CSS custom property override, or unlayered CSS instead.
+
+### Atoms
+
+| Class                                                                                                        | Purpose                                                                                                                                                   |
+| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mx-background--primary` `--accent` `--alt` `--reverse` `--box` `--image`                                    | Coloured background regions                                                                                                                               |
+| `mx-button`                                                                                                  | Base button                                                                                                                                               |
+| `mx-button--dark` `--light` `--accent` `--secondary` `--destructive` `--white`                               | Button colour variants                                                                                                                                    |
+| `mx-button--outline`                                                                                         | Outline style — **requires a colour modifier** (see grammar)                                                                                              |
+| `mx-button--small` `--large` `--full-width` `--icon-only`                                                    | Button layout/size                                                                                                                                        |
+| `mx-heading--xs` `--s` `--m` `--l` `--xl` `--xxl`                                                            | Heading size overrides                                                                                                                                    |
+| `mx-headline`                                                                                                | Display headline                                                                                                                                          |
+| `mx-icon`                                                                                                    | Base icon                                                                                                                                                 |
+| `mx-icon--{name}`                                                                                            | Icon glyph — `{name}` from the `Icons` enum (e.g. `--close`)                                                                                              |
+| `mx-icon--color-brand` `--color-accent` `--color-error` `--color-info` `--color-success` `--color-warning`   | Icon colour                                                                                                                                               |
+| `mx-icon--size-sm` `--size-md` `--size-lg` `--size-xl`                                                       | Icon size                                                                                                                                                 |
+| `mx-icon--rotate-90` `--rotate-180` `--rotate-270`                                                           | Icon rotation                                                                                                                                             |
+| `mx-icon--end` `--only` `--status`                                                                           | Icon placement / icon-only                                                                                                                                |
+| `mx-link`                                                                                                    | Base link                                                                                                                                                 |
+| `mx-link--external` `--download` `--more`                                                                    | Link variants                                                                                                                                             |
+| `mx-list`                                                                                                    | Base `<ul>`/`<ol>` list                                                                                                                                   |
+| `mx-list--notes` `--refs` `--stats` `--columns` `--summary` `__action`                                       | List variants — footnotes, hanging-indent references, stat grid, column grid, and (`DefinitionList`-only) review-answers summary rows with an action slot |
+| `mx-media--left` `--center` `--right` `--video`                                                              | Media alignment / video aspect                                                                                                                            |
+| `mx-rich-text`                                                                                               | Rich text (CMS content) region                                                                                                                            |
+| `mx-table--bordered` `--striped` `--flush` `--small` `--responsive` `--reset`                                | Table variants                                                                                                                                            |
+| `mx-text--xs` `--s` `--m` `--l` `--xl` `--xxl` `--xxxl`                                                      | Text size                                                                                                                                                 |
+| `mx-text--primary` `--accent` `--alt`                                                                        | Text colour                                                                                                                                               |
+| `mx-text--left` `--center` `--right`                                                                         | Text alignment                                                                                                                                            |
+| `mx-text--eyebrow` `--lede` `--meta` `--embellished` `--embellished-headline` `--section-headline` `--fluid` | Special text styles                                                                                                                                       |
+| `mx-video`                                                                                                   | Video embed                                                                                                                                               |
+| `mx-spacing--{side}-{size}` `mx-spacing--reset` `mx-spacing--{side}-reset`                                   | Padding utility — `{side}` = top/bottom/left/right, `{size}` = spacing scale                                                                              |
+| `mx-margin--{side}-{size}` `mx-margin--reset` `mx-margin--{side}-reset`                                      | Margin utility — same `{side}`/`{size}` grammar as spacing                                                                                                |
+| `mx-animated--fade-in` `--fade-out` `--scale-up` `--scale-down` `--spin`                                     | Animation utilities                                                                                                                                       |
+
+### Components
+
+| Class                                                                                                      | Purpose                                               |
+| ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| `mx-accordion` `mx-accordions` `mx-accordion--divided`                                                     | Accordion + group                                     |
+| `mx-back-to-top` `mx-back-to-top--l`                                                                       | Scroll-to-top trigger (breakpoint-gated)              |
+| `mx-callout`                                                                                               | Callout aside                                         |
+| `mx-card` `mx-card--block` `mx-card--collapse` `mx-card--reversed`                                         | Card + variants                                       |
+| `mx-carousel`                                                                                              | Carousel                                              |
+| `mx-content-block`                                                                                         | Rich content region                                   |
+| `mx-cookie-consent` `mx-cookie-consent__actions` `mx-cookie-consent__inner`                                | Site-wide cookie consent banner                       |
+| `mx-dialog` `mx-dialog--fullscreen`                                                                        | Modal dialog                                          |
+| `mx-drop-menu`                                                                                             | Dropdown menu                                         |
+| `mx-filters` `mx-filters--right` `mx-filters--sticky` `mx-filter-item`                                     | Filter controls                                       |
+| `mx-gallery` `mx-gallery__preview` `mx-gallery__trigger`                                                   | Image preview → fullscreen carousel modal             |
+| `mx-global-alert` `mx-global-alert--critical`                                                              | Site-wide alert banner                                |
+| `mx-hero-banner` `mx-hero-banner--hero`                                                                    | Hero banner (also used by HeroSearch)                 |
+| `mx-in-page-navigation`                                                                                    | In-page TOC nav                                       |
+| `mx-link-list`                                                                                             | Link list                                             |
+| `mx-list-item`                                                                                             | List item (extends Card)                              |
+| `mx-nav`                                                                                                   | Base navigation                                       |
+| `mx-nav--breadcrumbs` `--collapsible` `--dropdown` `--mega-nav` `--inline` `--reverse` `--footer` `--open` | Navigation variants + state                           |
+| `mx-pagination`                                                                                            | Pagination                                            |
+| `mx-popover`                                                                                               | Popover panel                                         |
+| `mx-progress-indicator` `__count` `__track` `__marker` `--done` `--now` `__steps` `__step` `--done`        | Horizontal step-progress tracker for wizards/forms    |
+| `mx-results-bar`                                                                                           | Results count + sort bar                              |
+| `mx-side-nav`                                                                                              | Secondary vertical nav                                |
+| `mx-social-links`                                                                                          | Social profile links                                  |
+| `mx-social-share`                                                                                          | Share-to-social buttons                               |
+| `mx-steps` `mx-steps--counters` `--fill` `--dark` `--supplementary`                                        | Step indicator                                        |
+| `mx-sticky` `mx-sticky--m` `mx-sticky--l`                                                                  | Sticky wrapper (breakpoint-gated)                     |
+| `mx-tabs` `mx-tabs--lined` `mx-tabs--centered`                                                             | Tabs                                                  |
+| `mx-tag` `mx-tags` `mx-tag--dismissible`                                                                   | Tag + tag list. **No colour/outline variants exist**  |
+| `mx-translate` `__trigger` `__code` `__menu` `__item` `__notice`                                           | Language switcher, drives Google's Website Translator |
+| `mx-utility-list`                                                                                          | Utility link bar                                      |
+
+### Forms
+
+| Class                                                                       | Purpose                                               |
+| --------------------------------------------------------------------------- | ----------------------------------------------------- |
+| `mx-autocomplete` `mx-autocomplete__listbox` `mx-autocomplete__option`      | Editable combobox with a suggestion listbox           |
+| `mx-feedback-form` `__rating` `__option` `__secondary` `__error` `__reveal` | Yes/no feedback control with a revealed comment field |
+| `mx-form-actions` `mx-form--inline-button`                                  | Form actions row / inline button                      |
+| `mx-form-item` `mx-form-item--inline`                                       | Field group                                           |
+| `mx-fieldset` `mx-fieldset--inline` `mx-fieldset--plain`                    | Fieldset                                              |
+| `mx-legend`                                                                 | Fieldset legend                                       |
+| `mx-label` `mx-label--inline`                                               | Field label                                           |
+| `mx-input` `mx-input--icon` `mx-input--small` `mx-input--wide`              | Text input                                            |
+| `mx-checkbox` `mx-radio`                                                    | Checkbox / radio                                      |
+| `mx-choice-card` `mx-choice-card__hint` `mx-choice-divider`                 | Card-style checkbox/radio + shared "or" divider       |
+| `mx-description`                                                            | Field helper text                                     |
+| `mx-required`                                                               | Required indicator                                    |
+| `mx-error-message` `mx-success-message`                                     | Field status messages                                 |
+
+### Layout
+
+| Class                                                                    | Purpose                                                                |
+| ------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| `mx-page` `mx-page--full` `mx-page--feature` `mx-page--narrow`           | Page grid wrapper + track widths                                       |
+| `mx-container`                                                           | Container-query context (**not** a width constraint)                   |
+| `mx-section`                                                             | Page section                                                           |
+| `mx-section--s` `--m` `--l` `--xl`                                       | Section padding scale                                                  |
+| `mx-section--top-s/-m/-l/-xl` `mx-section--bottom-s/-m/-l/-xl`           | Directional section padding                                            |
+| `mx-section--flow` `--group` `--divider` `--full` `--feature` `--narrow` | Section modes / layout                                                 |
+| `mx-section--has-background`                                             | Legacy `:has()` fallback for containing background images (no padding) |
+| `mx-grid` `mx-grid-item`                                                 | Grid wrapper + item                                                    |
+| `mx-grid--cols-{bp}-{n}`                                                 | Column count per breakpoint (`bp` = xs/sm/md/lg/xl, `n` = 2/3/4)       |
+| `mx-grid--collapse` `--collapse-cols` `--collapse-rows`                  | Grid gap collapse                                                      |
+| `mx-grid--sidebar` `--sidebar-rev` `--sidebar-rev-lg`                    | Sidebar grid variants                                                  |
+| `mx-header`                                                              | Site header                                                            |
+| `mx-masthead`                                                            | Top branding bar                                                       |
+| `mx-footer`                                                              | Site footer                                                            |
+| `mx-logo`                                                                | Logo                                                                   |
+| `mx-skip-links`                                                          | Skip-link container                                                    |
+
+### Utilities
+
+| Class                                                              | Purpose                     |
+| ------------------------------------------------------------------ | --------------------------- |
+| `mx-vertical-flow` `mx-vertical-flow-flex` `mx-vertical-flow-grid` | Vertical flow spacing       |
+| `mx-horizontal-flow-flex`                                          | Horizontal flow spacing     |
+| `skeleton--bg`                                                     | Loading skeleton background |
+
+---
+
+## Composition grammar
+
+The rules below live in CSS and are invisible to a consumer reading a README. **Follow them exactly.**
+
+### Modifiers that require a colour partner
+
+- `mx-button--outline` does **nothing on its own** — it only styles when combined with a colour modifier:
+  `mx-button--outline mx-button--dark` (also works with `--accent`, `--destructive`, `--white`). Outline + `--light`/`--secondary` has no effect.
+
+### Backgrounds & full-bleed
+
+`mx-page` **defines** a named column grid (`full` / `container` / `feature` / `narrow`) — see [Page layout](./src/Layout/Page/README.md). **Only a _direct grid child_ of `mx-page` can span the full-bleed width.** This is the most common invisible-rule bug: a background applied at the wrong nesting level silently fails to span.
+
+- **Put `mx-background--*` on a section-level wrapper that is a direct child of `mx-page`** — not on inner content. When it is, that element spans `full` and inherits the parent's tracks as a **subgrid**, so its own children fall back to the `container` track automatically (the colour bleeds edge-to-edge while text stays aligned). Only these nested full-bleed children (and nested `mx-page` elements) become subgrids — the top-level `mx-page` is the grid definition itself, not a subgrid.
+- **Add section padding** with a spacing modifier (`mx-section--m` / `--l` / etc.) — a coloured region with no padding looks broken. Padding comes from the spacing classes, _not_ from the background.
+- **`mx-section--has-background`** is a legacy `:has()` fallback (for browsers without `:has()` support) that sets `overflow`/`position` so a background image is contained — it does **not** add padding. Modern browsers derive this from `:has(.mx-background--image)` automatically.
+- **Exception:** `mx-background--box` is an inline, non-bleeding background (a boxed panel) — it does _not_ trigger the subgrid span and can sit on inner content.
+
+Correct nesting:
+
+```
+mx-page
+└─ mx-section mx-section--l mx-background--primary   ← direct child, spans full-bleed (--l adds padding)
+   └─ content                                         ← stays on the container track
+```
+
+Wrong (background won't span — applied below the grid child):
+
+```
+mx-page
+└─ mx-section
+   └─ div.mx-background--primary   ← not a direct grid child; no full-bleed
+```
+
+### Card layout requires a container-query wrapper
+
+`mx-card`'s two-column (media + content) layout is driven by **container queries**, not viewport breakpoints. It only activates when the card sits inside an element that establishes the `card` container context — in practice, wrap the card in `mx-container` (or place it as a direct child of `mx-grid`, which sets it up).
+
+- ✅ `<div class="mx-container"><div class="mx-card">…</div></div>` → card can switch to side-by-side at wide container widths.
+- ❌ A bare `mx-card` with no `mx-container` / `mx-grid` ancestor → stays stacked forever, regardless of available width. Same invisible-rule class as `mx-button--outline` without a colour: the class is correct but a required companion is missing.
+
+### Modifiers that combine
+
+- **Button:** one colour (`--dark`/`--light`/`--accent`/`--secondary`/`--destructive`/`--white`) + optionally `--outline` + optionally one size (`--small`/`--large`) + optionally `--full-width` or `--icon-only`.
+- **Steps:** `mx-steps--counters` adds numbered counters; combine with a colour mode (`--dark`/`--supplementary`) and/or `--fill`.
+- **Section:** a padding scale (`--s`/`--m`/`--l`/`--xl`) + optionally `--flow` or `--group`. For colour, add an `mx-background--*` class (the padding still comes from the scale class). `--has-background` is only the legacy `:has()` fallback, not part of this composition.
+
+### Modifiers that do NOT exist (common false positives)
+
+- ❌ `mx-button--primary` — use `mx-button--dark`
+- ❌ `mx-section--primary` — use `mx-section` + `mx-background--primary`
+- ❌ `mx-tag--accent`, `mx-tag--outline`, `mx-tag--primary` — Tag has **no colour or outline variants**; only `mx-tag--dismissible`
+- ❌ `mx-hero__eyebrow` or any custom eyebrow class — use `mx-text--eyebrow`
+- ❌ `mx-card--primary` / colour modifiers on Card — set a background via `mx-background--*` on the card or its section
+
+---
+
+## Anti-patterns — things that look right but aren't
+
+- **`mx-button--outline` without a colour modifier.** Renders invisible. Always pair with a colour (see [Composition grammar](#composition-grammar)).
+- **A `mx-background--*` region that doesn't bleed.** Almost always caused by applying it below the direct child of `mx-page` — see [Backgrounds & full-bleed](#backgrounds--full-bleed).
+- **A `mx-card` stuck in stacked layout.** Missing the `mx-container` / `mx-grid` wrapper that provides its container-query context — see [Card layout requires a container-query wrapper](#card-layout-requires-a-container-query-wrapper).
+
+> Reinventing classes that don't exist (`mx-button--primary`, custom eyebrow utilities, `--primary` colour modifiers, etc.) is covered in [Modifiers that do NOT exist](#modifiers-that-do-not-exist-common-false-positives) — don't do it.
+
+---
+
+## What to use for X — cheatsheet
+
+Common visual intents mapped to the idiomatic Mixtape class. Reach for these before inventing anything.
+
+| I want…                                         | Use                                                                                                                                                                                                                                                                                                                            |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Small uppercase label above a heading (eyebrow) | `mx-text--eyebrow` (with underbar: `mx-text--embellished`)                                                                                                                                                                                                                                                                     |
+| A section with a brand-coloured background      | `mx-section` + `mx-background--primary`                                                                                                                                                                                                                                                                                        |
+| A bold call-to-action button on a light surface | `mx-button--dark`                                                                                                                                                                                                                                                                                                              |
+| A CTA button on a dark/reverse surface          | `mx-button--white`                                                                                                                                                                                                                                                                                                             |
+| A secondary/outline button                      | `mx-button--outline` **+** a colour (e.g. `mx-button--dark`)                                                                                                                                                                                                                                                                   |
+| An accent-coloured button                       | `mx-button--accent`                                                                                                                                                                                                                                                                                                            |
+| A large display heading                         | `mx-headline` or `mx-heading--xl` / `--xxl`                                                                                                                                                                                                                                                                                    |
+| Lead / intro paragraph                          | `mx-text--lede`                                                                                                                                                                                                                                                                                                                |
+| A responsive multi-column card grid             | `mx-grid` + `mx-grid--cols-lg-3` (etc.)                                                                                                                                                                                                                                                                                        |
+| A category label/badge                          | `mx-tag` (no colour variants — style via `--tag-*` tokens)                                                                                                                                                                                                                                                                     |
+| Constrain content width                         | Content inside `mx-page` sits in the `container` track (`76ch`) by default; use `mx-section--narrow` (`58ch`) for reading width, `mx-section--feature` / `mx-section--full` to widen. See [Page layout](./src/Layout/Page/README.md). `mx-container` is **not** a width constraint — it establishes a container-query context. |
+
+---
+
+## Public token API
+
+These CSS custom properties are the **intended override surface** — set them (scoped to a context class) to customise a component. They are recognisable in source by the `var(--token, fallback)` pattern and are marked `/* @public */` in the CSS. **Everything else (`--line-width`, `--counter-top`, `--font-min`, `--plus`/`--minus`, `--grid-repeat`, positioning tokens, etc.) is internal — do not override.**
+
+### Button
+
+| Property                                                             | Default                                        | Intent                     |
+| -------------------------------------------------------------------- | ---------------------------------------------- | -------------------------- |
+| `--button-dark-bg` / `--button-dark-fg` / `--button-dark-line`       | `--colour-link` / reverse fg / `--colour-link` | Dark button colours        |
+| `--button-accent-bg` / `--button-accent-fg` / `--button-accent-line` | accent / `--colour-foreground` / accent        | Accent button colours      |
+| `--button-light-bg` / `--button-light-fg` / `--button-light-line`    | transparent / link / transparent               | Light button colours       |
+| `--button-accent-scheme`                                             | `light`                                        | Colour scheme for accent   |
+| `--button-font-size`                                                 | inherited                                      | Button text size           |
+| `--button-gap`                                                       | `--spacing-s`                                  | Gap between button content |
+| `--button-min-height`                                                | —                                              | Minimum height             |
+
+### Tag
+
+| Property           | Default               | Intent           |
+| ------------------ | --------------------- | ---------------- |
+| `--tag-background` | `--colour-background` | Tag fill         |
+| `--tag-foreground` | `--colour-foreground` | Tag text         |
+| `--tag-font-size`  | `--font-size-xs`      | Tag text size    |
+| `--tags-gap`       | `--spacing-s`         | Gap between tags |
+
+### Card
+
+| Property           | Default   | Intent                      |
+| ------------------ | --------- | --------------------------- |
+| `--card-gap`       | `--gap`   | Gap between card regions    |
+| `--card-alignment` | `stretch` | Cross-axis alignment        |
+| `--large-card-gap` | `6rem`    | Gap for large/feature cards |
+
+### Alert (GlobalAlert / InPageAlert)
+
+| Property             | Default                  | Intent        |
+| -------------------- | ------------------------ | ------------- |
+| `--alert-background` | `--colour-primary-light` | Alert fill    |
+| `--alert-foreground` | `--colour-foreground`    | Alert text    |
+| `--alert-scheme`     | `light`                  | Colour scheme |
+
+### HeroBanner / HeroSearch
+
+| Property              | Default           | Intent              |
+| --------------------- | ----------------- | ------------------- |
+| `--hero-height`       | `600px`           | Minimum hero height |
+| `--hero-columns`      | `50% 50%`         | Content/aside split |
+| `--hero-align`        | `center`          | Vertical alignment  |
+| `--hero-image-radius` | `--border-radius` | Aside image radius  |
+
+### Popover
+
+| Property               | Default               | Intent        |
+| ---------------------- | --------------------- | ------------- |
+| `--popover-padding`    | `--spacing-xs`        | Inner padding |
+| `--popover-background` | `--colour-background` | Fill          |
+| `--popover-foreground` | `--colour-foreground` | Text          |
+| `--popover-radius`     | `--border-radius`     | Corner radius |
+| `--popover-width`      | `30ch`                | Max width     |
+
+### Section
+
+| Property                                                       | Default       | Intent                            |
+| -------------------------------------------------------------- | ------------- | --------------------------------- |
+| `--section-s` / `--section-m` / `--section-l` / `--section-xl` | spacing scale | Per-size section padding override |
+
+### Lines & borders (global)
+
+Cross-cutting tokens used by borders, dividers, underlines, and focus outlines across many components (forms, buttons, tags, popover, etc.). Scope them to a context class to restyle lines in bulk, or override per-component.
+
+| Property        | Default (per component)                  | Intent                  |
+| --------------- | ---------------------------------------- | ----------------------- |
+| `--line-width`  | `2px` (forms/buttons), `1px` (tags/etc.) | Border / line thickness |
+| `--line-colour` | `--colour-border` (varies per component) | Border / line colour    |
+
+> Global tokens (`--colour-*`, `--font-size-*`, `--spacing-*`, `--gap*`, `--border-radius*`, `--box-shadow`, breakpoints) documented in [Design Tokens](#design-tokens) above are also public and overridable.
+
+---
+
+## Component Modifiers (from `@pnx-mixtape/ids-shape`)
+
+> Modifier enums live in [`@pnx-mixtape/ids-shape`](https://www.npmjs.com/package/@pnx-mixtape/ids-shape).
+> Full API reference: [TypeDoc-generated docs](https://unpkg.com/@pnx-mixtape/ids-shape/docs/index.html)
+
+→ See individual README.md files (eg. src/Atom/Button/README.md) for full modifier reference, React props, and CSS custom property overrides.
+
+---
+
+## Component Inventory
+
+> This lists components by name with descriptions. For the exhaustive list of every CSS **class**, see [Canonical class inventory](#canonical-class-inventory) above.
+
+### Atoms (`src/Atom/`)
+
+Smallest, single-purpose elements. Always use these as building blocks; never reproduce their styles.
+
+| Component        | Description                                                     |
+| ---------------- | --------------------------------------------------------------- |
+| `Background`     | Coloured background regions with scheme switching               |
+| `Blockquote`     | Styled `<blockquote>` for pull quotes                           |
+| `Button`         | All button and button-link variants                             |
+| `DefinitionList` | Styled `<dl>` for key/value pairs                               |
+| `Heading`        | Typographic headings (h1–h6) with size/weight modifiers         |
+| `Icon`           | SVG icon via CSS mask-image, sized with `--icon-size`           |
+| `Image`          | Responsive image wrapper with ratio control                     |
+| `InlineSvg`      | Inline SVG component                                            |
+| `Link`           | Base anchor with hover/focus styles                             |
+| `LinkedImage`    | Image wrapped in a link                                         |
+| `List`           | Styled `<ul>`/`<ol>` with notes, references, and stats variants |
+| `Media`          | Generic media container (images, video)                         |
+| `Spacing`        | Whitespace utility component                                    |
+| `Table`          | Accessible, responsive table                                    |
+| `Text`           | Body text wrapper                                               |
+| `Video`          | Video embed with aspect ratio                                   |
+
+### Components (`src/Component/`)
+
+Composed from Atoms. Have their own interaction behaviour.
+
+| Component           | Description                                                                                                          |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `Accordion`         | Collapsible content panels (Web Component: `<mx-accordion>`)                                                         |
+| `BackToTop`         | Trigger that appears after a scroll threshold and jumps back to a target element (Web Component: `<mx-back-to-top>`) |
+| `Breadcrumb`        | Hierarchical navigation trail                                                                                        |
+| `Callout`           | Highlighted aside/tip block                                                                                          |
+| `Card`              | Content card with image, title, body, and actions                                                                    |
+| `Carousel`          | Scrollable item carousel                                                                                             |
+| `ContentBlock`      | Rich text content region                                                                                             |
+| `CookieConsent`     | Site-wide cookie consent banner, fixed to viewport bottom                                                            |
+| `Dialog`            | Modal dialog (Web Component)                                                                                         |
+| `DropMenu`          | Dropdown navigation menu                                                                                             |
+| `Filters`           | Filter controls for listing pages                                                                                    |
+| `Gallery`           | Image preview that opens a fullscreen carousel modal                                                                 |
+| `GlobalAlert`       | Site-wide dismissible alert banner                                                                                   |
+| `HeroBanner`        | Full-width hero with image and headline                                                                              |
+| `HeroSearch`        | Hero with integrated search input                                                                                    |
+| `InPageAlert`       | Inline status alert (info/success/warning/error)                                                                     |
+| `InPageNavigation`  | Anchor-link navigation for long pages                                                                                |
+| `LinkList`          | Vertical or horizontal list of links                                                                                 |
+| `ListItem`          | Single item within a list context                                                                                    |
+| `Navigation`        | Primary site navigation                                                                                              |
+| `Pagination`        | Page navigation controls                                                                                             |
+| `Popover`           | Floating contextual content panel                                                                                    |
+| `ProgressIndicator` | Horizontal step-progress tracker for multi-step forms/wizards                                                        |
+| `ResultsBar`        | Shows result count and sort controls                                                                                 |
+| `SideNavigation`    | Secondary vertical navigation                                                                                        |
+| `SocialLinks`       | Links to social media profiles                                                                                       |
+| `SocialShare`       | Share-to-social buttons                                                                                              |
+| `Steps`             | Numbered step indicator                                                                                              |
+| `Sticky`            | Sticky-positioned wrapper                                                                                            |
+| `Tabs`              | Tab panel navigation                                                                                                 |
+| `Tag`               | Label/badge for categorisation                                                                                       |
+| `Translate`         | Language switcher that drives Google's Website Translator widget, built on DropMenu                                  |
+| `UtilityList`       | Utility link bar                                                                                                     |
+
+### Forms (`src/Form/`)
+
+| Component      | Description                                                                                  |
+| -------------- | -------------------------------------------------------------------------------------------- |
+| `Autocomplete` | Editable combobox with a suggestion listbox                                                  |
+| `Checkbox`     | Styled checkbox input                                                                        |
+| `CheckboxCard` | Card-style checkbox with a larger tap target                                                 |
+| `Description`  | Helper/hint text for form fields                                                             |
+| `FeedbackForm` | Yes/no feedback control that reveals a comment field, with a submit contract for any backend |
+| `Form`         | Form wrapper with spacing                                                                    |
+| `FormItem`     | Field group (label + input + description + error)                                            |
+| `Label`        | Form field label                                                                             |
+| `Radio`        | Styled radio input                                                                           |
+| `RadioCard`    | Card-style radio with a larger tap target                                                    |
+| `Search`       | Search input with button                                                                     |
+| `Select`       | Styled `<select>` dropdown                                                                   |
+| `Textarea`     | Styled `<textarea>`                                                                          |
+| `TextInput`    | Styled text `<input>`                                                                        |
+
+### Layout (`src/Layout/`)
+
+| Component  | Description               |
+| ---------- | ------------------------- |
+| `Footer`   | Site footer               |
+| `Grid`     | CSS grid layout wrapper   |
+| `Header`   | Site header               |
+| `Masthead` | Top-of-page branding bar  |
+| `Page`     | Full page layout wrapper  |
+| `Section`  | Page section with spacing |
+| `Sidebar`  | Two-column sidebar layout |
+
+### Utilities (`src/Utility/`)
+
+Utility classes, hooks, and context providers. Includes print styles, layout utilities, Drupal-specific helpers, and React hooks.
+
+---
+
+## React & Web Component Usage
+
+→ See [`docs/ComponentArchitecture.md`](./docs/ComponentArchitecture.md) for full patterns.
+
+React components are exported from `src/react.ts`. Web Components auto-register on import and use the `mx-` custom element prefix (e.g. `<mx-accordion>`).
+
+---
+
+## Accessibility
+
+→ WCAG 2.2 AA compliant. See [`docs/CSSGuidelines.md`](./docs/CSSGuidelines.md) for media query hooks (`--use-motion`, `--high-contrast`, etc.) and [`docs/ComponentArchitecture.md`](./docs/ComponentArchitecture.md) for ARIA patterns.
+
+---
+
+## Overriding Styles
+
+→ See [`docs/CSSGuidelines.md`](./docs/CSSGuidelines.md) for the full override guide.
+
+**Short version:** prefer CSS custom property overrides scoped to a context class. Unlayered CSS wins globally without needing `!important`.

package/README.md

@@ -206,7 +206,7 @@ import { Button } from "@pnx-mixtape/mxds/compiled/react"
 - ✅ **Framework-agnostic** - Web Components, React, Twig templates
 - ✅ **Design Tokens** - Customizable theming via tokens
 - ✅ **CSS Layers** - Easy overrides without specificity wars
-- ✅ **Accessible** - WCAG 2.0 AA compliant
+- ✅ **Accessible** - WCAG 2.2 AA compliant
 - ✅ **Responsive** - Mobile-first approach
 - ✅ **Modern CSS** - Logical properties, custom media, container queries
 - ✅ **TypeScript** - Full type support
@@ -222,8 +222,7 @@ Mixtape uses [@layers](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer)
 @import "@pnx-mixtape/mxds/src/Atom/base.css";
 
 /* Or manually define layer order */
-@layer design-system.defaults, design-system.atoms, design-system.layout, 
-       design-system.components, design-system.utilities;
+@layer design-system.defaults, design-system.atoms, design-system.layout, design-system.components, design-system.utilities;
 
 /* Your unlayered CSS automatically overrides design system */
 .mx-button {