@tailor-platform/app-shell 1.16.0 → 1.18.0

package/skills/app-shell-patterns/references/components/date-picker.md

@@ -181,6 +181,14 @@ Locale and timezone come from AppShell automatically. Override per field with `l
 <DatePicker aria-label="Date" locale="ja-JP" />
 ```
 
+### Day of the week
+
+`showDayOfWeek` adds the locale's short day of the week where the locale places it — `2025/12/19(金)` for ja-JP, `Fri, 12/19/2025` for en-US. It is read-only and derived from the entered date: it shows a placeholder until the date is complete, and while a date segment is mid-entry it keeps the previous day of the week (muted), so typing `25` into the day never flashes the 2nd's. Screen readers hear the full day name with each date segment's value.
+
+```tsx
+<DatePicker aria-label="Closing date" showDayOfWeek />
+```
+
 ## Keyboard
 
 - **Segments:** `↑`/`↓` increment/decrement, digits type-to-fill (auto-advance), `←`/`→` move between segments, `Backspace` clears, `/` commits the current segment and advances.
@@ -191,26 +199,29 @@ Locale and timezone come from AppShell automatically. Override per field with `l
 
 ### DateFieldProps
 
-| Prop                             | Type                                                          | Description                                                |
-| -------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------- |
-| `value` / `defaultValue`         | `DateValue \| null`                                           | Controlled / uncontrolled value                            |
-| `onChange`                       | `(v: DateValue \| null) => void`                              | Fires when the value changes                               |
-| `onBlur`                         | `() => void`                                                  | Fires when focus leaves the whole segmented control        |
-| `minValue` / `maxValue`          | `DateValue`                                                   | Inclusive date range bounds                                |
-| `isDateUnavailable`              | `(date: DateValue) => boolean`                                | Marks specific dates unavailable                           |
-| `isDisabled`                     | `boolean`                                                     | Disables interaction and form submission                   |
-| `isReadOnly`                     | `boolean`                                                     | Allows focus/navigation without editing                    |
-| `isRequired`                     | `boolean`                                                     | Marks the control required                                 |
-| `isInvalid`                      | `boolean`                                                     | Adds invalid styling / `aria-invalid` to the segmented UI  |
-| `placeholderValue`               | `DateValue`                                                   | Seeds unset segments                                       |
-| `autoFocus`                      | `boolean`                                                     | Focus the first segment on mount                           |
-| `locale`                         | `string`                                                      | BCP-47 locale override                                     |
-| `name`                           | `string`                                                      | Emits a form value through the proxy input                 |
-| `id`                             | `string`                                                      | Proxy input id (use with external `<label htmlFor>`).      |
-| `firstDayOfWeek`                 | `"sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat"` | Override the locale week start used by `w` / `k` shortcuts |
-| `aria-label` / `aria-labelledby` | `string`                                                      | Accessible name                                            |
-| `aria-describedby`               | `string`                                                      | IDs of description / error elements                        |
-| `className`                      | `string`                                                      | Root element class                                         |
+| Prop                             | Type                                                          | Description                                                  |
+| -------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
+| `value` / `defaultValue`         | `DateValue \| null`                                           | Controlled / uncontrolled value                              |
+| `onChange`                       | `(v: DateValue \| null) => void`                              | Fires when the value changes                                 |
+| `onBlur`                         | `() => void`                                                  | Fires when focus leaves the whole segmented control          |
+| `minValue` / `maxValue`          | `DateValue`                                                   | Inclusive date range bounds                                  |
+| `isDateUnavailable`              | `(date: DateValue) => boolean`                                | Marks specific dates unavailable                             |
+| `isDisabled`                     | `boolean`                                                     | Disables interaction and form submission                     |
+| `isReadOnly`                     | `boolean`                                                     | Allows focus/navigation without editing                      |
+| `isRequired`                     | `boolean`                                                     | Marks the control required                                   |
+| `isInvalid`                      | `boolean`                                                     | Adds invalid styling / `aria-invalid` to the segmented UI    |
+| `placeholderValue`               | `DateValue`                                                   | Seeds unset segments                                         |
+| `granularity`                    | `"day" \| "hour" \| "minute" \| "second"`                     | Smallest editable unit; time granularities add time segments |
+| `hourCycle`                      | `12 \| 24`                                                    | Force 12- or 24-hour time; defaults to the locale            |
+| `autoFocus`                      | `boolean`                                                     | Focus the first segment on mount                             |
+| `locale`                         | `string`                                                      | BCP-47 locale override                                       |
+| `showDayOfWeek`                  | `boolean`                                                     | Show the locale's short day of the week next to the date     |
+| `name`                           | `string`                                                      | Emits a form value through the proxy input                   |
+| `id`                             | `string`                                                      | Proxy input id (use with external `<label htmlFor>`).        |
+| `firstDayOfWeek`                 | `"sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat"` | Override the locale week start used by `w` / `k` shortcuts   |
+| `aria-label` / `aria-labelledby` | `string`                                                      | Accessible name                                              |
+| `aria-describedby`               | `string`                                                      | IDs of description / error elements                          |
+| `className`                      | `string`                                                      | Root element class                                           |
 
 ### DatePickerProps
 
@@ -227,7 +238,7 @@ See the calendar docs in-code: controlled/uncontrolled value, min/max, unavailab
 
 ### DateRangePickerProps
 
-The `DatePickerProps` surface (labeling, `isInvalid`, `min/maxValue`, `isDateUnavailable`, `granularity`, `firstDayOfWeek`, `timeZone`, `locale`, `autoFocus`, `isDisabled/ReadOnly/Required`), with the range-specific differences:
+The `DatePickerProps` surface (labeling, `isInvalid`, `min/maxValue`, `isDateUnavailable`, `granularity`, `hourCycle`, `firstDayOfWeek`, `timeZone`, `locale`, `showDayOfWeek`, `autoFocus`, `isDisabled/ReadOnly/Required`), with the range-specific differences:
 
 | Prop                     | Type                             | Description                                                                     |
 | ------------------------ | -------------------------------- | ------------------------------------------------------------------------------- |

package/skills/app-shell-patterns/references/components/filter-rail.md

@@ -0,0 +1,165 @@
+---
+title: FilterRail
+description: An always-visible faceted filter rail with user layout settings, driven by the same CollectionControl as DataTable
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/filter-rail.docs.outline.md — do not edit by hand. -->
+
+# FilterRail
+
+`FilterRail` shows every filterable axis beside the results instead of hiding it behind a filter dropdown. Each section shows its options up front, so users see what they can filter by without opening anything.
+
+It writes the same `CollectionControl` a `DataTable` reads, so there is no second filter engine: a checkbox section **is** the `in` operator, a radio section is `eq`, a range is `between`.
+
+```tsx
+import { FilterRail, type FilterRailSection } from "@tailor-platform/app-shell";
+
+const sections: FilterRailSection[] = [
+  {
+    id: "category",
+    label: "Category",
+    control: "checkbox",
+    field: "category",
+    options: categories,
+  },
+  { id: "status", label: "Status", control: "radio", field: "status", options: statuses },
+];
+
+<FilterRail.Root control={control} sections={sections}>
+  <FilterRail.Sections />
+</FilterRail.Root>;
+```
+
+## Sections and parts
+
+What the rail shows is **config**: `sections`, one entry per axis, in screen order. How the rail is assembled is **parts**: leave a part out and that feature is not rendered.
+
+| Part                  | Renders                                                                       |
+| --------------------- | ----------------------------------------------------------------------------- |
+| `FilterRail.Root`     | The rail. Takes `control`, `sections`, `layout`.                              |
+| `FilterRail.Header`   | A title row with a slot for actions.                                          |
+| `FilterRail.ClearAll` | Clears the rail's own filters only. Hidden while none are active.             |
+| `FilterRail.Settings` | Show / hide, reorder and sort sections. Needs `layout`.                       |
+| `FilterRail.Sections` | The sections, in the user's layout. Scrolls while the header stays put.       |
+| `FilterRail.Provider` | Holds the config when a `Trigger` sits outside the rail (see Narrow screens). |
+| `FilterRail.Trigger`  | The narrow-screen "Filters" button, placed anywhere inside `Provider`.        |
+
+```tsx
+<FilterRail.Root control={control} sections={sections} layout={layout}>
+  <FilterRail.Header>
+    <FilterRail.ClearAll />
+    <FilterRail.Settings />
+  </FilterRail.Header>
+  <FilterRail.Sections />
+</FilterRail.Root>
+```
+
+### Section types
+
+Every section has an `id`, a `label` and an optional `hint`. The operator is fixed per section — the user picks values, never operators.
+
+| `control`     | Commits                                    | Notes                                                       |
+| ------------- | ------------------------------------------ | ----------------------------------------------------------- |
+| `checkbox`    | `in` (or `nin`) with the ticked values     | `sort`, `truncate` (default 8), `pinned`, `searchThreshold` |
+| `radio`       | `eq` (or `ne`) with one value              | An "Any" row removes the filter; `anyLabel: null` hides it  |
+| `boolean`     | `eq` with `true` / `false`                 | Three states: Any, `trueLabel`, `falseLabel`                |
+| `text`        | `contains`, `hasPrefix` or `eq`            | Debounced (`debounceMs`, default 250)                       |
+| `numberRange` | `between` `{ min, max }`, or `gte` / `lte` | Commits on blur / Enter; one end alone is half-open         |
+| `date`        | `eq`, `gte` or `lte` a `YYYY-MM-DD`        | Uses `DatePicker`                                           |
+| `dateRange`   | `between` `{ min, max }`                   | Uses `DateRangePicker`; optional `presets`                  |
+| `custom`      | Whatever `render` writes                   | Declares the `fields` it owns so Clear all includes them    |
+
+A checkbox list long enough to be truncated also gets a search box, so a value can be found without scrolling (`searchThreshold` overrides when it appears).
+
+A field holds one filter, so two sections must not share a field; the rail warns in the console when they do.
+
+#### Typing fields
+
+Give `FilterRailSection` the row's keys so a `field` that is not on the table is a type error, the same way `createColumnHelper<Row>()` types columns. This works with a typed control or a plain one:
+
+```tsx
+const sections: FilterRailSection<keyof Product & string>[] = [
+  { id: "category", label: "Category", control: "checkbox", field: "category", options },
+  // field: "categroy" → type error
+];
+```
+
+With a typed control (from `useCollectionVariables({ tableMetadata })`), a section whose field the control does not have is also rejected.
+
+```tsx
+const stockLevel: FilterRailSection = {
+  id: "stockLevel",
+  label: "Stock level",
+  control: "custom",
+  fields: ["stock"],
+  render: ({ getFilter, setFilter }) => (
+    <Button
+      variant="outline"
+      size="xs"
+      onClick={() => setFilter("stock", { operator: "between", value: { min: 1, max: 20 } })}
+    >
+      Low stock
+    </Button>
+  ),
+};
+```
+
+The rail never hides state: a selected option is never truncated away, never disabled and never hidden by a section's search box.
+
+### Collapsing sections
+
+Each section collapses and expands from the chevron by its title. Sections start expanded; set `defaultCollapsed: true` to start one collapsed (for a rarely used axis). While a section is collapsed, its header still shows how many values are selected and keeps its **Clear**, so a collapsed section never hides an applied filter. The open / closed state is kept while the page is open, including across the narrow-screen sheet opening and closing.
+
+```tsx
+{ id: "warehouse", label: "Warehouse", control: "checkbox", field: "warehouse", options, defaultCollapsed: true }
+```
+
+## Choosing a control
+
+Checkbox and radio sections list every option, so they are only for **small, fixed sets** whose values you know up front — status, category, size, a handful of warehouses. Their `options` are a static array; the rail does not fetch them.
+
+Do **not** use a checkbox or radio list for a field whose values **keep growing** — product names, SKUs, customers, suppliers, order numbers. The list gets longer with every new record, takes over the rail, and becomes a scroll hunt. Give those fields a search instead:
+
+| The field's values are…                          | Use                                                                         |
+| ------------------------------------------------ | --------------------------------------------------------------------------- |
+| A small fixed set (≈ up to 20), pick any         | `checkbox`                                                                  |
+| A small fixed set, pick one                      | `radio` (or `boolean` for yes / no)                                         |
+| Open-ended and growing (names, codes, customers) | `text` — a search that commits `contains`, `hasPrefix` or `eq`              |
+| Open-ended, but users must pick exact records    | a `custom` section rendering a searchable picker (e.g. an async `Combobox`) |
+| Numbers or dates                                 | `numberRange`, `date`, `dateRange`                                          |
+
+In development the rail warns in the console when a checkbox or radio section lists more than 50 options, as a nudge towards a search.
+
+## User layout
+
+`useFilterRailLayout(storageKey)` persists the user's section order, hidden sections and option sort to localStorage. Pass it as `layout` and add `FilterRail.Settings`. Hiding a section that carries a filter also clears that filter. To share a layout across a team, pass your own `{ value, onChange, onReset }` binding instead.
+
+## Beside a DataTable
+
+The rail sits in its own `Layout.Column`, outside `DataTable.Root`, which is why `control` is a prop. Do not also render `DataTable.Filters` for the same fields — one fact in two places can drift.
+
+## Narrow screens
+
+Below the `lg` breakpoint there is no room for a side column, so the rail turns itself into a left sheet behind a **Filters** button carrying the active count — the same way the Sidebar handles small screens. Apps write no breakpoint code.
+
+By default the button appears where the rail would have been. To put it somewhere else — a table toolbar, a page header — wrap the page in `FilterRail.Provider`, move the config there, and place `FilterRail.Trigger` wherever you want it. The Trigger renders nothing on wide screens, and while one is mounted the rail skips its own button.
+
+```tsx
+<FilterRail.Provider control={control} sections={sections}>
+  <Layout fill>
+    <Layout.Column area="left">
+      <FilterRail.Root>
+        <FilterRail.Sections />
+      </FilterRail.Root>
+    </Layout.Column>
+    <Layout.Column area="main">
+      <DataTable.Root value={table}>
+        <DataTable.Toolbar>
+          <FilterRail.Trigger />
+        </DataTable.Toolbar>
+        <DataTable.Table />
+      </DataTable.Root>
+    </Layout.Column>
+  </Layout>
+</FilterRail.Provider>
+```

package/skills/app-shell-patterns/references/components/sidebar-group.md

@@ -124,13 +124,13 @@ Titles support i18n with `defineI18nLabels`:
 import { defineI18nLabels } from "@tailor-platform/app-shell";
 
 const labels = defineI18nLabels({
-  products: {
-    en: "Products",
-    ja: "商品",
+  en: {
+    products: "Products",
+    settings: "Settings",
   },
-  settings: {
-    en: "Settings",
-    ja: "設定",
+  ja: {
+    products: "商品",
+    settings: "設定",
   },
 });
 
@@ -381,6 +381,11 @@ The title styling is controlled by AppShell's theme. `SidebarGroup` takes no `cl
 - You want to organize a large navigation menu
 - Users need to focus on specific sections
 
+**Use [SidebarSection](./sidebar-section.md) when:**
+
+- You only need a heading above items that should always stay visible
+- The items should keep top-level styling instead of an indented submenu
+
 **Use SidebarItem directly when:**
 
 - You have standalone top-level navigation
@@ -453,6 +458,7 @@ Without `to`, only the chevron is clickable (for expand/collapse).
 ## Related Components
 
 - [SidebarItem](./sidebar-item.md) - Individual navigation items
+- [SidebarSection](./sidebar-section.md) - Static headings for flat items
 - [DefaultSidebar](./sidebar-layout.md) - Container for groups
 - [WithGuard](./with-guard.md) - Conditional rendering
 

package/skills/app-shell-patterns/references/components/sidebar-section.md

@@ -0,0 +1,114 @@
+---
+title: SidebarSection
+description: Static, non-collapsible heading for grouping flat sidebar navigation items
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/sidebar-section.docs.outline.md — do not edit by hand. -->
+
+# SidebarSection
+
+`SidebarSection` places a static heading above a run of flat navigation items. Unlike [`SidebarGroup`](./sidebar-group.md), a section is neither collapsible nor navigable, and its items keep the same styling and indentation as top-level items.
+
+## Import
+
+```tsx
+import { SidebarSection } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+```tsx
+import {
+  DefaultSidebar,
+  SidebarItem,
+  SidebarSection,
+  SidebarSeparator,
+} from "@tailor-platform/app-shell";
+
+<DefaultSidebar>
+  <SidebarItem to="/overview" />
+
+  <SidebarSeparator />
+
+  <SidebarSection title="Services">
+    <SidebarItem to="/ai-gateways" />
+    <SidebarItem to="/applications" />
+    <SidebarItem to="/auth-connections" />
+  </SidebarSection>
+
+  <SidebarSeparator />
+
+  <SidebarSection title="Logs">
+    <SidebarItem to="/activity-logs" />
+    <SidebarItem to="/dataplane-logs" />
+  </SidebarSection>
+</DefaultSidebar>;
+```
+
+## Props
+
+| Prop       | Type                        | Default      | Description                       |
+| ---------- | --------------------------- | ------------ | --------------------------------- |
+| `title`    | `string \| LocalizedString` | **Required** | Section heading (supports i18n)   |
+| `children` | `React.ReactNode`           | **Required** | Child items (usually SidebarItem) |
+
+## Behavior
+
+- **Not interactive.** The heading is plain text: it is not a link and has no expand/collapse toggle.
+- **Flat items.** Children render at the same level as top-level `SidebarItem`s, not as an indented submenu.
+- **Icon rail.** When the sidebar collapses to an icon rail, the heading is hidden and the items stay in the rail as ordinary icons. Unlike `SidebarGroup`, there is no hover flyout.
+- **No automatic dividers.** Add a `SidebarSeparator` between sections where you want a line.
+
+## Internationalization
+
+Titles support i18n with `defineI18nLabels`:
+
+```tsx
+import { defineI18nLabels } from "@tailor-platform/app-shell";
+
+const labels = defineI18nLabels({
+  en: { services: "Services" },
+  ja: { services: "サービス" },
+});
+
+<SidebarSection title={labels.t("services")}>
+  <SidebarItem to="/ai-gateways" />
+</SidebarSection>;
+```
+
+## When to Use
+
+**Use SidebarSection when:**
+
+- You want to label a run of items with a heading, but keep them always visible
+- The items are peers of your top-level items, not children of a parent page
+- You want the items to stay as individual icons in the icon rail
+
+**Use SidebarGroup when:**
+
+- Users should be able to collapse the items
+- The items belong under a parent with its own icon (or landing page via `to`)
+- You need nesting
+
+| Feature             | SidebarSection    | SidebarGroup              |
+| ------------------- | ----------------- | ------------------------- |
+| **Collapsible**     | ❌ No             | ✅ Yes                    |
+| **Heading is link** | ❌ No             | Optional (`to` prop)      |
+| **Icon**            | ❌ No             | Optional                  |
+| **Child styling**   | Same as top level | Indented submenu          |
+| **Icon rail**       | Heading hidden    | Group icon opens a flyout |
+| **Nesting**         | Not intended      | Can contain groups        |
+
+## Accessibility
+
+The children are rendered as their own list, labelled by the heading, so screen readers announce the section name (for example, "Services, list, 3 items") when entering it.
+
+## Related Components
+
+- [SidebarGroup](./sidebar-group.md) - Collapsible, nested navigation groups
+- [SidebarItem](./sidebar-item.md) - Individual navigation items
+- [DefaultSidebar](./default-sidebar.md) - Container for sidebar navigation
+
+## Related Concepts
+
+- [Sidebar Navigation](../concepts/sidebar-navigation.md) - Sidebar customization guide

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

@@ -0,0 +1,198 @@
+---
+title: Text
+description: Text with a typography role, rendered as an element you choose
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/text.docs.outline.md — do not edit by hand. -->
+
+# 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).
+
+## Import
+
+```tsx
+import { Text } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+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>
+    </div>
+  );
+}
+```
+
+## Props
+
+_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.                            |
+
+## Exports
+
+- `Text` — function
+- `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:
+
+```tsx
+<Text variant="label-md" render={<label htmlFor="quantity" />}>
+  Quantity
+</Text>
+```
+
+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`         | Default element | Use                                             |
+| ----------------- | --------------- | ----------------------------------------------- |
+| `heading-lg`      | `h2`            | Page title (`Layout.Header`)                    |
+| `heading-md`      | `h2`            | Section heading, card title                     |
+| `heading-sm`      | `h2`            | Sub-section heading                             |
+| `body-md`         | `p`             | Body copy, descriptions (default role)          |
+| `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-sm`        | `span`          | Small label, badge text                         |
+| `code-sm`         | `span`          | ID and code. `Text` adds `font-mono` for you    |
+
+<example-preview name="roles"></example-preview>
+
+```tsx
+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 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>
+      <Text variant="label-sm">label-sm: Draft</Text>
+      <Text variant="code-sm">code-sm: PO-2026-0001</Text>
+    </div>
+  );
+}
+```
+
+The sizes and line heights are in the [Typography section of the styling guide](../concepts/styling-theming.md#typography).
+
+## 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`:
+
+```tsx
+<Text variant="heading-md" render={<h3 />}>
+  Line items
+</Text>
+```
+
+To use a heading role for text that is not a heading, render a `div` or a `span`:
+
+```tsx
+<Text variant="heading-md" render={<div />}>
+  1,240 orders
+</Text>
+```
+
+## 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:
+
+```tsx
+// eslint-disable-next-line jsx-a11y/heading-has-content -- Text renders the children
+<Text variant="heading-md" render={<h3 />}>
+  Line items
+</Text>
+```
+
+## Color and Modifiers
+
+Set the color with a color token in `className`. Four modifiers may also be combined with a role: `leading-none` for single-line text, `tabular-nums`, `font-semibold` for emphasis, and `uppercase`.
+
+<example-preview name="color-and-modifiers"></example-preview>
+
+```tsx
+function ColorAndModifiers() {
+  return (
+    <div className="flex flex-col gap-3">
+      <Text variant="body-md" className="text-muted-foreground">
+        Orders sent this month.
+      </Text>
+      <Text variant="label-md" className="tabular-nums">
+        1,240.00
+      </Text>
+    </div>
+  );
+}
+```
+
+```tsx
+<Text variant="body-md" className="text-muted-foreground">
+  Orders sent this month.
+</Text>
+<Text variant="heading-md" render={<h3 />} className="leading-none">
+  Card title
+</Text>
+<Text variant="label-md" className="tabular-nums">
+  1,240.00
+</Text>
+```
+
+Do not combine a role with other `leading-*`, `tracking-*`, or `text-*` size values. Pick a different `variant` instead. A `text-*` size class such as `text-sm` has no effect on `Text`: AppShell's stylesheet loads after yours, so the role's size wins.
+
+## Using Roles Without Text
+
+Each role is also a plain utility, for example `text-heading-md`. Use the utility when you style your own element and do not need `Text`:
+
+```tsx
+<th className="text-label-md text-muted-foreground">Amount</th>
+```
+
+## TypeScript
+
+```typescript
+import { type TextProps } from "@tailor-platform/app-shell";
+```
+
+## 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.
+- 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.
+
+## Palettes
+
+The `cream` and `bloom` palettes set the line height and letter spacing of `h1` to `h6` elements. Under these palettes, a heading role on a heading element uses the palette values (line height 1.2, letter spacing `-0.03em`), including when you add `leading-none`. The same role on a `div` or `span` uses the role values. See the [Typography section of the styling guide](../concepts/styling-theming.md#typography).
+
+## Related Components
+
+- [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.

package/skills/app-shell-patterns/references/concepts/custom-components.md

@@ -44,7 +44,7 @@ export function StepIndicator({ steps, current }: Props) {
             flex items-center gap-2 rounded-md px-3 py-2
             bg-muted text-sm text-muted-foreground
             data-[active]:bg-primary data-[active]:text-primary-foreground
-            data-[completed]:text-status-completed
+            data-[completed]:text-success-text
           "
         >
           {i < current && <Check className="size-4" />}

package/skills/app-shell-patterns/references/concepts/file-based-routing.md

@@ -143,12 +143,18 @@ type AppShellPageProps = {
   meta?: {
     title?: LocalizedString;
     icon?: ReactNode;
-    breadcrumbTitle?: string | ((segment: string) => string);
+    breadcrumbTitle?: string | ((segment: string) => LocalizedString);
   };
   guards?: Guard[];
 };
 ```
 
+For a localized breadcrumb, use `meta: { breadcrumbTitle: labels.t("orders") }`, just like `meta.title`.
+AppShell recognizes translation functions created by `labels.t()` and resolves them with the current locale.
+For a dynamic label, use `breadcrumbTitle: (segment) => labels.t("order", { id: segment })`.
+Other callbacks receive the URL segment; AppShell resolves any returned `LocalizedString` with the current locale.
+The existing `() => labels.t("orders")` form remains supported. Wrap handwritten locale functions in an outer callback rather than passing them directly.
+
 ## Path Conventions
 
 | Directory Name | Converts To | Description                                    |