@agent-ui-kit/components 0.0.3

package/dist/controls/card/card.css

@@ -0,0 +1,445 @@
+/* card.css — the SINGLE-file stylesheet for the whole ui-card family (ADR-0003 one-sheet-per-folder):
+ * ui-card + ui-card-header / ui-card-content / ui-card-footer. Sectioned, one TOKEN `:where()` block + one
+ * STYLES block per element, mirroring button.css / text-field.css (declaration vs consumption split).
+ *
+ * Role-purity (ADR-0008 / tokens.md): the `--md-sys-color-*` colour roles and the shared `--md-sys-space-*` / `--md-sys-shape-corner-base`
+ * ramps enter ONLY in the `:where()` TOKEN blocks (the variable-definition side); every STYLES block (`@scope` /
+ * the region anatomy) consumes ONLY the element's own `--ui-card-*` chain plus the role-pure container surface
+ * seam `--ui-container-bg` (ADR-0015 cl.2 — the cross-family surface seam, not a raw role). A card holds zero
+ * colour opinion; forced-colors is handled by the role layer + the block at the foot.
+ *
+ * Surface (ADR-0015): ui-card sits on the shared container seam (controls/_surface/container.css paints
+ * `background-color: var(--ui-container-bg)` and maps [elevation]/[brightness] for the family). The base default
+ * is `transparent`; a card seeds its OWN default `--ui-container-bg: var(--md-sys-color-neutral-surface)` below so an
+ * UN-elevated card still reads as a surface (card.css is `@import`-ed AFTER container.css in s12 — later source,
+ * equal `:where()` specificity, wins).
+ *
+ * Nested radius (ADR-0018, one level): the concentric-corner law is `r_child = max(0, r_parent − pad_parent)`.
+ * The literal ADR formula (a card both reads AND declares `--ui-card-child-radius`) is a SELF-REFERENTIAL custom
+ * property — a CSS cycle (guaranteed-invalid), the exact failure ADR-0018 records. The cycle-free realization of
+ * the SAME seam: a card computes its own inner radius (`--ui-card-inner-radius`, NOT read back into its radius)
+ * and PUBLISHES it to its DESCENDANTS as `--ui-card-child-radius` (the `:where(ui-card) > *` rule — set on the
+ * children, never on self, so the publishing card never reads what it writes). A nested card (inside a region)
+ * reads the INHERITED `--ui-card-child-radius` for its own radius → one-level decrement, no cycle. The normal
+ * structure is card › ui-card-content › card; a card nested DIRECTLY inside another card (no region wrapper
+ * between, regardless of whether the outer card is bare or region-bearing) is the depth-≥2 manual case (set
+ * an explicit border-radius to reseed) — documented in card.md. The direct-child card matches BOTH
+ * `:where(ui-card)` (declaring its OWN `--ui-card-inner-radius`) and its parent's `:where(ui-card) > *` publish
+ * rule (setting `--ui-card-child-radius` directly ON it) — a genuine multi-property CYCLE
+ * (radius → child-radius → inner-radius → radius) collapses its radius to 0, independent of any padding value.
+ * ADR-0056's fallback below only ever sets padding/gap — it does not touch this chain, so it neither fixes nor
+ * worsens the pre-existing manual case (re-verified, card.browser.test.ts).
+ *
+ * REVISED 2026-07-04 (Kim, the region-inset pass): the card-only 6px inline-padding override is RESCINDED — a
+ * card now reads container-box.css's shared region defaults straight (inline 12px / block 6px), same as
+ * modal/select/menu/combo-box (one spacing vocabulary, restoring ADR-0046's original intent). Region padding
+ * going from 6px inline to 12px means `--ui-card-inner-radius` (below) now decrements against a LARGER value —
+ * with the default `--md-sys-shape-corner-base` of 12px, the inner radius floors at EXACTLY 0 for an unreseeded root card
+ * (12 − 12 = 0, a knife-edge, not the old 6px-positive headroom). This is a real visual consequence of removing
+ * the override, not a bug: an author who wants a visibly rounded nested corner now needs to reseed
+ * `--ui-card-radius` larger than 12px. Flagged for Kim; not silently patched around.
+ *
+ * Region-less humane default (ADR-0056): a card with NO region child (no header/content/footer) applies the
+ * region-equivalent padding + content rhythm to its OWN box (the `:not(:has(...))` leg in the STYLES block
+ * below) — a bare-children card, the wild-payload DEFAULT an LLM emits against a catalog whose Card has no
+ * region sub-types, reads as padded instead of the box-model's zero-padding law. `:has()` re-evaluation is
+ * streaming-safe by construction: a region child arriving late flips the fallback off and the presence-driven
+ * row template on in the same reflow, no double padding, no synthetic DOM (payload tree ≡ DOM tree). Mixed
+ * composition (a region PLUS loose siblings) does NOT match — regions present means the author owns the
+ * structure; the loose siblings render at the box-model default (documented, not repaired).
+ *
+ * Standalone sheet — linked via the component-styles barrel (s12), NEVER injected from card.ts (behaviour-only
+ * `.ts`, no runtime style; plan §2). */
+
+/* ════════════════ [ui-card] TOKEN BLOCK — :where(ui-card) declares the chain ════════════════ */
+
+:where(ui-card) {
+  /* Surface: the card's OWN default plane (the base seam defaults transparent — ADR-0015 cl.1). [elevation]/
+     [brightness] still repoint this via container.css; this is only the un-elevated default. */
+  --ui-container-bg: var(--md-sys-color-neutral-surface);
+
+  /* Layout spacing — the container BOX-MODEL (container-box.css, REVISED 2026-07-04): the card holds NO
+     padding (the shell law). A region (header/content/footer) carries the SAME uniform inset margin every
+     other [data-box] child gets, PLUS its own region padding. The card-only 6px-inline override is RESCINDED:
+     card reads container-box.css's shared region defaults straight (inline 12px / block 6px), matching
+     modal/select/menu/combo-box exactly (one spacing vocabulary). The DEFAULT (non-scroll) shell is plain BLOCK
+     FLOW (a flow-root BFC, like every other [data-box]) — NOT grid/flex (Kim: "containers should not use grid
+     or flex; let contents space themselves"): regions stack in normal flow (an absent region leaves no box →
+     presence-driven for free) and their uniform 6px margins COLLAPSE to clean 6px gutters, the 1px frame border
+     blocking collapse-through at the edges. No grid gap, no first/last margin split, no :has() row templates
+     needed.
+     SCROLL MODE (@scope, `[scrollable]`) is DIFFERENT (REVISED 2026-07-07, Kim, verbatim: "<ui-card-content>
+     should have the mask and manage overflow ... it should be set to use 100% of its parent height when
+     [scrollable]" — SUPERSEDES the short-lived WRAPPER MODEL, 2026-07-06): `ui-card-content` itself becomes the
+     scroll viewport (no author-written wrapper child any more), and the header/footer become OVERLAID PEERS
+     (`position: absolute`) rather than in-flow items — see the @scope STYLES block below for the full mechanism
+     and why the shell still needs `display: flex` even though header/footer no longer participate in it.
+     THE SCROLLBAR IS HIDDEN (Kim, 2026-07-08, resolving the mask-fades-the-scrollbar tension with a third
+     option: "keep native, but hide it" — ADR-0046 Amendment 6): no visible bar means nothing for the mask to
+     fade in the first place; native wheel/trackpad/keyboard scrolling is unaffected. Losing the visible bar
+     as a scroll affordance/keyboard entry point is why card-content.ts gives the region an explicit
+     tabindex=0 in scroll mode (WCAG 2.1.1) — see that file and the STYLES block below. */
+  --ui-card-padding: 0;
+  --ui-card-region-margin: var(--ui-box-inset, 0.375rem); /* 6px — the uniform inset margin around each region */
+  --ui-card-region-pad-inline: var(--ui-box-pad-inline, 0.75rem); /* 12px — shared region inline padding */
+  --ui-card-region-pad-block: var(--ui-box-pad-block, 0.375rem); /* 6px — shared region block padding */
+  --ui-card-content-gap: var(--ui-box-gap, 0.5rem); /* 8px region rhythm between content children */
+
+  /* Frame: the neutral hairline border + the corner radius. The radius reads the inherited
+     --ui-card-child-radius a PARENT card published (one-level nesting, ADR-0018), else the shared
+     --md-sys-shape-corner-base (a root card — the channel is unset → the fallback). */
+  --ui-card-border: var(--md-sys-color-neutral-outline-variant);
+  --ui-card-radius: var(--ui-card-child-radius, var(--md-sys-shape-corner-base));
+
+  /* The card's INNER radius (the concentric-corner law) — the value handed down to a nested card. Under the
+     box-model the inset is the CONTENT region's inline padding (a nested card lives inside ui-card-content),
+     so the chain re-bases off that, NOT the (now-zero) card padding. Not read back into --ui-card-radius → no
+     self-referential cycle (ADR-0018). */
+  --ui-card-inner-radius: max(0px, calc(var(--ui-card-radius) - var(--ui-card-region-pad-inline)));
+}
+
+/* PUBLISH the child radius ONE level (ADR-0018): hand every direct child the card's inner radius as the
+   inherited --ui-card-child-radius. Set on the CHILDREN (`> *`), never on the card itself, so the publishing
+   card never reads the property it writes (the cycle-free realization of the published seam). A nested card —
+   normally inside ui-card-content — inherits this through the region wrapper and reads it for its own radius. */
+:where(ui-card) > * {
+  --ui-card-child-radius: var(--ui-card-inner-radius);
+}
+
+/* ════════════════ [ui-card] STYLES — @scope (ui-card) consumes ONLY --ui-card-* ════════════════ */
+
+@scope (ui-card) {
+  /* The surface container: regions stack in plain BLOCK FLOW (a flow-root BFC — NOT grid/flex, per Kim's
+     "containers should not use grid or flex; let contents space themselves"). The surface PAINT rides the
+     shared container seam (container.css); here we own the frame (border/radius) and the region inset. */
+  :scope {
+    display: flow-root;
+    box-sizing: border-box;
+
+    padding: var(--ui-card-padding);
+    border: 1px solid var(--ui-card-border);
+    border-radius: var(--ui-card-radius);
+    /* min-inline-size: 0 — RETAINED, ADR-0100 cl.3 (the audited "Defect B" is DISPOSITIONED, not patched): the
+     * tile-crush the visual audit attributed to this floor is actually ADR-0100 cl.1's containment defect
+     * end-to-end (measured: a `min-content` floor renders the IDENTICAL crushed width under containment, and
+     * is equally irrelevant once containment is fixed — the wrap-row tiles land at their real content size,
+     * ~176–180px, with or without this floor). The declaration's own scenario IS real and measured: in a
+     * `ui-grid` track, a card with unbreakable content held the exact 200px track at `0` and BLEW OUT to
+     * 484.2px with a `min-content` floor — the "composes under any parent (a grid cell)" behavior ADR-0030
+     * already leans on. So `0` stays: it is NOT binding in the crush (nothing to fix) and IS protective in
+     * grid tracks (a floor would break them). Residual, accepted: a `reflow="locked"` nowrap row narrower than
+     * the sum of its cards' min-contents still crushes them below min-content — the tiles regression leg
+     * (card.browser.test.ts) watches for the crush class returning, it does not chase this named exotic case
+     * (the default row stacks below 24rem before that window opens). */
+    min-inline-size: 0;
+  }
+
+  /* Region INSET (REVISED 2026-07-04, block-flow): every region floats inside the frame with a uniform 6px
+     gutter, the same as every other [data-box] consumer (container-box.css). In the card's block-flow BFC the
+     adjacent region margins COLLAPSE (6px between siblings) and the 1px frame border blocks collapse-through
+     at the top/bottom edges (6px there too) — so ONE uniform margin gives clean 6px gutters everywhere; no
+     grid, no first/last split, no row templates. An ABSENT region simply contributes no box (presence-driven
+     for free — block flow, not a :has() grid template). */
+  :scope > :where(ui-card-header, ui-card-content, ui-card-footer) {
+    margin: var(--ui-card-region-margin);
+  }
+
+  /* Region-less humane default (ADR-0056): NO region child present → apply the region-equivalent PADDING +
+     content rhythm to the card's own box (the same OWN-ink-padding a real region would carry: inline 12 · block
+     6 · gap 8 — REVISED 2026-07-04, was 6·6·8 under the rescinded card-only override). This mirrors a region's
+     own padding, not its total frame-to-ink distance (a real region ALSO sits behind a 6px margin the bare
+     card's single flattened box has no equivalent layer for) — deliberately the simpler of the two readings;
+     flag to Kim if full margin+padding parity is wanted instead. Higher selector specificity than the base
+     `:scope` rule above wins outright (an extra :not(:has()) clause,
+     the same pattern the row legs already use), so this leg overrides the box-model's zero padding/gap ONLY
+     when it applies. The moment any region child exists, `:has()` re-evaluates false and this leg drops —
+     no double padding, no phantom transition state (streaming-safe). Mixed composition (a region present PLUS
+     loose siblings) is excluded by the same :has() test — regions present means the author owns the layout. */
+  :scope:not(:has(> ui-card-header, > ui-card-content, > ui-card-footer)) {
+    padding-inline: var(--ui-card-region-pad-inline);
+    padding-block: var(--ui-card-region-pad-block);
+  }
+  /* loose-child rhythm = adjacent-sibling margin (the shell is block flow now, not a grid/flex `gap`). */
+  :scope:not(:has(> ui-card-header, > ui-card-content, > ui-card-footer)) > * + * {
+    margin-block-start: var(--ui-card-content-gap);
+  }
+
+  /* SCROLL MODE — HEADER/FOOTER AS OVERLAID PEERS (REVISED 2026-07-07, Kim, verbatim: "<ui-card-content> should
+     have the mask and manage overflow, and adjust block-padding and linear gradient coordinates based on
+     presence of the peer footer and header. it should be set to use 100% of its parent height when
+     [scrollable]"). SUPERSEDES the short-lived WRAPPER MODEL (2026-07-06): no author-written `[scroll-wrapper]`
+     child any more — `ui-card-content` itself is now the ONE box that scrolls AND carries the mask.
+     `position: relative` anchors the header/footer (below, now `position: absolute` — removed from flow
+     entirely, no longer flex items). The shell still needs `display: flex; flex-direction: column` — NOT
+     dropped, despite the brackets leaving flex — because it is the SIZING MECHANISM that realizes "100% of
+     parent height": plain block layout's `height: 100%` on an auto-height parent bounded only by
+     `max-block-size` computes to 'auto', not 100% (the classic CSS percentage-height gap — a `max-height` alone
+     is never a "specified" height for a child's percentage resolution); flexbox explicitly carves out this case
+     for a flex item's used size. With header/footer no longer flex items, `ui-card-content` is the shell's SOLE
+     item — `flex: 1 1 auto` (below) is what actually fills the whole column; `display: flex` here is the
+     necessary plumbing, not new visual structure. No `gap`/`padding` needed on the shell any more (those existed
+     only to space THREE flex items without doubling the block-flow default's margin-collapse; one item needs
+     neither). */
+  :scope[scrollable],
+  :scope:has(> ui-card-content[scrollable]) {
+    position: relative;
+    isolation: isolate;
+    display: flex;
+    flex-direction: column;
+  }
+
+  /* Content's own 6px region margin (the block-flow default, above) — split by AXIS in scroll mode (Kim,
+     verbatim: "for contents of <ui-card-content ...> do not lose the default margins" — a screenshot caught
+     content's text sitting ~6px LEFT of the header/footer text once this went to `margin: 0` wholesale).
+     BLOCK (top/bottom) stays zeroed: it would otherwise shrink content away from "100% of parent" (the flex
+     item's margin box, not just its border box, fills the column), AND double-stack against the block-padding
+     bracket-clearance formula below (`max(band, plain-pad)` already reserves the exact vertical gutter a
+     present header/footer needs — `scroll-fade.ts`'s `bandOf()` measures the BRACKET's own rendered size, not
+     content's, so it does not shrink back if content also gained a margin here). INLINE (left/right) is KEPT at
+     the shared region margin — content is the flex item's CROSS-axis (column direction), so a left/right margin
+     only insets its stretched width, it does not touch the block/main-axis sizing at all — and it is what makes
+     content's text align with the header/footer text (which keep their own margin unchanged, below), both
+     reading at the SAME 6px+12px = 18px inset from the card's inner edge, matching the non-scroll shell. Header/
+     footer, below, were never zeroed (see their own rule for why). Higher specificity (an extra
+     `[scrollable]`/`:has()` clause) wins outright over the generic `> :where(ui-card-header, ui-card-content,
+     ui-card-footer) { margin: ... }` rule above. */
+  :scope[scrollable] > :where(ui-card-content),
+  :scope:has(> ui-card-content[scrollable]) > :where(ui-card-content) {
+    margin-block: 0;
+    margin-inline: var(--ui-card-region-margin);
+  }
+
+  /* Header/footer become OVERLAID PEERS — `position: absolute`, pinned to the card's inline edges and ONE
+     block edge each — removed from flow entirely (so `ui-card-content`, above, becomes the shell's sole flex
+     item and can fill the whole column). They KEEP their existing 6px region margin (the generic `> *` rule
+     earlier in this file, unaffected here): for an absolutely positioned box, `margin` still offsets it INWARD
+     from its resolved inset edges, so `inset-inline: 0` + a 6px margin nets the SAME floating 6px-inset look
+     the family's regions always carry, just out-of-flow now. NO background (Kim: the brackets stay see-
+     through) — `ui-card-content`'s own mask (below) fades content to transparent as it passes beneath a
+     bracket, so a transparently-backed header/footer shows the card's own surface through faded content, never
+     a hard bleed ("the gradient carries the occlusion"). `z-index: 1` is a defensive no-op here (a positioned
+     box already paints after a static in-flow sibling regardless of z-index) but matches the family's standing
+     bracket convention. */
+  :scope[scrollable] > :where(ui-card-header),
+  :scope:has(> ui-card-content[scrollable]) > :where(ui-card-header) {
+    position: absolute;
+    inset-inline: 0;
+    inset-block-start: 0;
+    z-index: 1;
+  }
+  :scope[scrollable] > :where(ui-card-footer),
+  :scope:has(> ui-card-content[scrollable]) > :where(ui-card-footer) {
+    position: absolute;
+    inset-inline: 0;
+    inset-block-end: 0;
+    z-index: 1;
+  }
+
+  /* `ui-card-content` IS the scroll viewport now (no separate wrapper, no separate paint target) — `flex: 1 1
+     auto` is the mechanism realizing "100% of parent height" (see the shell banner above); `min-block-size: 0`
+     overrides the flex-shrink floor so genuinely tall content can compress below its natural height and become
+     internally scrollable, rather than forcing the card to grow (an item whose `overflow` is non-`visible`
+     already gets an automatic min-size of 0 per spec, but the explicit override matches this family's
+     belt-and-suspenders style). The block-PADDING — NOT the outer flex size — is what clears the overlaid
+     brackets: `padding-block-start`/`-end` read `--ui-card-box-head`/`--ui-card-box-foot` (the TOKEN block
+     above — the SAME measured bracket bands the gradient offset, container-box.css, already consumes via their
+     un-namespaced `--ui-box-*` source) — ONE measured source drives BOTH, per Kim's ask. `max(band, plain-pad)`
+     collapses correctly either way: a PRESENT bracket's band is always well over the plain 6px region pad, so
+     the band wins (content clears the bracket exactly); an ABSENT bracket publishes 0px, so the plain 6px
+     region pad wins instead — "clears a present header/footer; else the plain region padding". */
+  :scope[scrollable] > :where(ui-card-content),
+  :scope:has(> ui-card-content[scrollable]) > :where(ui-card-content) {
+    flex: 1 1 auto;
+    min-block-size: 0;
+    overflow-y: auto;
+    padding-block-start: max(var(--ui-card-box-head), var(--ui-card-region-pad-block));
+    padding-block-end: max(var(--ui-card-box-foot), var(--ui-card-region-pad-block));
+    scrollbar-width: none; /* Firefox / the standard property — HIDE the native scrollbar (Kim's third
+                              option, 2026-07-08: "keep native, but hide it" — no visible bar for the mask to
+                              fade at all; native wheel/trackpad/keyboard scrolling is UNCHANGED, `overflow-y:
+                              auto` above still does the scrolling. The fade becomes the sole scroll
+                              affordance — its intended job all along. Keyboard operability moves to
+                              card-content.ts's own tabindex=0 wiring (a hidden-scrollbar region needs an
+                              explicit tab stop — see that file). */
+  }
+  /* Chromium/WebKit's own scrollbar-hiding hook — a separate rule (pseudo-elements cannot join a normal
+     declaration block). Scoped identically to the rule above (both scroll-mode triggers). */
+  :scope[scrollable] > :where(ui-card-content)::-webkit-scrollbar,
+  :scope:has(> ui-card-content[scrollable]) > :where(ui-card-content)::-webkit-scrollbar {
+    display: none;
+  }
+
+  /* Focus ring (ADR-0009, component-review, 2026-07-08 — the GO-blocker on the scrollbar-hide pass): hiding
+     the scrollbar made ui-card-content a genuine keyboard tab stop (card-content.ts's tabindex=0), and every
+     fleet control that can take keyboard focus draws the SAME shared ring — this region is no exception. The
+     colour/width read the identical fleet constants every sibling reads (checkbox.css is the fleet
+     reference) — `--md-sys-color-focus-ring` / `--md-sys-state-focus-ring-width`, never a per-control repoint.
+     THE RING PAINTS ON THE PARENT CARD, not on ui-card-content itself (Kim, 2026-07-08, superseding an
+     earlier inset/negative-offset draft): `:has(> ui-card-content:focus-visible)` lets the card react to its
+     content region's focus state and draw the ring around the WHOLE card instead. This sidesteps the clipping
+     problem entirely rather than working around it — ui-card-content is an `overflow-y: auto` scroll
+     container, so a ring on IT gets clipped by its own overflow (measured: a positive-offset ring there
+     painted nothing); ui-card itself has no such overflow, so its ring uses the STANDARD fleet-positive
+     (outward) offset like every other consumer — no sign flip, no divergence. `:focus-visible` (not `:focus`)
+     keeps it keyboard-only, matching the rest of the fleet. */
+  :scope[scrollable]:has(> ui-card-content:focus-visible),
+  :scope:has(> ui-card-content[scrollable]:focus-visible) {
+    outline: var(--md-sys-state-focus-ring-width) solid var(--md-sys-color-focus-ring);
+    outline-offset: var(--md-sys-state-focus-ring-offset);
+  }
+}
+
+/* ════════════════ [ui-card-header / -footer] TOKEN + anatomy — the host-as-grid ════════════════ */
+
+/* The header/footer reuse the family leading/label/trailing anatomy (anatomy.md / ADR-0006): a presence-driven
+   `:has()` host-as-grid where the `slot` PLACES (leading start cell · the default/label `1fr` centre · trailing
+   end cell). A Container-class region has NO control height, so the adornment cells size INTRINSICALLY (`auto`)
+   — the structure is reused, not the control-frame glyph sizing. A region that paints a fill now rounds ALL
+   FOUR of its own corners to the card's INNER radius (below) — REVISED 2026-07-04: a region is inset, not
+   full-bleed, so it no longer meets the card's outer edge at all. */
+:where(ui-card-header, ui-card-footer) {
+  --ui-card-region-gap: var(--md-sys-space-sm); /* adornment↔label column-gap (off the --md-sys-space ladder) */
+
+  display: grid;
+  grid-template-columns: 1fr; /* [label] — slotless */
+  align-items: center;
+  column-gap: var(--ui-card-region-gap);
+  border-radius: var(--ui-card-inner-radius); /* a region floats inset inside the frame (@scope margin rules
+                                                  above) — round it like the small concentric surface it now is,
+                                                  not clipped to the outer card radius (REVISED 2026-07-04) */
+  /* Box-model region padding — inline 12 / block 6, the shared container-box.css default (no card override
+     anymore); this is the region's OWN ink inset, separate from its 6px positional margin set in @scope above. */
+  padding-inline: var(--ui-card-region-pad-inline);
+  padding-block: var(--ui-card-region-pad-block);
+}
+
+/* [leading | label] — auto 1fr */
+:where(ui-card-header, ui-card-footer):has(> [slot='leading']):not(:has(> [slot='trailing'])) {
+  grid-template-columns: auto 1fr;
+}
+/* [label | trailing] — 1fr auto */
+:where(ui-card-header, ui-card-footer):has(> [slot='trailing']):not(:has(> [slot='leading'])) {
+  grid-template-columns: 1fr auto;
+}
+/* [leading | label | trailing] — auto 1fr auto */
+:where(ui-card-header, ui-card-footer):has(> [slot='leading']):has(> [slot='trailing']) {
+  grid-template-columns: auto 1fr auto;
+}
+
+/* ════════════════ [ui-card-content] TOKEN + STYLES — the body + scroll ════════════════ */
+
+:where(ui-card-content) {
+  /* Box-model content region — inset (its 6px positional margin is set in @scope (ui-card) above), with the
+     region's OWN inline 12 / block 6 padding — REVISED 2026-07-04: the card-only 6/6 override is gone; content
+     reads the shared container-box.css 12/6 default like every other family member. `display: block` is the
+     DEFAULT (non-scroll) shape — a normal block region that stacks in the card's flow. SCROLL MODE (REVISED
+     2026-07-07 — supersedes the short-lived WRAPPER MODEL) repoints `display`/`overflow`/the block-padding per
+     @scope (ui-card) above: content becomes the shell's sole flex item (`flex: 1 1 auto`, filling the whole
+     column) AND directly `overflow-y: auto` — it IS the scroll viewport now, one box, no wrapper, no separate
+     paint target. The 8px region rhythm between children comes from an adjacent-sibling margin (gap-without-
+     flex), applied in the @scope block below. NOTE: unlike the shared container-box.css `[data-region='content']`/
+     `main` model, a ui-card-content has NO nested-content padding-STEPPING law — it is not marked `[data-region]`,
+     so the shared L1/L2/L3 descendant-level rules never match it; this region padding stays FLAT (12/6) at every
+     nesting depth (a card-in-card-content-in-card sees 12/6 inside 12/6, not a decrement). Only the RADIUS chain
+     steps one level (ADR-0018, above). */
+  display: block;
+  padding-inline: var(--ui-card-region-pad-inline);
+  padding-block: var(--ui-card-region-pad-block);
+  min-inline-size: 0; /* may shrink in a constrained (flex/grid) parent */
+
+  /* Edge-fade depth for the scroll mask painted HERE (Kim: "the mask should not be placed on the container
+     element — it should be on ui-card-content", REVISED 2026-07-07: content now manages its own overflow AND
+     carries the mask directly — no split at all). Density-linked; the 1rem fallback keeps it self-contained
+     where only this sheet is loaded. */
+  --ui-box-fade: var(--md-sys-space-lg, 1rem);
+
+  /* The bracket bands `traits/scroll-fade.ts` publishes as INLINE `--ui-box-head`/`--ui-box-foot` on this very
+     element (card-content.ts's `brackets` points at the card) — re-declared under the card's own `--ui-card-*`
+     namespace, the same pattern `--ui-card-region-margin` etc. above already use for the shared `--ui-box-*`
+     seam, so the STYLES block below stays role-pure (consumes only `--ui-card-*`). 0px when that edge has no
+     bracket. Drives BOTH this region's own block-padding (below) AND (unchanged) container-box.css's gradient
+     offset — one measured source, two consumers, per Kim's ask. */
+  --ui-card-box-head: var(--ui-box-head, 0px);
+  --ui-card-box-foot: var(--ui-box-foot, 0px);
+
+  /* Opt INTO the shared HOLD (container-box.css's `--ui-box-head-hold`/`-foot-hold`, both default 0px — a
+     coincident-stop no-op every OTHER consumer never touches): ui-card-content's own brackets are backgroundless
+     overlays (no fill of their own), so the gradient must hold fully transparent/opaque THROUGH each bracket's
+     entire band, not just ramp continuously across it — else a crisp bracket sits over PARTIALLY visible
+     scrolled content (measured, card.browser.test.ts). Declared under the SHARED (un-namespaced) name — this is
+     the one deliberate exception to the role-purity split above, since container-box.css's generic rule expects
+     this literal name, exactly like `--ui-box-fade` already is. */
+  --ui-box-head-hold: var(--ui-box-head, 0px);
+  --ui-box-foot-hold: var(--ui-box-foot, 0px);
+}
+
+@scope (ui-card-content) {
+  /* The 8px region rhythm between content children — an adjacent-sibling margin (gap-without-flex). The FIRST
+     child has no top margin (the block padding provides the inset). */
+  :scope > * + * {
+    margin-block-start: var(--ui-card-content-gap);
+  }
+
+  /* The `scrollable` prop is a SIGNAL that this region should become the scroll viewport (REVISED 2026-07-07 —
+     supersedes the short-lived WRAPPER MODEL). `<ui-card-content scrollable>` (the A2UI-mapped signal) triggers
+     the PARENT card's scroll mode through `@scope (ui-card)`'s `:has(> ui-card-content[scrollable])`, which is
+     where `overflow-y: auto` + the block-padding formula actually live (this element's OWN box is the thing
+     that scrolls now — no wrapper, no separate viewport). (Named `scrollable`, not `scroll`, to avoid shadowing
+     the native Element.scroll() method — see card-content.ts.)
+
+     The edge-fade mask paints HERE, on ui-card-content — Kim (2026-07-05): "the mask should not be placed on
+     the container element — it should be on ui-card-content"; REVISED 2026-07-07: content now measures AND
+     paints itself directly (`traits/scroll-fade.ts`'s `viewport` stays its default, `this`) — the sticky→
+     overlaid ui-card-header/ui-card-footer siblings never carry the mask at all (the MUST-PASS: they stay fully
+     crisp, proven cross-engine, card.browser.test.ts). AUTOMATIC in scroll mode (no opt-in), self-gates on real
+     overflow. card.md documents the contract; card-css.test.ts / card.browser.test.ts prove the mechanism.
+
+     WHY THIS SHAPE FIXES THE FLAGGED CONSEQUENCE the 2026-07-05 revision measured (cross-engine, Chromium +
+     WebKit — not silently patched around): `mask-image`'s gradient paints relative to the MASKED element's OWN
+     border-box (0%–100% of its full height). Under the 2026-07-05 shape, ui-card-content was masked while the
+     CARD scrolled — content's own box was a plain block, growing to its full natural (un-clipped) height, so
+     for content genuinely taller than roughly 2×(bracket band + fade depth) the fade zone was only ever visible
+     within the first/last ~60–90px of the TOTAL scroll range; through the middle of a long scroll the visible
+     slice sat in the gradient's opaque middle, text cut hard at the header/footer boundary with NO visible
+     fade. Under THIS shape, ui-card-content's own box is bounded (`flex: 1 1 auto` off a `max-block-size`-only
+     card — the @scope (ui-card) banner above) and it is ALSO the element that scrolls (`overflow-y: auto`) — so
+     its "full height" IS the small, fixed, currently-visible frame, and the SAME 0%–100% gradient is genuinely
+     viewport-registered and visible throughout the WHOLE scroll, at any content length (measured cross-engine,
+     card.browser.test.ts), without a separate wrapper element at all. The header/footer crispness (unchanged
+     across every revision of this mechanism) holds regardless.
+
+     THE HOLD (2026-07-07, a second measured finding on the SAME shape): a bare ramp from the true edge lets
+     content go partially visible WITHIN the bracket's own band (a backgroundless bracket has no occlusion of
+     its own) — content behind bracket text could still read as faintly layered underneath. `--ui-box-head-hold`/
+     `--ui-box-foot-hold` (declared in the TOKEN block above, off the SAME measured band) tell container-box.css's
+     shared mask to hold fully transparent/opaque THROUGH the whole bracket band before ramping — see that file's
+     own banner for the coincident-stop no-op that keeps every other `--ui-box-fade` consumer untouched. */
+}
+
+/* ════════════════ forced-colors (WHCM) ════════════════ */
+
+/* Keep the card frame visible as a system colour. The edge-fade mask drop is now handled generically by the
+   shared `[data-fade-top], [data-fade-bottom]` forced-colors block (container-box.css) — which the scrollFade
+   trait targets on ui-card-content directly (REVISED 2026-07-07: content measures + paints itself, no split).
+   The surface itself survives via container.css's forced-colors block (the role layer maps it to Canvas). */
+@media (forced-colors: active) {
+  :where(ui-card) {
+    border-color: CanvasText;
+  }
+
+  /* Scroll-mode bracket bleed-through (component-review, 2026-07-07): the shared `[data-fade-top]`/
+     `[data-fade-bottom]` block above drops container-box.css's mask entirely under forced-colors — but in
+     THIS revision the gradient is the SOLE occluder (the overlaid brackets are deliberately backgroundless,
+     "the gradient carries the occlusion"). With no mask AND no bracket fill, scrolled content bleeds straight
+     through the header/footer text in WHCM — text over text, illegible. Give the scroll-mode brackets an
+     opaque Canvas fallback, WHCM-only, so Kim's no-background normal-mode look is untouched. Both scroll-mode
+     triggers (`<ui-card scrollable>` and `<ui-card-content scrollable>` via `:has()`) are covered. (A ~6px
+     top/bottom gutter sliver above/below each bracket stays unmasked in WHCM — the same minor, pre-existing
+     exposure every other [data-box] consumer has; not chased here.) */
+  @scope (ui-card) {
+    :scope[scrollable] > :where(ui-card-header, ui-card-footer),
+    :scope:has(> ui-card-content[scrollable]) > :where(ui-card-header, ui-card-footer) {
+      background: Canvas;
+    }
+  }
+}

package/dist/controls/card/card.d.ts

@@ -0,0 +1,51 @@
+import { type ReactiveProps } from '../../dom/index.js';
+import { UIContainerElement } from '../../dom/container.js';
+import './card-header.js';
+import './card-content.js';
+import './card-footer.js';
+declare const props: {
+    scrollable: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+    elevation: {
+        reflect: true;
+        type: import("../../index.js").PropType<"0" | "1" | "2" | "3" | "-3" | "-2" | "-1">;
+        default: "0" | "1" | "2" | "3" | "-3" | "-2" | "-1";
+        attribute?: string | false;
+    };
+    brightness: {
+        reflect: true;
+        type: import("../../index.js").PropType<"0" | "1" | "2" | "3" | "-3" | "-2" | "-1">;
+        default: "0" | "1" | "2" | "3" | "-3" | "-2" | "-1";
+        attribute?: string | false;
+    };
+};
+export interface UICardElement extends ReactiveProps<typeof props> {
+}
+export declare class UICardElement extends UIContainerElement {
+    static props: {
+        scrollable: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+        elevation: {
+            reflect: true;
+            type: import("../../index.js").PropType<"0" | "1" | "2" | "3" | "-3" | "-2" | "-1">;
+            default: "0" | "1" | "2" | "3" | "-3" | "-2" | "-1";
+            attribute?: string | false;
+        };
+        brightness: {
+            reflect: true;
+            type: import("../../index.js").PropType<"0" | "1" | "2" | "3" | "-3" | "-2" | "-1">;
+            default: "0" | "1" | "2" | "3" | "-3" | "-2" | "-1";
+            attribute?: string | false;
+        };
+    };
+    protected connected(): void;
+}
+export {};

package/dist/controls/card/card.js

@@ -0,0 +1,61 @@
+// card.ts — UICardElement, the surface container of the G9 card family (goals.md §G9 / decomp
+// g9-containers slice s7). BEHAVIOUR + props + the opt-in ARIA role + self-define ONLY; the surface, the
+// presence-driven region grid, the padding, the border and the one-level nested radius all live in card.css.
+//
+// `ui-card` is the FIRST non-form container with a default plane: it extends `UIContainerElement` (NOT
+// form-associated — a container contributes nothing to a form) and folds the spreadable `surfaceProps`
+// (elevation/brightness, ADR-0015) into its OWN `static props` — NOT `flexProps` (a card lays its regions out
+// as a presence-driven grid, not a flex line; ADR-0016 governs row/column, not card). The two surface axes
+// repoint the role-pure `--ui-container-bg`/`-tint` seam in controls/_surface/container.css; card.css adds the
+// one card-specific surface decision the base does NOT make — an un-elevated card still reads as a SURFACE
+// (the base default is `transparent`), so card.css seeds its own `--ui-container-bg: var(--md-sys-color-neutral-surface)`.
+//
+// Content model — host-as-grid over the region SUB-ELEMENTS (`ui-card-header`/`-content`/`-footer`, the
+// ratified "regions = sub-elements"): the card does NOT `render()` a wrapper, so `render()` stays the
+// inherited void and the agent's light-DOM regions are never clobbered. The presence-driven grid (card.css
+// `:has()`) collapses the row of an absent region — no phantom gap.
+//
+// ARIA is minimal + opt-in (ADR-0014 widgets-not-elements posture): a card with an author-supplied accessible
+// name (`aria-label`/`aria-labelledby`) reads as a `group` THROUGH `internals` (never a host `role` attribute);
+// an unnamed card stays a generic container with no role. `controls → dom` is the allowed import direction.
+import { prop } from "../../dom/index.js";
+import { UIContainerElement } from "../../dom/container.js";
+// Self-define the region sub-elements as a side effect of importing the family entry, so `ui-card` is a
+// self-contained compound (the `ui-tabs` → `ui-tab`/`ui-tab-panel` precedent): importing `card.ts` — directly
+// or via the controls barrel (decomp s12) — registers all four card tags, and a consumer who imports only
+// `ui-card` still gets its regions. Side-effect imports (no binding needed): each module self-defines its tag.
+import "./card-header.js";
+import "./card-content.js";
+import "./card-footer.js";
+// `static props = { ...surfaceProps, scrollable }` — the elevation/brightness axes (no flexProps; a card lays
+// its regions out in block flow, not a flex line) PLUS the ergonomic scroll signal. `<ui-card scrollable>`
+// (Kim, 2026-07-07: "<ui-card-content> should have the mask and manage overflow ... it should be set to use
+// 100% of its parent height when [scrollable]") puts the card into scroll mode: card.css makes ui-card-content
+// ITSELF the scroll viewport (`overflow-y:auto`, filling 100% of the card via the flex carve-out — the shell's
+// SOLE flex item), while the header/footer become OVERLAID PEERS (`position: absolute`, no background —
+// removed from flow entirely) rather than sticky/flex siblings. The edge-fade mask paints directly on
+// ui-card-content (wired in card-content.ts) — the brackets never carry it and stay crisp. It is the ergonomic
+// convenience over marking the content region itself —
+// `<ui-card-content scrollable>` (the A2UI-mapped signal); card.css triggers scroll mode off EITHER. Note the
+// two are not identical at RUNTIME: the content signal is fully reactive, while this parent `scrollable` is read
+// once at the content region's connect for the fade-mask arming — toggle scroll at runtime via the content
+// region's `[scrollable]` (CSS scroll engages either way; only the JS fade differs). Spread, not inherited (props.ts has no static-props prototype merge — the ADR-0013 pattern the
+// container base exposes `surfaceProps` for).
+const props = {
+    ...UIContainerElement.surfaceProps,
+    scrollable: { ...prop.boolean(false), reflect: true },
+};
+export class UICardElement extends UIContainerElement {
+    static props = props;
+    connected() {
+        // Opt-in landmark: a NAMED card reads as an ARIA `group` (set THROUGH internals — never a host attribute,
+        // the family discipline). An unnamed card stays a generic container (no role). The accessible name is
+        // author-supplied (`aria-label` / `aria-labelledby`); read once at connect — dynamic re-naming is out of
+        // this slice's scope (documented in card.md). `role` is the only ARIA a card opts into.
+        if (this.hasAttribute('aria-label') || this.hasAttribute('aria-labelledby')) {
+            this.internals.role = 'group';
+        }
+    }
+}
+if (!customElements.get('ui-card'))
+    customElements.define('ui-card', UICardElement);