@uxelle/skills 0.2.1-beta.0 → 0.2.3

package/skills/uxelle-design-harness/density.md

@@ -0,0 +1,138 @@
+# Density: spacing and type by experience
+
+The same structural role wants different space in different experiences. A dense
+console packs sections together so more data fits on screen; a marketing page opens
+them up so one idea lands per band. Both are correct — on the *same* grid, with the
+*same* ramp.
+
+Density is the lever. Pick a **mode** for the experience, then resolve each spacing
+**role** and each **heading rank** through that mode. Roles are the vocabulary the
+recipes speak in ("section gap", "field stack"); the mode decides which ramp step
+each one lands on ([spacing-steps.md](spacing-steps.md)).
+
+## 1. Pick the mode
+
+One mode per experience, chosen once before you write any layout:
+
+- **`compact`** — data-dense product surfaces where screen real estate is the
+  scarce resource: dashboards, data tables, consoles, admin and ops tooling,
+  monitoring, inbox/queue views.
+- **`standard`** — task product surfaces where comprehension beats density:
+  forms, settings, record detail, wizards, generic page bodies. **This is the
+  default** when the brief is unclear.
+- **`spacious`** — public marketing and editorial surfaces that sell an idea:
+  landing pages, heroes, pricing, closing CTAs, feature bands.
+
+State the mode in a comment at the top of the surface so the choice is auditable:
+
+```tsx
+// Density: compact (data-dense dashboard) — see density.md
+```
+
+## 2. Resolve the roles
+
+| Role — what it separates | `compact` | `standard` | `spacious` |
+|---|---|---|---|
+| **Flush** — lines already separated by their line box | `0` | `0` | `0` |
+| **Tight** — lockup internals, chip rows, label over value | `micro-1` | `micro-2` | `micro-3` |
+| **Control** — related fields, same-row clusters, toolbars | `micro-3` | `small-4` | `small-6` |
+| **Group** — subgroups within a section, bespoke section padding | `small-6` | `medium-8` | `medium-10` |
+| **Section** — between page sections | `medium-9` | `medium-12` | `large-14` |
+| **Band** — block padding on a full-bleed band | `medium-12` | `large-13` | `large-15` |
+
+`large-16` is reserved for a deliberate editorial statement — a full-viewport hero
+band — not the default `spacious` band. `small-5`, `medium-7`, and `medium-11` are
+tuning room between modes; reach for them only to fix a specific rhythm problem.
+
+Emit the resolved token, not the role name — a compact section gap is
+`gap="var(--uxl-theme-layout-spacing-medium-9)"`. There is no `--uxl-*` density
+variable and no app-owned alias layer; resolve at generation time.
+
+`standard` is the harness baseline — it is the value every recipe used before
+density existed, so a `standard` surface looks exactly as it always did.
+
+## 3. Resolve the heading ranks
+
+Rank is semantics; **type** is what makes rank visible. Map every heading through
+the same mode so size and weight carry hierarchy — never color
+([principles.md](principles.md)).
+
+| Rank | `compact` | `standard` | `spacious` |
+|---|---|---|---|
+| `h1` — one per page | `Display Small` | `Display Small` | `Display Large` |
+| `h2` — page section | `Display Extra Small` | `Display Extra Small` | `Display Medium` |
+| `h3` — subsection | `Component Medium` | `Component Medium` | `Display Small` |
+| Body copy | `Body Medium` | `Body Medium` | `Body Medium` |
+
+**Consecutive ranks must never share a type.** The `Display` scale is `Large`
+(64px) → `Medium` (45) → `Small` (32) → `Extra Small` (22), then `Component Medium`
+(18) and `Body Medium` (16) on desktop. An `h1` and `h2` both set to
+`Display Extra Small` render identically and flatten the page, which reads as one
+undifferentiated block no matter how correct the markup is.
+
+`compact` and `standard` share the heading ramp on purpose: density is a *spacing*
+concern, while Display-led headlines are a *marketing* one. On a genuinely dense
+console where vertical space is critical, `compact` may drop to `h1`
+`Display Extra Small` / `h2` `Component Medium` — still one full stop apart.
+
+**Step down one stop inside a bounded container, but never below
+`Display Extra Small`.** A heading inside a `Card`, `ProductCard`, or tile takes the
+type one stop below its rank's default, because the container's border and padding
+already supply the separation the larger type would carry — a `spacious` feature
+card's `h2` is `Display Small`, not `Display Medium`. `Display Extra Small` is the
+floor for any heading: a product `h2` already sits there, so a product card heading
+stays put rather than dropping to `Component Medium`, which would read as a label
+instead of a heading.
+
+Dense supporting text — table cells, metadata, KPI labels — may use `Body Small`
+(14px) under `compact`. Never go below `Body Small` for reading copy.
+
+## 4. Guardrails
+
+**The grid never moves.** Page chrome — `--uxl-breakpoints-max-container-width`,
+`-margin`, and `-gutter` — is **density-invariant**. Density modulates rhythm
+*within* and *between* blocks, never the column cap, the page inset, or column
+gaps. That is what keeps a compact page and a spacious page on one grid, and it is
+the Swiss commitment in [principles.md](principles.md). Grid gaps stay
+`--uxl-breakpoints-gutter` in every mode.
+
+**Keep the gap roles at least ~1.5x apart.** A reader infers grouping by comparing
+gaps, so **Tight → Control → Group → Section** must stay visibly distinct or the
+page reads as undifferentiated mush. Every mode above satisfies this (`compact`
+runs 4 → 10 → 16 → 24px on desktop). This is the failure mode of `compact`: tighten
+the section gap to `medium-9` while leaving the group gap at `medium-8` and sections
+stop being legible as sections. Tighten *the whole column* or none of it — never one
+role in isolation.
+
+**Band** is exempt: it is padding inset from a band edge, not a gap between
+siblings, so it is not compared against the gap roles. A `spacious` band's `large-15`
+padding sitting near the `large-14` section gap is correct, not a collision.
+
+**`compact` has an accessibility floor.** Tightening must never bring touch targets
+below 24 CSS px or let interactive rows collide. Catalog controls already meet the
+floor — do not claw space back by shrinking hit areas
+([how-to-accessibility.md](how-to-accessibility.md)).
+
+**No breakpoint logic for density.** The ramp already remaps per breakpoint (a
+`spacious` section gap is 72px on desktop and 48px on mobile on its own), so density
+and responsiveness compose for free. Never add `matchMedia` or a second mode for
+small screens ([how-to-page-layout.md](how-to-page-layout.md#responsiveness)).
+
+**Do not mix modes in one experience.** A dense surface nested inside a spacious
+page (a pricing comparison on a landing page, a table in a marketing section) keeps
+its *own internals* compact, but the surrounding **section** rhythm stays the page's
+mode. Density describes the experience, not each component.
+
+## 5. Out of scope
+
+Density does not reach into **component internals**. `Card` padding, `Table` row
+height, `Button` insets, `Lockup` internals, and `Footer` band padding are
+component-owned and already tuned — do not wrap a component in compensating padding
+or override its spacing to hit a mode.
+
+## A2UI
+
+Chat surfaces are inherently narrow and have no full-bleed bands, so **`spacious`
+never applies** and the `Band` role has no meaning. Use `standard` by default and
+`compact` for data-heavy runtime output, resolving the same
+`var(--uxl-theme-layout-spacing-*)` strings ([a2ui.md](a2ui.md)).

package/skills/uxelle-design-harness/how-to-accessibility.md

@@ -2,6 +2,8 @@
 
 WCAG 2.x **Level AA** for pages and composed experiences. Prefer catalog components (`Button`, `Textfield`, `Textarea`, `Dialog`, …) so keyboard, focus rings, and field associations come for free. Contrast is theme-owned — use `--uxl-color-switcher-*`.
 
+This file covers **composition**: landmarks, heading ranks, names, and live regions across a whole page. Component-level patterns (keyboard behavior, focus management, ARIA inside a single component) live in the workspace rule `.cursor/rules/accessibility.mdc`, and token/color relationships are owned by the theme layer. Read that rule when building or fixing a component rather than a page.
+
 ## Baseline
 
 - One `h1`, then `h2`… with no skipped ranks (`Text as="h1"` / `as="h2"`).
@@ -24,7 +26,7 @@ WCAG 2.x **Level AA** for pages and composed experiences. Prefer catalog compone
 - `aria-describedby` — extra help, not the name (`fieldDescription`, instructions).
 - `aria-hidden="true"` — decorative / redundant graphics (default `Icon`).
 - `aria-live="polite"` — status that appears without moving focus. `assertive` only for urgent interruptions.
-- `aria-current="page"` — current item in nav (`NavLink`, or `activated` on `NavigationSideItem` / `NavigationSideSubItem` destinations — not accordion parents).
+- `aria-current="page"` — current item in nav (`NavLink`, or `activated` on `NavigationSideItem` / `NavigationSideSubItem` destinations — not accordion parents). When the side rail is collapsed, an accordion parent of an activated nested row still shows the selected appearance so the current section remains visible on the icon-only rail.
 - `aria-expanded` — only on a real disclosure control, not on every section.
 - `aria-pressed` — toggle buttons (`IconButton` `activated`); `Switch` uses `checked` instead.
 

package/skills/uxelle-design-harness/how-to-color.md

@@ -10,8 +10,10 @@ in [tokens.md](tokens.md)); choose which palette those roles resolve to with
 `data-color-switcher="<palette>"` on a region remaps the `--uxl-color-switcher-*`
 roles for that subtree; nested components inherit from the nearest ancestor.
 
-- Set it on a **region** — a nav band, hero, section band, banner, or badge — not
-  on `<html>`. The host owns the page-level default (`default`).
+- Set it on a **region** — a nav band, hero, section band, banner, or badge. The
+  **host** owns the one page-level default on `<html>`
+  (`data-color-switcher="default"`, set once during host setup —
+  [how-to-host.md](how-to-host.md)); recipes and page content never touch `<html>`.
 - Some components take a `dataColorSwitcher` prop *or* the `data-color-switcher`
   attribute (e.g. `LabelBadge`, `BannerAnnouncement`, `Button`, `DynamicAngle*`).
   The attribute wins when both are set; for buttons rendered into another
@@ -72,7 +74,8 @@ To choose:
 
 - Do apply a palette on the region, and style children with role tokens.
 - Do keep status palettes for real status, paired with text or an icon.
-- Don't set `data-color-switcher` on `<html>` or invent palette names.
+- Don't re-set `data-color-switcher` on `<html>` from page content or a recipe
+  (host setup only), and don't invent palette names.
 - Don't hardcode hex/rgb, and don't stack multiple loud brand bands in one view.
 
 ## A2UI

package/skills/uxelle-design-harness/how-to-host.md

@@ -10,35 +10,22 @@ Agents consume **published packages**, not repo filesystem paths. Do not import
 
 ## Load CSS
 
-Theme CSS is a **placeholder import** — use the theme id the host documents.
-Open-source example:
+Load component and theme CSS as in
+[getting-started.md](../uxelle-components/getting-started.md). Do not set
+`font-family` in app CSS — `Text` uses theme tokens.
 
-```ts
-import "@uxelle/themes/open-source";
-import "@uxelle/components/styles.css";
-```
-
-Until `@uxelle/components/styles.css` is the full bundle, also load extracted
-component CSS:
-
-```ts
-import "@uxelle/components/index.css";
-```
-
-Enterprise hosts swap the theme module (`@uxelle/themes/<theme-id>`) and the root
-data attribute. Do not set `font-family` in app CSS — `Text` uses theme tokens.
-Load the typeface the theme expects (open-source: Open Sans).
+If generated UI uses Material Symbol names beyond GPF chrome (`home`, `mail`,
+`campaign`, …), add `import "@uxelle/icons/register"` once at the app entry.
+`@uxelle/a2ui` already registers the full catalog.
 
 On `<html>`:
 
 - Theme mode (host-owned): `data-open-source="light" | "dark"` (other themes use
   `data-<theme-id>`).
-- Color switcher default: `data-color-switcher="default"` on `<html>`. Apply other
+- Color switcher default: `data-color-switcher="default"` on `<html>` — this is the
+  one place `<html>` carries a palette, and only the host sets it. Apply other
   palettes per region, not here ([how-to-color.md](how-to-color.md)).
 
-Optional: `UXelleThemeProvider` from `@uxelle/themes/react` with
-`theme="open-source"` keeps those attributes in sync.
-
 ## Skip link
 
 First focusable node in the DOM, targeting `id="main-content"` on `<main>`:

package/skills/uxelle-design-harness/how-to-page-layout.md

@@ -11,6 +11,24 @@ Page chrome comes from theme variables (do not invent `uxl-breakpoint-*` singula
 
 Stacks inside the column use `--uxl-theme-layout-spacing-*` ([spacing-steps.md](spacing-steps.md)).
 
+## Who owns the content column
+
+**The experience owns it — chrome does not.** [recipe-app-chrome.md](recipe-app-chrome.md)
+renders the skip link, `Navigation`, and a scrolling `<main>`, and stops there.
+`<main>` is a scrollport with no padding and no cap. The experience recipe
+(dashboard, data-table page, settings, page shell) renders the one capped column
+inside it.
+
+The column carries `maxWidth`, `mh="auto"`, `p`, and `gap`, and all four are
+experience-level decisions: the `gap` is the density **Section** step
+([density.md](density.md)) and the cap may be the `600px` reading measure instead of
+the container token. Chrome cannot know either, which is why it does not emit them.
+
+So exactly one element in the tree sets `maxWidth="var(--uxl-breakpoints-max-container-width)"`
+plus `p="var(--uxl-breakpoints-margin)"`. If you find yourself writing that pair
+twice — once from chrome and once from the experience — the page is capped and
+padded twice; delete the chrome one.
+
 ## Content column
 
 One capped, centered column carries the page:
@@ -27,9 +45,12 @@ One capped, centered column carries the page:
 >
 ```
 
-`mh="auto"` centers the column; `medium-12` is the gap between page sections. Cap
-with the token, not a literal (`1120px` / `1600px`), and keep page internals off
-the theme-internal `--uxl-theme-layout-*-gutter` / `*-margin`.
+`mh="auto"` centers the column; the `gap` is the **Section** step, shown here at its
+`standard` value — a `compact` dashboard uses `medium-9` and a `spacious` landing
+page `large-14` ([density.md](density.md)). Cap with the token, not a literal
+(`1120px` / `1600px`), and keep page internals off the theme-internal
+`--uxl-theme-layout-*-gutter` / `*-margin`. The cap, the margin, and the gutter are
+density-invariant — only the `gap` moves.
 
 If the host already renders `<main>` (the skip-link target), keep this column a
 `div`; otherwise set `as="main"`.
@@ -38,6 +59,23 @@ If the host already renders `<main>` (the skip-link target), keep this column a
 prose section inside a wider page) caps at the **reading measure** rather than the
 container token — see [Reading measure](#reading-measure).
 
+## Intrinsic sizes in rem
+
+The no-px rule targets **breakpoints** and **theme values** — things the theme
+already owns and remaps. It does not forbid an intrinsic size that expresses
+"how small may this box get before it should reflow", because no theme variable
+carries that. Use `rem` (never `px`) for:
+
+- **`minmax()` minimums** on `auto-fit` grids — the smallest comfortable cell.
+  `16rem` for a text card, `18rem` for a media/CTA tile, `12rem`-`14rem` for a
+  metric tile.
+- **A bounded search field** — `width="16rem"` with `flexShrink={0}`.
+
+These are not breakpoints and must never be used as one: no media query, no
+`matchMedia`, and no `maxWidth` on the page column. Anything the theme *does* own —
+the column cap, page inset, gutter, spacing, type, color — always comes from a
+variable ([tokens.md](tokens.md)).
+
 ## Reading measure
 
 Text you read in a single column — a form, an FAQ, a paragraph block — is easiest
@@ -156,8 +194,9 @@ Bands: `tablet` (from `--uxl-theme-layout-tablet-screen-width-min`), `desktop`,
 
 ## Keep controls with what they operate
 
-Group a control with the surface it drives; `medium-12` is the gap between
-*sections*, not between a control and its target.
+Group a control with the surface it drives; the **Section** step is the gap between
+*sections*, not between a control and its target — a control sits with its target at
+the **Control** step in every density mode ([density.md](density.md)).
 
 - **Page navigation** (`Navigation` / `NavLink`) changes routes — don't repeat
   those destinations as in-page tabs.
@@ -170,7 +209,7 @@ Group a control with the surface it drives; `medium-12` is the gap between
   To stack when tight, switch the header `flexDirection` to `column` below tablet —
   not `flexWrap="wrap"`.
 - **Related form fields** (first/last name, city/state/ZIP): `display="grid"` with
-  `fr` tracks and `small-4` gap; collapse to one column when narrow. See
+  `fr` tracks and the **Control** gap; collapse to one column when narrow. See
   [recipe-form-section.md](recipe-form-section.md).
 
 ## Action clusters
@@ -196,6 +235,12 @@ Delete/Upload, banner CTAs with two+ text buttons.
 (Filter/Export beside search), icon-only clusters. Do not use the tablet switch to
 restyle card grids — those reflow intrinsically ([recipe-card-grid.md](recipe-card-grid.md)).
 
+**One button** needs no `direction` at all. `ButtonGroup` already defaults to
+`direction="row"` / `fullWidth={false}`, and a single child renders identically in
+either direction, so pass neither — a lone `direction="row"` reads as a deliberate
+override of the switch above and invites a false review flag. Add a second text
+button and the cluster takes the switch like any other.
+
 ## A2UI
 
 Chat adapters allow only `var(--uxl-theme-layout-spacing-*)` (or `0`) — no

package/skills/uxelle-design-harness/principles.md

@@ -17,10 +17,13 @@ expressive, but within the *same* grid, hierarchy, and limited palette.
 - **Restraint / minimalism.** Prefer fewer elements. Few type roles, few
   accents, one dominant brand band per view. If a divider, box, or color is not
   doing a job, remove it. Whitespace is the default separator.
-- **Whitespace and rhythm.** Space is structural. Use the ramp deliberately:
-  tight stacks `micro`, related controls `small-4`, card/section padding
-  `medium-8`, page-section gaps `medium-12`, hero breathing `large-13`+.
-  See [spacing-steps.md](spacing-steps.md).
+- **Whitespace and rhythm.** Space is structural, and how much of it is *the*
+  expression of an experience's character. Use the ramp deliberately by **role** —
+  Tight stacks, Control clusters, Group padding, Section gaps, Band breathing —
+  and resolve those roles through one **density mode**: `compact` where data
+  volume is the point, `spacious` where a single idea must land. The grid stays
+  fixed while the rhythm changes. See [spacing-steps.md](spacing-steps.md) and
+  [density.md](density.md).
 - **Clarity and legibility.** Objective, plain language. Render copy with `Text`
   so type, line-height, and contrast come from the theme; never set font-size or
   hex in app CSS.
@@ -63,10 +66,11 @@ The whole flow is assembled in [recipe-landing-page.md](recipe-landing-page.md).
 | | Product | Marketing |
 |---|---|---|
 | Palette | `default` / `default-subtle` + status | + brand bands for emphasis |
-| Density | Compact, information-dense | Airy, one idea per band |
+| Density mode | `compact` (data-dense) or `standard` (task) | `spacious` |
 | Type | Restrained; Body-led | Expressive; Display-led headlines |
 | Motion / accents | Minimal | `DynamicAngle*` accents, still restrained |
 | Goal | Get the task done | Build trust and convert |
 
 Same grid, same tokens, same components. The difference is emphasis, not a
-different system.
+different system — density shifts which ramp step each role lands on, never the
+column cap, page inset, or gutter ([density.md](density.md)).

package/skills/uxelle-design-harness/recipe-app-chrome.md

@@ -7,18 +7,25 @@ React app frame: skip link, [`Navigation`](../uxelle-components/Navigation.md),
 ## When not
 
 - Not an `AppChrome` / `PageShell` component.
+- **Chrome does not render the content column.** `<main>` here is only the
+  scrollport — the **experience** inside it owns the capped column
+  ([how-to-page-layout.md](how-to-page-layout.md#who-owns-the-content-column)). Do
+  not emit a `maxWidth` + `--uxl-breakpoints-margin` wrapper from this recipe *and*
+  from the experience recipe, or the page is padded and capped twice.
 - Theme CSS and `data-*`: [how-to-host.md](how-to-host.md).
 - A2UI chat surfaces: skip link, 100% viewport shell, and html `data-*` are host-owned. Do not emit this recipe as A2UI. Optional `A2uiNavigation` / `A2uiFooter` only when the host already has a surface.
 
 ## Regions
 
-skip link → `Navigation` (header) and/or `NavigationSide` (side rail wrapping `NavigationSideGroup` rows) → `<main id="main-content">` → content column ([how-to-page-layout.md](how-to-page-layout.md)) → optional `Footer` **inside that same `<main>`**
+skip link → `Navigation` (header) and/or `NavigationSide` (side rail wrapping `NavigationSideGroup` rows) → `<main id="main-content">` → *the experience's* content column ([how-to-page-layout.md](how-to-page-layout.md#who-owns-the-content-column)) → optional `Footer` **inside that same `<main>`**
 
 ## Spacing
 
-Nav is a catalog component (its own tokens). Main is the scrollport (no page padding). The **page column inside main** uses breakpoint margin / max-container-width (one-column settings may use `600px` — [recipe-settings-page.md](recipe-settings-page.md)). When present, `Footer` sits after that column in the same scrollport.
+Chrome is **density-invariant**: nav and footer are catalog components with their own tokens, and the margin / max-container-width on the experience's column never shift with the mode either. The experience picks the density mode and renders that column ([density.md](density.md)) — chrome does neither.
 
-Do not wrap `Footer` in extra `Layout` padding. Band padding is catalog-owned: two-band footers use `--uxl-breakpoints-padding-large-13`; a **single** band (legal-only, unused slot `null`) uses `--uxl-theme-layout-spacing-small-4` on the block axis. That is the related-controls step, not page-section (`medium-12`) or hero (`large-13`).
+Nav is a catalog component (its own tokens). Main is the scrollport — **no page padding and no column cap here**; the experience's own column supplies breakpoint margin / max-container-width (one-column settings may use `600px` — [recipe-settings-page.md](recipe-settings-page.md)). When present, `Footer` sits after that column in the same scrollport.
+
+Do not wrap `Footer` in extra `Layout` padding. Band padding is catalog-owned: two-band footers use `--uxl-breakpoints-padding-large-13`; a **single** band (legal-only, unused slot `null`) uses `--uxl-theme-layout-spacing-small-4` on the block axis. That is the **Control** step, not **Section** or **Band**.
 
 ## A11y
 
@@ -73,17 +80,14 @@ Import from `@uxelle/components`. Put skip-link CSS in the host stylesheet.
     />
   </Layout>
   <main id="main-content" tabIndex={-1} style={{ flexGrow: 1, minHeight: 0, overflow: "auto" }}>
-    <Layout
-      display="flex"
-      flexDirection="column"
-      width="100%"
-      maxWidth="var(--uxl-breakpoints-max-container-width)"
-      mh="auto"
-      p="var(--uxl-breakpoints-margin)"
-      gap="var(--uxl-theme-layout-spacing-medium-12)"
-    >
-      {/* page body — recipe-page-shell.md / recipe-form-section.md / recipe-data-table-page.md / recipe-settings-page.md */}
-    </Layout>
+    {/*
+      The experience renders its own capped column here — chrome does not.
+      It owns maxWidth / mh / p / gap so it can set its density mode and, for a
+      one-column form or settings view, the 600px reading measure.
+      recipe-page-shell.md / recipe-dashboard-overview.md / recipe-data-table-page.md /
+      recipe-settings-page.md
+    */}
+    <PageBody />
     <Footer
       topMainContent={null}
       bottomMainContent={
@@ -108,7 +112,7 @@ When-not for this recipe. Host owns chrome (skip link, viewport shell, html `dat
 
 ## Help and marketing chrome
 
-Use the same `Navigation` when there are **no** primary app links (help center, marketing). Pass `bottomSlot={null}` to hide the secondary bar. Unused **primary** slots must not be omitted — omitted (`undefined`) or `null` on leading/center/trailing still fill catalog demo content (`??`). Pass `centerSlot={false}` when there is no center nav.
+Use the same `Navigation` when there are **no** primary app links (help center, marketing). Pass `bottomSlot={null}` to hide the secondary bar. Unused **primary** slots must not be omitted — an omitted (`undefined`) `leadingSlot` / `centerSlot` / `trailingSlot` fills catalog demo content. Pass **`null`** to drop a slot entirely (`centerSlot={null}` when there is no center nav) — the same pattern as `bottomSlot={null}`. Do not pass `false`: it clears the content but still renders an empty slot wrapper in the flex row.
 
 Nav trailing (search, language, Log in / Register) stays a **row** at every width — [how-to-page-layout.md](how-to-page-layout.md#action-clusters). Do not stack those controls on mobile.
 
@@ -122,7 +126,7 @@ Nav trailing (search, language, Log in / Register) stays a **row** at every widt
       <Logo name="generic" width={40} interactive aria-hidden />
     </a>
   }
-  centerSlot={false}
+  centerSlot={null}
   trailingSlot={
     <>
       <LanguageSelector value="EN" />

package/skills/uxelle-design-harness/recipe-card-grid.md

@@ -35,13 +35,20 @@ minmax(MIN, 1fr))` drops from 3-up to 2-up to 1-up as width shrinks; pick `MIN`
 
 ## Spacing
 
-`gap="var(--uxl-breakpoints-gutter)"`. Card inner padding is component-owned. The
-page column still uses [how-to-page-layout.md](how-to-page-layout.md).
+`gap="var(--uxl-breakpoints-gutter)"`. Card inner padding is component-owned. Both
+are **density-invariant** — a card grid looks the same in every mode, so do not
+tighten the gutter for a `compact` dashboard or pad it out for a marketing page
+([density.md](density.md)). Stacks *inside* a card use the host's **Control** or
+**Group** step. The page column still uses [how-to-page-layout.md](how-to-page-layout.md).
 
 ## A11y
 
 Name the group when the cards are a set (`aria-label` on the grid `Layout`).
-Headings inside cards continue page rank (`h2` under the page `h1`). A `ProductCard`
+Headings inside cards continue page rank (`h2` under the page `h1`) but take the
+type **one stop below** that rank's default, since the card already supplies the
+separation — with `Display Extra Small` as the floor. A `spacious` card `h2` is
+`Display Small`; a product card `h2` is already at the floor and stays
+`Display Extra Small`, as shown ([density.md](density.md)). A `ProductCard`
 CTA names itself; if the whole card is the link, the heading text is the name. See
 [how-to-accessibility.md](how-to-accessibility.md).
 
@@ -100,5 +107,7 @@ Case-study / product tiles (`ProductCard`, media + CTA):
 ## A2UI
 
 `A2uiLayout` has no `gridTemplateColumns` — stack `A2uiCard` / `A2uiProductCard` in
-a column with `var(--uxl-theme-layout-spacing-*)` `gap`. No
-`getUxelleRecipe("card-grid")` ([a2ui.md](a2ui.md)).
+a column with `var(--uxl-theme-layout-spacing-*)` `gap`. Media in
+`A2uiProductCard` `centerSlotContent` is `A2uiImage` with `aspectRatio` (omit
+`width` so it fills the card). No `getUxelleRecipe("card-grid")`
+([a2ui.md](a2ui.md)).

package/skills/uxelle-design-harness/recipe-cta-band.md

@@ -16,8 +16,10 @@ A single, decisive conversion moment: "Start free," "Talk to sales."
 
 - One primary action (an optional secondary is fine) — not a menu of links.
 - Section heading is `h2`, not another `h1`.
-- Keep it to one dominant brand band per page; if the hero is loud, this can be
-  quieter, or vice versa.
+- Keep it to one dominant brand band per page, and make that concrete rather than
+  vague: if the hero already carries a brand palette, set this band to
+  `default-subtle`. Only one of the two gets a `brand-*` palette
+  ([recipe-landing-page.md](recipe-landing-page.md)).
 
 ## Regions
 
@@ -33,8 +35,10 @@ viewports and stack `fullWidth` below tablet (`useBreakpointUp("tablet")`). See
 
 ## Spacing
 
-`large-13`+ block padding for the band; `medium-8` between the lockup and actions
-([spacing-steps.md](spacing-steps.md)).
+**Band** step for the band's block padding and **Group** between the lockup and the
+actions — `large-15` and `medium-10` on a `spacious` marketing page, its usual home
+([density.md](density.md), [spacing-steps.md](spacing-steps.md)). A CTA closing a
+`standard` product surface resolves to `large-13` / `medium-8`.
 
 ## A11y
 
@@ -50,20 +54,26 @@ role tokens — never hardcode hex. Pick the brand palette by the look you want
 
 ## React
 
+`tabletUp` is the shared `useBreakpointUp("tablet")` helper — copy it from
+[how-to-page-layout.md](how-to-page-layout.md#3-token-driven-js-narrow-fallback),
+do not reimplement it or inline a px literal.
+
 ```tsx
+const tabletUp = useBreakpointUp("tablet");
+
 <Layout
   as="section"
   data-color-switcher="brand-1"
   display="flex"
   justifyContent="center"
-  p="var(--uxl-theme-layout-spacing-large-13)"
+  p="var(--uxl-theme-layout-spacing-large-15)"
   style={{ backgroundColor: "var(--uxl-color-switcher-background)" }}
 >
   <Layout
     display="flex"
     flexDirection="column"
     alignItems="center"
-    gap="var(--uxl-theme-layout-spacing-medium-8)"
+    gap="var(--uxl-theme-layout-spacing-medium-10)"
     width="100%"
     maxWidth="var(--uxl-breakpoints-max-container-width)"
   >

package/skills/uxelle-design-harness/recipe-dashboard-overview.md

@@ -32,18 +32,26 @@ sections
 
 KPI and card grids reflow with `auto-fit` / `minmax` (no JS); the header stacks and
 its actions go `fullWidth` below tablet; the primary `Table` scrolls horizontally
-when narrow. See [how-to-page-layout.md](how-to-page-layout.md#responsiveness).
+when narrow. StatTile labels ellipsize on one line so a KPI row stays scannable.
+See [how-to-page-layout.md](how-to-page-layout.md#responsiveness).
 
 ## Spacing
 
-`medium-12` between page sections (header / KPIs / primary / supporting);
-`--uxl-breakpoints-gutter` inside the grids. Section intros are `micro-2`
+**Density: `compact`** — a dashboard's job is to show more at a glance, so the
+column tightens ([density.md](density.md)). **Section** gap between page sections
+(header / KPIs / primary / supporting) is `medium-9`; subgroups inside a section
+use **Group** (`small-6`); section intros use **Tight** (`micro-1`).
+`--uxl-breakpoints-gutter` stays the grid gap in every mode
 ([spacing-steps.md](spacing-steps.md)).
 
+Step up to `standard` when the overview is a light landing page with two or three
+KPIs rather than a dense monitoring surface — but pick one mode and hold it.
+
 ## A11y
 
 One `main`, one `h1`. Name each region (KPIs `aria-label="Key metrics"`, the primary
-surface by its heading). KPI deltas pair color with a sign or word. Loading and empty
+surface by its heading). KPI deltas pair color with a sign or word. Truncated KPI
+labels keep the full name on the group; hover or focus reveals it. Loading and empty
 for the primary surface follow [states](recipe-states.md). See
 [how-to-accessibility.md](how-to-accessibility.md).
 
@@ -55,6 +63,7 @@ alerts, never as decoration ([how-to-color.md](how-to-color.md)).
 ## React
 
 ```tsx
+// Density: compact (data-dense dashboard) — see density.md
 <Layout
   display="flex"
   flexDirection="column"
@@ -62,7 +71,7 @@ alerts, never as decoration ([how-to-color.md](how-to-color.md)).
   maxWidth="var(--uxl-breakpoints-max-container-width)"
   mh="auto"
   p="var(--uxl-breakpoints-margin)"
-  gap="var(--uxl-theme-layout-spacing-medium-12)"
+  gap="var(--uxl-theme-layout-spacing-medium-9)"
 >
   {/* Page header — recipe-page-header.md */}
   <DashboardHeader />
@@ -90,18 +99,23 @@ alerts, never as decoration ([how-to-color.md](how-to-color.md)).
         <LabelBadge label="+4" dataColorSwitcher="success" emphasis="low" leadingIcon leadingIconName="trending_up" />
       }
     />
+    {/*
+      Palette tracks whether the change is *good*, not whether the number rose.
+      Fewer open tickets is an improvement, so this delta is `success` while
+      trending down — say so in the label rather than relying on the arrow.
+    */}
     <StatTile
       label="Open tickets"
       value="18"
       trailingSlot
       trailingSlotContent={
-        <LabelBadge label="-6" dataColorSwitcher="success" emphasis="low" leadingIcon leadingIconName="trending_down" />
+        <LabelBadge label="6 fewer" dataColorSwitcher="success" emphasis="low" leadingIcon leadingIconName="trending_down" />
       }
     />
   </Layout>
 
   {/* Primary surface — recipe-data-table-page.md (with states) */}
-  <Layout as="section" display="flex" flexDirection="column" gap="var(--uxl-theme-layout-spacing-small-4)">
+  <Layout as="section" display="flex" flexDirection="column" gap="var(--uxl-theme-layout-spacing-micro-3)">
     <Text type="Display Extra Small" as="h2" width={false}>Recent activity</Text>
     {isLoading ? <ActivitySkeleton /> : rows.length ? <ActivityTable rows={rows} /> : <ActivityEmpty />}
   </Layout>