@uxelle/skills 0.2.0-beta.2

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

@@ -0,0 +1,108 @@
+# Recipe: multi-step flow
+
+A product **experience**: a task split into ordered steps — onboarding, checkout,
+guided setup. A stepper shows progress, each step is a focused form, and a final
+review confirms before commit.
+
+Assembles [`Stepper`](../uxelle-components/Stepper.md) (with `StepperItem`),
+[form-section](recipe-form-section.md), [summary-list](recipe-summary-list.md) (the
+review), [`ButtonGroup`](../uxelle-components/ButtonGroup.md), and
+[states](recipe-states.md) (submit feedback).
+
+## When
+
+A multi-step task with a clear order and a commit at the end.
+
+## When not
+
+- A single form is a [form-section](recipe-form-section.md), not a flow.
+- The `Stepper` is **progress**, not page navigation — do not wire it to routes as
+  primary nav.
+- Do not skip the review step before an irreversible commit.
+
+## Regions
+
+page column -> flow title (`h1`) -> `<nav>` `Stepper` (progress) -> current step
+(step `h2` + [form-section](recipe-form-section.md)) -> footer action row
+(Back / Next, Next becomes Confirm on the review step)
+
+## Responsive
+
+`Stepper` is `horizontal` from tablet up and vertical below
+(`useBreakpointUp("tablet")`); the footer `ButtonGroup` stacks `fullWidth` when
+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)).
+
+## A11y
+
+One `main`, one `h1` (the flow); each step title is `h2`. Wrap the `Stepper` in
+`<nav aria-label="Progress">`. Move focus to the step heading on change and keep the
+`currentStep` in sync. The review uses a [summary-list](recipe-summary-list.md);
+submit feedback follows [states](recipe-states.md). See
+[how-to-accessibility.md](how-to-accessibility.md).
+
+## React
+
+```tsx
+const tabletUp = useBreakpointUp("tablet");
+const steps = [
+  { label: "Details", description: "Your workspace" },
+  { label: "Members", description: "Invite people" },
+  { label: "Review", description: "Confirm" },
+];
+const isLast = step === steps.length;
+
+<Layout
+  display="flex"
+  flexDirection="column"
+  width="100%"
+  maxWidth="600px"
+  mh="auto"
+  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>
+
+  <nav aria-label="Progress">
+    <Stepper
+      steps={steps}
+      currentStep={step}
+      horizontal={tabletUp}
+      onStepClick={(s) => s < step && setStep(s)}
+    />
+  </nav>
+
+  <Layout as="section" display="flex" flexDirection="column" gap="var(--uxl-theme-layout-spacing-medium-8)">
+    <Text type="Display Extra Small" as="h2" width={false}>
+      {steps[step - 1].label}
+    </Text>
+    {/* Steps 1-2: a form-section. Final step: a summary-list review. */}
+    {isLast ? <ReviewSummary /> : <StepForm step={step} />}
+  </Layout>
+
+  <ButtonGroup
+    direction={tabletUp ? "row" : "column"}
+    fullWidth={!tabletUp}
+    aria-label="Flow navigation"
+  >
+    <Button emphasis="medium" disabled={step === 1} onClick={() => setStep(step - 1)}>
+      <Text type="Button" width>Back</Text>
+    </Button>
+    <Button emphasis="high" onClick={isLast ? onConfirm : () => setStep(step + 1)}>
+      <Text type="Button" width>{isLast ? "Confirm" : "Next"}</Text>
+    </Button>
+  </ButtonGroup>
+</Layout>
+```
+
+The flow is one column, so the `600px` cap applies ([how-to-page-layout.md](how-to-page-layout.md)).
+
+## A2UI
+
+No `getUxelleRecipe("multi-step-flow")` — compose `A2uiStepper` + `A2uiStepperItem`,
+the step form adapters, and an `A2uiButtonGroup` footer (`"direction": "column"`).
+Bind `currentStep` and field values to the host model ([a2ui.md](a2ui.md)).

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

@@ -0,0 +1,102 @@
+# Recipe: page header
+
+A shared **piece**: the top band of a page — title, optional supporting line,
+optional status, and page-level actions. Used by
+[data-table-page](recipe-data-table-page.md), [record-detail](recipe-record-detail.md),
+[dashboard-overview](recipe-dashboard-overview.md), and most product pages.
+
+Composes [`Lockup`](../uxelle-components/Lockup.md),
+[`LabelBadge`](../uxelle-components/LabelBadge.md),
+[`ButtonGroup`](../uxelle-components/ButtonGroup.md), and
+[`Text`](../uxelle-components/Text.md). Optional [`Breadcrumbs`](../uxelle-components/Breadcrumbs.md)
+sit above it, in the page column.
+
+## When
+
+The first section of a page body: one `h1`, optional supporting copy, optional
+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
+  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)).
+- 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.
+
+## Regions
+
+optional `Breadcrumbs` (in the column) -> header row: left `Lockup`
+(`h1` + optional body, optional status `LabelBadge` in `overline`) · right action
+`ButtonGroup`
+
+## Responsive
+
+Row from tablet up, column below (`useBreakpointUp("tablet")`,
+[how-to-page-layout.md](how-to-page-layout.md#action-clusters)); the stacked actions
+go `fullWidth`. Keep `flexWrap="nowrap"` — never `wrap` (the full-width `Lockup`
+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)).
+
+## A11y
+
+One `h1` per page, here. Give the action `ButtonGroup` an `aria-label`. A status
+`LabelBadge` conveys meaning by its visible text; keep `dataColorSwitcher` paired
+with that text ([how-to-color.md](how-to-color.md)).
+
+## React
+
+```tsx
+const tabletUp = useBreakpointUp("tablet");
+
+<Layout
+  display="flex"
+  flexDirection={tabletUp ? "row" : "column"}
+  flexWrap="nowrap"
+  justifyContent="space-between"
+  alignItems={tabletUp ? "flex-end" : "stretch"}
+  gap="var(--uxl-theme-layout-spacing-small-4)"
+>
+  <Lockup
+    overline={<LabelBadge label="Active" dataColorSwitcher="success" emphasis="low" />}
+    title={
+      <Text type="Display Small" as="h1" width={false}>
+        Invoices
+      </Text>
+    }
+    body={
+      <Text type="Body Medium" width={false}>
+        Every invoice across your workspace.
+      </Text>
+    }
+  />
+  <Layout flexShrink={0}>
+    <ButtonGroup
+      direction={tabletUp ? "row" : "column"}
+      fullWidth={!tabletUp}
+      aria-label="Invoice actions"
+    >
+      <Button emphasis="medium">
+        <Text type="Button" width>Export</Text>
+      </Button>
+      <Button emphasis="high">
+        <Text type="Button" width>New invoice</Text>
+      </Button>
+    </ButtonGroup>
+  </Layout>
+</Layout>
+```
+
+Omit `overline` when there is no status; omit `body` when the title stands alone.
+
+## A2UI
+
+No `getUxelleRecipe("page-header")` — compose adapters ([a2ui.md](a2ui.md)).
+`Lockup` has no adapter: stack `A2uiText` (optional `A2uiLabelBadge`, then the `h1`,
+then the body). Actions use `A2uiButtonGroup` with `"direction": "column"`.

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

@@ -0,0 +1,82 @@
+# Recipe: page shell
+
+## When
+
+Themed page column with stacked sections. Records: [recipe-data-table-page.md](recipe-data-table-page.md). Preferences: [recipe-settings-page.md](recipe-settings-page.md).
+
+## When not
+
+- Not a layout framework; not a `PageShell` component.
+- Agents do not set theme attributes (`data-*` / `A2uiThemeScope` are host-owned).
+- Do not hardcode `1120px` / `1600px`. React uses `--uxl-breakpoints-max-container-width`, except a **one-column** settings/form page may use `600px` — [recipe-settings-page.md](recipe-settings-page.md).
+- A2UI chat surfaces do not use page chrome tokens — keep `var(--uxl-theme-layout-spacing-*)` only.
+
+## Regions
+
+host canvas → content column (`max-container-width`, `mh="auto"`, `p` = breakpoints-margin) → sections
+
+`medium-12` between **sections**. Controls that belong to a section (table tabs, query bar, form actions) stay inside that section at `small-4`. Do not lift data tabs up to sit under the page `h1` as if they were app navigation — that is [recipe-app-chrome.md](recipe-app-chrome.md) (`NavLink`). Table datasets: [recipe-data-table-page.md](recipe-data-table-page.md).
+
+## 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).
+
+## A11y
+
+[how-to-accessibility.md](how-to-accessibility.md). One `main` per page (host `<main>` or `as="main"` on this column). Heading rank starts at `h1` once; section titles `h2`.
+
+## React
+
+[`Lockup`](../uxelle-components/Lockup.md) for section intros; [`Layout`](../uxelle-components/Layout.md) + [`Text`](../uxelle-components/Text.md) build the column. Import from `@uxelle/components`.
+
+```tsx
+<Layout
+  as="main"
+  display="flex"
+  flexDirection="column"
+  width="100%"
+  maxWidth="var(--uxl-breakpoints-max-container-width)"
+  mh="auto"
+  p="var(--uxl-breakpoints-margin)"
+  gap="var(--uxl-theme-layout-spacing-medium-12)"
+>
+  <Lockup
+    topSlot={false}
+    title={
+      <Text type="Display Extra Small" as="h1" width={false}>
+        Account settings
+      </Text>
+    }
+    body={
+      <Text type="Body Medium" width={false}>
+        Manage how your team appears across products.
+      </Text>
+    }
+  />
+  <Layout as="section" display="flex" flexDirection="column" gap="var(--uxl-theme-layout-spacing-small-4)">
+    <Lockup
+      overline={<Text type="Overline" width={false}>Workspace</Text>}
+      title={
+        <Text type="Display Extra Small" as="h2" width={false}>
+          Profile
+        </Text>
+      }
+      body={
+        <Text type="Body Medium" width={false}>
+          Shown on invoices and shared reports.
+        </Text>
+      }
+    />
+  </Layout>
+</Layout>
+```
+
+If the host already renders `<main>` (skip-link target), omit `as="main"` on this column.
+
+## Responsive
+
+The capped content column reflows on its own — `--uxl-breakpoints-max-container-width`, `-margin`, and section gaps remap per breakpoint, so sections stack and tighten on mobile with nothing to set. Grids inside a section reflow with `auto-fit` / `minmax` ([how-to-page-layout.md](how-to-page-layout.md#responsiveness)).
+
+## A2UI
+
+Same `var(--uxl-theme-layout-spacing-*)` strings on `A2uiLayout` — no gutter / margin / max-container-width. Headings as `A2uiText` (`Lockup` has no adapter). Runtime: `getUxelleRecipe("page-shell")` from `@uxelle/a2ui`. See [a2ui.md](a2ui.md).

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

@@ -0,0 +1,83 @@
+# Recipe: pricing
+
+A marketing **piece**: two to four comparable plans, one marked recommended, each
+with a price, a feature list, and a call to action.
+
+Composes [`ProductCard`](../uxelle-components/ProductCard.md) (or
+[`Card`](../uxelle-components/Card.md)),
+[`LabelBadge`](../uxelle-components/LabelBadge.md) (the recommended flag),
+[`List`](../uxelle-components/List.md) + [`ListItem`](../uxelle-components/ListItem.md)
+(features), [`Text`](../uxelle-components/Text.md), and
+[`ButtonGroup`](../uxelle-components/ButtonGroup.md).
+
+## When
+
+Comparable plans the visitor chooses between.
+
+## When not
+
+- Five-plus plans overwhelm — group or simplify.
+- One recommended tier at most; do not badge them all.
+- Section heading is `h2`; each plan name is `h3`.
+
+## Regions
+
+section -> grid of tier `ProductCard`s: top (recommended `LabelBadge` + plan `h3` +
+price) · center (feature `List`) · bottom (CTA `Button`)
+
+## Responsive
+
+Tiers reflow with `repeat(auto-fit, minmax(MIN, 1fr))` — side by side on wide
+viewports, stacked on mobile, no JS. Pick `MIN` (e.g. `16rem`) for the narrowest
+comfortable tier. See [how-to-page-layout.md](how-to-page-layout.md#responsiveness).
+
+## 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)).
+
+## A11y
+
+Section `h2`; plan names `h3`. Each CTA names its plan (`aria-label="Choose Team"`)
+so buttons are distinguishable out of context. The recommended `LabelBadge` states
+"Recommended" in text. See [how-to-accessibility.md](how-to-accessibility.md).
+
+## React
+
+```tsx
+<Layout
+  as="section"
+  display="grid"
+  gridTemplateColumns="repeat(auto-fit, minmax(16rem, 1fr))"
+  gap="var(--uxl-breakpoints-gutter)"
+  aria-label="Plans"
+>
+  <ProductCard
+    topSlotContent={
+      <>
+        <LabelBadge label="Recommended" emphasis="high" />
+        <Text type="Display Extra Small" as="h3" width={false}>Team</Text>
+        <Text type="Display Small" as="p" width={false}>$24<Text type="Body Small" as="span" inline> / user / mo</Text></Text>
+      </>
+    }
+    centerSlotContent={
+      <List>
+        <ListItem leadingSlot leading={<Icon iconName="check" variant="sharpUnfilled" aria-hidden />} centerText={<Text type="Body Small Alt">Unlimited projects</Text>} />
+        <ListItem leadingSlot leading={<Icon iconName="check" variant="sharpUnfilled" aria-hidden />} centerText={<Text type="Body Small Alt">Advanced roles</Text>} />
+        <ListItem leadingSlot leading={<Icon iconName="check" variant="sharpUnfilled" aria-hidden />} centerText={<Text type="Body Small Alt">Priority support</Text>} />
+      </List>
+    }
+    bottomSlotContent={
+      <Button fullWidth emphasis="high" aria-label="Choose Team">
+        <Text type="Button" width>Choose Team</Text>
+      </Button>
+    }
+  />
+  {/* repeat tiers; only one carries the Recommended badge */}
+</Layout>
+```
+
+## A2UI
+
+No `getUxelleRecipe("pricing")` and no `fr` grid — stack `A2uiProductCard` tiers in a
+column; features via `A2uiList` + `A2uiListItem`; CTA `A2uiButton` ([a2ui.md](a2ui.md)).

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

@@ -0,0 +1,108 @@
+# Recipe: query bar
+
+A shared **piece**: the toolbar that narrows the current view — filter, facets,
+search, and export. It rides on the surface it controls (a `Table` `topSlot`, or a
+card grid's header), not under the page title.
+
+Composes [`Button`](../uxelle-components/Button.md),
+[`Sheet`](../uxelle-components/Sheet.md),
+[`Textfield`](../uxelle-components/Textfield.md),
+[`ChoiceChip`](../uxelle-components/ChoiceChip.md), and
+[`FilterChipGroup`](../uxelle-components/FilterChipGroup.md). Full table context:
+[data-table-page](recipe-data-table-page.md).
+
+## When
+
+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).
+- 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`.
+- No pagination here — that goes in the `Table` `bottomSlot`.
+
+## Regions
+
+one row, `justifyContent="space-between"`: **left** = constrain (Filter `Button`
+-> `Sheet`, optional `ChoiceChip` facet) · **right** = find (search `Textfield`
+bounded + `Export` `Button`, `nowrap`). Applied filters: `FilterChipGroup` on the
+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.
+Keep the filter and export buttons together (`flexShrink={0}`).
+
+## 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)).
+
+## A11y
+
+Name the bar `aria-label="Table filters and search"`. The compact search
+`Textfield` uses `aria-label` (no visible label). The filter `Sheet` has a `title`.
+See [how-to-accessibility.md](how-to-accessibility.md).
+
+## React
+
+```tsx
+<Layout display="flex" flexDirection="column" gap="var(--uxl-theme-layout-spacing-small-4)">
+  <Layout
+    display="flex"
+    flexDirection="row"
+    flexWrap="nowrap"
+    justifyContent="space-between"
+    alignItems="center"
+    gap="var(--uxl-theme-layout-spacing-small-4)"
+    aria-label="Table filters and search"
+  >
+    <Layout display="flex" flexDirection="row" flexWrap="nowrap" alignItems="center" gap="var(--uxl-theme-layout-spacing-small-4)">
+      <Sheet
+        direction="Right"
+        title="Filters"
+        closeLabel="Close filters"
+        trigger={
+          <Button emphasis="medium" leadingIcon leadingIconName="filter_list">
+            <Text type="Button" width>Status</Text>
+          </Button>
+        }
+      >
+        <CheckboxGroup name="status" label labelText="Status">
+          <Checkbox value="open"><Text type="Body Medium">Open</Text></Checkbox>
+          <Checkbox value="matched"><Text type="Body Medium">Matched</Text></Checkbox>
+        </CheckboxGroup>
+      </Sheet>
+      <ChoiceChip label="Top match" onChange={() => {}} />
+    </Layout>
+    <Layout display="flex" flexDirection="row" flexWrap="nowrap" alignItems="center" gap="var(--uxl-theme-layout-spacing-small-4)" flexShrink={0}>
+      <Layout width="16rem" flexShrink={0}>
+        <Textfield
+          label={false}
+          aria-label="Search by name"
+          name="table-search"
+          autoComplete="off"
+          placeholder="Search by name"
+          leadingIcon
+          leadingIconName="search"
+        />
+      </Layout>
+      <Layout flexShrink={0}>
+        <Button emphasis="low"><Text type="Button" width>Export all</Text></Button>
+      </Layout>
+    </Layout>
+  </Layout>
+  {/* Applied filters */}
+  {/* <FilterChipGroup> … </FilterChipGroup> */}
+</Layout>
+```
+
+## A2UI
+
+No `getUxelleRecipe("query-bar")` — compose `A2uiSheet` / `A2uiTextfield` /
+`A2uiButton` / `A2uiChoiceChip` / `A2uiFilterChipGroup` ([a2ui.md](a2ui.md)). One
+column; bind filter and search state to the host model.

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

@@ -0,0 +1,96 @@
+# Recipe: record detail
+
+A product **experience**: one record (customer, invoice, project). A header with
+title, status, and record actions; the key facts at a glance; then deeper sections,
+optionally tabbed.
+
+Assembles the [page-header](recipe-page-header.md),
+[summary-list](recipe-summary-list.md),
+[`TabsCompact`](../uxelle-components/TabsCompact.md), and section pieces
+([form-section](recipe-form-section.md), [data-table-page](recipe-data-table-page.md),
+[states](recipe-states.md)). Lives inside the [app-chrome](recipe-app-chrome.md).
+
+## When
+
+The drill-in for a single row: read its state, then act on it or explore related
+data.
+
+## When not
+
+- Not a list — a collection is a [data-table-page](recipe-data-table-page.md).
+- Tabs here switch **sections of this record** (Overview / Activity / Files), not
+  pages — page routes stay in `Navigation`.
+- One `h1` (the record name); section headings are `h2`.
+
+## Regions
+
+optional `Breadcrumbs` -> [page-header](recipe-page-header.md) (`h1` + status
+`LabelBadge` + record actions) -> body: main column + aside
+[summary-list](recipe-summary-list.md) -> section content, optionally under
+`TabsCompact`
+
+## Responsive
+
+The body is a two-column grid (main + aside) that collapses to one column below
+tablet (`useBreakpointUp("desktop")` or `auto-fit`); the header stacks; `TabsCompact`
+scrolls when the labels overflow. See [how-to-page-layout.md](how-to-page-layout.md#responsiveness).
+
+## 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)).
+
+## A11y
+
+One `main`, one `h1`. The status `LabelBadge` states meaning in text. `TabsCompact`
+gets an `aria-label` when the tablist needs a name. Related sections use `h2`. See
+[how-to-accessibility.md](how-to-accessibility.md).
+
+## React
+
+```tsx
+const desktopUp = useBreakpointUp("desktop");
+
+<Layout
+  display="flex"
+  flexDirection="column"
+  width="100%"
+  maxWidth="var(--uxl-breakpoints-max-container-width)"
+  mh="auto"
+  p="var(--uxl-breakpoints-margin)"
+  gap="var(--uxl-theme-layout-spacing-medium-12)"
+>
+  {/* Header with status + actions — recipe-page-header.md */}
+  <RecordHeader />
+
+  <Layout
+    display="grid"
+    gridTemplateColumns={desktopUp ? "2fr 1fr" : "1fr"}
+    gap="var(--uxl-breakpoints-gutter)"
+  >
+    {/* Main: tabbed sections of THIS record */}
+    <Layout as="section" display="flex" flexDirection="column" gap="var(--uxl-theme-layout-spacing-small-4)">
+      <TabsCompact
+        amount={3}
+        tabLabels={["Overview", "Activity", "Files"]}
+        activeTab={tab}
+        onChange={setTab}
+        aria-label="Record sections"
+      />
+      {/* render the active section: form-section / table / states */}
+      <SectionForActiveTab tab={tab} />
+    </Layout>
+
+    {/* Aside: key facts — recipe-summary-list.md */}
+    <Layout as="aside" aria-label="Summary">
+      <RecordSummaryList />
+    </Layout>
+  </Layout>
+</Layout>
+```
+
+## A2UI
+
+No `getUxelleRecipe("record-detail")` — one narrow column: stacked `A2uiText` header
+(no `Lockup` adapter), `A2uiLabelBadge` status, `A2uiTabGroup` + `A2uiTab` for
+sections, and stacked label/value `A2uiText` for the summary ([a2ui.md](a2ui.md)).