@uxelle/skills 0.2.1-beta.0 → 0.2.2

package/skills/uxelle-design-harness/recipe-hero.md

@@ -19,7 +19,8 @@ The first impression: one sentence of value, one clear action, and supporting me
 - One `h1` for the whole page lives here — later sections are `h2`.
 - Keep the media non-interactive; actions go in `contentSlot`.
 - Pass media as a **direct** `Image` / `img` / `picture` / `video` — no wrappers
-  (Hero owns the crop; a nested `Image.aspectRatio` has no effect).
+  (Hero owns the crop; nested `Image.aspectRatio` and box size — `width`,
+  `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight` — have no effect).
 
 ## Regions
 
@@ -27,16 +28,24 @@ The first impression: one sentence of value, one clear action, and supporting me
 
 ## Responsive
 
-`Hero` owns it: `contentDirection="Left" | "Right"` pins a side panel on tablet and
-up and drops to a full-width bottom panel below; `Bottom` is full-width at every
-size. The crop adapts automatically. If the two actions feel tight on mobile, switch
-the `ButtonGroup` `direction` to `column` (`useBreakpointUp("tablet")`).
+`Hero` owns the panel and crop: `contentDirection="Left" | "Right"` pins a side
+panel on tablet and up and drops to a full-width bottom panel below; `Bottom` is
+full-width at every size. The crop adapts automatically.
+
+The actions are **not** component-owned. Two text `Button`s take the tablet switch
+here exactly as anywhere else — `direction={tabletUp ? "row" : "column"}` with
+`fullWidth={!tabletUp}`, not a judgement call about whether they "feel tight"
+([how-to-page-layout.md](how-to-page-layout.md#action-clusters)). A hero with a
+single action passes no `direction`.
 
 ## Spacing
 
-Content-area spacing is component-owned. The hero is a full-bleed band, so it sits
-outside the capped content column — following sections resume the column
-([how-to-page-layout.md](how-to-page-layout.md)).
+Content-area spacing is component-owned and **density-invariant** — `Hero` owns its
+own band padding, so do not wrap it in compensating `p` to reach a mode. The hero is
+a full-bleed band, so it sits outside the capped content column — following sections
+resume the column at the page's **Section** gap (`large-14` on the `spacious`
+marketing page where a hero lives) ([how-to-page-layout.md](how-to-page-layout.md),
+[density.md](density.md)).
 
 ## A11y
 
@@ -53,7 +62,13 @@ dominant brand band; keep later sections calmer ([how-to-color.md](how-to-color.
 
 ## 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");
+
 <Hero
   contentDirection="Left"
   data-color-switcher="brand-1"
@@ -63,7 +78,7 @@ dominant brand band; keep later sections calmer ([how-to-color.md](how-to-color.
       <Lockup
         overline={<Text type="Overline" width={false}>New</Text>}
         title={
-          <Text type="Display Medium" as="h1" width={false}>
+          <Text type="Display Large" as="h1" width={false}>
             One workspace for every team
           </Text>
         }
@@ -73,9 +88,13 @@ dominant brand band; keep later sections calmer ([how-to-color.md](how-to-color.
           </Text>
         }
       />
-      <ButtonGroup aria-label="Get started">
-        <Button emphasis="high"><Text type="Button" width={false}>Start free</Text></Button>
-        <Button emphasis="medium"><Text type="Button" width={false}>Book a demo</Text></Button>
+      <ButtonGroup
+        direction={tabletUp ? "row" : "column"}
+        fullWidth={!tabletUp}
+        aria-label="Get started"
+      >
+        <Button emphasis="high"><Text type="Button" width>Start free</Text></Button>
+        <Button emphasis="medium"><Text type="Button" width>Book a demo</Text></Button>
       </ButtonGroup>
     </>
   }
@@ -84,6 +103,7 @@ dominant brand band; keep later sections calmer ([how-to-color.md](how-to-color.
 
 ## A2UI
 
-`A2uiHero` with a nested `A2uiImage` and a `contentSlot` of stacked `A2uiText`
-(no `Lockup` adapter) plus `A2uiButtonGroup`. Set the palette via the adapter's
-`data-color-switcher` ([a2ui.md](a2ui.md)).
+`A2uiHero` with a nested `A2uiImage` (`src` + `alt` only — omit `aspectRatio` and
+box size) and a `contentSlot` of stacked `A2uiText` (no `Lockup` adapter) plus
+`A2uiButtonGroup`. Set the palette via the adapter's `data-color-switcher`
+([a2ui.md](a2ui.md)).

package/skills/uxelle-design-harness/recipe-landing-page.md

@@ -41,8 +41,16 @@ clusters) — no page-level breakpoint logic. See
 
 ## Spacing
 
-`medium-12` between in-column sections; `large-13`+ block padding for full-bleed
-bands; `--uxl-breakpoints-gutter` inside grids ([spacing-steps.md](spacing-steps.md)).
+**Density: `spacious`** — generous whitespace is the argument on a public page, and
+one idea should land per band ([density.md](density.md)). **Section** gap between
+in-column sections is `large-14`; full-bleed bands take the **Band** step
+(`large-15`, or `large-16` for a deliberate full-viewport hero statement);
+`--uxl-breakpoints-gutter` stays the grid gap in every mode
+([spacing-steps.md](spacing-steps.md)).
+
+Hold one mode for the whole page. A dense piece inside it (a pricing comparison, an
+embedded table) keeps its own internals tight but still sits at the page's
+`large-14` **Section** gap — density describes the experience, not each component.
 
 ## A11y
 
@@ -56,9 +64,23 @@ One dominant brand band (usually the hero). Apply palettes per section with
 `data-color-switcher`, style with role tokens, keep the calmer sections on `default`
 / `default-subtle` ([how-to-color.md](how-to-color.md)).
 
+This page ships **two** full-bleed bands, so make the choice explicit rather than
+letting both default to `brand-1`: the hero takes the brand palette and the closing
+[cta-band](recipe-cta-band.md) drops to `default-subtle`. Flip it if the CTA is the
+louder moment. What you must not do is set both to a brand palette — that is the
+"stacked loud bands" this recipe's **when not** rules out, and it costs the hero its
+dominance.
+
 ## React
 
+`<main>` comes from [app-chrome](recipe-app-chrome.md) and is shown here only for
+context — this recipe owns what goes *inside* it
+([how-to-page-layout.md](how-to-page-layout.md#who-owns-the-content-column)). Note
+that a marketing page caps only its mid-page sections: the full-bleed bands are
+deliberately outside any column.
+
 ```tsx
+// Density: spacious (public marketing page) — see density.md
 <main id="main-content" tabIndex={-1} style={{ flexGrow: 1, minHeight: 0, overflow: "auto" }}>
   {/* Full-bleed hero — recipe-hero.md (contains the h1) */}
   <MarketingHero />
@@ -71,7 +93,7 @@ One dominant brand band (usually the hero). Apply palettes per section with
     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-large-14)"
   >
     <LogoWall />        {/* recipe-logo-wall.md */}
     <FeatureSections /> {/* recipe-feature-section.md (alternating) */}
@@ -80,7 +102,8 @@ One dominant brand band (usually the hero). Apply palettes per section with
     <Pricing />         {/* recipe-pricing.md */}
   </Layout>
 
-  {/* Full-bleed closing CTA — recipe-cta-band.md */}
+  {/* Full-bleed closing CTA — recipe-cta-band.md.
+      Hero above is the brand band, so this one runs default-subtle. */}
   <CtaBand />
 
   {/* Footer — recipe-footer.md (marketing: directory band + legal bar) */}

package/skills/uxelle-design-harness/recipe-logo-wall.md

@@ -29,9 +29,10 @@ fit — no JS, no breakpoint literals. Bound each mark's `width` so rows stay ev
 
 ## Spacing
 
-`gap="var(--uxl-theme-layout-spacing-medium-8)"` between marks; `small-4` under the
-eyebrow. As a band, add section breathing with `large-13`+ block padding
-([spacing-steps.md](spacing-steps.md)).
+**Group** step between marks and **Control** under the eyebrow — `medium-10` and
+`small-6` on the `spacious` marketing page where a trust bar lives (`medium-8` /
+`small-4` under `standard`). As a band, add breathing with the **Band** step
+(`large-15`) ([density.md](density.md), [spacing-steps.md](spacing-steps.md)).
 
 ## A11y
 
@@ -55,7 +56,7 @@ full-color marks on dark). Keep one dominant brand band per view
   display="flex"
   flexDirection="column"
   alignItems="center"
-  gap="var(--uxl-theme-layout-spacing-small-4)"
+  gap="var(--uxl-theme-layout-spacing-small-6)"
   aria-label="Trusted by leading teams"
 >
   <Text type="Overline" width={false}>Trusted by teams at</Text>
@@ -64,17 +65,18 @@ full-color marks on dark). Keep one dominant brand band per view
     flexWrap="wrap"
     justifyContent="center"
     alignItems="center"
-    gap="var(--uxl-theme-layout-spacing-medium-8)"
+    gap="var(--uxl-theme-layout-spacing-medium-10)"
   >
     <Logo name="generic" width={112} color="colorSwitcherIcon" aria-label="Northwind" />
     <Logo name="generic" width={112} color="colorSwitcherIcon" aria-label="Acme" />
-    {/* Logos not in the catalog use Image */}
-    <Image src="/logos/contoso.svg" alt="Contoso" />
+    {/* Logos not in the catalog use Image; bound height to match the row */}
+    <Image src="/logos/contoso.svg" alt="Contoso" height={40} />
   </Layout>
 </Layout>
 ```
 
 ## A2UI
 
-No `getUxelleRecipe("logo-wall")` — compose `A2uiLogo` / `A2uiImage` inside an
-`A2uiLayout` (single wrapping row, layout-spacing only) ([a2ui.md](a2ui.md)).
+No `getUxelleRecipe("logo-wall")` — compose `A2uiLogo` (`width`) / `A2uiImage`
+(`height` or `width` so marks stay even) inside an `A2uiLayout` (single wrapping
+row, layout-spacing only) ([a2ui.md](a2ui.md)).

package/skills/uxelle-design-harness/recipe-multi-step-flow.md

@@ -34,8 +34,10 @@ narrow. See [how-to-page-layout.md](how-to-page-layout.md#action-clusters).
 
 ## Spacing
 
-`medium-12` between the stepper, the step body, and the footer; the step form uses
-its own `medium-8` field stack ([spacing-steps.md](spacing-steps.md)).
+**Density: `standard`** — a flow asks for one decision at a time, so keep it calm
+even inside a `compact` app ([density.md](density.md)). **Section** gap between the
+stepper, the step body, and the footer (`medium-12`); the step form uses its own
+**Group** field stack (`medium-8`) ([spacing-steps.md](spacing-steps.md)).
 
 ## A11y
 
@@ -65,7 +67,7 @@ const isLast = step === steps.length;
   p="var(--uxl-breakpoints-margin)"
   gap="var(--uxl-theme-layout-spacing-medium-12)"
 >
-  <Text type="Display Extra Small" as="h1" width={false}>Create a workspace</Text>
+  <Text type="Display Small" as="h1" width={false}>Create a workspace</Text>
 
   <nav aria-label="Progress">
     <Stepper

package/skills/uxelle-design-harness/recipe-page-header.md

@@ -19,9 +19,16 @@ status, and the actions that operate on the whole page.
 ## When not
 
 - Not a `PageHeader` component — it is a `Layout` composition.
-- Page actions only (create, import, export, delete). Controls that filter a table
+- Page actions only (create, import, delete). Controls that filter a table
   belong to the [query-bar](recipe-query-bar.md); tabs that swap a table's rows
   belong on the `Table` ([data-table-page](recipe-data-table-page.md)).
+- **Export splits by scope.** Export of the *whole dataset* is a page action and
+  belongs here — label it for that scope ("Export all"). Export of the *rows
+  currently in view* (after filters and search) belongs on the
+  [query-bar](recipe-query-bar.md), labelled for the view ("Export view"). Never
+  put both on one page: pick the scope the user actually needs. A
+  [data-table-page](recipe-data-table-page.md) defaults to "Export view" — omit
+  export from this header when that query bar is present.
 - Do not wrap `Lockup` in a nested `Layout` to share the row — let it be the flex
   sibling that shrinks and put `flexShrink={0}` on the action cluster.
 
@@ -40,9 +47,12 @@ would claim the row and drop the actions).
 
 ## Spacing
 
-`small-4` gap between title and actions. Lockup internals are `micro-2`
-(component-owned). The header sits in the page column at the `medium-12` section gap
-([spacing-steps.md](spacing-steps.md)).
+**Control** step between title and actions. Lockup internals are component-owned
+(`micro-2`) and do not shift with the mode. The header sits in the page column at
+the **Section** gap ([spacing-steps.md](spacing-steps.md)).
+
+Inherits the host experience's mode — `micro-3` / `medium-9` under `compact`,
+`small-4` / `medium-12` under `standard` ([density.md](density.md)).
 
 ## A11y
 

package/skills/uxelle-design-harness/recipe-page-shell.md

@@ -19,7 +19,7 @@ host canvas → content column (`max-container-width`, `mh="auto"`, `p` = breakp
 
 ## Spacing
 
-React page column: [how-to-page-layout.md](how-to-page-layout.md). Section stacks: medium-8 or small-4. Intro lockup internals: micro-2. Form/dialog action groups: [how-to-page-layout.md](how-to-page-layout.md#action-clusters). A2UI: layout-spacing only (`p` large-13, `gap` medium-12).
+**Density: `standard`** unless the body is data-dense (then `compact`) or public marketing (then `spacious`) — [density.md](density.md). React page column: [how-to-page-layout.md](how-to-page-layout.md). **Section** gap between sections (`medium-12`); section stacks use **Group** (`medium-8`) or **Control** (`small-4`); intro lockup internals **Tight** (`micro-2`). Form/dialog action groups: [how-to-page-layout.md](how-to-page-layout.md#action-clusters). A2UI: layout-spacing only, `spacious` never applies (`p` **Band**-equivalent `large-13`, `gap` **Section** `medium-12`).
 
 ## A11y
 
@@ -43,7 +43,7 @@ React page column: [how-to-page-layout.md](how-to-page-layout.md). Section stack
   <Lockup
     topSlot={false}
     title={
-      <Text type="Display Extra Small" as="h1" width={false}>
+      <Text type="Display Small" as="h1" width={false}>
         Account settings
       </Text>
     }

package/skills/uxelle-design-harness/recipe-pricing.md

@@ -33,8 +33,11 @@ comfortable tier. See [how-to-page-layout.md](how-to-page-layout.md#responsivene
 
 ## Spacing
 
-`--uxl-breakpoints-gutter` between tiers; feature rows are the `List` default;
-`large-13`+ block padding as a band ([spacing-steps.md](spacing-steps.md)).
+`--uxl-breakpoints-gutter` between tiers in every mode; feature rows keep the
+`List` default (component-owned, density-invariant); the **Band** step as a band —
+`large-15` on the `spacious` marketing page. A tier comparison is the one dense
+piece on an airy page: let its feature rows stay tight while the section still sits
+at the page's **Section** gap ([density.md](density.md), [spacing-steps.md](spacing-steps.md)).
 
 ## A11y
 

package/skills/uxelle-design-harness/recipe-query-bar.md

@@ -18,6 +18,11 @@ Controls that filter, facet, search, or export the rows/cards currently in view.
 ## When not
 
 - Page-level actions (create, import, delete) belong to the [page-header](recipe-page-header.md).
+- **Export here is view-scoped only.** This bar exports what the filters and search
+  currently leave on screen, so label it for that ("Export view"). Exporting the
+  *whole dataset* ignores this bar's controls and is a page action —
+  [page-header](recipe-page-header.md). Never put both on one page: pick the
+  scope the user actually needs.
 - Data tabs that swap which rows are shown sit above the query bar, first in the
   `Table` `topSlot` — not on this row.
 - No filter *fields* on the bar: a filter *trigger* opens a right `Sheet`.
@@ -33,14 +38,25 @@ row **below**.
 ## Responsive
 
 The bar stays a row of controls. When very tight, let the search field take the
-full line above the filter/export cluster; the applied `FilterChipGroup` wraps.
+full line above the filter/export cluster; the applied `FilterChipGroup` wraps
+whole chips. A chip wider than the row ellipsizes so dismiss stays visible.
 Keep the filter and export buttons together (`flexShrink={0}`).
 
+Chip labels are component-owned: pass `label` on `ChoiceChip` / `FilterChip` — do
+not wrap `Text`. Unchecked choice chips use Condensed; checked use Condensed Alt.
+Filter chips use Condensed. Exclusive `ChoiceChip` selection is one checked value
+in app state (`role="group"`); use `RadioGroup` or `SegmentedControl` for radio
+semantics.
+
 ## Spacing
 
-`small-4` gap within and between the two clusters; the applied-chips row is
-`small-4` below. This whole stack lives in the table's `topSlot` at `small-4`, not
-the page-section gap ([spacing-steps.md](spacing-steps.md)).
+The **Control** step throughout — within and between the two clusters, and for the
+applied-chips row below. This whole stack lives in the table's `topSlot` at the
+**Control** step, never the **Section** gap ([spacing-steps.md](spacing-steps.md)).
+
+As a piece, it inherits the host experience's density mode: `micro-3` on a
+`compact` data-table page (its usual home), `small-4` under `standard`
+([density.md](density.md)).
 
 ## A11y
 
@@ -92,7 +108,7 @@ See [how-to-accessibility.md](how-to-accessibility.md).
         />
       </Layout>
       <Layout flexShrink={0}>
-        <Button emphasis="low"><Text type="Button" width>Export all</Text></Button>
+        <Button emphasis="low"><Text type="Button" width>Export view</Text></Button>
       </Layout>
     </Layout>
   </Layout>

package/skills/uxelle-design-harness/recipe-record-detail.md

@@ -37,8 +37,11 @@ scrolls when the labels overflow. See [how-to-page-layout.md](how-to-page-layout
 
 ## Spacing
 
-`medium-12` between page sections; `--uxl-breakpoints-gutter` between the main and
-aside columns; summary rows `small-4` ([spacing-steps.md](spacing-steps.md)).
+**Density: `standard`**; step to `compact` when the record is a dense diagnostic
+view (many fields scanned side by side) rather than a read-and-act page
+([density.md](density.md)). **Section** gap between page sections (`medium-12`);
+**Control** for summary rows (`small-4`); `--uxl-breakpoints-gutter` between the
+main and aside columns in every mode ([spacing-steps.md](spacing-steps.md)).
 
 ## A11y
 

package/skills/uxelle-design-harness/recipe-settings-page.md

@@ -38,7 +38,7 @@ Standalone fields (email, language, phone, about) stay in the section stack at `
 
 ## Spacing
 
-Page column: [how-to-page-layout.md](how-to-page-layout.md). Section gap: `medium-12`. Lockup internals: `micro-2`. Form field stack: `medium-8`. Inline related fields: `small-4`. Do not add extra padding around `ListControls`. Form actions: [how-to-page-layout.md](how-to-page-layout.md#action-clusters).
+**Density: `standard`** — settings are read and decided on, so comprehension beats volume; do not compact a preferences page ([density.md](density.md)). Page column: [how-to-page-layout.md](how-to-page-layout.md). **Section** gap `medium-12`. **Tight** lockup internals `micro-2`. **Group** form field stack `medium-8`. **Control** inline related fields `small-4`. Do not add extra padding around `ListControls` — its row rhythm is component-owned. Form actions: [how-to-page-layout.md](how-to-page-layout.md#action-clusters).
 
 ## A11y
 
@@ -65,7 +65,7 @@ Import from `@uxelle/components`. Pass `bottomText` (or `""`) so the catalog dem
   <Lockup
     topSlot={false}
     title={
-      <Text type="Display Extra Small" as="h1" width={false}>
+      <Text type="Display Small" as="h1" width={false}>
         Settings
       </Text>
     }
@@ -163,7 +163,7 @@ Import from `@uxelle/components`. Pass `bottomText` (or `""`) so the catalog dem
 </Layout>
 ```
 
-If the host already renders `<main>` and the page column (skip-link target), omit `as="main"` and extra `p` on this stack — still set `maxWidth="600px"` on the settings column (or on the host column when this is the only page in view).
+If chrome already renders `<main>` (the skip-link target), omit `as="main"` — but still render this column yourself, `p` and `maxWidth="600px"` included. Chrome supplies only the scrollport, never a column, so there is nothing to avoid duplicating ([how-to-page-layout.md](how-to-page-layout.md#who-owns-the-content-column)).
 
 ## A2UI
 

package/skills/uxelle-design-harness/recipe-stat-callouts.md

@@ -38,8 +38,13 @@ its track. A row variant can use vertical `Divider`s between cells that simply w
 
 ## Spacing
 
-`gap="var(--uxl-breakpoints-gutter)"` between cells. As a marketing band, add
-section breathing with `large-13`+ block padding
+`gap="var(--uxl-breakpoints-gutter)"` between cells — the grid gap is
+density-invariant, so KPI tiles align identically in every mode.
+
+This piece serves both ends of the density range and inherits the host's mode
+([density.md](density.md)). As dashboard KPIs on a `compact` page it takes no band
+padding at all and sits at the page's `medium-9` **Section** gap. As a marketing
+band on a `spacious` page it adds breathing with the **Band** step (`large-15`)
 ([spacing-steps.md](spacing-steps.md)).
 
 ## A11y
@@ -69,7 +74,7 @@ Plain figures (marketing proof band):
   gap="var(--uxl-breakpoints-gutter)"
   aria-label="By the numbers"
 >
-  <Layout display="flex" flexDirection="column" gap="var(--uxl-theme-layout-spacing-micro-2)">
+  <Layout display="flex" flexDirection="column" gap="var(--uxl-theme-layout-spacing-micro-3)">
     <Text type="Display Medium" as="p" width={false}>10k+</Text>
     <Text type="Body Small" width={false}>Teams onboarded</Text>
   </Layout>

package/skills/uxelle-design-harness/recipe-states.md

@@ -19,8 +19,10 @@ Any region backed by data or an async action: lists, tables, cards, forms, panel
 - Do not blank the whole page for a partial load — scope the state to the region.
 - Do not signal status with color alone; pair with an icon or words
   ([how-to-color.md](how-to-color.md)).
-- Do not swap a `SkeletonGroup` out of the tree while loading — keep it mounted and
-  toggle `loading`.
+- Do not swap a `SkeletonGroup` out of the tree while loading. Keep **the group**
+  mounted across the whole load and toggle its `loading` prop; swapping its
+  *children* between shapes and real content is expected (see the example).
+  Unmounting the group loses the load/complete announcement.
 
 ## Loading
 
@@ -68,7 +70,10 @@ where the data would be, plus the action that creates the first item.
 ## Error
 
 A recoverable, in-flow failure uses a non-dismissible `danger` `Banner` with a retry
-action.
+action. The single action passes no `direction` — row is the `ButtonGroup` default
+and one child looks the same either way. Add a second text button (a Dismiss beside
+Try again) and the cluster takes the tablet switch like any other
+([how-to-page-layout.md](how-to-page-layout.md#action-clusters)).
 
 ```tsx
 <Banner
@@ -77,7 +82,7 @@ action.
   alert
   leadingSlotContent={<Icon iconName="error" variant="sharpUnfilled" aria-hidden />}
   actionsSlotContent={
-    <ButtonGroup direction="row" aria-label="Error actions">
+    <ButtonGroup aria-label="Error actions">
       <Button emphasis="medium" onClick={retry}>
         <Text type="Button" width>Try again</Text>
       </Button>

package/skills/uxelle-design-harness/recipe-summary-list.md

@@ -33,9 +33,11 @@ long, stack each pair (label above value) below tablet by switching
 
 ## Spacing
 
-Row/column `gap` = `var(--uxl-theme-layout-spacing-small-4)`. Reset the browser
-`dd` indent with `margin: 0`. Group inside a section at the page rhythm
-([spacing-steps.md](spacing-steps.md)).
+Row/column `gap` = the **Control** step
+(`var(--uxl-theme-layout-spacing-small-4)` under `standard`, `micro-3` under
+`compact` — a key/value summary is a common dense surface). Reset the browser `dd`
+indent with `margin: 0`. Group inside a section at the page rhythm
+([spacing-steps.md](spacing-steps.md), [density.md](density.md)).
 
 ## A11y
 

package/skills/uxelle-design-harness/recipe-template.md

@@ -32,6 +32,12 @@ narration.
    ([how-to-page-layout.md](how-to-page-layout.md#responsiveness)).
 5. **Spacing** — stacks use `var(--uxl-theme-layout-spacing-*)` (or `0`); page
    chrome uses the breakpoint tokens ([spacing-steps.md](spacing-steps.md)).
+   Name spacing by **role** (Flush / Tight / Control / Group / Section / Band), not
+   by a bare step. An **experience** declares its default **density mode**
+   (`compact` | `standard` | `spacious`) and why; a **piece** says it inherits the
+   host's mode and gives the resolution for the modes it realistically appears in.
+   Call out anything density-invariant (component-owned padding, grid gutters)
+   ([density.md](density.md)).
 6. **A11y** — landmarks, heading ranks, names, live regions
    ([how-to-accessibility.md](how-to-accessibility.md)).
 7. **Color** — include when the recipe uses palettes or brand bands: set

package/skills/uxelle-design-harness/recipe-testimonial.md

@@ -32,8 +32,10 @@ A single testimonial is a centered, measure-capped block. A set reflows with
 
 ## Spacing
 
-`small-4` between the quote and attribution; `--uxl-breakpoints-gutter` between cards
-in a grid; `large-13`+ block padding as a band ([spacing-steps.md](spacing-steps.md)).
+**Control** step between the quote and its attribution (`small-6` on the `spacious`
+marketing page, `small-4` under `standard`); `--uxl-breakpoints-gutter` between
+cards in a grid in every mode; the **Band** step (`large-15`) as a band
+([density.md](density.md), [spacing-steps.md](spacing-steps.md)).
 
 ## A11y
 
@@ -54,7 +56,7 @@ associated. A customer `Logo` is decorative when the name is in text
         </Text>
       </blockquote>
       <figcaption>
-        <Layout display="flex" flexDirection="column" gap="var(--uxl-theme-layout-spacing-micro-2)">
+        <Layout display="flex" flexDirection="column" gap="var(--uxl-theme-layout-spacing-micro-3)">
           <Text type="Body Small Alt" width={false}>Dana Lee</Text>
           <Text type="Condensed" width={false}>VP Operations, Northwind</Text>
         </Layout>

package/skills/uxelle-design-harness/spacing-steps.md

@@ -18,16 +18,24 @@ number"). The size band must match the index, so `medium-10` exists but
 
 ## Choosing a step
 
+Do not pick a step directly. Pick the **role** the space plays, then resolve it
+through the experience's **density mode** — [density.md](density.md).
+
 - **Flush** (line boxes already separate lines, e.g. name over email) -> `0`.
-- **Tight stacks / chips** -> `micro-2`.
-- **Related controls / field stacks** -> `small-4`. Same-row clusters (search +
+- **Tight** stacks / chips / lockup internals.
+- **Control** — related controls and field stacks. Same-row clusters (search +
   export, filter + facet) use this gap and stay `nowrap`.
-- **Card / section padding** (also the default A2UI gap) -> `medium-8`.
-- **Page-section gap** (lockup vs table vs a later block) -> `medium-12`.
-- **Hero / extra breathing inside a section** -> `large-13`+.
+- **Group** — bespoke section padding and subgroups (also the default A2UI gap).
+- **Section** — between page sections (lockup vs table vs a later block).
+- **Band** — block padding on a full-bleed band (hero, CTA).
+
+The `standard` mode resolves these to `0` / `micro-2` / `small-4` / `medium-8` /
+`medium-12` / `large-13` — the harness baseline. `compact` shifts the column down
+for data-dense product surfaces, `spacious` up for marketing. Resolve the whole
+column from one mode; never tighten a single role in isolation.
 
-Do not use the page-section gap (`medium-12`) between a table's tabs and its grid —
-those belong together at `small-4`.
+Do not use the **Section** gap between a table's tabs and its grid — those belong
+together at the **Control** gap.
 
 ## Usage
 
@@ -50,7 +58,8 @@ emit them in new generated UI** — use the indexed tokens.
 ## Not part of this ramp
 
 Page inset, column cap, and column/`fr` gaps are **page chrome**, not ramp steps:
-`--uxl-breakpoints-margin` / `-max-container-width` / `-gutter`. See
+`--uxl-breakpoints-margin` / `-max-container-width` / `-gutter`. They are also
+**density-invariant** — they do not change with the mode ([density.md](density.md)). See
 [how-to-page-layout.md](how-to-page-layout.md) and [tokens.md](tokens.md). One-column
 reading content (a settings/form page, or a form / FAQ / prose section on a wider
 page) may cap at the `maxWidth="600px"` reading measure — centered — instead of the

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

@@ -38,8 +38,10 @@ Never hardcode hex/rgb for themeable UI. Palette selection (`default`,
 ## Spacing (layout ramp)
 
 Stacks on `Layout` / `A2uiLayout` pass `0` or `var(--uxl-theme-layout-spacing-*)`
-on `gap` / padding / margin. The full 0-16 ramp and how to choose a step is in
-[spacing-steps.md](spacing-steps.md). Set `display="flex"` (or `grid`) when using `gap`.
+on `gap` / padding / margin. The full 0-16 ramp and the spacing **roles** are in
+[spacing-steps.md](spacing-steps.md); which step each role resolves to depends on
+the experience's **density mode** ([density.md](density.md)). Set `display="flex"`
+(or `grid`) when using `gap`.
 
 ## Page chrome (React app/page body)
 
@@ -50,6 +52,13 @@ Usage in [how-to-page-layout.md](how-to-page-layout.md).
 - `--uxl-breakpoints-margin` — padding around the body
 - `--uxl-breakpoints-gutter` — gap between columns / `fr` tracks
 
+`--uxl-breakpoints-padding-<band>-<index>` is the per-breakpoint source the spacing
+ramp aliases (`--uxl-theme-layout-spacing-medium-8` resolves to
+`--uxl-breakpoints-padding-medium-8`). Use the `--uxl-theme-layout-spacing-*` name
+in app and recipe CSS; the `padding` family appears only where a catalog component
+documents its own band padding (e.g. `Footer` —
+[recipe-app-chrome.md](recipe-app-chrome.md)). Same index rule applies.
+
 Breakpoint bounds (read-only, for the rare JS switch) are exposed as
 `--uxl-theme-layout-{mobile,tablet,desktop,desktop-plus}-screen-width-{min,max}`,
 and the active band as `--uxl-breakpoints-screen-width-{min,max}`. Reference these
@@ -71,12 +80,44 @@ must, compose a `box-shadow` from levels `1`-`3` at depths `1`-`4`:
 ## Typography
 
 Render copy with the `Text` component (`type="Display Small"`, `Body Medium`,
-`Button`, …) and its `as` prop — never set font-size in app CSS. Font-family
-variables exist for custom chrome only:
+`Button`, …) and its `as` prop — never set font-size in app CSS. Which `type` a
+heading rank gets depends on the density mode ([density.md](density.md)).
+Font-family variables exist for custom chrome only:
 
 - `--uxl-component-text-font-family-display`
 - `--uxl-component-text-font-family-body`
 
+### `width` on `Text`
+
+`width` defaults to `true` and makes the text box **hug its content**;
+`width={false}` makes it **span its container**, which is what lets long copy wrap
+and `truncation` clip to a stable width.
+
+- **`width={false}`** for anything that wraps or truncates — headings, body copy,
+  descriptions, `Lockup` slots, `Dialog` titles and bodies.
+- **`width`** (the default) for a short label inside a control — `type="Button"`
+  labels, chips, badges — so the control sizes to its text.
+
+Chip labels are **component-owned**. Pass the `label` string on `ChoiceChip` /
+`FilterChip` (and their A2UI adapters) — do not wrap a `Text` node.
+
+- **ChoiceChip** — `Condensed` when unchecked, `Condensed Alt` when checked.
+  Exclusive single-select is one checked value in app/host state. Keep
+  `role="group"`; chips stay `aria-pressed` toggles. Use `RadioGroup` or
+  `SegmentedControl` for radio semantics.
+- **FilterChip** — `Condensed`. Labels hug content so `FilterChipGroup` wraps
+  whole chips. A chip wider than its container ellipsizes so the dismiss
+  control stays visible.
+
+## Inline `style` on the React track
+
+React recipes may use inline `style` for what `Layout` props do not express —
+a scrollport (`overflow`, `minHeight`), a `backgroundColor` on a palette region, or
+native `dl` grid tracks — **provided every value is a `--uxl-*` variable**. Inline
+`style` is not a licence to hardcode: no hex, no px, no font-size. The "no
+`className` / `style`" rule is **A2UI-only**, where styling must come from adapter
+props ([a2ui.md](a2ui.md)).
+
 ## Component tokens
 
 `--uxl-component-<component>-*` tokens style a specific component from inside that