@uxelle/skills 0.2.1-beta.0 → 0.2.3

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

@@ -24,6 +24,8 @@ A small set of headline numbers — revenue, active users, uptime, "10k+ teams."
 - Do not put `onClick` on StatTile — put a `Link` or `IconButton` in
   `trailingSlotContent`.
 - Do not signal a delta with color alone — pair it with a sign or word.
+- Do not wrap StatTile labels yourself. The label stays on one line and
+  ellipsizes; hover or focus a truncated label to read the full name.
 
 ## Regions
 
@@ -38,17 +40,22 @@ 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
 
 Each figure and its label read together. StatTile names the group from `label`
-automatically (including `valueFirst`). If there is no label, set `aria-label`
-that combines the figure and its meaning. If the trailing slot holds a delta,
-keep the meaning in text, not color alone. See
-[how-to-accessibility.md](how-to-accessibility.md).
+automatically (including `valueFirst`), including when the visible label is
+ellipsized. If there is no label, set `aria-label` that combines the figure and
+its meaning. If the trailing slot holds a delta, keep the meaning in text, not
+color alone. See [how-to-accessibility.md](how-to-accessibility.md).
 
 ## Color
 
@@ -69,7 +76,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