@epilot/volt-ui-experimental-griffel 0.2.1 → 0.2.3

package/AGENTS.md

@@ -0,0 +1,153 @@
+# Agent rules — `@epilot/volt-ui-experimental-griffel`
+
+These rules govern every file under `packages/experimental-griffel/`. They are normative: where any
+other document in this package disagrees with this file, **this file wins** and the other one is a
+bug worth fixing.
+
+`packages/experimental/AGENTS.md` does **not** apply here. It governs
+`@epilot/volt-ui-experimental-css-modules`, a different package with a different styling engine, and
+its rules on CSS Modules, `var(--volt-*)` tokens and `bun run *:experimental` scripts are all wrong
+for this one. The two are siblings, not parent and child.
+
+**What the other documents are for.** `AUTHORING.md` explains the defect behind each rule — read it
+when you want to know _why_, not _what_. `DECISIONS.md` records architecture rationale as a dated
+log. `STATUS.md` is a snapshot of measurements and progress at a point in time; treat every number
+in it as of its commit, never as a live fact. This file holds no counts and no measurements on
+purpose, because those are what rot.
+
+## Architecture, as it is now
+
+- **Primitives are Radix**, at the same versions v1 pins, plus `sonner` for Toast and `cmdk` for
+  Command. There is no `@base-ui/react` in this package — not in the manifest, not in `src`.
+  Anything telling you to use Base UI primitives, or to prefer `data-checked` over Radix's
+  `data-state="checked"`, is describing an abandoned detour. Radix state attributes are
+  **value-based**: `&[data-state='checked']`, not `&[data-checked]`.
+- **Styling is Griffel**, emitted as runtime atoms. No Tailwind, no `cn`, no `tailwind-merge`, no
+  shipped stylesheet. Use `mergeClasses` from `@epilot/volt-ui-runtime` — this package
+  does not import `@griffel/core` anywhere, and `gate:one-bare-specifier` enforces that.
+- **The runtime target is React 18**, while the repo compiles against `@types/react@19`. Both suites
+  must stay green.
+- ESM only. `react` and `react-dom` are peers; everything else is vendored into `dist`.
+  `sideEffects: false`.
+
+## Authoring rules
+
+1. **`&` must be the first token of every selector.** Griffel prepends its class to the whole
+   selector and substitutes `&` nowhere else, so `"[data-pressed] &"` emits
+   `.hash[data-pressed] .hash` and can never match. No warning, no error, no failing test. To style a
+   descendant from an ancestor's state, declare the rule on the _ancestor's_ slot and reach down via
+   `SLOT_ATTR`. A selector list is fine when each part is legal alone.
+   `src/ancestor-selector.test.ts` enforces this.
+
+2. **Declaration order inside a slot encodes precedence, and v1's order does not.** Griffel emits
+   atoms in source order, so the later rule wins. v1's precedence comes from Tailwind's utility
+   layer, where `aria-invalid:` beats `disabled:` regardless of class order. Transcribing v1's order
+   inverts the outcome. Put the state that must **win** last.
+
+3. **Match a neighbour's property shape, not just its value.** Griffel dedupes only when expanded
+   property keys match, so `paddingLeft`/`paddingRight` against a neighbour's
+   `shorthands.paddingInline` leaves both standing and the cascade picks the wrong one.
+
+4. **No CSS shorthands** — an atom is one declaration, so a shorthand cannot be resolved against a
+   longhand. Use `shorthands.*`. Griffel only warns at runtime, so the warnings-as-errors test is
+   what catches it.
+
+5. **Animations use the object form**, `animationName: { from: {…}, to: {…} }`. Griffel hashes
+   keyframe names from content but does **not** apply the class-name salt to them, so a hand-authored
+   global `@keyframes` collides across co-resident copies silently.
+
+6. **`forwardRef` is required.** `ref`-as-a-plain-prop is React 19; every consumer runs React 18,
+   where a function component without `forwardRef` never receives `ref`.
+
+7. **`asChild` is supported and should stay supported.** Components wrapping a Radix primitive
+   inherit it through `React.ComponentProps<typeof Primitive.X>` and need no work. Components that
+   render their own element — Button and BreadcrumbItem — implement it with Radix's `Slot`. v1
+   exposes it on thirteen components and consumers use it to wrap router links, so dropping it
+   breaks call sites. It was briefly removed while this package was on Base UI; that reason no
+   longer exists. Do not expose Base UI's `render` prop, which is a different thing.
+
+8. **Colour is a value, never part of a class name.** Components with a `color` prop follow Badge:
+   atoms read inline custom properties the component sets. Never emit a per-colour rule.
+
+9. **Call `ensurePaletteTokens()` whenever you reference any family outside
+   accent / gray / error / warning / success / info** — whether or not the component has a `color`
+   prop. Those six are in the core sheet; every other family is in the palette sheet, which is not
+   loaded by default, and referencing it without installing gives an invalid computed value and no
+   error.
+
+10. **No module-scope DOM or stylesheet mutation.** Installing tokens, inserting styles or touching
+    `document` must happen lazily at first render, never at import time — that is what makes
+    `sideEffects: false` true and keeps an unused import free.
+    `src/components/avatar/avatar.tsx` currently calls `ensurePaletteTokens()` at module scope. **That
+    is a known defect, not a precedent.** Do not copy it.
+
+11. **`SLOT_ATTR` for selectors, `data-slot` for diagnostics.** Emit both, and never write a selector
+    keyed on `data-slot` — those values are shared with v1, so such a rule also matches v1-rendered
+    DOM. Portalled parts each carry their own styling class and their own slot marker; a class on an
+    ancestor outside the portal does not reach them.
+
+12. **Preserve the caller's `className` and forward DOM refs.**
+
+## Tokens
+
+- Use a token wherever one exists (`tokens.textSm`, `tokens.spacingElement2`, `tokens.grayA11`).
+  Where none exists, a literal is correct — say so in your report. Never
+  `calc(var(--spacing) * n)`: reintroducing Tailwind's numeric scale is what this rebuild exists to
+  avoid.
+- **Spacing and size are different axes.** There is no dimension token family, so `width: "0.75rem"`
+  on an svg stays a literal even though `spacingElement3` shares the number.
+- **Never edit a generated token file, and never hardcode a namespace or salt hash.** Run
+  `bun run tokens`.
+- Core and palette carry **independent** namespaces, so a palette-only change does not rename core
+  properties. `GRIFFEL_CLASS_SALT` covers the pinned Griffel version and nothing else — token
+  isolation is the namespaces' job, not the salt's.
+
+## Rule 0 — v1's rendered OUTPUT is the fidelity target
+
+Not v1's source, and not a task file's summary of it. Where a task file and v1 disagree on a visual
+value, v1 wins; where v1's source and what v1 actually renders disagree, **what it renders wins**.
+Reproduce v1's defects when they are cosmetic, and say so. Do not reproduce one that makes a
+component non-functional. Every intentional difference needs an explicit, reviewed VR exception.
+
+There is one standing exception, and it is the only one: **leading**. v1's shipped sheet references
+every `--text-*--line-height` unprefixed and so applies none of them, and v2 follows what v1
+declares instead of what it renders. That is decided in `DECISIONS.md` D9, corrected on the v1 arm of
+the VR harness by `V1_DECLARED_LEADING_SHIM`, and dated by `vr/v1-leading-references.test.ts`. Pair
+every `fontSize: tokens.text*` with the matching `lineHeight: tokens.leading*` in the same slot; do
+not read it as licence to prefer v1's source anywhere else.
+
+## Verifying
+
+Run these, by name — not against a remembered count:
+
+```sh
+bun run build          # tokens, tsc, vite
+bun run test           # React 19
+bun run react18:test   # React 18
+bun run gate:vr        # visual regression against v1
+bun run gates          # all architecture gates, fail-fast
+```
+
+Wire your component into `src/index.ts` **before** running the gates: several build the package from
+its entrypoint, so an unexported component is invisible to them and they will pass without having
+seen it.
+
+**A green gate is evidence for the assertions that gate actually makes, and nothing wider.** Every
+gate here has a `GATE_NEGATIVE_CONTROL` mode, documented in its own header, demonstrated to trip
+exactly the checks it should. If you add or strengthen an architectural claim, add a control that
+breaks the property under test and show it failing. A check that cannot fail is worse than no check,
+because it reads as coverage — this suite had two such checks for months.
+
+## Done means
+
+Exported from `src/index.ts`, both suites green, tsc clean, VR specimens covering the component's
+**states** and not merely its default, and gates green. A component with no state-bearing specimens
+is not finished.
+
+## Working agreements
+
+- Do not add dependencies or edit `package.json` unless the task says so explicitly.
+- Do not commit, push, or run any git write command unless asked.
+- Put throwaway probes in `.scratch/` (gitignored) inside this package, never in `/tmp`.
+- Report: file paths, the vitest and tsc results, any literal used for want of a token, any behaviour
+  delta from v1, and anything you were unsure about.

package/AUTHORING.md

@@ -0,0 +1,292 @@
+# Authoring volt-ui-v2 — what went wrong, and why the rules exist
+
+`AGENTS.md` is the brief: what to do, and it is normative. This is the reasoning: what broke, how it was found,
+and what it cost. Every item here is a defect that actually shipped into the branch, and most of them
+passed source review, a green unit suite and a source-level audit before a rendering comparison caught
+them.
+
+Read this before changing a component or adding one. The single most useful thing in it is the pattern
+at the end: **the same class of mistake recurred four times, and it was never caught by reading.**
+
+---
+
+## 1. The engine — four Griffel constraints, all of which fail silently
+
+### 1.1 `&` must be the first token of a selector
+
+Writing `"[data-pressed] &"` reads as "style me when an ancestor is pressed". Griffel does not
+substitute `&` in that position; it prepends its own class to the whole selector and emits:
+
+```css
+.f1y9ypwo[data-pressed] .f1y9ypwo {
+  opacity: 1;
+}
+```
+
+That needs one element to carry the class AND be pressed AND contain a second element with the same
+class. It never matches. No warning, no error, no failing test.
+
+**Cost: fifteen dead declarations across six components**, every one a feature that silently did not
+work — all four of Toast's type colours (every toast looked identical), OptionCard's six
+selected-state glyphs, Label's disabled dimming, Select's chevron rotation.
+
+Only OptionCard's was caught by the visual gate, because it was the only one with a specimen that
+exercised the state. `src/ancestor-selector.test.ts` now forbids the form, and reads source for
+exactly that reason.
+
+**Instead:** declare the rule on the slot of the element that carries the state, and reach the
+descendant by `SLOT_ATTR`:
+
+```ts
+[`&[data-pressed] [${SLOT_ATTR}="option-card-radio-dot"]`]: { opacity: 1 }
+```
+
+If the ancestor belongs to another component, the rule belongs in that component — Label's disabled
+rules live in `field.tsx`. **And there is a real capability loss here:** v1 expresses these with
+Tailwind's `group-data-[…]:` and `peer-disabled:`, which work only because Tailwind emits _global_
+utility classes that can be rooted anywhere. Scoped atomic CSS cannot. A Label used outside a Field,
+next to a disabled input, will not dim.
+
+### 1.2 Declaration order inside a slot encodes precedence
+
+Griffel emits atoms in source order, so a later state selector beats an earlier one. **v1's precedence
+does not come from order** — it comes from Tailwind's utility layer, where `aria-invalid:` beats
+`disabled:` no matter where either sits in the class string.
+
+Transcribing v1's class order therefore inverts the result. Checkbox and Radio both put
+`&[aria-invalid='true']` before `&[data-disabled]`, so a disabled invalid control lost its error
+border to the gray one: 17% and 44% pixel differences on a 16×16 box.
+
+**Put the state that must win last.**
+
+### 1.3 Dedup only happens when the expanded property keys match
+
+OptionCard's card is a `ToggleGroupItem`. Toggle declares `shorthands.paddingInline`; the card
+declared `paddingLeft`/`paddingRight`. Different keys, so both survived and the cascade kept Toggle's
+value — the padding stayed 4px-per-side wrong _after the value itself had been corrected_, which is a
+confusing thing to debug.
+
+Match the neighbour's property shape, not just its value.
+
+### 1.4 A typo'd slot name used to compile
+
+`makeVoltStyles` was generic over the key union:
+
+```
+makeVoltStyles<Slots extends string>(styles: Record<Slots, GriffelStyle>): () => Record<Slots, string>
+```
+
+Inferring a type parameter from `Record<Slots, …>` against an object literal **widens `Slots` to
+`string`**, so the result was `Record<string, string>` and every slot name typechecked — including
+ones that did not exist.
+
+OptionCard read `styles.card` and `styles[layout]` with neither declared. The component rendered with
+**no card styling at all** — v1's card properties had been copied onto the `group` slot and applied to
+the wrong element. `tsc` clean, 322 tests green.
+
+Now generic over the object, so `keyof S` is the real union. It found exactly three errors, all in
+OptionCard: the hole was library-wide, the exploitation was not.
+
+---
+
+## 2. Shipping no reset — v2 inherits nothing v1 got for free
+
+v1's components were never written against a reset either. They inherited whatever the _element Radix
+happened to render_ got from the browser's UA stylesheet. Base UI renders different elements, so v2
+inherits nothing.
+
+**Checkbox rendered 2px wide.** Base UI's root is a `<span>`: `display: inline`, where width and
+height **do not apply at all**. v1's Radix root is a `<button>`, which the UA sheet gives
+`inline-block` and `border-box`. v1's own class list declares neither.
+
+Two further subtleties from the same fix:
+
+- `inline-block` specifically, not `inline-flex`. The box is 16×16 either way, but an inline-flex box
+  takes its baseline from its first flex item and sat the line box 2px taller.
+- Declare `boxSizing` where the element type changed, but **not library-wide**. Where v1 also renders
+  a plain div, both arms are already `content-box` and agree — adding `border-box` there would
+  _create_ a difference. 26 slots across 17 components set a size and a border; only the ones the
+  visual gate flagged were actually wrong.
+
+**The reset does exist in production, but do not rely on it.** `epilot360-root-config` imports
+`tailwindcss/preflight.css` globally at the single-spa root. So `box-sizing: border-box` is there for
+an MFE inside the portal — and absent for one bundled standalone. Explicit declarations are no-ops in
+the first case and load-bearing in the second.
+
+---
+
+## 3. The primitive layer is Radix — and the Base UI detour is why
+
+**Historical. v2 uses Radix, at v1's exact pins.** Nothing in this section is current guidance; it is
+here because the detour cost real time and the reasoning generalises. `src/lib/auto-portal.tsx`, the
+`InsideMenuGroupContext` wrapper and `collectItemLabels` are all deleted — if you find a reference to
+them, it is stale.
+
+v2 was first built on Base UI and rolled back. The measured case against it:
+
+- **2.1x the size** for the same primitive — tooltip 33.9k vs 16.8k gzip.
+- Its shipped types **forced every consumer onto `@types/react` 19**: 312 errors under 18, none of them
+  in our own logic. It was the sole source of that requirement.
+- It needed wrappers Radix does not — `<Dialog.Portal>` is mandatory, `DropdownMenuLabel` must sit
+  inside a `Menu.Group` — so **every overlay in the package rendered nothing**: nine specimens, blank
+  pages, while 321 tests and four isolation gates stayed green. The package's own tests used the
+  explicit composition Base UI documents, which is exactly why they never hit it.
+
+Two lessons that outlive the decision:
+
+- **Silent acceptance of an unsupported option.** `toast("…", { duration: Infinity })` was accepted,
+  did nothing, and reported nothing; all four toast specimens rendered a bare viewport.
+- **Strictness is not uniformly one way.** v1 **throws** on `OptionCardGroup` without a `type` prop
+  where v2 tolerates it silently — so "v2 is more permissive" is not a safe generalisation, and neither
+  is its opposite.
+
+Radix state attributes are what the code uses now: `data-state="checked" | "on" | "open" | "closed"`,
+and enter/exit transitions key on `data-state` rather than on separate start/end hooks.
+
+---
+
+## 4. Rule 0 means v1's OUTPUT, not v1's source
+
+This is the subtlest thing in the package, and it cuts both ways.
+
+**Four v1 production bugs were found here, all one family — the prefixer rewrites definitions and
+misses references:**
+
+1. `--color-level-2`/`-3` point at `--volt-level-2`/`-3`, which nothing defines.
+2. `.volt-text-xs` resolves `line-height: var(--volt-leading, var(--text-xs--line-height))` — the
+   definition ships prefixed, the reference does not, and the unprefixed name is defined nowhere. So
+   **every text utility in v1 computes an invalid line-height and inherits instead.**
+3. Label's `leading-none` never reaches the DOM at all: v1's `cn()` runs tailwind-merge, which treats
+   the later `text-sm` as owning line-height and drops it. Combined with (2), production v1 renders
+   labels at preflight's 1.5 rather than at 1.
+4. ScrollOverflow's viewport declares `[&>div]:!flex` and `[&>div]:!flex-row`, and neither survives
+   the build — so v1's _horizontal_ scroller stacks its children vertically.
+
+**The rule: reproduce the harmless ones, refuse the harmful ones.**
+
+- ScrollOverflow does **not** reproduce bug (4). Matching it would ship a horizontal scroll container
+  that cannot scroll horizontally. That field requires a written reason and prints on every run.
+- Nor does anything reproduce bugs (2) and (3), and that is the one **standing** exception, decided
+  in DECISIONS.md D9. Every slot that sets `fontSize: tokens.text*` also sets the matching
+  `lineHeight: tokens.leading*`, Label included — it follows the `text-sm` its class list actually
+  ships, not the `leading-none` tailwind-merge ate. Bug (2) is not cosmetic: it kills the leading at
+  every one of the seven steps, so reproducing it means shipping a type scale with no vertical
+  rhythm. It is also too wide for an `acceptedDifference` — every specimen containing text would need
+  one — so the VR harness corrects it on the v1 arm instead, once and by name
+  (`V1_DECLARED_LEADING_SHIM` in `vr/run.mjs`, pinned and dated by
+  `vr/v1-leading-references.test.ts`).
+
+Read the exception narrowly. It is about leading and nothing else; everywhere else, output still
+wins.
+
+The same principle settles smaller cases without any bug involved: v1 doesn't style disabled tabs at
+all, so v2's invented `opacity: 0.5` was removed. v1's toast declares `shadow-md` and renders a fully
+transparent one, so v2 has no shadow. v1's OptionCard has a bare Tailwind `border` with no colour
+utility, so its border is `currentColor` — a near-black `rgba(2, 0, 8, 0.88)` that looks like an
+accident and is nevertheless what ships.
+
+**When in doubt, measure the rendered result on both arms. Do not read the class list and infer.**
+
+---
+
+## 5. Retiring a dependency inherits its defaults
+
+Toast's width (356px), corner offset (24px), zero-width border and absent shadow were all **sonner**
+defaults, not choices in v1's source. The port replaced sonner's behaviour and kept Tailwind-flavoured
+values — 24rem, 1rem, a real 1px border, a real shadow — so every toast was 28px too wide, 8px too
+close to the corner, and carried an edge and a shadow v1 does not render.
+
+Nothing but a pixel comparison would have said so. The same exposure applies to `cmdk` in Command,
+which has no v1 export to compare against at all.
+
+---
+
+## 6. The token layer
+
+- **There was no 0.75rem spacing step, and that is why `spacingElement3` now exists.** The scale ran
+  0.25 / 0.5 / 0.5 / 1 / 1.5 / 2 rem while v1 uses Tailwind's `*-3` freely, so authors reached for the
+  nearest-_sounding_ token (`spacingGroup1`, which is **0.5rem**) and silently lost 4px per side.
+  **That exact mistake was found four times** — Toast, Command, Field, SegmentedControl — which made
+  it a scale problem, not four authoring slips. The step was added; use `tokens.spacingElement3`.
+  This paragraph used to end "use the literal `0.75rem`", which was correct only before the token
+  landed. Sizes are still literals: there is no dimension token family, so `width: "0.75rem"` on an
+  svg is not `spacingElement3` — spacing and size are different axes that share a number.
+- **Line-height tokens are v1's own declared values, and they are applied.** This paragraph used to
+  read "deliberately unused", on the reasoning that applying them diverges from what v1 _renders_
+  (§4 bug 2). That was reversed in DECISIONS.md D9: the divergence is from v1's bug, not from v1, and
+  the harness now measures against v1-as-declared. Pair the leading with the size in the same slot,
+  `fontSize` first. Leave alone the slots that already declare a line-height — those are v1
+  `leading-*` utilities that survived tailwind-merge, so they are v1's output as well as its intent.
+- **The namespace segment is derived from the token values.** `--volt2-<hash>-accent-9` changes
+  whenever any token changes; that is what lets two builds coexist on `:root`. **Never hardcode it.**
+  One test did and broke the moment line-height tokens were added.
+- The accessor is 942 **named exports**, not an object literal, because a bundler cannot drop unused
+  properties of a literal. Worth 6.5 kB gzip to every partial consumer. Authoring is unchanged:
+  `import * as tokens` and keep saying `tokens.accentSolid`.
+
+---
+
+## 7. Verifying — where the checks themselves were wrong
+
+A gate that cannot fail is worse than no gate, because it launders an unverified claim. Every one of
+these was a real false pass:
+
+- **Run gates AFTER wiring exports.** `gates/isolation-fixture.tsx` imports the package namespace, so
+  it only inspects what `src/index.ts` exports. Running it on an unwired component is a meaningless
+  pass — that is how Select's `data-slot` violation shipped.
+- **The visual gate reads `dist`.** The first negative control perturbed a padding by 2px and still
+  reported a clean pass, because the edit was in `src`. Staleness is now a hard error.
+- **A blank render is not a match.** Nine overlays rendered nothing while the gate reported
+  "116/124 match", because a blank capture against a mostly-white v1 is a _small_ diff. Uniform
+  captures and thrown pages are now hard failures.
+- **A parse error makes everything pass.** Typechecking a real consumer against v2 reported 0 errors,
+  and a positive control importing a nonexistent name also reported 0 — because the consumer's
+  TypeScript 4.9 could not parse Base UI's `.d.ts`, so the module resolved to an error type. Under TS
+  5.6 the same code reports 148.
+- **A state nobody renders is a state nobody has checked.** That is the whole reason §1.1 needed a
+  source scan on top of the visual gate.
+- **Identical results after a change that should have moved something is a signal.** A patch adding
+  preflight to the harness silently missed its target line; the numbers came back byte-identical and
+  only a direct `box-sizing` measurement caught it.
+- **A test that passes in the file and fails alone has not passed.** Four overlay dismissal tests were
+  green under React 19 and red under React 18, and the component behaved _identically_ in both. Run
+  the suspect test with `-t` before you believe either colour: all four also failed under React 19 in
+  isolation. Three defects were stacked, each masking the next — see §7.1.
+
+### 7.1 The three that hid behind each other
+
+Worth reading as a set, because no single one of them was visible while the others stood:
+
+1. **Testing Library's auto-cleanup never ran.** It self-registers only when the framework's
+   `afterEach` is a global, and neither vitest config sets `globals: true`. Test files had compensated
+   with `document.body.innerHTML = ""`, which detaches nodes without unmounting roots. Radix delivers
+   Escape only to the topmost `DismissableLayer`, so layers left behind by earlier tests swallowed the
+   key. The tell was `data-scroll-locked="3"` on a page containing one dialog.
+   Now registered explicitly in `src/setup.testing-library.ts`, in both configs.
+2. **The removal assertion could not pass on its own merits.** Radix's `Presence` holds a closed node
+   until `animationend`, and jsdom runs no animations. `fireEvent.animationEnd` does not fix it:
+   jsdom implements no `AnimationEvent`, so Testing Library falls back to a plain `Event` and drops
+   `animationName` — precisely the field `Presence` gates on. Construct the event by hand
+   (`src/overlay-test-helpers.ts`). Asserting `data-state="closed"` instead would be vacuous: that
+   attribute is set before `Presence` decides anything.
+3. **Tooltip's Escape raced its own listener.** Radix attaches it in an effect, and the `waitFor`
+   resolved on DOM presence — under React 18, before that effect ran, so the keydown landed with
+   nothing listening. `await act(async () => {})` first. React 19 flushed early enough to hide it.
+
+The general shape: **a version-dependent test result is a claim about the test, until you have shown
+the component behaves differently.** Here it never did.
+
+---
+
+## 8. The pattern worth internalising
+
+Four separate times, the same 4px spacing error. Fifteen dead selectors of one shape. Every overlay
+non-functional. A component with no styling at all. None of it was found by reading code — not by
+source review, not by unit tests, not by three source-level audit passes that each found _other_ real
+defects.
+
+All of it was found by rendering both versions and comparing pixels.
+
+So: **when you change a component, run `bun run gate:vr`.** When you add one, add specimens for its
+states, not just its default. And when a check comes back clean on something that has been wrong
+before, find out whether the check can fail at all.

package/README.md

@@ -137,9 +137,14 @@ fails on the insertion-point count and `gate:class-salt-skew` fails on atom-name
 
 ## What is not here
 
-`DataTable` is not ported and stays on v1. It is the only component still missing, and the only gap
-in what consumers actually import: of 143 distinct Volt symbols used across shipped MFE code, this
-package covers 127, and all 16 it does not are DataTable or a TanStack type it re-exports.
+`Collapsible` has no equivalent here, and neither does v1 — depend on `@radix-ui/react-collapsible`
+directly, as both pilot MFEs do.
+
+**Corrected in 0.2.2:** this section used to say `DataTable` was unported and "the only component
+still missing". It has shipped since 0.2.0 — `DataTable`, `DataTableBody`, `DataTableContent`,
+`DataTableHeader`, `DataTableLoading`, `DataTableError` and `TablePagination` are all exported. The
+stale sentence cost real work: the Variable Builder read it and hand-built its list page on the
+`Table` primitives.
 
 There is no `--volt-*` compatibility layer. Consumer CSS reading v1's variable names by hand needs
 migrating to this package's exported token bindings — 217 references across six MFEs, two thirds of
@@ -148,6 +153,73 @@ them in `entity`.
 Animation is unverified. The visual harness disables it on both arms, so transitions are the one thing
 264 matching specimens do not cover.
 
+## Treatments: stamp the document element, not a subtree
+
+Role tokens resolve per treatment through `[data-surface="…"]` blocks. Those are **bare attribute
+selectors**, not `:root[data-surface=…]`, so the stamp cascades from whatever element carries it —
+and that invites putting it on a micro-frontend root. Don't.
+
+`Popover`, `Select`, `Tooltip`, `Dialog` and `DropdownMenu` render their content into
+`document.body`. Griffel's atomic classes are global and travel with the element, but token
+**values** are custom properties resolved against the element's ancestors, and portalled content is
+no longer inside your stamped subtree. It resolves against `:root` instead. So a `glass` panel would
+open a `plain` popover, silently, with no error and nothing in the DOM to suggest why.
+
+```js
+// Right — every portal is a descendant of this.
+document.documentElement.setAttribute("data-surface", "glass")
+
+// Wrong — the popover this panel opens escapes the stamp.
+mfeRoot.setAttribute("data-surface", "glass")
+```
+
+Two consumers have not hit this, and only because `plain` is the `:root` default: the role values in
+the bare `:root, .light, [data-theme="light"]` block are identical to `[data-surface="plain"]`, so a
+`plain` consumer needs no stamp at all and a portal that falls back to `:root` lands on the same
+values. The first consumer to stamp `bordered`, `glass`, `tint` or `card` on a subtree is the first
+to see it.
+
+Propagating the stamp onto portalled roots would remove the constraint, and is not done here: it
+would mean every portal component reading its trigger's nearest `[data-surface]` at mount, which is
+five components, a new failure mode when the trigger is not yet mounted, and a behaviour change for
+a case no consumer has reached. The **document boundary** pattern is the same mechanism used
+deliberately — customer content stamps `data-theme="light"` plus a treatment on its own root so it
+keeps its mode inside a dark page.
+
+## Testing
+
+The package is ESM-only, and Jest 26 and 27 ignore the `exports` field. Before 0.2.2 that made a
+bare import resolve to nothing: `Cannot find module '@epilot/volt-ui-experimental-griffel'`, in a
+suite that had been green only because no test rendered one of these components yet. 0.2.2 adds a
+`main` field, so those resolvers find `dist/index.js` themselves.
+
+What they still need is a transform, because the file is ESM and Jest's default
+`transformIgnorePatterns` skips everything under `node_modules`. Take it from here:
+
+```js
+// jest.config.js
+const griffel = require("@epilot/volt-ui-experimental-griffel/testing/jest-preset.cjs")
+
+module.exports = griffel.withGriffel(
+  {
+    preset: "ts-jest",
+    transform: { "^.+\\.(ts|tsx)$": ["ts-jest"] },
+  },
+  { alsoTransform: ["@xyflow"] }
+)
+```
+
+`withGriffel` replaces `transformIgnorePatterns` outright rather than appending to it, because Jest
+ignores a file when **any** pattern matches — so an added pattern can never un-ignore what the
+default `/node_modules/` already caught. Anything else you need transformed out of `node_modules`
+goes in `alsoTransform`. Needs `babel-jest` and `@babel/preset-env` as devDependencies.
+
+**There is no CommonJS build, deliberately.** The runtime holds module-level state: the `installed`
+Set that dedups token sheets, and one shared renderer. A dual ESM/CJS package would hand a consumer
+two copies of both, breaking the single-insertion-point and single-renderer properties that
+`gate:isolation` and `gate:griffel-contract` exist to assert. One format is a correctness
+requirement here. See `DECISIONS.md` D13.
+
 ## Verification
 
 Every check below has a `GATE_NEGATIVE_CONTROL` mode that has been demonstrated to fail when the
@@ -164,10 +236,16 @@ fail-fast. A green gate is evidence for that gate's own assertions and nothing w
 | `bun run gate:griffel-contract` | `insertionCache` still dedups, and every copy resolves the same renderer                          |
 | `bunx vitest run`               | 493 tests, plus 497 under React 18                                                                |
 
-`AGENTS.md` is the normative rule set and overrides every other document in the package. `AUTHORING.md`
-states the defect behind each rule. `DECISIONS.md` holds the architecture rationale. `STATUS.md` is a
-dated snapshot of measurements — more current than this file on numbers, but not authoritative on
-rules.
+`AGENTS.md` is the normative rule set and overrides every other document in the package.
+`AUTHORING.md` states the defect behind each rule. **Both ship in the tarball as of 0.2.2** — before
+that this paragraph cited four documents that `files` excluded, so a consumer was told the normative
+rules existed and had no way to read them.
+
+The other two stay in the repository, on branch
+[`experiment/griffel`](https://gitlab.com/e-pilot/product/frontend/volt-ui/-/tree/experiment/griffel):
+`DECISIONS.md` at the root holds the architecture rationale, and
+`packages/experimental-griffel/STATUS.md` is a dated snapshot of measurements — more current than
+this file on numbers, but not authoritative on rules.
 
 ## Releasing
 

package/dist/components/alert-dialog/alert-dialog.js

@@ -5,7 +5,7 @@ import { shorthands as c } from "../../packages/volt-runtime/dist/vendor/@griffe
 import { SLOT_ATTR as n } from "../../packages/volt-runtime/dist/renderer/contract.js";
 import { mergeClasses as d } from "../../packages/volt-runtime/dist/vendor/@griffel/core/src/mergeClasses.js";
 import { makeVoltStyles as v } from "../../styles/make-styles.js";
-import { spacingGroup2 as f, grayA1 as N, grayA11 as z, leadingSm as F, textSm as W, grayA12 as O, fontWeightSemibold as H, leadingXl as P, textXl as X, containerXl as j, containerLg as k, containerMd as _, containerSm as I, body as L, spacingElement2 as p, radiusXl as B } from "../../tokens/index.js";
+import { spacingElement2 as f, spacingGroup2 as p, grayA1 as N, radiusXl as z, grayA11 as F, leadingSm as W, textSm as O, grayA12 as H, fontWeightSemibold as P, leadingXl as X, textXl as j, containerXl as k, containerLg as _, containerMd as I, containerSm as L, body as B } from "../../tokens/index.js";
 import { Button as u } from "../button/button.js";
 const g = v({
   overlay: {
@@ -34,7 +34,7 @@ const g = v({
     }
   },
   content: {
-    backgroundColor: L,
+    backgroundColor: B,
     position: "fixed",
     top: "50%",
     left: "50%",
@@ -43,10 +43,10 @@ const g = v({
     display: "grid",
     width: "100%",
     maxWidth: "calc(100% - 2rem)",
-    ...c.gap(f),
-    ...c.borderRadius(B),
+    ...c.gap(p),
+    ...c.borderRadius(z),
     ...c.border("1px", "solid", N),
-    ...c.padding(f),
+    ...c.padding(p),
     // v1 shadow-lg
     boxShadow: "0 10px 15px -3px #0000001a, 0 4px 6px -4px #0000001a",
     outlineStyle: "none",
@@ -80,40 +80,40 @@ const g = v({
     }
   },
   sm: {
-    maxWidth: I
+    maxWidth: L
   },
   md: {
-    maxWidth: _
+    maxWidth: I
   },
   lg: {
-    maxWidth: k
+    maxWidth: _
   },
   xl: {
     "@media (min-width: 640px)": {
-      maxWidth: j
+      maxWidth: k
     }
   },
   header: {
     display: "flex",
     flexDirection: "column",
-    ...c.gap(p),
+    ...c.gap(f),
     textAlign: "left"
   },
   footer: {
     display: "flex",
-    ...c.gap(p),
+    ...c.gap(f),
     justifyContent: "flex-end"
   },
   title: {
-    fontSize: X,
-    lineHeight: P,
-    fontWeight: H,
-    color: O
+    fontSize: j,
+    lineHeight: X,
+    fontWeight: P,
+    color: H
   },
   description: {
-    fontSize: W,
-    lineHeight: F,
-    color: z
+    fontSize: O,
+    lineHeight: W,
+    color: F
   }
 }), Y = i.forwardRef(
   function(t, a) {