@uxelle/skills 0.2.0-beta.2 → 0.2.2

package/skills/uxelle-components/getting-started.md

@@ -0,0 +1,54 @@
+<!-- Generated from README.md (getting-started region). Do not edit. -->
+
+# Getting started
+
+New app or host without uxElle packages and CSS? Read this file first, then set up page chrome in [how-to-host.md](../uxelle-design-harness/how-to-host.md). Component APIs live in [SKILL.md](SKILL.md). Optional A2UI runtime: [a2ui.md](../uxelle-design-harness/a2ui.md). Do not preload every component file.
+
+## Quick Start
+
+Peer dependencies: React 18 or 19.
+
+```bash
+npm install @uxelle/components @uxelle/themes
+```
+
+```tsx
+import "@uxelle/components/styles.css";
+import "@uxelle/components/index.css";
+import "@uxelle/themes/themes/open-source/open-source.css";
+
+import { Button } from "@uxelle/components";
+
+function App() {
+  return <Button emphasis="high">Get Started</Button>;
+}
+```
+
+`styles.css` loads Material Symbols and the global baseline. `index.css` ships the bundled component rules. Load both stylesheets in the host app — the package JS does not import CSS automatically.
+
+### Next.js / SSR
+
+- Import the three stylesheets in `app/layout.tsx` (or a top-level provider). JS side effects will not style App Router.
+- Published `@uxelle/components` JS is prefixed with `"use client"`. Importing any component places that file in the client graph.
+- Pass `mobile={true}` or `mobile={false}` on `NavigationSide` so server and client markup match. Omit `mobile` only in client-only surfaces.
+
+Optional: for an agent-driven UI surface, also install `@uxelle/a2ui`.
+
+## Themes
+
+Theme CSS is published as `@uxelle/themes` and generated from design tokens. Apply a theme by importing one CSS file. Set `data-open-source="light"` or `data-open-source="dark"` on `<html>`, plus `data-color-switcher="default"`. Optional: wrap the app with `UXelleThemeProvider` so those attributes stay in sync.
+
+```tsx
+import "@uxelle/themes/themes/open-source/open-source.css";
+import { UXelleThemeProvider } from "@uxelle/themes/react";
+
+function AppShell({ children }: { children: React.ReactNode }) {
+  return (
+    <UXelleThemeProvider theme="open-source" darkMode={false} colorSwitcher="default">
+      {children}
+    </UXelleThemeProvider>
+  );
+}
+```
+
+Open Source uses **Open Sans** (self-hosted in the theme package). Do not set `font-family` in app CSS — `Text` uses theme tokens.

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

@@ -37,29 +37,38 @@ palette. The full mapping of principles to uxElle mechanisms lives in
 1. Load this `SKILL.md`. The foundations below always apply.
 2. Read the variable foundation once: [tokens.md](tokens.md) and
    [spacing-steps.md](spacing-steps.md).
-3. Creating an app shell? [how-to-host.md](how-to-host.md). Building a page body?
-   [how-to-page-layout.md](how-to-page-layout.md) (layout **and** responsiveness),
-   [how-to-color.md](how-to-color.md), and [how-to-accessibility.md](how-to-accessibility.md).
-4. Prefer an existing component. Link its doc at point of use, e.g.
+3. Pick the **density mode** for the experience — `compact` (data-dense product),
+   `standard` (task product, the default), `spacious` (marketing). One mode per
+   experience, chosen before any layout: [density.md](density.md).
+4. Creating a **new** app/host? Install and load CSS from
+   [getting-started.md](../uxelle-components/getting-started.md), then the
+   shell in [how-to-host.md](how-to-host.md). Building a page body in an
+   existing host? [how-to-page-layout.md](how-to-page-layout.md) (layout
+   **and** responsiveness), [how-to-color.md](how-to-color.md), and
+   [how-to-accessibility.md](how-to-accessibility.md).
+5. Prefer an existing component. Link its doc at point of use, e.g.
    `Table` -> `../uxelle-components/Table.md`. Import from `@uxelle/components`.
-5. Otherwise follow a recipe (see the index). If nothing fits, compose `Layout` +
+6. Otherwise follow a recipe (see the index). If nothing fits, compose `Layout` +
    `Text` + primitives on the grid.
-6. Building a runtime surface? Read [a2ui.md](a2ui.md) and each recipe's **A2UI** note.
-7. Before you finish, run the quality checklist below.
+7. Building a runtime surface? Read [a2ui.md](a2ui.md) and each recipe's **A2UI** note.
+8. Before you finish, run the quality checklist below.
 
 ## Decision tree
 
-- **New app/host** (loads theme CSS, `data-*`, skip link, `main`) -> [how-to-host.md](how-to-host.md).
-  Composing inside an existing host -> skip host setup; do not set theme `data-*` on `<html>`.
+- **New app/host** (packages not installed, or CSS / `data-*` not loaded) ->
+  [getting-started.md](../uxelle-components/getting-started.md), then
+  [how-to-host.md](how-to-host.md) for skip link, `main`, and column chrome.
+  Composing inside an existing host -> skip both; do not set theme `data-*` on `<html>`.
 - **Product experience** (signed-in app):
   app frame -> [recipe-app-chrome.md](recipe-app-chrome.md);
-  landing/overview -> [recipe-dashboard-overview.md](recipe-dashboard-overview.md);
-  records list -> [recipe-data-table-page.md](recipe-data-table-page.md);
+  landing/overview -> [recipe-dashboard-overview.md](recipe-dashboard-overview.md) (`compact`);
+  records list -> [recipe-data-table-page.md](recipe-data-table-page.md) (`compact`);
   one record -> [recipe-record-detail.md](recipe-record-detail.md);
   settings -> [recipe-settings-page.md](recipe-settings-page.md);
   wizard/checkout -> [recipe-multi-step-flow.md](recipe-multi-step-flow.md);
   generic body -> [recipe-page-shell.md](recipe-page-shell.md).
-- **Marketing experience** (public): whole page -> [recipe-landing-page.md](recipe-landing-page.md),
+  Unmarked product recipes default to `standard` ([density.md](density.md)).
+- **Marketing experience** (public, `spacious`): whole page -> [recipe-landing-page.md](recipe-landing-page.md),
   composed from the marketing pieces below.
 - **A piece** (part of an experience): page intro -> [recipe-page-header.md](recipe-page-header.md);
   filter/search toolbar -> [recipe-query-bar.md](recipe-query-bar.md);
@@ -79,6 +88,11 @@ palette. The full mapping of principles to uxElle mechanisms lives in
   padding / margin. Page chrome (inset, column cap, `fr` gaps) uses
   `--uxl-breakpoints-margin` / `-max-container-width` / `-gutter`. See
   [spacing-steps.md](spacing-steps.md) and [how-to-page-layout.md](how-to-page-layout.md).
+- **Density**: choose the step by **role** (Flush / Tight / Control / Group /
+  Section / Band) and the heading type by **rank**, both resolved through one
+  **mode** for the whole experience — `compact` | `standard` | `spacious`. Page
+  chrome and component internals are density-invariant. Never mix modes or tighten
+  one role alone. See [density.md](density.md).
 - **Color**: style via `--uxl-color-switcher-*` roles; apply a palette with
   `data-color-switcher` on a **region** (never invent switcher names). See
   [how-to-color.md](how-to-color.md).
@@ -86,10 +100,12 @@ palette. The full mapping of principles to uxElle mechanisms lives in
   never use `--uxl-component-*` in app/recipe CSS (those belong inside components).
 - **No hardcoded values**: no hex, no font-family, no breakpoint px. Read
   breakpoint bounds from theme variables when JS is unavoidable
-  ([how-to-page-layout.md](how-to-page-layout.md)). Exception: one-column reading
-  content (a form/settings page, or a form / FAQ / prose section on a wider page)
-  may cap at the `maxWidth="600px"` **reading measure** — always centered with
-  `mh="auto"` ([how-to-page-layout.md](how-to-page-layout.md#reading-measure)).
+  ([how-to-page-layout.md](how-to-page-layout.md)). Two exceptions: one-column
+  reading content (a form/settings page, or a form / FAQ / prose section on a wider
+  page) may cap at the `maxWidth="600px"` **reading measure**, always centered with
+  `mh="auto"` ([how-to-page-layout.md](how-to-page-layout.md#reading-measure)); and
+  **intrinsic sizes** — `minmax()` mins and a bounded search field — use `rem`
+  ([how-to-page-layout.md](how-to-page-layout.md#intrinsic-sizes-in-rem)).
 - **Components first**: prefer a catalog component over bespoke markup; link its
   doc at point of use (`../uxelle-components/<Name>.md`); do not open package source.
 - **Recipes are patterns, not exports**: never add `PageShell` / `AppChrome` /
@@ -104,14 +120,21 @@ Every generated screen must pass this. It is the definition of done.
 
 - **Grid & rhythm**: content sits on the grid; one capped content column via
   `--uxl-breakpoints-max-container-width` / `-gutter` / `-margin`; section spacing
-  from the ramp (page sections use `medium-12`). One-column reading sections
+  from the ramp at the experience's **Section** step. One-column reading sections
   (form / FAQ / prose) share the `600px` reading measure and are centered
   (`mh="auto"`); a decision cluster (form actions) is separated from its fields by
-  `medium-12`, not the field gap.
+  the **Section** step, not the field gap.
+- **Density**: one mode declared for the surface and applied to every role; the gap
+  roles (Tight -> Control -> Group -> Section) stay ~1.5x apart; page chrome and
+  component internals unchanged; no breakpoint logic added for density
+  ([density.md](density.md)).
 - **Tokens only**: spacing from `--uxl-theme-layout-spacing-*`; color from
   `--uxl-color-switcher-*`; no hardcoded hex or px, no invented `--uxl-*`, no
   `--uxl-component-*` in app CSS, no `var(--x, fallback)`.
-- **Hierarchy**: exactly one `h1`; heading ranks unbroken; few `Text` type roles.
+- **Hierarchy**: exactly one `h1`; heading ranks unbroken; each rank resolved to a
+  **distinct** `Text` type through the density mode — consecutive ranks never share
+  a type (an `h1` and `h2` both on `Display Extra Small` flatten the page), and
+  headings inside a `Card` step down one stop ([density.md](density.md)).
 - **Responsive**: reflows mobile -> up with no px literals; clusters stack, `Table`
   scrolls, nav collapses; touch targets stay >= 24 CSS px.
 - **Color discipline**: at most one dominant brand band per view; status palettes
@@ -126,9 +149,10 @@ Every generated screen must pass this. It is the definition of done.
 
 **Foundations** (always apply): [principles.md](principles.md) ·
 [tokens.md](tokens.md) · [spacing-steps.md](spacing-steps.md) ·
+[density.md](density.md) ·
 [how-to-page-layout.md](how-to-page-layout.md) · [how-to-color.md](how-to-color.md) ·
 [how-to-accessibility.md](how-to-accessibility.md) · [how-to-host.md](how-to-host.md) ·
-[a2ui.md](a2ui.md)
+[getting-started](../uxelle-components/getting-started.md) · [a2ui.md](a2ui.md)
 
 **Experiences** — product: [app-chrome](recipe-app-chrome.md) ·
 [page-shell](recipe-page-shell.md) · [dashboard-overview](recipe-dashboard-overview.md) ·

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

@@ -19,6 +19,10 @@ use the catalog schema the host provides.
 - **No `className` / `style`.** Styling comes from the theme and adapter props.
 - **Layout-spacing tokens only.** `A2uiLayout` accepts `0` or
   `var(--uxl-theme-layout-spacing-*)`; never emit page-chrome breakpoint tokens.
+- **`standard` or `compact` density only.** Chat surfaces are narrow and have no
+  full-bleed bands, so `spacious` never applies and the **Band** role has no
+  meaning. Use `standard` by default, `compact` for data-heavy runtime output
+  ([density.md](density.md)).
 - **No responsive JS.** There is no `matchMedia`. Default to a single, narrow
   column (chat is mobile-like) and stack action clusters (`"direction": "column"`).
 - **Host owns theme.** Never set theme `data-*` or a skip link from adapters; the
@@ -45,12 +49,27 @@ recipe JSON into the customer app.
 Most catalog components map 1:1 to an `A2ui<Name>` adapter (e.g. `Button` ->
 `A2uiButton`, `Textfield` -> `A2uiTextfield`, `Textarea` -> `A2uiTextarea`,
 `Table` -> `A2uiTable`, `Sheet` -> `A2uiSheet`, `Hero` -> `A2uiHero`,
-`Stepper` -> `A2uiStepper` + `A2uiStepperItem`, `ListControls` -> `A2uiListControls`,
+`Image` -> `A2uiImage`, `Stepper` -> `A2uiStepper` + `A2uiStepperItem`,
+`ListControls` -> `A2uiListControls`,
 `Banner` -> `A2uiBanner`, `LabelBadge` -> `A2uiLabelBadge`, `StatTile` -> `A2uiStatTile`,
+`ChoiceChip` -> `A2uiChoiceChip`, `ChoiceChipGroup` -> `A2uiChoiceChipGroup`,
+`FilterChip` -> `A2uiFilterChip`, `FilterChipGroup` -> `A2uiFilterChipGroup`,
 `DynamicAngle*` -> `A2uiDynamicAngle*`). `Table` has the full family (`A2uiTableGrid`,
 `A2uiTableHead`, `A2uiTableBody`, `A2uiTableRow`, `A2uiTableCell`,
 `A2uiTableHeaderCell`, `A2uiTableColumnSizingProvider`).
 
+`A2uiImage` box size (`width`, `height`, `minWidth`, `maxWidth`, `minHeight`,
+`maxHeight`) is `number|string` — numbers are pixels, strings pass through as CSS
+(including `var(--uxl-…)`). `aspectRatio` crops and computes the missing axis.
+Omit size and `aspectRatio` on an `A2uiImage` nested in `A2uiHero`.
+
+`A2uiChoiceChip` / `A2uiFilterChip` take a `label` string. Do not nest `A2uiText`
+inside a chip. Choice-chip labels use Condensed when unchecked and Condensed Alt
+when checked; filter-chip labels use Condensed. `A2uiFilterChipGroup` wraps whole
+chips; a chip wider than its container ellipsizes so dismiss stays visible.
+Exclusive `A2uiChoiceChip` selection is one checked value in host state (toggles,
+not radios). Use `A2uiRadioGroup` or `A2uiSegmentedControl` for radio semantics.
+
 Known gaps — substitute rather than invent:
 
 | React | A2UI |
@@ -66,7 +85,8 @@ If a design needs a gap component as its backbone, say so in the recipe's
 
 ## Translating a React recipe
 
-1. Keep the same region order and layout-spacing values.
+1. Keep the same region order. Keep the layout-spacing values too, unless the React
+   surface was `spacious` — then re-resolve its roles at `standard`.
 2. Swap each component for its adapter; expand `Lockup` to stacked `A2uiText`.
 3. Replace `useBreakpointUp` switches with a single narrow column.
 4. Replace React state with host bindings.

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"`).

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,18 @@ 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:
-
-```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).
+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.
 
 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)).