@uxelle/skills 0.2.0-beta.2

package/skills/uxelle-components/Textfield.md

@@ -0,0 +1,62 @@
+# Textfield
+
+Import: `import { Textfield } from "@uxelle/components";`
+
+Single-line text input with design tokens, optional `Label`, icon slots, and `FieldMessage`.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label | `boolean` | `true` | When false, the label row is not rendered; pass `aria-label` so the input keeps an accessible name. |
+| labelText | `string` | `"Label"` | Visible label text, rendered as Body Medium Alt inside `Label`; ignored when `labelSlot` is set, and an empty string hides the label row. |
+| labelSlot | `ReactNode` | `—` | Replaces `labelText` with custom content inside `Label`, which keeps `htmlFor` and the required asterisk. Pass `id` on `Textfield` for a stable label association. |
+| fieldMessage | `boolean` | `false` | Renders a `FieldMessage` row below the input; `validation` set to `success` or `error` shows the row as well, so use this flag for neutral helper copy. |
+| fieldMessageContent | `string` | `""` | Content for the `FieldMessage` row; when omitted, the row falls back to built-in copy for the current `validation` state. |
+| validation | `"none" \| "success" \| "error"` | `"none"` | Validation state: `success` and `error` restyle the field message and force the row; `error` also sets `aria-invalid` and links the message via `aria-errormessage`. |
+| leadingIcon | `boolean` | `false` | When true, renders the built-in leading `Icon` from `leadingIconName`; `leadingSlot` is the identical alias and `leading` overrides both. |
+| leadingSlot | `boolean` | `false` | Alias of `leadingIcon`: either flag turns the leading region on, matching the `ListItem` slot naming. |
+| leadingIconName | `string` | `"add"` | Material Symbol rendered in the leading region; used only when `leadingIcon` (or `leadingSlot`) is true and `leading` is unset. An empty string falls back to `add`. |
+| leadingIconVariant | `"sharpFilled" \| "sharpUnfilled"` | `—` | Icon style for the built-in leading icon — `sharpUnfilled` (outlined) or `sharpFilled` (solid); ignored when `leading` supplies its own icon. |
+| leading | `ReactNode` | `—` | Custom node rendered in the leading region instead of the built-in icon, with no need for `leadingIcon`. Buttons and links here keep their own click target. |
+| trailingIcon | `boolean` | `false` | When true, renders the built-in trailing `Icon` from `trailingIconName`; `trailingSlot` is the identical alias, while `trailing` and `passwordVisibilityToggle` take the region over. |
+| trailingSlot | `boolean` | `false` | Alias of `trailingIcon`: either flag turns the trailing region on, matching the `ListItem` slot naming. |
+| trailingIconName | `string` | `"visibility_off"` | Material Symbol rendered in the trailing region; an empty string falls back to `visibility_off`. Used only when `trailingIcon` (or `trailingSlot`) is true and neither `trailing` nor `passwordVisibilityToggle` owns the region. |
+| trailingIconVariant | `"sharpFilled" \| "sharpUnfilled"` | `—` | Icon style — `sharpUnfilled` (outlined) or `sharpFilled` (solid) — for the built-in trailing icon and for the `passwordVisibilityToggle` button icon. |
+| trailing | `ReactNode` | `—` | Custom node rendered in the trailing region, taking precedence over `passwordVisibilityToggle` and the built-in trailing icon. Use it for actions such as a clear or search `IconButton`. |
+| passwordVisibilityToggle | `boolean` | `false` | Adds a trailing `IconButton` that swaps the input between `password` and `text`, overriding `type` while it is on. Ignored when `trailing` is set; pair it with `autoComplete` (`current-password` or `new-password`). |
+| showPasswordAriaLabel | `string` | `"Show password"` | `aria-label` on the password toggle while the value is masked; localize it together with `hidePasswordAriaLabel`. |
+| hidePasswordAriaLabel | `string` | `"Hide password"` | `aria-label` on the password toggle while the value is visible; localize it together with `showPasswordAriaLabel`. |
+| placeholder | `string` | `""` | Hint text shown inside the input while it is empty; it disappears on typing, so it is not a substitute for `labelText` or `aria-label`. |
+| disabled | `boolean` | `false` | Blocks typing, removes the input from the tab order, and applies disabled styling; disabled inputs are not submitted with the form. |
+| readOnly | `boolean` | `false` | Read-only state (token background, no hover; focus uses the focus stroke) |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<Textfield labelText="Email" placeholder="e.g. name@example.com" leadingIcon fieldMessage />
+```
+
+```tsx
+<Textfield
+  labelText="Password"
+  type="password"
+  passwordVisibilityToggle
+  autoComplete="current-password"
+  name="password"
+/>
+```
+
+
+## Notes
+
+- Associates label and field message with the input for accessibility.
+- **Simple API** — `labelText`, `leadingIcon` / `trailingIcon`, and icon names.
+- **Composable API** — `labelSlot`, `leading`, and `trailing` (same idea as `ListItem` slots). Use `leadingIcon` / `trailingIcon` or the equivalent `leadingSlot` / `trailingSlot` flags to show the side regions.
+- **Password visibility** — `passwordVisibilityToggle` renders an accessible trailing toggle (unless `trailing` is set).
+- **Multi-line** — Use `Textarea` for comments, notes, bios, and other multi-line copy. `Textfield` is single-line only.
+- **Accessibility** — Pass `id` for stable `label` association; use `autoComplete` for known field types; pass `aria-label` when `label={false}`.

package/skills/uxelle-components/Tooltip.md

@@ -0,0 +1,33 @@
+# Tooltip
+
+Import: `import { Tooltip } from "@uxelle/components";`
+
+Hover/focus supplementary disclosure (`role="tooltip"`).
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children (required) | `ReactElement` | `—` | The trigger the tooltip attaches to and describes — usually a button, link, or icon. Must be a single React element (not a fragment or bare string): it is cloned to receive `aria-describedby` pointing at the panel while open, and hovering or focusing it is what reveals the panel. |
+| content (required) | `ReactNode` | `—` | Supplementary text rendered inside the floating panel. Keep it short and non-interactive — the panel is `role="tooltip"` and cannot be tabbed into. |
+| direction | `"Top Right" \| "Top Center" \| "Top Left" \| "Right Top" \| "Right Center" \| "Right Bottom" \| "Bottom Right" \| "Bottom Center" \| "Bottom Left" \| "Left Bottom" \| "Left Center" \| "Left Top"` | `"Top Right"` | Preferred panel position: the first word is the trigger edge the panel sits on, the second is its alignment along that edge. Flips to the opposite edge when the viewport lacks room. |
+| open | `boolean` | `false` | Controlled visibility of the panel. Pass it with `onOpenChange`; omit it to let hover, focus, and Escape drive visibility internally. |
+| onOpenChange | `(open: boolean) => void` | `—` | Called with the requested visibility whenever hover, focus, blur, or Escape asks to change it. Required when `open` is passed, since the component then keeps no visibility state of its own. |
+| tooltipId | `string` | `""` | Id put on the panel and referenced by the trigger's `aria-describedby` while open. Leave empty to auto-generate a unique id. |
+| tooltipLabel | `string` | `""` | Sets `aria-label` on the panel, replacing `content` as its accessible name when the visible text alone reads poorly. Leave empty to let `content` name the panel. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<Tooltip content={/* ReactNode */}>
+  {/* ReactElement */}
+</Tooltip>
+```
+
+## Notes
+
+- Use non-interactive `content` and theme tokens for color/contrast. Omit `open` for hover/focus-driven visibility. Pass `open` (with `onOpenChange`) to control visibility, including design/docs previews.

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

@@ -0,0 +1,149 @@
+---
+name: uxelle-design-harness
+description: >-
+  The single home for building on-brand, enterprise uxElle experiences: Swiss
+  design principles, the --uxl-* variable foundation (layout spacing, page
+  chrome, color-switcher palettes, radius, elevation, type), first-class mobile
+  responsiveness, WCAG AA, and composition recipes for product and marketing
+  surfaces (app chrome, dashboards, data tables, record detail, settings,
+  multi-step flows, states, landing pages, heroes, pricing, CTAs) across React
+  (@uxelle/components) and A2UI (@uxelle/a2ui). Use when generating pages, apps,
+  forms, layouts, dashboards, marketing/landing pages, greenfield React, or A2UI
+  surfaces, or when writing CSS / inline styles that need --uxl-* tokens.
+---
+
+# uxElle design harness
+
+The home for generating on-brand uxElle experiences. It carries the design
+**principles**, the **variable foundation** (tokens), the **layout and
+responsiveness** rules, and the **recipes** that compose components into whole
+experiences and reusable pieces.
+
+One approach, two projections: **React** (`@uxelle/components`) for IDE agents
+and **A2UI** (`getUxelleRecipe` from `@uxelle/a2ui`) for runtime hosts. Write the
+design once; [a2ui.md](a2ui.md) maps it to the runtime track.
+
+## Philosophy
+
+Design like the International Typographic (Swiss) school: a clear grid, strong
+typographic hierarchy, generous whitespace, restraint, and objective, content-first
+layouts. Restraint is **context-aware** — product surfaces are maximally calm;
+marketing surfaces are expressive within the *same* grid, hierarchy, and limited
+palette. The full mapping of principles to uxElle mechanisms lives in
+[principles.md](principles.md).
+
+## Use the harness
+
+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.
+   `Table` -> `../uxelle-components/Table.md`. Import from `@uxelle/components`.
+5. 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.
+
+## 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>`.
+- **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);
+  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),
+  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);
+  form block -> [recipe-form-section.md](recipe-form-section.md);
+  key/value summary -> [recipe-summary-list.md](recipe-summary-list.md);
+  card row -> [recipe-card-grid.md](recipe-card-grid.md);
+  metrics -> [recipe-stat-callouts.md](recipe-stat-callouts.md);
+  empty/loading/error -> [recipe-states.md](recipe-states.md);
+  page footer -> [recipe-footer.md](recipe-footer.md);
+  hero -> [recipe-hero.md](recipe-hero.md); feature -> [recipe-feature-section.md](recipe-feature-section.md);
+  trust bar -> [recipe-logo-wall.md](recipe-logo-wall.md); testimonial -> [recipe-testimonial.md](recipe-testimonial.md);
+  pricing -> [recipe-pricing.md](recipe-pricing.md); closing CTA -> [recipe-cta-band.md](recipe-cta-band.md).
+
+## Core rules
+
+- **Spacing**: stacks use `0` or `var(--uxl-theme-layout-spacing-*)` on `gap` /
+  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).
+- **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).
+- **No fabrication**: never invent `--uxl-*` names, never `var(--token, fallback)`,
+  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)).
+- **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` /
+  `FormSection` to `@uxelle/components`, and never author new recipes in the
+  customer app — contribute them back to uxElle ([recipe-template.md](recipe-template.md)).
+- **A2UI**: catalog adapters only — no `className` / `style`, layout-spacing only,
+  `import { getUxelleRecipe } from "@uxelle/a2ui"`. See [a2ui.md](a2ui.md).
+
+## Quality checklist (run before you finish)
+
+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
+  (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.
+- **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.
+- **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
+  only for semantic status, never color-alone (paired with text or icon).
+- **Accessibility**: skip link + one `main`; landmarks named; focus visible; every
+  control has an accessible name; async regions announced.
+- **Components first**: composed existing components (linked at point of use) over
+  bespoke markup; no recipe exported as a component; package source not opened.
+- **A2UI (if used)**: catalog adapters only; no `className` / `style`; layout-spacing only.
+
+## Index
+
+**Foundations** (always apply): [principles.md](principles.md) ·
+[tokens.md](tokens.md) · [spacing-steps.md](spacing-steps.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)
+
+**Experiences** — product: [app-chrome](recipe-app-chrome.md) ·
+[page-shell](recipe-page-shell.md) · [dashboard-overview](recipe-dashboard-overview.md) ·
+[data-table-page](recipe-data-table-page.md) · [record-detail](recipe-record-detail.md) ·
+[settings-page](recipe-settings-page.md) · [multi-step-flow](recipe-multi-step-flow.md).
+Marketing: [landing-page](recipe-landing-page.md).
+
+**Pieces** — shared: [page-header](recipe-page-header.md) ·
+[form-section](recipe-form-section.md) · [query-bar](recipe-query-bar.md) ·
+[card-grid](recipe-card-grid.md) · [summary-list](recipe-summary-list.md) ·
+[states](recipe-states.md) · [stat-callouts](recipe-stat-callouts.md) ·
+[logo-wall](recipe-logo-wall.md) · [footer](recipe-footer.md). Marketing: [hero](recipe-hero.md) ·
+[feature-section](recipe-feature-section.md) · [testimonial](recipe-testimonial.md) ·
+[pricing](recipe-pricing.md) · [cta-band](recipe-cta-band.md).
+
+**Component APIs**: link each at point of use — [uxelle-components](../uxelle-components/SKILL.md).
+
+**Contributing** a recipe: [recipe-template.md](recipe-template.md).

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

@@ -0,0 +1,73 @@
+# A2UI: the runtime translation layer
+
+A2UI is the runtime-host projection of the same designs. Instead of React JSX, a
+host renders uxElle components from catalog **adapters** driven by JSON messages.
+Design the experience once with the principles, tokens, and recipes here; this file
+maps it to A2UI. Each recipe also carries a short **A2UI** note with its specifics.
+
+```ts
+import { getUxelleRecipe, uxelleCatalogSchema } from "@uxelle/a2ui";
+```
+
+Hosts inject `uxelleCatalogSchema` (and optionally a recipe's messages) into the
+agent prompt and render the result. Do not open package source to "discover" props —
+use the catalog schema the host provides.
+
+## Hard constraints
+
+- **Catalog adapters only.** No raw HTML, no custom components.
+- **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.
+- **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
+  host wraps content in its theme scope.
+- **Bind, don't hold state.** Wire values through the host data model (bindings),
+  not React state.
+
+## Prebuilt recipes
+
+Registered runtime recipes today:
+
+- `getUxelleRecipe("page-shell")`
+- `getUxelleRecipe("form-section")`
+- `getUxelleRecipe("navigation-side")` — side rail; Overview trailing
+  `A2uiLabelBadge` uses `"emphasis": "high"`; account row is `A2uiList` +
+  `A2uiListItem` (`label` plus optional `bottomText`)
+
+Every other recipe in this harness has **no `getUxelleRecipe` yet** — compose it
+from adapters following the recipe's regions and its A2UI note. Do not duplicate
+recipe JSON into the customer app.
+
+## Adapter map
+
+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`,
+`Banner` -> `A2uiBanner`, `LabelBadge` -> `A2uiLabelBadge`, `StatTile` -> `A2uiStatTile`,
+`DynamicAngle*` -> `A2uiDynamicAngle*`). `Table` has the full family (`A2uiTableGrid`,
+`A2uiTableHead`, `A2uiTableBody`, `A2uiTableRow`, `A2uiTableCell`,
+`A2uiTableHeaderCell`, `A2uiTableColumnSizingProvider`).
+
+Known gaps — substitute rather than invent:
+
+| React | A2UI |
+|-------|------|
+| `Lockup` | no adapter — stack `A2uiText` (eyebrow / title / body) |
+| `TabsCompact` / `TabsStretch` | `A2uiTabGroup` + `A2uiTab` |
+| `Pagination` / `PaginationSimple` / `PaginationComplex` | no adapter yet — omit or use a bound prev/next with `A2uiButton` |
+| `SkeletonGroup` | no adapter — repeat `A2uiSkeleton` |
+| `Quantity` | no adapter — use `A2uiTextfield` (numeric) |
+
+If a design needs a gap component as its backbone, say so in the recipe's
+**when-not** and pick the closest supported composition.
+
+## Translating a React recipe
+
+1. Keep the same region order and layout-spacing values.
+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.
+5. Drop skip link and theme `data-*` (host-owned).

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

@@ -0,0 +1,31 @@
+# How to: accessibility (generated UI)
+
+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-*`.
+
+## Baseline
+
+- One `h1`, then `h2`… with no skipped ranks (`Text as="h1"` / `as="h2"`).
+- One `main`. If nav/chrome exists, put a skip link first in the DOM (`href="#main-content"`). CSS: [how-to-host.md](how-to-host.md).
+- Landmarks: `Layout as="main"|"nav"|"section"`. Name a region with a visible heading (`aria-labelledby`) or `aria-label` when there is no heading. `NavigationSide` is chrome (`<aside>`, or `<header>` when `mobile`) — not a `nav`. When `mobile`, the menu opens a right `Sheet` that already contains the same `NavigationSideGroup` landmarks. `NavigationSideGroup` is already a named `<nav>` — do not wrap it in another `nav`. Pass `aria-label` when more than one group is on the page. SSR hosts must pass `mobile` on `NavigationSide` (`true` or `false`); omitting it hydrates the rail on the server and can swap to the top bar on the client.
+- Native controls: `Button`, `Link`, catalog fields — not clickable `div`s.
+- Visible label first. `aria-label` only when there is no visible name (icon-only `IconButton`, unlabeled `ButtonGroup`).
+- Decorative `Icon` stays default-hidden. Meaningful icons: `role="img"` + `aria-label`.
+- Color is not the only status signal (pair with text or icon).
+- Keyboard: no custom traps (`Dialog` / `Sheet` already trap). DOM order = tab order. No positive `tabindex`. Do not remove or restyle catalog `:focus-visible` rings.
+- Pointer targets: use catalog controls (they meet 24×24 CSS px). Do not shrink hit areas with custom CSS.
+- Decorative motion (`DynamicAngle*`, transitions) is muted under `prefers-reduced-motion: reduce`. Do not add app animation that ignores it.
+- Injected status: `role="status"` or `aria-live="polite"`. Field errors: `FieldMessage` `Danger` (catalog fields wire `aria-invalid` / `aria-errormessage`).
+- `ButtonGroup` / `RadioGroup` / `CheckboxGroup`: visible legend or `aria-label`.
+
+## ARIA helpers
+
+- `aria-label` — accessible name when no visible text (keep short; do not duplicate visible copy).
+- `aria-labelledby` — id(s) of a visible heading/label that name this region or control.
+- `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-expanded` — only on a real disclosure control, not on every section.
+- `aria-pressed` — toggle buttons (`IconButton` `activated`); `Switch` uses `checked` instead.
+
+Do not invent roles on `Layout` when `as` already maps (`main`, `nav`, `section`). Do not `aria-label` headings or buttons that already have visible text.

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

@@ -0,0 +1,82 @@
+# How to: color and the color switcher
+
+uxElle color is applied by **palette**, not by hardcoded values. Style every
+themeable surface with the `--uxl-color-switcher-*` role tokens (the role table is
+in [tokens.md](tokens.md)); choose which palette those roles resolve to with
+`data-color-switcher`.
+
+## Mechanism
+
+`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`).
+- 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
+  component's slot, pass the prop so the palette reaches the DOM.
+- Always style with role tokens inside the region. Never hardcode hex — the palette
+  guarantees text/headline contrast on its own surface.
+
+```tsx
+// A brand band: one region, one palette, role tokens throughout.
+<Layout
+  as="section"
+  data-color-switcher="brand-1"
+  p="var(--uxl-theme-layout-spacing-large-13)"
+  style={{
+    backgroundColor: "var(--uxl-color-switcher-background)",
+    color: "var(--uxl-color-switcher-text)",
+  }}
+>
+  {/* Text + Button inside inherit this palette */}
+</Layout>
+```
+
+## Palette catalog
+
+- **`default`** — the page baseline: neutral surface and text. The default look
+  for product surfaces.
+- **`default-subtle`** — a low-contrast neutral fill to separate a section, well,
+  or sidebar *without* introducing brand color (alternating sections, cards on a
+  neutral page).
+- **`neutral`** — an internal subtle neutral used by some components (e.g. file
+  lists). Component-owned; you rarely set it by hand.
+- **`success` / `warning` / `danger` / `info`** — semantic **status** only, on
+  `Banner`, `BannerAnnouncement`, `LabelBadge`, and inline feedback (`Textarea`
+  `softOverflow` uses `data-color-switcher="warning"` on the counter; pass
+  `softOverflowMessage` for a warning `FieldMessage`). Never
+  decorative, and never the only signal: pair the color with text or an icon.
+- **`brand-1` / `brand-2` / `brand-3` / `brand-4`** — the expressive, high-impact
+  palettes. See below.
+
+## Choosing a brand palette
+
+`brand-1..4` are the high-impact set, meant for high-impact components — heroes,
+CTA bands, and loud statements in general. They have **no priority order and no
+fixed per-index meaning**: which hue each maps to is theme-owned and differs across
+platforms and themes, so never assume "brand-1 = red / primary" or
+"brand-2 = informational."
+
+To choose:
+
+- Reach for a brand palette when a region should make a statement (hero, CTA,
+  standout feature band); keep product task surfaces on `default` / `default-subtle`.
+- Pick whichever palette **renders** the look you want, and confirm the rendered
+  output (e.g. in Storybook) rather than assuming a color.
+- Use **one dominant brand band per view** and let `default` / `default-subtle`
+  carry the calmer regions, so the loud band stays loud.
+
+## Do / don't
+
+- 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 hardcode hex/rgb, and don't stack multiple loud brand bands in one view.
+
+## A2UI
+
+Set the palette through the adapter where a prop exists (e.g. `A2uiBanner` status,
+`A2uiLabelBadge`); otherwise wrap the region in one `A2uiLayout` with the switcher.
+One palette per region, same rules as above.

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

@@ -0,0 +1,108 @@
+# How to: host (React app entry)
+
+Use this when **creating** a React app shell — the same shell serves product and
+marketing surfaces. If the host (an MCP runtime or existing app) already loads
+theme CSS, component CSS, and `data-*` on `<html>`, skip this file and compose
+pages inside it.
+
+Agents consume **published packages**, not repo filesystem paths. Do not import
+`packages/themes/build/…` or invent Vite aliases to source.
+
+## 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).
+
+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
+  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>`:
+
+```css
+.uxl-skip-link {
+  position: absolute;
+  z-index: 100;
+  inset-inline-start: var(--uxl-theme-layout-spacing-small-4);
+  inset-block-start: var(--uxl-theme-layout-spacing-small-4);
+  padding: var(--uxl-theme-layout-spacing-small-4);
+  background-color: var(--uxl-color-switcher-background);
+  color: var(--uxl-color-switcher-text);
+  text-decoration: underline;
+}
+
+.uxl-skip-link:not(:focus-visible) {
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.uxl-skip-link:focus-visible {
+  outline: 2px solid var(--uxl-color-switcher-interactive-icon);
+  outline-offset: 2px;
+}
+```
+
+## React entry
+
+```tsx
+<html data-open-source="light" data-color-switcher="default">
+```
+
+```tsx
+<Layout
+  display="flex"
+  flexDirection="column"
+  height="100%"
+  style={{
+    backgroundColor: "var(--uxl-color-switcher-background)",
+    overflow: "hidden",
+  }}
+>
+  <a className="uxl-skip-link" href="#main-content">
+    Skip to main content
+  </a>
+  {/* Navigation — recipe-app-chrome.md */}
+  <main id="main-content" tabIndex={-1} style={{ flexGrow: 1, minHeight: 0, overflow: "auto" }}>
+    {/* page column — how-to-page-layout.md */}
+    {/* Footer — inside this scrollport; recipe-app-chrome.md */}
+  </main>
+</Layout>
+```
+
+Set `html, body, #root { height: 100%; margin: 0; }` so the column can fill the
+viewport.
+
+## A2UI hosts
+
+A2UI runtimes load the same theme CSS and wrap content in `A2uiThemeScope`; they do
+**not** emit skip-link CSS or theme `data-*` from adapters. See [a2ui.md](a2ui.md).