@uxelle/skills 0.2.2 → 0.2.4

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

@@ -0,0 +1,433 @@
+# Recipe: navigation
+
+A shared **piece**: the header bar — brand lockup, optional category disclosures,
+utilities, and a compact menu [`Sheet`](../uxelle-components/Sheet.md). Used by
+[app-chrome](recipe-app-chrome.md) (product and marketing).
+
+Composes [`Navigation`](../uxelle-components/Navigation.md),
+[`Logo`](../uxelle-components/Logo.md), [`Text`](../uxelle-components/Text.md),
+[`NavLink`](../uxelle-components/NavLink.md),
+[`IconButton`](../uxelle-components/IconButton.md),
+[`Sheet`](../uxelle-components/Sheet.md), [`Menu`](../uxelle-components/Menu.md),
+[`List`](../uxelle-components/List.md), [`ListItem`](../uxelle-components/ListItem.md),
+[`Layout`](../uxelle-components/Layout.md), [`Button`](../uxelle-components/Button.md),
+and optionally [`Textfield`](../uxelle-components/Textfield.md),
+[`LanguageSelector`](../uxelle-components/LanguageSelector.md),
+[`Accordion`](../uxelle-components/Accordion.md),
+[`NotificationBadge`](../uxelle-components/NotificationBadge.md), and
+[`BannerAnnouncement`](../uxelle-components/BannerAnnouncement.md).
+
+Slots are **open** — any node may live in any region. The defaults below are
+generation defaults; a prompt may override them.
+
+## When
+
+The top-of-page wayfinding for an experience that uses header `Navigation`. Place
+it in the app frame above `<main>` ([app-chrome](recipe-app-chrome.md)).
+
+## When not
+
+- Not an `AppChrome` / `NavigationBar` component to export from the customer app.
+- Signed-in product destinations belong on
+  [`NavigationSide`](../uxelle-components/NavigationSide.md) — do not also put the
+  full IA in a header mega menu or a second hamburger. The header then holds
+  identity + utilities only.
+- Focused flows (login, checkout, wizard): lockup only — no hamburger, no center
+  row, no footer.
+- Breadcrumbs, table search, and data tabs stay in the **page column**
+  ([recipe-data-table-page.md](recipe-data-table-page.md)), not in `Navigation`.
+- A zip / region / “add store” strip above the bar is `BannerAnnouncement`, not a
+  fourth Navigation slot.
+- Pass real slot content; omitting a slot (`undefined`) fills catalog demo
+  content. Pass **`null`** to drop a region. Do not pass `false` (empty wrapper
+  remains).
+
+## Chrome pattern
+
+Choose a frame **before** filling slots. Stacking every pattern is the usual miss.
+
+- **Marketing / public** — header `Navigation` only (lockup + Sheet or mega menu).
+  This recipe’s default.
+- **Signed-in product** — `NavigationSide` owns destinations; the header is
+  identity + utilities (search, account).
+- **Hybrid portal** — lockup + hamburger Sheet, little or no center row, even on
+  desktop.
+- **Focused flow** — lockup only; `centerSlot={null}`, no menu control.
+
+## Regions
+
+`leadingSlot` (brand lockup) · `centerSlot` (desktop category disclosures when
+the IA is two or more levels deep; otherwise `null`, which leaves blank space
+between leading and trailing) · `trailingSlot` (utilities + compact hamburger) ·
+`bottomSlot` (`null` unless a persistent L2 module bar).
+
+Optional `BannerAnnouncement` sits **above** `Navigation`, not in a slot.
+
+## Lockup (`leadingSlot`)
+
+- [`Logo`](../uxelle-components/Logo.md) when the experience has a mark
+  (`width={48}`). **Home is the mark**, not the whole lockup: wrap only `Logo` in
+  a plain `<a href="/" aria-label="Home">` and set `interactive`. Keep the mark
+  `aria-hidden` when title text is present.
+- Two-line type — **no extra gap** (`gap={0}`). Condensed line boxes already
+  separate the lines; do not add Tight / `micro-2` between them
+  ([recipe-data-table-page.md](recipe-data-table-page.md) identity cells):
+  - Top — `Text type="Condensed Alt"` `truncation`: the **site or experience
+    name**.
+  - Bottom — `Text type="Condensed"`: **location or a short descriptor**. Omit
+    the second line when there is nothing to say.
+- Do not use Display or Body types in the lockup.
+- Do **not** wrap the lockup in [`Link`](../uxelle-components/Link.md) or nest the
+  title in `<a>` / `uxl-link`. `Link` underlines at rest — that underline on
+  Condensed lockup text looks wrong.
+- No mark → do not turn the title into a link just to get a home control.
+- Do not also add a “Home” `NavLink` or Sheet row when the logo already goes home.
+- The lockup is not the page `h1`.
+
+## Center and overflow
+
+- **One-level IA:** `centerSlot={null}`. Destinations live in the Sheet.
+- **Two or more levels, from desktop up:** fill `centerSlot` with top-level
+  category controls that **click** open a disclosure panel (see
+  [IA depth](#ia-depth-what-is-inside-the-menu)). Hide that row below desktop.
+  Never show `centerSlot` and the compact hamburger together.
+- About five to seven L1 items, then a `NavLink withMenu` labeled More
+  (overflow only). Do not wrap an unbounded row of categories.
+
+## Menu control and Sheet
+
+[`IconButton`](../uxelle-components/IconButton.md) `iconName="menu"`
+`iconVariant="sharpUnfilled"` `emphasis="low"` `aria-label="Menu"` opens a
+`Sheet` whose body is the destination tree.
+
+Control the Sheet with `open` / `onOpenChange` (same idea as `NavigationSide`
+`menuOpen` / `onMenuOpenChange`). Close it after a leaf: `onClick={() =>
+setMenuOpen(false)}` on each destination `ListItem`. An uncontrolled Sheet
+stays open after in-app navigation.
+
+- **From desktop up:** the menu control may live in **any slot**. For two- and
+  three-level IA, omit it while `centerSlot` is visible — the compact control
+  is for below desktop.
+- **Below desktop:** the **visible** menu control defaults to **`trailingSlot`**
+  (right edge). If a desktop menu is in `leadingSlot`, hide that instance below
+  desktop and show a trailing one — one visible hamburger per breakpoint, not
+  two. Switch with `useBreakpointUp("desktop")` (the band catalog chrome uses).
+  Do not use the tablet band for this — tablet would keep L1 links and the
+  hamburger on screen together.
+- Do not leave only a leading hamburger glued to the title at compact widths.
+- Do not add a header hamburger when the frame already uses `NavigationSide`
+  (it already owns the compact menu + right Sheet).
+
+**Sheet `direction` follows the menu.** Open the panel from the same side as the
+visible control:
+
+- Menu on the **right** (`trailingSlot`) → `direction="Right"`.
+- Menu on the **left** (`leadingSlot`) → `direction="Left"`.
+- Ambiguous (e.g. center) → `Right`.
+- Desktop leading + below-desktop trailing: switch `direction` with the same
+  breakpoint as the visible trigger (`useBreakpointUp("desktop")`), or use one
+  Sheet per visible trigger.
+
+Leave the Sheet header empty except the close control: `title=""` and
+`aria-label="Menu"` (same as `NavigationSide`). Do not put a visible “Menu”
+heading before the close button. Use the `trigger` slot for the `IconButton`.
+
+## Trailing utilities
+
+Stay a **row** at every width
+([how-to-page-layout.md](how-to-page-layout.md#action-clusters)). Typical
+cluster, left to right: search → language (if needed) → session → compact
+hamburger.
+
+- **Search** — marketing/catalog: visible [`Textfield`](../uxelle-components/Textfield.md)
+  (`label={false}`, `aria-label="Search"`) in a [`Layout`](../uxelle-components/Layout.md)
+  `width="16rem"` `flexShrink={0}`. Dense product: search `IconButton`. Table/query
+  search stays on the page, not here.
+- **Session** — logged out: Log in + optional Register (one high-emphasis CTA).
+  Logged in: account `IconButton` + `Menu` (profile, settings, log out), optional
+  `NotificationBadge`. Do not keep Register when the user is signed in.
+- Do not bury Log in / search in the Sheet.
+
+## Secondary bar (`bottomSlot`)
+
+`null` unless there is a persistent **L2 module bar** under the primary bar
+(app section switcher). `NavLink`s there use `navigationLevel="Secondary"`. Not
+breadcrumbs, not in-page tabs, not a dump for extra links.
+
+## IA depth: what is inside the menu
+
+Treat depth of the information architecture as the switch. Compose existing
+pieces; do not invent a mega-menu component.
+
+**Open on click, not hover.** Destination panels are `Menu` `pattern="disclosure"`
+with a `NavLink` trigger (no `href`, `trailingIcon`) so Tab walks links.
+`NavLink withMenu` is overflow labeled More only (`pattern="menu"`, Tab
+dismisses). `keyboard_arrow_down` on a category trigger signals a disclosure.
+`chevron_right` on a row means **another column / level**, not outbound.
+
+### One level (flat site)
+
+Destinations are peers. `centerSlot={null}`. The Sheet holds a `List` of
+interactive `ListItem`s with `href` — **no chevrons**. Example: About, Contact.
+Pass `bottomText=""` so the catalog demo line does not show.
+
+### Two levels
+
+Top-level groups, each with a flat list of leaves.
+
+- **From desktop up:** `centerSlot` is `Menu` `pattern="disclosure"` per group
+  (`NavLink` trigger, no `href`, `trailingIcon`). Panel is one column of leaf
+  `ListItem`s (`href`, no chevron). Optional short group intro above the list.
+  Overflow labeled More uses `NavLink withMenu`.
+- **Below desktop:** hide `centerSlot`. Sheet lists the groups as
+  [`Accordion`](../uxelle-components/Accordion.md) (omit `headingLevel` — these
+  are not page headings). Each panel is the leaf list. Leaves have no chevron.
+  Close the Sheet from each leaf `onClick`.
+
+### Three levels
+
+Top-level areas → categories → leaves. Chevron means another column / level.
+
+- **From desktop up:** `centerSlot` uses `Menu` `pattern="disclosure"` with a
+  `NavLink` trigger (no `href`, `trailingIcon`). The panel is a **wide**
+  `Layout` row, not a skinny dropdown:
+  1. **Intro column** — area title (`Text`), one-line descriptor, `Link` to the
+     area landing. Quieter surface; not a list.
+  2. **Category column** — interactive `ListItem`s. Rows with children get
+     `trailingSlot` + `trailingIconName="chevron_right"`. Hold the selected
+     category in state and set `activated` from that state (it drives the next
+     column). A row with no children is a leaf (no chevron).
+  3. **Leaf column** — map the selected category to `ListItem` `href` rows with
+     **no** chevron. Optional “View all {category}” at the bottom of this
+     column only.
+- **Below desktop:** do **not** lay out three columns in the Sheet. Same tree as
+  a **drill-down**: Accordion (or nested Accordion) so one extra level expands in
+  place; leaves are `href` rows. One visible extra level at a time.
+
+Selecting a category in the desktop panel **updates the next column in place**
+(does not navigate away). Only leaf rows and “Explore …” / “View all …”
+navigate. Close the panel or Sheet after a leaf navigation (`onOpenChange` /
+`setMenuOpen(false)`).
+
+## Responsive
+
+- One-level: hamburger may sit in `trailingSlot` at every width (valid on
+  desktop and below desktop).
+- Two- and three-level: show `centerSlot` from desktop up; below desktop set
+  `centerSlot={null}` and put the menu `IconButton` + Sheet in `trailingSlot`.
+  Switch with `useBreakpointUp("desktop")`
+  ([how-to-page-layout.md](how-to-page-layout.md#responsiveness)). Never
+  hard-code breakpoint px. Do not use the tablet band for this chrome switch.
+- Trailing utilities stay a row at every width.
+
+## Spacing
+
+`Navigation` is **density-invariant** chrome (its own tokens). Do not wrap it in
+extra `p` / `gap`. Lockup lines use `gap={0}` — not the Tight step. Slot content
+inherits the host experience’s density mode ([density.md](density.md)).
+
+## A11y
+
+[how-to-accessibility.md](how-to-accessibility.md). `Navigation` already exposes
+named `nav` landmarks. Name the home control on the Logo’s wrapping `<a>`
+(`aria-label="Home"`); keep the mark decorative. Name the menu `IconButton`.
+`aria-current="page"` on the current leaf `NavLink` / `ListItem` `href`.
+`activated` on the selected mega-menu category (not a leaf). Name the Sheet with
+`aria-label="Menu"` and `title=""` so the header is only the close control.
+Every `IconButton` has an `aria-label`.
+
+## Color
+
+`Navigation` owns each band’s surface — style slot content with role tokens; do
+not hardcode color ([how-to-color.md](how-to-color.md)). Secondary-bar
+`NavLink`s use `navigationLevel="Secondary"` so they follow that band.
+
+## React
+
+Import from `@uxelle/components`. One-level marketing/public default (lockup +
+trailing hamburger Sheet). Control the Sheet with `open` / `onOpenChange` and
+close it from each leaf `onClick`. `desktopUp` is unused here because the menu
+stays in `trailingSlot` at every width.
+
+```tsx
+const [menuOpen, setMenuOpen] = useState(false);
+
+<Navigation
+  bottomSlot={null}
+  leadingSlot={
+    <>
+      <a href="/" aria-label="Home">
+        <Logo name="generic" width={48} interactive aria-hidden />
+      </a>
+      <Layout
+        display="flex"
+        flexDirection="column"
+        gap={0}
+      >
+        <Text type="Condensed Alt" truncation width={false}>
+          Crop Science
+        </Text>
+        <Text type="Condensed" truncation width={false}>
+          United States
+        </Text>
+      </Layout>
+    </>
+  }
+  centerSlot={null}
+  trailingSlot={
+    <>
+      <LanguageSelector value="EN" />
+      <Button emphasis="low" size="small">
+        Log in
+      </Button>
+      <Button emphasis="high" size="small">
+        Register
+      </Button>
+      <Sheet
+        open={menuOpen}
+        onOpenChange={setMenuOpen}
+        direction="Right"
+        title=""
+        aria-label="Menu"
+        trigger={
+          <IconButton
+            emphasis="low"
+            size="small"
+            iconName="menu"
+            iconVariant="sharpUnfilled"
+            aria-label="Menu"
+          />
+        }
+      >
+        <List>
+          <ListItem
+            interactive
+            href="/about"
+            centerText="About"
+            bottomText=""
+            onClick={() => setMenuOpen(false)}
+          />
+          <ListItem
+            interactive
+            href="/contact"
+            centerText="Contact"
+            bottomText=""
+            onClick={() => setMenuOpen(false)}
+          />
+        </List>
+      </Sheet>
+    </>
+  }
+/>
+```
+
+Two-level desktop `centerSlot` (hide below desktop; overflow More uses
+`withMenu`; Sheet in trailing carries the same tree):
+
+```tsx
+<Menu
+  pattern="disclosure"
+  direction="Bottom Left"
+  trigger={<NavLink label="Crop Protection" trailingIcon />}
+>
+  <List>
+    <ListItem interactive href="/crop-protection/fungicides" centerText="Fungicides" bottomText="" />
+    <ListItem interactive href="/crop-protection/herbicides" centerText="Herbicides" bottomText="" />
+    <ListItem interactive href="/crop-protection/trial-data" centerText="Trial Data" bottomText="" />
+  </List>
+</Menu>
+<NavLink label="More" withMenu trailingIcon>
+  <List>
+    <ListItem interactive href="/seeds" centerText="Seeds" bottomText="" />
+  </List>
+</NavLink>
+```
+
+Three-level desktop `centerSlot` — selected category in state fills the next
+column; close the panel from each leaf:
+
+```tsx
+const [panelOpen, setPanelOpen] = useState(false);
+const [category, setCategory] = useState<"fungicides" | "herbicides">("fungicides");
+
+const leaves = {
+  fungicides: [
+    { href: "/products/delaro", label: "Delaro" },
+    { href: "/products/luna", label: "Luna Family" },
+    { href: "/crop-protection/fungicides", label: "View all Fungicides" },
+  ],
+  herbicides: [
+    { href: "/products/roundup", label: "Roundup" },
+    { href: "/crop-protection/herbicides", label: "View all Herbicides" },
+  ],
+} as const;
+
+<Menu
+  pattern="disclosure"
+  direction="Bottom Left"
+  open={panelOpen}
+  onOpenChange={setPanelOpen}
+  trigger={<NavLink label="Crop Protection" trailingIcon />}
+>
+  <Layout display="flex" gap="var(--uxl-theme-layout-spacing-small-4)">
+    <Layout display="flex" flexDirection="column" gap="var(--uxl-theme-layout-spacing-micro-2)">
+      <Text type="Condensed Alt" width={false}>
+        Crop Protection
+      </Text>
+      <Text type="Condensed" width={false}>
+        Innovation to help farmers protect their harvests.
+      </Text>
+      <Link href="/crop-protection">Explore Crop Protection</Link>
+    </Layout>
+    <List>
+      <ListItem
+        interactive
+        activated={category === "fungicides"}
+        trailingSlot
+        trailingIconName="chevron_right"
+        centerText="Fungicides"
+        bottomText=""
+        onClick={() => setCategory("fungicides")}
+      />
+      <ListItem
+        interactive
+        activated={category === "herbicides"}
+        trailingSlot
+        trailingIconName="chevron_right"
+        centerText="Herbicides"
+        bottomText=""
+        onClick={() => setCategory("herbicides")}
+      />
+      <ListItem
+        interactive
+        href="/crop-protection/trial-data"
+        centerText="Trial Data"
+        bottomText=""
+        onClick={() => setPanelOpen(false)}
+      />
+    </List>
+    <List>
+      {leaves[category].map((item) => (
+        <ListItem
+          key={item.href}
+          interactive
+          href={item.href}
+          centerText={item.label}
+          bottomText=""
+          onClick={() => setPanelOpen(false)}
+        />
+      ))}
+    </List>
+  </Layout>
+</Menu>
+```
+
+## A2UI
+
+No `getUxelleRecipe("navigation")`. Hosts often own chrome; when the surface
+already has `A2uiNavigation`, use the same slot assignment. Runtime chat has no
+`matchMedia` — default to one-level (lockup + trailing `A2uiSheet` `direction`
+`"Right"`). Empty or omitted child lists become catalog placeholders (the adapter
+maps them to `undefined`); prefer host-owned chrome when a region must be absent.
+Compose `A2uiLogo`, `A2uiText`, `A2uiNavLink`, `A2uiList` / `A2uiListItem`,
+`A2uiIconButton`, `A2uiSheet`. See [a2ui.md](a2ui.md).

package/skills/uxelle-design-harness/recipe-stat-callouts.md

@@ -24,6 +24,8 @@ A small set of headline numbers — revenue, active users, uptime, "10k+ teams."
 - Do not put `onClick` on StatTile — put a `Link` or `IconButton` in
   `trailingSlotContent`.
 - Do not signal a delta with color alone — pair it with a sign or word.
+- Do not wrap StatTile labels yourself. The label stays on one line and
+  ellipsizes; hover or focus a truncated label to read the full name.
 
 ## Regions
 
@@ -50,10 +52,10 @@ band on a `spacious` page it adds breathing with the **Band** step (`large-15`)
 ## A11y
 
 Each figure and its label read together. StatTile names the group from `label`
-automatically (including `valueFirst`). If there is no label, set `aria-label`
-that combines the figure and its meaning. If the trailing slot holds a delta,
-keep the meaning in text, not color alone. See
-[how-to-accessibility.md](how-to-accessibility.md).
+automatically (including `valueFirst`), including when the visible label is
+ellipsized. If there is no label, set `aria-label` that combines the figure and
+its meaning. If the trailing slot holds a delta, keep the meaning in text, not
+color alone. See [how-to-accessibility.md](how-to-accessibility.md).
 
 ## Color