@uxelle/skills 0.2.0-beta.2

package/skills/uxelle-design-harness/recipe-dashboard-overview.md

@@ -0,0 +1,118 @@
+# Recipe: dashboard overview
+
+A product **experience**: the signed-in landing page. A page header, a band of KPIs,
+then the primary work surface (a table or list) with supporting groupings.
+
+Assembles the [page-header](recipe-page-header.md),
+[stat-callouts](recipe-stat-callouts.md), a [`Table`](../uxelle-components/Table.md)
+or [`List`](../uxelle-components/List.md) (see [data-table-page](recipe-data-table-page.md)),
+[card-grid](recipe-card-grid.md), and [states](recipe-states.md). Lives inside the
+[app-chrome](recipe-app-chrome.md).
+
+## When
+
+The first screen after sign-in: orient the user with headline metrics and route
+them to the main work.
+
+## When not
+
+- Not a records manager — deep lists belong on their own
+  [data-table-page](recipe-data-table-page.md).
+- Do not crowd in every metric; 2-4 KPIs, then the primary surface.
+- One `h1` (the page title); KPI and section titles are `h2`.
+
+## Regions
+
+page column -> [page-header](recipe-page-header.md) (`h1`, optional actions) ->
+KPI [stat-callouts](recipe-stat-callouts.md) -> primary surface (`Table` / `List`,
+with [states](recipe-states.md)) -> supporting [card-grid](recipe-card-grid.md) or
+sections
+
+## Responsive
+
+KPI and card grids reflow with `auto-fit` / `minmax` (no JS); the header stacks and
+its actions go `fullWidth` below tablet; the primary `Table` scrolls horizontally
+when narrow. See [how-to-page-layout.md](how-to-page-layout.md#responsiveness).
+
+## Spacing
+
+`medium-12` between page sections (header / KPIs / primary / supporting);
+`--uxl-breakpoints-gutter` inside the grids. Section intros are `micro-2`
+([spacing-steps.md](spacing-steps.md)).
+
+## A11y
+
+One `main`, one `h1`. Name each region (KPIs `aria-label="Key metrics"`, the primary
+surface by its heading). KPI deltas pair color with a sign or word. Loading and empty
+for the primary surface follow [states](recipe-states.md). See
+[how-to-accessibility.md](how-to-accessibility.md).
+
+## Color
+
+Product dashboard: stay on `default`; use status palettes only for KPI deltas and
+alerts, never as decoration ([how-to-color.md](how-to-color.md)).
+
+## React
+
+```tsx
+<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)"
+>
+  {/* Page header — recipe-page-header.md */}
+  <DashboardHeader />
+
+  {/* KPIs — recipe-stat-callouts.md */}
+  <Layout
+    display="grid"
+    gridTemplateColumns="repeat(auto-fit, minmax(14rem, 1fr))"
+    gap="var(--uxl-breakpoints-gutter)"
+    aria-label="Key metrics"
+  >
+    <StatTile
+      label="Monthly revenue"
+      value="$1.24M"
+      trailingSlot
+      trailingSlotContent={
+        <LabelBadge label="+8.2%" dataColorSwitcher="success" emphasis="low" leadingIcon leadingIconName="trending_up" />
+      }
+    />
+    <StatTile
+      label="Active teams"
+      value="312"
+      trailingSlot
+      trailingSlotContent={
+        <LabelBadge label="+4" dataColorSwitcher="success" emphasis="low" leadingIcon leadingIconName="trending_up" />
+      }
+    />
+    <StatTile
+      label="Open tickets"
+      value="18"
+      trailingSlot
+      trailingSlotContent={
+        <LabelBadge label="-6" dataColorSwitcher="success" emphasis="low" leadingIcon leadingIconName="trending_down" />
+      }
+    />
+  </Layout>
+
+  {/* Primary surface — recipe-data-table-page.md (with states) */}
+  <Layout as="section" display="flex" flexDirection="column" gap="var(--uxl-theme-layout-spacing-small-4)">
+    <Text type="Display Extra Small" as="h2" width={false}>Recent activity</Text>
+    {isLoading ? <ActivitySkeleton /> : rows.length ? <ActivityTable rows={rows} /> : <ActivityEmpty />}
+  </Layout>
+
+  {/* Supporting — recipe-card-grid.md */}
+  <ShortcutsGrid />
+</Layout>
+```
+
+## A2UI
+
+No `getUxelleRecipe("dashboard-overview")` — compose the piece adapters in one
+narrow column: stack `A2uiStatTile` (no `fr` grid), then the `A2uiTable*` surface
+([a2ui.md](a2ui.md)).

package/skills/uxelle-design-harness/recipe-data-table-page.md

@@ -0,0 +1,323 @@
+# Recipe: data table page
+
+## When
+
+A records page: a titled collection, then a `Table` you can switch (data tabs), filter, search, and page.
+
+Composes [`Table`](../uxelle-components/Table.md), [`TabsCompact`](../uxelle-components/TabsCompact.md), [`Sheet`](../uxelle-components/Sheet.md), [`Textfield`](../uxelle-components/Textfield.md), [`ButtonGroup`](../uxelle-components/ButtonGroup.md), [`Pagination`](../uxelle-components/Pagination.md), [`Lockup`](../uxelle-components/Lockup.md), [`LabelBadge`](../uxelle-components/LabelBadge.md), and [`FilterChipGroup`](../uxelle-components/FilterChipGroup.md). Header and query bar are the shared [page-header](recipe-page-header.md) and [query-bar](recipe-query-bar.md) pieces.
+
+## When not
+
+- Not a `DataTablePage` / `TablePage` component.
+- Do not invent a toolbar component. Two bands, two jobs — do not mix them:
+  - **Page actions** (add, invite, import, delete, re-upload) sit with the title, in a `ButtonGroup`.
+  - **Query controls** (filter, facets, search, export) sit on the table, in `Table` `topSlot`.
+- **Data tabs are not page navigation.** `Navigation` / `NavLink` change pages (Referrals vs Earnings). `TabsCompact` that switch which rows are in **this** table (referrals vs connections, active vs invited) live in `Table` `topSlot`, immediately above the query bar and grid. Do not park them under the page title.
+- Do not put a `Banner` (or any other page section) between data tabs and the grid.
+- `ButtonGroup` only renders `Button` children — do not nest `Sheet` or `Textfield` in it.
+- Do not put filter *fields* on the query bar. A filter *trigger* opens a right `Sheet` (v1).
+- Do not put pagination on the query bar. Use `Pagination` in `Table` `bottomSlot`.
+- Do not put table search in `Navigation`.
+- `Lockup` and `Textfield` are `width: 100%` of the parent. Do not put them in a `flexWrap="wrap"` row with actions — they take the line and stack siblings underneath. Keep `flexWrap="nowrap"` (Layout default). Do **not** wrap `Lockup` in another `Layout` (`flexGrow` / `flexBasis={0}`) to sit beside a `ButtonGroup`. Do not put `minWidth` on the actions to invent a wrap threshold. Size a search field (`width="16rem"`, `flexShrink={0}`). Actions: `Layout` `flexShrink={0}` around the `ButtonGroup` only. Stack the header with `flexDirection="column"` below tablet.
+- Table has no expandable / nested-row API. v1 is **flat rows**.
+- A2UI: no `getUxelleRecipe("data-table-page")` yet. Compose `A2uiTable*` / `A2uiSheet` / `A2uiTabGroup` / `A2uiTextfield`. `Lockup` has no adapter — stack `A2uiText`. Layout-spacing only (no breakpoint chrome).
+
+## Regions
+
+page column → **header** (title left, page actions right) → optional `Banner` → **`Table`** (`topSlot`: data tabs → query bar → optional chips → grid or empty copy → `bottomSlot` pagination)
+
+```
+┌ Title + optional subtitle                    [Delete] [Upload] ┐
+├ optional Banner                                                ┤
+├ Table.topSlot:  Tabs (this dataset / that dataset)             ┤
+├                 [Filter] [facet]     [Search……] [Export]       ┤
+├                 [FilterChip] [FilterChip]                      ┤
+├ Table.tableSlot: grid, or empty copy                           ┤
+└ Table.bottomSlot: Pagination                                   ┘
+```
+
+Page `gap` (`medium-12`) is between **page sections** (header vs table). Inside `topSlot`, use `small-4` so tabs sit on the table, not in a previous section.
+
+## What goes where
+
+**Header — change the collection.** `Lockup` left (direct child), `ButtonGroup` right, **same row** (`flexWrap="nowrap"`, actions `Layout` `flexShrink={0}`). Do not wrap `Lockup` in a nested `Layout` to share the row. Do not `flexWrap="wrap"` this header, and do not add `minWidth` on the actions to make wrap wait. Below tablet, that header Layout may be `flexDirection="column"` so stacked actions sit under the title ([how-to-page-layout.md](how-to-page-layout.md#action-clusters)). Destructive / import actions open a `Dialog` — title and body `Text` use `width={false}` (100% of the slot). Button labels stay `width` (fit). Query-bar buttons stay a row at every width.
+
+**Banner — page offer.** After the header, before `Table`. Never between data tabs and the grid.
+
+**Data tabs — switch which rows.** First child of `Table` `topSlot`. Optional counts in the label (`"Referrals (12)"`). No `panels` wrapping the grid — controlled `activeTab` / `onChange`, then render one `Table` body for the active set. Do not put Filter or Search on this row.
+
+**Query bar — narrow the current view.** Next in `topSlot`, one row, `justifyContent="space-between"`:
+
+- **Left — constrain:** Filter `Button` → `Sheet`. Name the trigger after a single dimension (`Status`, `Role`); use `Filter` when the sheet has several groups. Optional `ChoiceChip` for a sticky facet. Applied values: `FilterChipGroup` **under** this row.
+- **Right — find:** search and utilities **on one line**. Wrapper around `Textfield` with a bounded `width` (e.g. `16rem`) and `flexShrink={0}`. `Export all` / Refresh as `emphasis="low"` `Button` siblings, cluster `flexWrap="nowrap"`. Not inside the Filter `ButtonGroup`.
+
+**Footer — page the result.** `Pagination` in `bottomSlot`.
+
+## Spacing
+
+Page column: [how-to-page-layout.md](how-to-page-layout.md). Header and query bar: `small-4` gap, `space-between`. `topSlot` stack (tabs → query bar → chips): `small-4`. Do not wrap `Table` in extra padding. Placement rules: [how-to-page-layout.md](how-to-page-layout.md#keep-controls-with-what-they-operate).
+
+## A11y
+
+[how-to-accessibility.md](how-to-accessibility.md). One page `h1`. `TableGrid` `aria-label` matches the active dataset. Filter `Sheet` has a title. Compact search `Textfield` uses `aria-label`. Empty copy is `role="status"`. Each `ButtonGroup` needs `aria-label`. Query bar: `aria-label="Table filters and search"`. Data tabs: `TabsCompact` `aria-label` if the tablist needs a name (`"Referral records"`).
+
+## Column alignment
+
+Set `alignment` on **both** `TableHeaderCell` and `TableCell`:
+
+- Text, names, emails, SKUs, links → `left` (default)
+- Money, counts, numeric → `right`
+- Category / visibility / status (`LabelBadge`) → `center`
+- A column that is only a CTA (`Button` / `IconButton` / `Link`) → `center`
+
+Identity cells: stack `Text type="Body Small Alt"` (name) and `Text type="Condensed"` (email) with `gap={0}`. Line boxes already separate the lines — do not add `micro-2` (or any layout-spacing) between them. Do not invent an Avatar component.
+
+Missing **cell** values: em dash (`—`). Missing **rows**: empty copy, not dashes.
+
+## Empty state
+
+Keep `Table`, data tabs, and the query bar in `topSlot`. Put a `role="status"` sentence in `tableSlot`: “There are no {what this view lists} here.” Omit pagination when there are no rows.
+
+## Responsive
+
+- **Header** stacks below tablet: switch the header `Layout` `flexDirection` to `column` and let the `ButtonGroup` go `direction="column"` `fullWidth` (`useBreakpointUp("tablet")`, [how-to-page-layout.md](how-to-page-layout.md#action-clusters)).
+- **Query bar** stays a row of controls; when very tight, the search field can take the full line above the filter/export cluster. Applied `FilterChipGroup` wraps.
+- **Table** scrolls horizontally when narrower than its columns — there is no stacked-row API. Keep the query bar and tabs above it.
+- **Pagination** swaps to [`PaginationSimple`](../uxelle-components/PaginationSimple.md) where the full control is too wide.
+
+## React
+
+Import from `@uxelle/components`. Data tabs and the query bar both go in `topSlot` — tabs first. `tabletUp` comes from `useBreakpointUp("tablet")` ([how-to-page-layout.md](how-to-page-layout.md#action-clusters)).
+
+```tsx
+<Layout as="section" display="flex" flexDirection="column" gap="var(--uxl-theme-layout-spacing-small-4)">
+  <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
+      topSlot={false}
+      title={
+        <Text type="Display Extra Small" as="h1" width={false}>
+          Referrals
+        </Text>
+      }
+      body={
+        <Text type="Body Medium" width={false}>
+          Connections, matches, and potential earnings in one register.
+        </Text>
+      }
+    />
+    <Layout flexShrink={0}>
+      <ButtonGroup
+        direction={tabletUp ? "row" : "column"}
+        fullWidth={!tabletUp}
+        aria-label="Referral actions"
+      >
+        <Button emphasis="medium">
+          <Text type="Button" width>
+            Delete
+          </Text>
+        </Button>
+        <Button emphasis="high">
+          <Text type="Button" width>
+            Upload
+          </Text>
+        </Button>
+      </ButtonGroup>
+    </Layout>
+  </Layout>
+
+  {/* optional Banner — here, not inside Table */}
+
+  <Table
+    topSlot={
+      <Layout display="flex" flexDirection="column" gap="var(--uxl-theme-layout-spacing-small-4)">
+        <TabsCompact
+          amount={2}
+          tabLabels={["Referrals (12)", "Connections (6)"]}
+          activeTab={activeTab}
+          onChange={setActiveTab}
+          aria-label="Referral records"
+        />
+        <TableQueryBar />
+      </Layout>
+    }
+    tableSlot={
+      rows.length === 0 ? (
+        <Text type="Body Medium" width={false} role="status">
+          There are no referrals here.
+        </Text>
+      ) : (
+        <TableColumnSizingProvider columns={columns}>
+          <RecordsGrid rows={rows} />
+        </TableColumnSizingProvider>
+      )
+    }
+    bottomSlot={
+      rows.length === 0 ? undefined : (
+        <Pagination totalItems={rows.length} defaultItemsPerPage={10} aria-label="Referrals pagination" />
+      )
+    }
+  />
+</Layout>
+```
+
+Query bar (filters left; search and export **nowrap** on the right):
+
+```tsx
+function TableQueryBar() {
+  return (
+    <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>
+      {/* Optional: FilterChipGroup of applied filters */}
+    </Layout>
+  );
+}
+```
+
+Grid cells (alignment on header and body):
+
+```tsx
+<TableHeaderCell columnId={0} title="Connection" showControls={false} />
+<TableHeaderCell columnId={1} title="Status" showControls={false} alignment="center" />
+<TableHeaderCell columnId={2} title="Potential earnings" showControls={false} alignment="right" />
+<TableCell columnId={0}>
+  <Layout display="flex" flexDirection="column" gap={0}>
+    <Text type="Body Small Alt">{row.name}</Text>
+    <Text type="Condensed">{row.email ?? "—"}</Text>
+  </Layout>
+</TableCell>
+<TableCell columnId={1} alignment="center">
+  <LabelBadge label={row.status} />
+</TableCell>
+<TableCell columnId={2} alignment="right">
+  <Text type="Body Small">{row.amount}</Text>
+</TableCell>
+```
+
+Confirm / upload `Dialog` (page actions, not on the table):
+
+```tsx
+<Dialog
+  size="Small"
+  open={deleteOpen}
+  onOpenChange={setDeleteOpen}
+  aria-labelledby="delete-dialog-title"
+  aria-describedby="delete-dialog-body"
+  topSlotContent={
+    <>
+      <Text id="delete-dialog-title" type="Component Medium" width={false}>
+        Delete referral information
+      </Text>
+      <IconButton
+        emphasis="low"
+        size="small"
+        iconName="close"
+        iconVariant="sharpFilled"
+        aria-label="Close"
+        onClick={() => setDeleteOpen(false)}
+      />
+    </>
+  }
+  centerSlotContent={
+    <Text id="delete-dialog-body" type="Body Medium" width={false}>
+      This removes the referral register from this session. It cannot be undone.
+    </Text>
+  }
+  bottomSlotContent={
+          <ButtonGroup
+            direction={tabletUp ? "row" : "column"}
+            fullWidth={!tabletUp}
+            aria-label="Delete confirmation"
+          >
+      <Button emphasis="low" size="medium" onClick={() => setDeleteOpen(false)}>
+        <Text type="Button" width>
+          Cancel
+        </Text>
+      </Button>
+      <Button emphasis="high" size="medium" onClick={onDelete}>
+        <Text type="Button" width>
+          Delete
+        </Text>
+      </Button>
+    </ButtonGroup>
+  }
+/>
+```
+
+Upload dialogs put `FileUpload` `fullWidth` in `centerSlotContent`. Title `Text` still uses `width={false}`.
+
+## A2UI
+
+Same region order and layout-spacing strings. Bind row data and search/filter state. Runtime: no `getUxelleRecipe("data-table-page")` yet — compose `A2uiTable*` / `A2uiSheet` / `A2uiTabGroup` / `A2uiTextfield` ([a2ui.md](a2ui.md)). `Lockup` has no adapter — stack `A2uiText`. `A2uiText` in `A2uiDialog` slots uses `"width": false`.

package/skills/uxelle-design-harness/recipe-feature-section.md

@@ -0,0 +1,96 @@
+# Recipe: feature section
+
+A marketing **piece**: a capability shown as media beside copy. Stack several down
+the page, alternating the media side for rhythm; or switch capabilities with a
+segmented control.
+
+Composes [`Layout`](../uxelle-components/Layout.md) grid,
+[`Lockup`](../uxelle-components/Lockup.md),
+[`Image`](../uxelle-components/Image.md),
+[`ButtonGroup`](../uxelle-components/ButtonGroup.md), and optionally
+[`SegmentedControl`](../uxelle-components/SegmentedControl.md) or
+[`TabsCompact`](../uxelle-components/TabsCompact.md) for the switched variant.
+
+## When
+
+Explaining one capability at a time with a supporting visual.
+
+## When not
+
+- Three-plus equal cells are a [card-grid](recipe-card-grid.md), not this.
+- Section headings are `h2` (the page `h1` is the [hero](recipe-hero.md)).
+- Do not alternate sides with absolute positioning — reorder grid columns.
+
+## Regions
+
+section -> two-column grid: `Lockup` (`h2` + body + optional `ButtonGroup`) and
+`Image`. Alternate which column is the media per section. Switched variant: a
+`SegmentedControl` / `TabsCompact` above one media+copy block.
+
+## Responsive
+
+Two columns from tablet up, single column (media over copy) below — use
+`useBreakpointUp("tablet")` to set `gridTemplateColumns` and the visual order. See
+[how-to-page-layout.md](how-to-page-layout.md#responsiveness).
+
+## Spacing
+
+`--uxl-breakpoints-gutter` between the columns; `medium-12` between stacked feature
+sections; `large-13`+ block padding if the section is its own band
+([spacing-steps.md](spacing-steps.md)).
+
+## A11y
+
+Section heading `h2`; name the region with it (`aria-labelledby`). The
+`SegmentedControl` variant carries a legend or `aria-label`; meaningful media gets
+`alt`. See [how-to-accessibility.md](how-to-accessibility.md).
+
+## React
+
+Alternating media + copy:
+
+```tsx
+const tabletUp = useBreakpointUp("tablet");
+
+<Layout
+  as="section"
+  display="grid"
+  gridTemplateColumns={tabletUp ? "1fr 1fr" : "1fr"}
+  gap="var(--uxl-breakpoints-gutter)"
+  alignItems="center"
+>
+  <Lockup
+    overline={<Text type="Overline" width={false}>Automation</Text>}
+    title={<Text type="Display Small" as="h2" width={false}>Ship without the busywork</Text>}
+    body={<Text type="Body Medium" width={false}>Rules handle the repetitive steps so your team ships.</Text>}
+  />
+  <Image src="/features/automation.png" alt="Automation rules editor" aspectRatio="4:3" />
+</Layout>
+```
+
+For the next section, place the `Image` first (or set column order) so the media
+alternates sides.
+
+Switched variant (capabilities behind a control):
+
+```tsx
+<Layout as="section" display="flex" flexDirection="column" gap="var(--uxl-theme-layout-spacing-medium-8)">
+  <SegmentedControl
+    labelText="Capabilities"
+    value={feature}
+    onValueChange={setFeature}
+    segments={[
+      { value: "plan", label: "Plan" },
+      { value: "build", label: "Build" },
+      { value: "ship", label: "Ship" },
+    ]}
+  />
+  {/* render the media+copy block for the active `feature` */}
+</Layout>
+```
+
+## A2UI
+
+No `getUxelleRecipe("feature-section")` and no `gridTemplateColumns` — stack
+`A2uiText` copy then `A2uiImage` in one column; the switched variant uses
+`A2uiSegmentedControl` or `A2uiTabGroup` ([a2ui.md](a2ui.md)).