@tailor-platform/app-shell 1.18.0 → 1.19.0

package/skills/app-shell-patterns/references/components/form.md

@@ -100,14 +100,14 @@ A compound component that groups all parts of a form field and manages its valid
 
 ### Sub-components
 
-| Sub-component       | Description                                                                                   |
-| ------------------- | --------------------------------------------------------------------------------------------- |
-| `Field.Root`        | Context boundary for a single field. Manages validation state.                                |
-| `Field.Label`       | Accessible label; `htmlFor` is resolved automatically via context.                            |
-| `Field.Control`     | Styled `<input>`. Can be omitted when using a Base UI-backed AppShell component as the input. |
-| `Field.Description` | Supplementary help text; automatically linked via `aria-describedby`.                         |
-| `Field.Error`       | Validation error message. Use `match` to target specific validity states.                     |
-| `Field.Validity`    | Render-prop access to the field's `ValidityState` for fully custom validation UI.             |
+| Sub-component       | Description                                                                                                            |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `Field.Root`        | Context boundary for a single field. Manages validation state.                                                         |
+| `Field.Label`       | Accessible label; `htmlFor` is resolved automatically via context.                                                     |
+| `Field.Control`     | Styled text `<input>`. `Select`, `Combobox`, and the other self-wired controls go directly under `Field.Root` instead. |
+| `Field.Description` | Supplementary help text; automatically linked via `aria-describedby`.                                                  |
+| `Field.Error`       | Validation error message. Use `match` to target specific validity states.                                              |
+| `Field.Validity`    | Render-prop access to the field's `ValidityState` for fully custom validation UI.                                      |
 
 ### Field.Root Props
 
@@ -134,7 +134,17 @@ A compound component that groups all parts of a form field and manages its valid
 
 ### Using Another AppShell Component as the Control
 
-`Field.Control` can be omitted when using a Base UI-backed AppShell component (e.g. `Select`, `Combobox`). The component registers itself with the `Field` context automatically, inheriting label association and validation state.
+`Field.Control` is a text input. It is the control for plain text-like fields, and you can pass it a native element such as `render={<textarea />}`. The controls in the last row of the table below go **directly under `Field.Root`**, as a sibling of `Field.Label`. Each one registers itself with the `Field` context, so it gets label association, `aria-describedby`, `disabled`, and validation state without `Field.Control`.
+
+| Control                                                                                                                         | Where it goes                                     |
+| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| Plain text, email, number, password, … input                                                                                    | `<Field.Control type="…" />`                      |
+| Native element (`<textarea>`, `<input type="…">`)                                                                               | `<Field.Control render={<textarea />} />`         |
+| `Select`, `Combobox`, `Autocomplete`, `Checkbox`, `Textarea`, `DateField`, `DatePicker`, `DateRangePicker` (and their `.Async`) | Directly under `Field.Root` — not `Field.Control` |
+
+`Input` is the exception. It is a plain `<input>` that does not connect to `Field.Root`, so inside a field use `<Field.Control />` in its place.
+
+Do not pass the self-wired controls to `Field.Control`'s `render` prop. They draw their own frame, so `<Field.Control render={<Select />} />` renders a second border around the select. `Field.Control` also passes them `<input>` props they don't take. `Field.Control` logs a console warning when it is given one of these controls directly as an element. A wrapper component or the function form of `render` is not detected.
 
 ```tsx
 const [country, setCountry] = React.useState<string | null>(null);

package/skills/app-shell-patterns/references/components/item-list.md

@@ -0,0 +1,191 @@
+---
+title: ItemList
+description: Compact icon-and-label lists for consistent navigation inside and outside the Sidebar
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/item-list.docs.outline.md — do not edit by hand. -->
+
+# ItemList
+
+`ItemList` presents compact icon-and-label rows for navigation and actions. Use it for in-content navigation, tables of contents, or other lists that should share the Sidebar's list presentation without depending on its layout or providers.
+
+It does not require `AppShell`, a router, or a Sidebar provider. Resource metadata, translations, permissions, and active-route matching remain the caller's responsibility.
+
+## Import
+
+```tsx
+import { ItemList } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  const [view, setView] = useState("Overview");
+  return (
+    <>
+      <ItemList.Root aria-label="Workspace">
+        <ItemList.Item
+          icon={<Home />}
+          isActive={view === "Overview"}
+          onClick={() => setView("Overview")}
+        >
+          Overview
+        </ItemList.Item>
+        <ItemList.Separator />
+        <ItemList.Section title="Business">
+          <ItemList.Item icon={<ShoppingCart />} onClick={() => setView("Orders")}>
+            Orders
+          </ItemList.Item>
+          <ItemList.Group title="Products" icon={<Package />}>
+            <ItemList.Item onClick={() => setView("All products")}>All products</ItemList.Item>
+            <ItemList.Item onClick={() => setView("Categories")}>Categories</ItemList.Item>
+          </ItemList.Group>
+        </ItemList.Section>
+      </ItemList.Root>
+      <output>Current view: {view}</output>
+    </>
+  );
+}
+```
+
+## Sub-components
+
+| Sub-component        | Description                                                                      |
+| -------------------- | -------------------------------------------------------------------------------- |
+| `ItemList.Root`      | A semantic `ul`; accepts standard list props                                     |
+| `ItemList.Item`      | A compact icon-and-label row containing a button or supplied interactive element |
+| `ItemList.Group`     | A collapsible, indented child list; open by default                              |
+| `ItemList.Section`   | A labeled, non-collapsible list whose items retain their normal indentation      |
+| `ItemList.Separator` | A decorative divider that remains a valid list child                             |
+
+## Items, Links, and Actions
+
+`ItemList.Item` is for links and actions, not static rows. It requires `onClick`, `render`, or both; omitting both is a type error, including for a disabled Item. With `onClick`, it renders a `button` with `type="button"` by default. Supply an anchor or application link through `render` for navigation.
+
+`render` replaces the interactive element inside the row, not the containing `li`. `children` supplies its label, and `icon` supplies an optional decorative leading icon. Standard button props, classes, attributes, and refs apply to the inner operation. A disabled Item is skipped by Tab and cancels clicks, including navigation through a supplied link.
+
+<example-preview name="links-and-actions"></example-preview>
+
+```tsx
+function LinksAndActions() {
+  const [checks, setChecks] = useState(0);
+  const handleCheckNotifications = () => {
+    setChecks((count) => count + 1);
+  };
+  return (
+    <>
+      <ItemList.Root aria-label="Quick access">
+        <ItemList.Item icon={<Home />} render={<a href="https://example.com/help" />}>
+          Help center
+        </ItemList.Item>
+        <ItemList.Item icon={<Bell />} onClick={handleCheckNotifications}>
+          Check notifications
+        </ItemList.Item>
+      </ItemList.Root>
+      <output>Notification checks: {checks}</output>
+    </>
+  );
+}
+```
+
+For application navigation, use `Link` or `NavLink` from `@tailor-platform/app-shell` inside an AppShell-managed page. Do not import routing APIs directly from `react-router` or create a separate router around the list. The routes in this example belong to the documentation app; use your application's route paths in your own pages.
+
+<example-preview name="app-shell-routing"></example-preview>
+
+```tsx
+function AppShellRouting() {
+  return (
+    <ItemList.Root aria-label="Documentation pages">
+      <ItemList.Item render={<Link to="/components/button" />}>Button documentation</ItemList.Item>
+      <ItemList.Item render={<NavLink to="/components/item-list" end />}>
+        ItemList documentation
+      </ItemList.Item>
+    </ItemList.Root>
+  );
+}
+```
+
+`NavLink` owns route matching and supplies `aria-current="page"` when matched; ItemList styles that attribute with the same emphasis as `isActive`. Use `end` when only the exact destination should be current. With a plain link, the caller supplies `aria-current="page"` when appropriate.
+
+`isActive` remains a boolean for explicit visual emphasis, including local actions. It does not imply `aria-current`, selection state, a `listbox` role, or `aria-selected`. ItemList does not perform route matching.
+
+### Item Props
+
+| Prop        | Type                                   | Default | Description                                                        |
+| ----------- | -------------------------------------- | ------- | ------------------------------------------------------------------ |
+| `icon`      | `ReactNode`                            | —       | Optional decorative leading icon                                   |
+| `children`  | `ReactNode`                            | —       | Compact row label                                                  |
+| `render`    | `ReactElement`                         | —       | Replaces the inner button; required unless `onClick` is supplied   |
+| `onClick`   | `MouseEventHandler<HTMLButtonElement>` | —       | Action handler; required unless `render` is supplied               |
+| `isActive`  | `boolean`                              | `false` | Explicit visual emphasis without route matching or selection state |
+| `disabled`  | `boolean`                              | —       | Disables clicks and removes the operation from the tab order       |
+| `className` | `string`                               | —       | Classes applied to the inner operation                             |
+
+Other standard button props, such as `title` and ARIA attributes, are forwarded to the inner operation. Put link-specific props such as `href`, `target`, and `rel` on the element passed to `render`.
+
+Rows without an `icon` do not reserve icon space. To align a mixed list, explicitly pass `icon={<span />}` on a row that needs an empty icon slot. Lists with no icons keep their compact indentation.
+
+## Groups and Heading Hierarchies
+
+`expandOnClick` defaults to `true`: clicking a group's heading toggles its child list, whether or not `render` is supplied. `render` only replaces the heading's main operation; it does not determine the expansion behavior. `defaultOpen` defaults to `true`; set it to `false` to start collapsed. Groups can be nested.
+
+Set `expandOnClick={false}` to separate the heading's main operation from expansion. This requires `onClick` or `render` so the heading does not become an inert button. A separate button, named by the group title, expands and collapses the group. Use this for linked headings so navigation does not toggle the list.
+
+`onClick` applies only to the heading's main operation. Clicking a child Item or the separate expand button does not invoke it. `isActive` and `aria-current="page"` control emphasis on the main heading operation, not the separate expand button.
+
+For a table of contents, use a linked Group for a parent heading and Items for its child headings. Keep the list data aligned with the actual heading hierarchy and anchor IDs in the document.
+
+<example-preview name="linked-group"></example-preview>
+
+```tsx
+function LinkedGroup() {
+  return (
+    <ItemList.Root aria-label="Contents">
+      <ItemList.Group
+        title="Installing"
+        render={<a href="#installing" aria-label="Installing" />}
+        expandOnClick={false}
+      >
+        <ItemList.Item render={<a href="#configuration" aria-label="Configuration" />}>
+          Configuration
+        </ItemList.Item>
+      </ItemList.Group>
+    </ItemList.Root>
+  );
+}
+```
+
+### Group Props
+
+| Prop            | Type                                   | Default | Description                                                                                       |
+| --------------- | -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
+| `title`         | `ReactNode`                            | —       | Accessible group label, including text and optional decorations                                   |
+| `icon`          | `ReactNode`                            | —       | Optional decorative leading icon                                                                  |
+| `render`        | `ReactElement`                         | —       | Replaces the main heading operation without changing expansion behavior                           |
+| `onClick`       | `MouseEventHandler<HTMLButtonElement>` | —       | Handler for the main heading operation only                                                       |
+| `expandOnClick` | `boolean`                              | `true`  | Toggle from the heading; `false` requires `onClick` or `render` and adds a separate expand button |
+| `isActive`      | `boolean`                              | `false` | Explicit visual emphasis for the heading operation                                                |
+| `defaultOpen`   | `boolean`                              | `true`  | Initial uncontrolled expanded state                                                               |
+| `children`      | `ReactNode`                            | —       | Nested Items, Groups, Sections, or Separators                                                     |
+
+Other standard `li` props, including `className`, apply to the containing group item, not its heading operation. `onClick` is the exception described above.
+
+A Group's rendered label names its heading operation, separate expand button, and child list. Keep meaningful text in a rich `title`; ReactNode content is not converted into a string. Meaningful details such as counts can be read with the label, while purely decorative elements should use `aria-hidden="true"`. An icon-only title needs screen-reader text. Do not put links or buttons inside the title, because the heading itself is interactive.
+
+## Sections and Separators
+
+Use `Group` for hierarchy and `Section` for flat classification. A Section accepts a resolved string `title` and `children`, keeps child rows at their normal indentation, and does not add an interactive heading. Other standard `li` props apply to its outer item.
+
+Neither Group nor Section requires wrapping its children in another `ItemList.Root`. Use `ItemList.Separator` between logical runs of items; it is decorative and renders a list item rather than an invalid direct `div` child of `ul`.
+
+## Styling and Accessibility
+
+- Keep labels concise; they truncate in narrow containers.
+- Use `aria-label` or `aria-labelledby` on Root when a list needs an accessible name.
+- Native links and buttons retain their keyboard interactions. Group buttons announce their expanded state and support Enter and Space.
+- Resolve translations before passing labels; ItemList does not translate them. Group titles can contain ReactNode content, while Section titles remain strings.
+- ItemList is an ordinary list, not a menu or selection widget. It does not provide arrow-key selection, search, reordering, or Sidebar icon-rail behavior.
+- Existing Sidebar components retain route metadata resolution, rail tooltips and flyouts, and drawer dismissal while sharing the underlying list presentation.

package/skills/app-shell-patterns/references/components/select.md

@@ -171,6 +171,16 @@ const { Root, Trigger, Value, Content, Item, Group, GroupLabel, Separator } = Se
 
 ## Form submission
 
+Inside a form, place `Select` directly under `Field.Root`, not inside `Field.Control`. `Select` draws
+its own trigger and registers with the field itself.
+
+```tsx
+<Field.Root name="country">
+  <Field.Label>Country</Field.Label>
+  <Select items={["Japan", "United States"]} placeholder="Select a country" />
+</Field.Root>
+```
+
 Inside a `Field.Root`, the field's `name` identifies the value and these props are unnecessary —
 see [Form](./form.md). They matter for **native** submission: a plain `<form>`, `new FormData(form)`,
 or a server action.

package/skills/app-shell-patterns/references/components/text.md

@@ -7,7 +7,7 @@ description: Text with a typography role, rendered as an element you choose
 
 # Text
 
-The `Text` component applies a [typography role](../concepts/styling-theming.md#typography) to its content. A role sets font size, line height, font weight, and letter spacing together. The role does not set the color, and it does not choose the HTML element. Use the `render` prop to choose the element (Base UI render pattern).
+The `Text` component applies a [typography role](../concepts/styling-theming.md#typography) to its content. A role sets font size, line height, font weight, and letter spacing together. The role does not set the color, and it does not choose the HTML element. To choose the element, use an element component such as `Text.h1` or `Text.p`, or use the `render` prop (Base UI render pattern) to compose with another component.
 
 ## Import
 
@@ -23,8 +23,8 @@ import { Text } from "@tailor-platform/app-shell";
 function BasicUsage() {
   return (
     <div className="flex flex-col gap-1">
-      <Text variant="heading-md">Purchase orders</Text>
-      <Text className="text-muted-foreground">Orders sent to suppliers this month.</Text>
+      <Text.h2>Purchase orders</Text.h2>
+      <Text.p className="text-muted-foreground">Orders sent to suppliers this month.</Text.p>
     </div>
   );
 }
@@ -36,18 +36,57 @@ _Generated from the type surface — first-party props only._
 
 ### TextProps
 
-| Prop       | Type                                                                                                                                                                | Default     | Description                                                                                                        |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
-| `ref?`     | `React.Ref<HTMLElement>`                                                                                                                                            | -           | Ref to the rendered element.                                                                                       |
-| `render?`  | `React.ReactElement`                                                                                                                                                | -           | Custom element to render as (Base UI render prop). Use it to set the heading level, for example `render={<h3 />}`. |
-| `variant?` | `"heading-lg" \| "heading-md" \| "heading-sm" \| "body-md" \| "body-sm" \| "label-md" \| "label-sm" \| "code-sm" \| "body-md-relaxed" \| "body-sm-relaxed" \| null` | `"body-md"` | Typography role. Sets font size, line height, font weight, and letter spacing together.                            |
+| Prop       | Type                                                                                                                                                                | Default     | Description                                                                                                                                                                              |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ref?`     | `React.Ref<HTMLElement>`                                                                                                                                            | -           | Ref to the rendered element.                                                                                                                                                             |
+| `render?`  | `React.ReactElement`                                                                                                                                                | -           | Custom element to render as (Base UI render prop). Use it to compose with another component. For a plain HTML element, use `Text.h1` to `Text.h6`, `Text.p`, `Text.span`, or `Text.div`. |
+| `variant?` | `"heading-lg" \| "heading-md" \| "heading-sm" \| "body-md" \| "body-sm" \| "label-md" \| "label-sm" \| "code-sm" \| "body-md-relaxed" \| "body-sm-relaxed" \| null` | `"body-md"` | Typography role. Sets font size, line height, font weight, and letter spacing together.                                                                                                  |
 
 ## Exports
 
-- `Text` — function
+- `Text` — const
 - `TextProps` — type
 
-All standard HTML attributes are also accepted. Put an attribute that belongs to one element, such as `htmlFor` on a `label`, on the `render` element:
+## Element Components
+
+`Text.h1` to `Text.h6`, `Text.p`, `Text.span`, and `Text.div` always render their named HTML element. Each one applies a default role, so you do not repeat `variant` for ordinary text:
+
+<example-preview name="element-components"></example-preview>
+
+```tsx
+function ElementComponents() {
+  return (
+    <div className="flex flex-col gap-1">
+      <Text.h3>Shipping address</Text.h3>
+      <Text.p className="text-muted-foreground">Orders ship from the main warehouse.</Text.p>
+      <Text.span className="tabular-nums">3 packages</Text.span>
+    </div>
+  );
+}
+```
+
+| Component           | Default `variant` |
+| ------------------- | ----------------- |
+| `Text.h1`           | `heading-lg`      |
+| `Text.h2`           | `heading-md`      |
+| `Text.h3`–`Text.h6` | `heading-sm`      |
+| `Text.p`            | `body-md`         |
+| `Text.span`         | `label-md`        |
+| `Text.div`          | `body-md`         |
+
+The element sets the meaning and `variant` sets the appearance. The default is only a starting point, and any role works on any element:
+
+```tsx
+<Text.h1 variant="heading-sm">A compact page title</Text.h1>
+<Text.h3 variant="heading-lg">A visually prominent subsection</Text.h3>
+<Text.span variant="body-sm">Updated recently</Text.span>
+```
+
+The element components take `variant`, `className`, the element's own attributes, and a ref typed for the element (`HTMLHeadingElement` for `Text.h2`). They do not take `render`. For any other element, or to compose with another component, use `Text` with `render`.
+
+## Using `render`
+
+All standard HTML attributes are also accepted by `Text`. Put an attribute that belongs to one element, such as `htmlFor` on a `label`, on the `render` element:
 
 ```tsx
 <Text variant="label-md" render={<label htmlFor="quantity" />}>
@@ -59,7 +98,7 @@ Some lint rules report this example; see [Lint](#lint).
 
 ## Roles
 
-`variant` takes one of the ten roles. Each role renders a default element when you do not pass `render`:
+`variant` takes one of the ten roles. On `Text`, each role renders a default element when you do not pass `render`:
 
 | `variant`         | Default element | Use                                             |
 | ----------------- | --------------- | ----------------------------------------------- |
@@ -70,7 +109,7 @@ Some lint rules report this example; see [Lint](#lint).
 | `body-sm`         | `p`             | Caption, timestamp, metadata                    |
 | `body-md-relaxed` | `p`             | Long text, such as a chat message or a document |
 | `body-sm-relaxed` | `p`             | Long text at the small size                     |
-| `label-md`        | `span`          | Field label, short UI text, figures in a table  |
+| `label-md`        | `span`          | Field label, short UI text                      |
 | `label-sm`        | `span`          | Small label, badge text                         |
 | `code-sm`         | `span`          | ID and code. `Text` adds `font-mono` for you    |
 
@@ -81,15 +120,9 @@ function Roles() {
   return (
     <div className="flex flex-col gap-3">
       {/* The headings render a div so that this specimen is not a document heading. */}
-      <Text variant="heading-lg" render={<div />}>
-        heading-lg: Purchase orders
-      </Text>
-      <Text variant="heading-md" render={<div />}>
-        heading-md: Line items
-      </Text>
-      <Text variant="heading-sm" render={<div />}>
-        heading-sm: Shipping address
-      </Text>
+      <Text.div variant="heading-lg">heading-lg: Purchase orders</Text.div>
+      <Text.div variant="heading-md">heading-md: Line items</Text.div>
+      <Text.div variant="heading-sm">heading-sm: Shipping address</Text.div>
       <Text variant="body-md">body-md: Orders sent to suppliers this month.</Text>
       <Text variant="body-sm">body-sm: Updated 2 hours ago</Text>
       <Text variant="label-md">label-md: Total amount</Text>
@@ -104,30 +137,28 @@ The sizes and line heights are in the [Typography section of the styling guide](
 
 ## Heading Level
 
-All three heading roles render `h2` by default. The heading level comes from the document structure, not from the visual size, so set it with `render`:
+On `Text`, all three heading roles render `h2` by default. The heading level comes from the document structure, not from the visual size, so set it with `Text.h1` to `Text.h6`:
 
 ```tsx
-<Text variant="heading-md" render={<h3 />}>
-  Line items
-</Text>
+<Text.h3 variant="heading-md">Line items</Text.h3>
 ```
 
-To use a heading role for text that is not a heading, render a `div` or a `span`:
+To use a heading role for text that is not a heading, use `Text.div` or `Text.span`:
 
 ```tsx
-<Text variant="heading-md" render={<div />}>
-  1,240 orders
-</Text>
+<Text.div variant="heading-md">1,240 orders</Text.div>
 ```
 
 ## Lint
 
-Some `jsx-a11y` rules check that an element has text inside it, for example `heading-has-content` for `<h3 />` and `label-has-associated-control` for `<label />`. These rules report the element in `render` as empty, because they do not see that `Text` passes its children to that element. If your app enables them, disable the rule on that line. ESLint and oxlint both read this comment:
+Some `jsx-a11y` rules check that an element has text inside it, for example `heading-has-content` for `<h3 />` and `label-has-associated-control` for `<label />`. These rules report the element in `render` as empty, because they do not see that `Text` passes its children to that element.
+
+For headings, use `Text.h1` to `Text.h6`. The rules do not report them. For other elements, such as `label`, use `render`, and if your app enables the rule, disable it on that line. ESLint and oxlint both read this comment:
 
 ```tsx
-// eslint-disable-next-line jsx-a11y/heading-has-content -- Text renders the children
-<Text variant="heading-md" render={<h3 />}>
-  Line items
+// eslint-disable-next-line jsx-a11y/label-has-associated-control -- Text renders the children
+<Text variant="label-md" render={<label htmlFor="quantity" />}>
+  Quantity
 </Text>
 ```
 
@@ -156,9 +187,9 @@ function ColorAndModifiers() {
 <Text variant="body-md" className="text-muted-foreground">
   Orders sent this month.
 </Text>
-<Text variant="heading-md" render={<h3 />} className="leading-none">
+<Text.h3 variant="heading-md" className="leading-none">
   Card title
-</Text>
+</Text.h3>
 <Text variant="label-md" className="tabular-nums">
   1,240.00
 </Text>
@@ -180,11 +211,17 @@ Each role is also a plain utility, for example `text-heading-md`. Use the utilit
 import { type TextProps } from "@tailor-platform/app-shell";
 ```
 
+The element components have no exported props type. Read it from the component:
+
+```tsx
+type SectionTitleProps = React.ComponentProps<typeof Text.h2>;
+```
+
 ## Accessibility
 
-- A heading role renders a real heading (`h2`) by default, so screen readers list it with the other headings. Set the level with `render` so the levels follow the page structure.
+- A heading role on `Text` renders a real heading (`h2`) by default, so screen readers list it with the other headings. Set the level with `Text.h1` to `Text.h6` so the levels follow the page structure.
 - Do not choose a heading level for its size. `Text` keeps the size and the level separate.
-- `body-*` roles render `p`. Inside another `p`, render a `span` instead (`<Text render={<span />}>`): the browser closes the outer `p` before the inner one, so React warns and server rendering fails to hydrate. Inside inline elements such as `button`, `label` or `span`, a `p` is invalid HTML too, so render a `span` there as well.
+- `body-*` roles render `p` on `Text`. Inside another `p`, use `Text.span` instead (`<Text.span variant="body-md">`): the browser closes the outer `p` before the inner one, so React warns and server rendering fails to hydrate. Inside inline elements such as `button`, `label` or `span`, a `p` is invalid HTML too, so render a `span` there as well.
 
 ## Palettes
 
@@ -195,4 +232,4 @@ The `cream` and `bloom` palettes set the line height and letter spacing of `h1`
 - [Card](./card.md) - The table above lists `heading-md` for card titles
 - [Layout](./layout.md) - The table above lists `heading-lg` for the page title
 
-AppShell's own components, including these two, still use the stock utilities. They will move to the roles in a later change.
+AppShell's own components, including these two, render their titles and descriptions with `Text`.

package/skills/app-shell-patterns/references/concepts/sidebar-navigation.md

@@ -69,16 +69,18 @@ const App = () => (
 ### SidebarItem
 
 A navigation item that automatically resolves title and icon from resource definitions.
+Active internal sidebar links expose `aria-current="page"` on the link itself, including
+items with custom `render` content. Inactive and external links do not expose it.
 
 #### Props
 
-| Prop       | Type              | Required | Description                                                                     |
-| ---------- | ----------------- | -------- | ------------------------------------------------------------------------------- |
-| `to`       | `string`          | Yes      | Target URL. External URLs (http://...) are rendered as external links           |
-| `title`    | `LocalizedString` | No       | Override title (i18n supported). When omitted, auto-resolved from resource meta |
-| `icon`     | `ReactNode`       | No       | Override icon. When omitted, auto-resolved from resource meta                   |
-| `external` | `boolean`         | No       | Opens link in new tab with external link icon                                   |
-| `render`   | `function`        | No       | Custom render function for full UI control                                      |
+| Prop       | Type              | Required | Description                                                                                                                      |
+| ---------- | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `to`       | `string`          | Yes      | Target URL. External URLs (http://...) are rendered as external links                                                            |
+| `title`    | `LocalizedString` | No       | Override title (i18n supported). When omitted, auto-resolved from resource meta                                                  |
+| `icon`     | `ReactNode`       | No       | Override icon. When omitted, auto-resolved from resource meta; with no icon at all, the icon rail shows the title's first letter |
+| `external` | `boolean`         | No       | Opens link in new tab with external link icon                                                                                    |
+| `render`   | `function`        | No       | Custom render function for full UI control                                                                                       |
 
 #### Examples
 
@@ -124,13 +126,13 @@ A collapsible group for organizing navigation items.
 
 #### Props
 
-| Prop          | Type              | Required | Description                                    |
-| ------------- | ----------------- | -------- | ---------------------------------------------- |
-| `title`       | `LocalizedString` | Yes      | Group title (supports i18n)                    |
-| `icon`        | `ReactNode`       | No       | Group icon                                     |
-| `to`          | `string`          | No       | When specified, title becomes a clickable link |
-| `defaultOpen` | `boolean`         | No       | Initial expanded state. Default: `true`        |
-| `children`    | `ReactNode`       | Yes      | Child items (SidebarItem, SidebarGroup, etc.)  |
+| Prop          | Type              | Required | Description                                                            |
+| ------------- | ----------------- | -------- | ---------------------------------------------------------------------- |
+| `title`       | `LocalizedString` | Yes      | Group title (supports i18n)                                            |
+| `icon`        | `ReactNode`       | No       | Group icon. When omitted, the icon rail shows the title's first letter |
+| `to`          | `string`          | No       | When specified, title becomes a clickable link                         |
+| `defaultOpen` | `boolean`         | No       | Initial expanded state. Default: `true`                                |
+| `children`    | `ReactNode`       | Yes      | Child items (SidebarItem, SidebarGroup, etc.)                          |
 
 #### Examples
 

package/skills/app-shell-patterns/references/concepts/styling-theming.md

@@ -217,7 +217,14 @@ Each intent has eight roles. The intents are `info`, `success`, `warning`, `dang
 <span className="rounded-md bg-success-surface px-2 py-0.5 text-success-text">Paid</span>
 ```
 
-In the default palette, `text` on `surface` and `contrast` on `solid` and `solid-hover` are at least 4.5:1 for the four hue intents, in light and dark mode, on `--card` and `--background`. A unit test checks this from the shipped CSS. `text` on `surface-hover` is held at 4.2:1 by the same test; it is below 4.5:1 for `danger` and `success` in light mode. The test does not cover the `cream` and `bloom` palettes or the `neutral` intent.
+The hue roles have the same values in every shipped palette. `cream` and `bloom` change brand and surface colors, not status colors. The `neutral` roles follow the palette, because they read the system tokens.
+
+**Contrast.** AppShell's thresholds are 4.5:1 for text (WCAG 1.4.3) and 3:1 for non-text (WCAG 1.4.11). In every shipped palette (`default`, `cream`, `bloom`), in light and dark mode, on `--card` and `--background`, `text` on `surface` and `contrast` on `solid` and `solid-hover` are at least 4.5:1 for the four hue intents, and `danger` `solid` (the invalid-input border) is at least 3:1. A browser test checks this in Chromium against the built stylesheet. Known exceptions:
+
+- `text` on `surface-hover` is below 4.5:1 for `danger` and `success` in light mode. The test holds it at 4.2:1 or more.
+- In `cream` and `bloom`, the main content area is transparent over the shell gradient. At the top of the `bloom` light gradient, `text` on `surface` is 4.49:1 for `success` and 4.48:1 for `danger`. Put status content on a card when it needs to pass.
+- `warning` `solid` and `indicator` are 2.15:1 against a light card. Use them with a label, not as the only sign of a state.
+- The `neutral` intent reads the system tokens and is not checked.
 
 Most `surface` and `border` values are translucent tints, so an opacity modifier compounds rather than replaces — `bg-info-surface/50` halves the tint's alpha instead of setting it to 50%. Some light-mode values are opaque instead of translucent: the `warning` surface, surface-hover and border, the `info` border and the `danger` surface-hover. They do not blend with a tinted parent. All dark-mode values are translucent.
 
@@ -227,7 +234,7 @@ Most `surface` and `border` values are translucent tints, so an opacity modifier
 
 `--sidebar`, `--sidebar-foreground`, `--sidebar-border`, `--sidebar-primary(-foreground)`, `--sidebar-accent(-foreground)`, `--sidebar-ring` → `bg-sidebar`, `text-sidebar-foreground`, and so on. These let a palette tint the shell independently of page content.
 
-`--chart-1` … `--chart-5` → `bg-chart-1`, `text-chart-1`, `fill-chart-1`. Use them in order for categorical series.
+`--chart-1` … `--chart-5` → `bg-chart-1`, `text-chart-1`, `fill-chart-1`. Use them in order for categorical series. They tell series apart and carry no status, so they are not semantic roles and have literal values.
 
 #### Alerts
 
@@ -283,7 +290,7 @@ There are 8 core roles and 2 relaxed body variants:
 | `heading-sm`      | `text-heading-sm`      | 14px / 20px        | 600    | Sub-section heading                             |
 | `body-md`         | `text-body-md`         | 14px / 20px        | 400    | Body copy, descriptions                         |
 | `body-sm`         | `text-body-sm`         | 12px / 16px        | 400    | Caption, timestamp, metadata                    |
-| `label-md`        | `text-label-md`        | 14px / 20px        | 500    | Field label, short UI text, figures in a table  |
+| `label-md`        | `text-label-md`        | 14px / 20px        | 500    | Field label, short UI text                      |
 | `label-sm`        | `text-label-sm`        | 12px / 16px        | 500    | Small label, badge text                         |
 | `code-sm`         | `text-code-sm`         | 12px / 18px        | 400    | ID and code. Use with `font-mono`               |
 | `body-md-relaxed` | `text-body-md-relaxed` | 14px / 24px        | 400    | Long text, such as a chat message or a document |
@@ -301,7 +308,7 @@ Pair a role with a color token from the Color section above. These pairings are
 | Body copy                         | `text-body-md`                                 |
 | Secondary copy, descriptions      | `text-body-md text-muted-foreground`           |
 | Caption, timestamp, metadata      | `text-body-sm text-muted-foreground`           |
-| Numeric value in a table or field | `text-label-md tabular-nums`                   |
+| Numeric value in a table or field | `text-body-md tabular-nums`                    |
 | ID, code                          | `font-mono text-code-sm text-muted-foreground` |
 
 <example-preview name="typography-roles"></example-preview>
@@ -404,20 +411,21 @@ function TypographyRoles() {
 }
 ```
 
+For headings, body copy, labels, and captions, use the [`Text`](../components/text.md) component. Do not style a bare `p`, `h1` to `h6`, or `span` with `text-sm`, `text-xs`, or `font-*`. A form field label is [`Field.Label`](../components/form.md), which already has the `label-md` role. `Text` applies the same roles with a `variant` prop. It renders a default element for each role (`h2` for headings, `p` for body text, `span` for the others). To set the element, such as the heading level, use an element component (`Text.h1` to `Text.h6`, `Text.p`, `Text.span`, `Text.div`):
+
 ```tsx
-<h2 className="text-heading-md">Section</h2>
-<p className="text-body-md text-muted-foreground">Description copy</p>
-<span className="text-body-sm text-muted-foreground">Updated 2h ago</span>
+<Text.h3 variant="heading-md">Line items</Text.h3>
+<Text variant="body-md" className="text-muted-foreground">Description copy</Text>
+<Text variant="body-sm" className="text-muted-foreground">Updated 2h ago</Text>
 ```
 
-The [`Text`](../components/text.md) component applies the same roles with a `variant` prop. It renders a default element for each role (`h2` for headings, `p` for body text, `span` for the others), and its `render` prop sets the element, such as the heading level:
+Use the role utility when you style an element that you render yourself, such as a table header cell or a link:
 
 ```tsx
-<Text variant="heading-md" render={<h3 />}>Line items</Text>
-<Text variant="body-md" className="text-muted-foreground">Description copy</Text>
+<th className="text-label-md text-muted-foreground">Amount</th>
 ```
 
-On an `h1` to `h6` element, the `cream` and `bloom` palettes replace the role's line height and letter spacing, including `leading-none`; see "Change a role" below. AppShell's own components still use the stock utilities (`text-sm`, `font-medium`, and so on) today. They will move to the roles in later changes, so the two sets can appear side by side for now.
+On an `h1` to `h6` element, the `cream` and `bloom` palettes replace the role's line height and letter spacing, including `leading-none`; see "Change a role" below. AppShell's own components use the roles: content text renders with `Text`, and controls use the role utility.
 
 **Rules**
 

package/skills/app-shell-patterns/references/migrations.md

@@ -33,7 +33,7 @@ Each entry states which versions are affected, what breaks, how to detect it, an
 - **`text-destructive` resolves to the solid.** In dark mode it changes from `#f87171` to `#dc2626`, which is 3.71:1 on the dark card, below 4.5:1 for text. Components shipped with AppShell now use `text-danger-text` for error text, and invalid borders and focus rings read `--danger-solid`. In dark mode the invalid border changes from `#f87171` to `#dc2626`.
 - **Themes that override `--destructive` no longer reach the components.** `Button`, invalid `Input`, `Textarea`, `Checkbox`, `Field` and `DateField` borders and rings, error text and the `CsvImporter` error cells read `--danger-*`. An override of `--destructive` still changes `bg-destructive` and `text-destructive` on your own elements, so the two reds can drift apart. The `cream` and `bloom` palettes no longer set `--destructive`; their values were the same as the default.
 
-How to detect it: search the app for `destructive` in class names and in theme CSS, including Theme Generator output that sets `--destructive`. Compare `Button variant="destructive"`, an invalid `Input` and an error message in light and dark mode after upgrading.
+How to detect it: search the app for `destructive` in class names and in theme CSS, including Theme Generator output that sets `--destructive`. In JS and TS files, the `no-deprecated-tokens` rule in `@tailor-platform/eslint-plugin-app-shell` reports these names and the role to use instead. The rule is available from version 0.2.0 of the plugin, and it does not read CSS files. Compare `Button variant="destructive"`, an invalid `Input` and an error message in light and dark mode after upgrading.
 
 What to change:
 
@@ -53,7 +53,7 @@ The roles are documented in [Styling & theming](https://github.com/tailor-platfo
 - **Component recolouring moves to the roles.** `Badge`, `Alert`, `CsvImporter` and `MetricCard` read the roles directly. A theme that overrides `--status-*` or `--alert-*` no longer changes these components; override `--{intent}-*` instead. `Badge` `error` / `subtle-error` and `Alert` `error` read `--danger-*`, so overriding `--destructive` no longer reaches them either. `Button variant="destructive"` and `text-destructive` still follow `--destructive`.
 - **`text-status-*` loses contrast in dark mode.** The `--status-*` values are now the step-9 fills, which are below 4.5:1 as text on the dark card.
 
-How to detect it: search the app for `status-`, `alert-` and theme overrides of `--status-`, `--alert-` and `--destructive`. Compare `Badge` and `Alert` in light and dark mode after upgrading.
+How to detect it: search the app for `status-`, `alert-` and theme overrides of `--status-`, `--alert-` and `--destructive`. In JS and TS files, the `no-deprecated-tokens` rule in `@tailor-platform/eslint-plugin-app-shell` reports these names and the role to use instead. The rule is available from version 0.2.0 of the plugin, and it does not read CSS files. Compare `Badge` and `Alert` in light and dark mode after upgrading.
 
 What to change: