@starci/grammar 0.11.0 → 0.12.1

package/README.md

@@ -17,7 +17,7 @@ npm install @starci/grammar @heroui/react react react-dom
 npm install ./.claude/packages/grammar
 ```
 
-The package needs Node.js 20 or newer. Its peer dependencies are React 18+, `@xyflow/react` 12 (for `FlowGraph`) and `@heroui/react`
+The package needs Node.js 22 or newer. Its peer dependencies are React 18+, `@xyflow/react` 12 (for `FlowGraph`) and `@heroui/react`
 3.2+. Load the HeroUI stylesheet once in the app, as HeroUI's own setup describes. Then import
 exactly one Grammar family stylesheet. Each family sheet already imports Common anatomy first.
 
@@ -36,6 +36,18 @@ its root from one place. Heritage does not re-export Common. It exports `heritag
 
 ## Usage
 
+### App shell
+
+The [app-shell canon](../../knowledge/ui/composition/app-shell.yaml) owns `FE-APP-SHELL-1` through `FE-APP-SHELL-7`.
+The `Compositions/App shell` stories show the fixed shell, grouped sidebar, icon rail and mobile drawer.
+
+- `size="control"` is available on `Button`, `IconButton`, `TextAction`, `PlainPressable`, `IdentityLockup`, `Input` and `SearchField`, alongside `Switch`, `Avatar` and `AvatarButton`.
+- `SidebarItem.badge`, `badgeLabel` and `badgeMax` show and announce unread counts in both sidebar presentations. `SidebarGroup.placement="end"` places settings groups after the main groups and pushes them to the bottom.
+- The collapsed Sidebar uses Grammar's internal `AnchoredTooltip` on hover and focus. Its native popover reaches the top layer without leaving the family DOM scope or changing HeroUI's collection anatomy. `onAction` runs for every activated destination, including the selected item, so a drawer can close consistently.
+- A fixed `WorkspaceShell` frames its `compactHeader` slot as the mobile opener band; pass a client `Drawer` with an ellipsis `IconButton` trigger. The `navigationDrawer` form owns the same band when it supplies the opener.
+- `AvatarButton seed` passes the stable identity id to Grammar's shared `Avatar`, which draws the deterministic local DiceBear image; an uploaded `src` takes precedence.
+- `DropdownMenuItem.mark` accepts a decorative identity mark and is mutually exclusive with `iconSource`. A destructive item uses `tone="danger"`; the existing `negative` tone has the same vendor presentation.
+
 ### Common (neutral structure only)
 
 ```tsx
@@ -140,20 +152,77 @@ Each group below matches a Storybook group. Run `npm run storybook`: every story
 the family and theme chosen in the toolbar. It shows the default, disabled, invalid, pending and
 selected/current states where they apply. Overlay stories open by default.
 
-**Primitives (26).** Avatar, Badge, Button, CloseButton, Divider, GrammarRoot, Heading, Icon,
+**Primitives (27).** Avatar, Badge, Button, CloseButton, Divider, GrammarRoot, Heading, Icon,
 IconButton, IconTile, Image, IncludedMark, Kbd, Label, LeadingNumber, Link, Meter, PlainPressable,
-Progress, ProgressCircle, RankArtwork, Skeleton, Spinner, StateMark, Text, TextAction.
+Progress, ProgressCircle, RankArtwork, RelativeTime, Skeleton, Spinner, StateMark, Text, TextAction.
 
 **Forms (24).** ButtonGroup, Checkbox, CheckboxGroup, ComboBox, DateField, DatePicker,
 DateRangePicker, Field, Fieldset, FileDropzone, Form, Input, NumberField, OtpInput,
 PressableField, RadioGroup, Rating, SearchField, SegmentedControl, Select, Slider, Switch,
 Textarea, TimeField. Every Field-contract control takes `label`, `description`, `errorMessage`,
 `isRequired`, `isDisabled`, `isReadOnly` and `isInvalid`. `Select`, `ComboBox`, `SearchField` and
-`Form` also take `isPending`. `OtpInput` has no label prop, so name it with a `<label for>`.
+`Form` also take `isPending`. `OtpInput` names the code with `label` or an existing label's `labelledBy`.
 
 **Overlays (9).** Alert, AlertDialog, Dialog, Drawer, DropdownMenu, Popover, Toast, Toaster,
-Tooltip. Dialog, AlertDialog, Drawer, Popover and DropdownMenu are controlled through
-`isOpen`, `defaultOpen` and `onOpenChange`.
+Tooltip. Dialog, AlertDialog, Drawer, Popover and DropdownMenu support uncontrolled `defaultOpen`
+and controlled `isOpen` / `onOpenChange` through the shared overlay contract.
+
+`DropdownMenuItem` accepts either `iconSource` or `mark`, a `ReactNode` such as a logo; its public
+type rejects both together. Grammar renders either in the same decorative leading slot, with the
+same alignment and icon-size rule. Keep the visible item label as its accessible name and supply
+the mark without visual slot CSS.
+
+`RelativeTime` renders `<time dateTime>` for live relative copy such as "5 minutes ago" and a
+countdown such as "in 5 minutes". Pass `dateTime` as a timezone-qualified ISO string and `locale`
+as the active BCP 47 locale. `mode="relative"` is the default; `mode="countdown"` reduces the time
+remaining and settles at the locale's "now" when the target expires. `size` (`xs`, `sm`, `md`) and
+`tone` (`default`, `muted`, `accent`) use Common's text presentation.
+
+```tsx
+<RelativeTime dateTime="2026-10-25T09:00:00Z" locale="en" />
+<RelativeTime dateTime="2026-10-25T10:00:00+01:00" locale="en" mode="countdown" />
+```
+
+The server and initial hydration render show `fallback`, or the canonical ISO instant when it is
+omitted. After hydration, every instance reads the same shared ticker. The first subscriber starts
+it and the last unsubscribe stops it; leaves own no clock or refresh interval. Supply translated
+`fallback` copy when an ISO instant is unsuitable. Time changes are not a live announcement, so a
+page of timestamps does not repeatedly interrupt assistive technology. Grammar owns native
+`Intl.RelativeTimeFormat` for this primitive; other application date display follows FE-DATE.
+
+**DropdownMenu entries.** `entries` is a list of items and sections; the app writes data and no markup, no separator, no
+className and no size. An item takes `id`, `label`, `description`, `shortcut`, `href`, `isDisabled`, `submenu` and:
+
+- `iconSource`: a glyph component (the app's Heroicons). Grammar draws it in HeroUI's leading position at the canon icon size,
+  20px (`size-5`, `Icon` `leading`; the Heroicons rule R93 / FE-ICON). HeroUI's own docs example draws its sample glyph at
+  `size-4`, which is example content and not a component default, so 20px is StarCi's icon rule and not a vendor override.
+- `mark`: a decorative node instead of `iconSource`, e.g. an identity mark (`<Avatar size="sm" shape="rounded" isDecorative />`). The public type rejects both props together.
+- `tone: "danger"`: HeroUI's `danger` variant, which colours the label and the glyph. Sign out, delete, remove, leave workspace
+  and revoke are destructive; the lint rule `starci-fe/destructive-menu-entry-needs-danger-tone` refuses such an entry without it.
+
+A section takes `label` and optionally `selection` (`mode: "single" | "multiple"`, `selectedIds`, `onChange`). Between two
+adjacent entries, when either is a section, Grammar always inserts HeroUI's own `Separator`: the app cannot forget one. The selection
+mark is HeroUI's `Dropdown.ItemIndicator` in its default placement (the check sits at the start of the item, and at the end only for
+an item with a submenu).
+
+```tsx
+<DropdownMenu
+  trigger={<AvatarButton name="Alex Morgan" />}
+  placement="bottom end"
+  entries={[
+    { kind: "section", id: "workspace", label: "Workspace", selection: { mode: "single", selectedIds, onChange },
+      items: [{ id: "hakuen", label: "Hakuen", description: "Owner", mark: <Avatar name="Hakuen" size="sm" shape="rounded" isDecorative /> }] },
+    { kind: "section", id: "account", items: [{ id: "profile", label: "Profile", description: "Name and photo", iconSource: UserIcon }] },
+    { kind: "section", id: "session", items: [{ id: "sign-out", label: "Sign out", tone: "danger", iconSource: ArrowRightStartOnRectangleIcon }] },
+  ]}
+/>
+```
+
+**HeroUI parity.** Grammar is a wrapper of HeroUI, so a wrapper keeps HeroUI's anatomy and defaults. The vendor reference
+(`knowledge/vendor/heroui/<component>.yaml` in the StarCi runtime) is measured from the installed `@heroui/react` and
+`@heroui/styles`; the gate `GRAMMAR_VENDOR_PARITY` fails a wrapper that renders a part HeroUI does not have, omits one it
+requires, restyles what the vendor decides, or replaces a vendor default, unless an owner-pinned override declares it. `ListBox`
+and `Select` are HeroUI's own list-box items (a `Label`, a `Description`, the item indicator at the end of the row).
 
 **Navigation & Data (14).** Accordion, AvatarGroup, Breadcrumbs, Calendar, DataTable,
 DescriptionList, Disclosure, ListBox, Pagination, Stepper, Subnav, Tabs, TagGroup, Timeline.
@@ -192,27 +261,89 @@ defines the native loading and caption behaviour (reviewed 2026-10-18).
 `thumbIcon` / `selectedThumbIcon` for a glyph inside the thumb, so a sun/moon theme switch is
 `<Switch size="lg" label="Dark mode" thumbIcon={Sun} selectedThumbIcon={Moon} />`.
 
+`Switch size="control"` and `Avatar` / `AvatarButton size="control"` share the control height (2.75rem, the
+IconButton of a bar), so a language button, a theme switch, a bell and an avatar line up at one height; `Switch
+isLabelHidden` keeps its label as the accessible name and draws nothing. `WorkspaceShell viewport="fixed"` is one
+viewport tall (`100dvh`) with the header on top and the navigation and primary regions scrolling on their own, so an
+app writes no viewport arithmetic; `navigationDrawer` adds the compact-width opener row (the bar's height, an
+edge-to-edge divider, a round tertiary icon button) and its left Sidebar drawer. Pass `defaultOpen`
+to let the Drawer own its state; no state hook or callback is needed in the layout. The shell
+reuses the shared overlay contract, so optional `isOpen` / `onOpenChange` remain available for
+coordinated client interactions. The opener is the Drawer's own trigger, which owns activation,
+dismissal and focus return.
+
 `PlainPressable` is a pressable that does not look like a button: no padding, background, border or
 shape in any state, no hover effect, a zoom-out on press, a focus ring, and no zoom under
 `prefers-reduced-motion`. `AvatarButton` is a circle-only avatar built on it (an account-menu
 trigger) and `IdentityLockup` a mark beside a title and a muted subtitle with no caret (a workspace
-switcher trigger). All three work as the `trigger` of `DropdownMenu` and `Popover`. `IdentityLockup`'s mark is a transparent, uncropped square by default (`markShape="rounded"` opts in to a
+switcher trigger). All three work as the `trigger` of `DropdownMenu` and `Popover`. `IdentityLockup`'s mark and monogram fallback are transparent, with foreground-colored initials; the mark is an uncropped square by default (`markShape="rounded"` opts in to a
 corner) and `Avatar` takes `shape="square" | "rounded"`.
 
+Personal avatars are circles. Pass the user or identity id as `seed` on `Avatar`, `AvatarButton`
+or each `AvatarGroup` member. Grammar renders the fixed Lorelei DiceBear style chosen by its DNA,
+memoized for that seed with identical server and client output. An uploaded `src` wins; with
+neither `src` nor `seed`, the existing initials fallback remains. Images have `alt=""`; the avatar
+shell carries its name, or `isDecorative` hides it beside a visible name. `AvatarButton` names the
+button and keeps its inner avatar decorative. Apps install and import Grammar; its pinned
+DiceBear runtime dependencies and avatar drawing stay inside the package.
+The package requires Node 22 or newer, as does the pinned DiceBear engine.
+
+```tsx
+<Avatar name={user.name} seed={user.id} isDecorative />
+<AvatarButton name={user.name} seed={user.id} src={user.avatarUrl} />
+<AvatarGroup label="Team" items={members.map(user => ({ id: user.id, name: user.name, seed: user.id }))}
+  overflowLabel={count => `${count} more members`} />
+```
+
 **Surfaces (14).** EmptyNotice, FencedCodeBlock, HorizontalScrollRegion, MarkdownArticle,
 MarkdownTableFrame, MediaFrame, Rail, SectionHeader, StaticStateRow, SurfaceAccordionCard,
 SurfaceCard, SurfaceCopyGroup, SurfaceListCard, VerticalScrollRegion.
 
 **Compositions (9).** BottomNav, ChatWorkspace, Footer, NavigationFeatureNav, PageContainer,
-PrimaryRailLayout, Sidebar, TopBar, WorkspaceShell. Storybook also pins three page recipes to
-each family: a settings form, a data list with a filter drawer and pagination, and a mobile home
-with TopBar, BottomNav and a Toast.
+PrimaryRailLayout, Sidebar, TopBar, WorkspaceShell. Storybook pins settings and data-list content
+recipes to each family; the mobile app recipes reuse the fixed App shell with its left navigation drawer.
 
 `COMMON_GRAMMAR_COMPONENTS` is the frozen registry of the published renderers.
 `COMMON_FORMS_COMPONENTS`, `COMMON_OVERLAYS_COMPONENTS` and `COMMON_NAVIGATION_COMPONENTS` are the
 0.5.0 groups. `defineGrammarFamily` builds a new family over the registry. It may replace
 renderers with prop-compatible versions and add extensions whose names don't collide with Common's.
 
+### Surface controls, panel lists and group identity
+
+SurfaceCard (including `frame="frameless"`), SurfaceListCard, SurfaceAccordionCard, Rail, Sidebar
+and the content of Drawer, Dialog, AlertDialog and Popover supply the nesting context of ANATOMY-2.
+Omit a field's `variant`: Input, SearchField, Textarea, NumberField, DateField, TimeField, Select,
+ComboBox, DatePicker, DateRangePicker, Checkbox, CheckboxGroup, RadioGroup, PressableField and OtpInput use `secondary`
+inside these surfaces and `primary` outside. Overlay triggers keep their surrounding context.
+The FE canon's `FE_NESTED_VARIANT` rejects an explicit primary field inside a surface and raw
+`bg-surface` paint in application classNames.
+
+ListBox defaults to `inset="panel"` inside the same context. The list container extends into the
+panel gutter so row content, loading content and section captions align with the header and search
+field without padding wrappers (PADDING-0). Items keep HeroUI's default padding and selection-indicator
+space; row backgrounds extend into the gutter. Outside a surface, the vendor list inset stays;
+`inset="panel"` also selects the alignment explicitly. Pass flat `items` or named `sections`
+(`ListBoxSection`), with unique item ids across the whole list. `FE_LIST_PANEL_PADDING` rejects
+horizontal padding wrappers around a list or its section caption. Sidebar's expanded and collapsed
+rows also retain HeroUI item padding.
+
+```tsx
+<SurfaceCard ariaLabel="Conversations">
+  <Heading level={2}>Conversations</Heading>
+  <SearchField label="Find a conversation" />
+  <ListBox label="Conversations" sections={[
+    { id: "recent", label: "Recent", items: [{ id: "team", label: "Design team" }] },
+  ]} />
+</SurfaceCard>
+```
+
+For a conversation or group identity, use `AvatarGroup layout="grid"` (COLLECTION-3, the Zalo
+reference). It is one round Avatar-sized mark at `sm`, `md`, `lg` or `control`: two members split
+the circle, three show one above two, and four use a 2 by 2 grid with a hairline gap. With more
+members, the fourth cell shows `+N` for everyone beyond the first three. Each member uses Avatar's
+uploaded image, `seed` and initials fallback, and accepts the same custom `fallback`. A single
+person uses Avatar. The default `layout="row"` keeps the overlapping member row.
+
 ## Theming
 
 - **Tokens.** Each family writes its DNA as CSS custom properties on its root: `--starci-core-*`,
@@ -224,8 +355,8 @@ renderers with prop-compatible versions and add extensions whose names don't col
   `--starci-core-surface-tertiary`; HeroUI's `--surface-tertiary` is left to Common and is never
   re-bound by the family. To adjust a family, override its tokens on the
   root, for example `<CoreGrammarRoot style={{ "--starci-core-accent": "#2f6bff" }}>`. The
-  `*_TOKEN_NAMES` / `*_TOKEN_DEFAULTS` exports are the supported list. Values are validated by the
-  family specs, not at runtime.
+  `*_TOKEN_NAMES` / `*_TOKEN_DEFAULTS` exports are the supported list. The DNA generator measures
+  their packaged values; callers own their token overrides.
 - **Spacing.** Every family uses the Common 4px scale (`COMMON_SPACING_SCALE`,
   `COMMON_SPACING_TOKENS`), and Common's `--grammar-*-gap` / `--grammar-page-inset` variables.
 - **Dark.** `theme` on any root takes `"light"`, `"dark"` or `"system"` (the default), which sets

package/dist/.build-stamp.json

@@ -1,9 +1,9 @@
 {
   "schema": "starci/grammar-build-stamp@1",
   "package": "@starci/grammar",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "algorithm": "starci/grammar-source-digest@1",
-  "sourceDigest": "sha256:9cb2cc563d7e0a1acdcc56a70dbc7c9944be34777c34cb8c6fcb1b5a247aba66",
-  "distDigest": "sha256:5a334f07de9b640740b93c311007b8bdcaec035154a457f2cd3721e4386ed919",
-  "builtAt": "2026-10-25T07:24:32.396Z"
+  "sourceDigest": "sha256:f6fce286c3f714d14372fa19725d4d9b92b8ed98d49342f022224250b09a1e14",
+  "distDigest": "sha256:53e4a14158e106244c9d13a98bdde5ad226f689c070e7170ecd71d58bb7a0120",
+  "builtAt": "2026-10-25T12:13:44.249Z"
 }

package/dist/common/components-avatar-group.css

@@ -0,0 +1,65 @@
+@layer starci-grammar-common {
+    /* The vendor Avatar shell supplies the exact single-avatar dimensions, including the control size. */
+    .starci-core-avatar-group[data-grammar-avatar-layout="grid"] {
+        --starci-avatar-group-text-size: calc(var(--avatar-size, 2.5rem) / 4);
+        overflow: hidden;
+        border-radius: 50%;
+    }
+
+    .starci-core-avatar-group-grid {
+        display: grid;
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+        grid-template-rows: repeat(2, minmax(0, 1fr));
+        gap: 1px;
+        inline-size: 100%;
+        block-size: 100%;
+        background: var(--surface, Canvas);
+    }
+
+    .starci-core-avatar-group[data-grammar-avatar-cells="1"] > .starci-core-avatar-group-grid {
+        grid-template-columns: minmax(0, 1fr);
+        grid-template-rows: minmax(0, 1fr);
+    }
+
+    .starci-core-avatar-group[data-grammar-avatar-cells="2"] > .starci-core-avatar-group-grid {
+        grid-template-rows: minmax(0, 1fr);
+    }
+
+    /* Zalo's three-member identity has one full-width member above the two remaining members. */
+    .starci-core-avatar-group[data-grammar-avatar-cells="3"] .starci-core-avatar-group-member:first-child {
+        grid-column: 1 / -1;
+    }
+
+    .starci-core-avatar-group-grid > .starci-core-avatar-group-member {
+        inline-size: 100% !important;
+        block-size: 100% !important;
+        min-inline-size: 0;
+        min-block-size: 0;
+        border-radius: 0 !important;
+        font-size: inherit;
+    }
+
+    .starci-core-avatar-group-member > * {
+        border-radius: 0 !important;
+    }
+
+    .starci-core-avatar-group:not([data-grammar-avatar-cells="1"]) .starci-core-avatar-group-member [data-grammar-avatar-fallback] {
+        font-size: var(--starci-avatar-group-text-size) !important;
+    }
+
+    .starci-core-avatar-group-member img {
+        object-fit: cover;
+    }
+
+    .starci-core-avatar-group-count {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        min-inline-size: 0;
+        background: var(--surface-secondary, Canvas);
+        color: var(--foreground, CanvasText);
+        font-size: var(--starci-avatar-group-text-size);
+        font-weight: 600;
+        line-height: 1;
+    }
+}

package/dist/common/components-forms.css

@@ -145,7 +145,10 @@
         border-radius: var(--field-radius, calc(var(--radius, 0.5rem) * 1.5));
     }
 
-    .starci-core-field-skeleton-control:is([data-grammar-field-skeleton="select"], [data-grammar-field-skeleton="input"]) { block-size: 2.5rem; }
+    .starci-core-field-skeleton-control:is([data-grammar-field-skeleton="input"]) { block-size: 2.5rem; }
+
+    /* The select trigger is HeroUI's own (min-h-9). */
+    .starci-core-field-skeleton-control[data-grammar-field-skeleton="select"] { block-size: 2.25rem; }
 
     /* Joined segments: one block, a segment-width (5rem) per option, never wider than the field; `fill` takes the whole row. */
     .starci-core-field-skeleton-control[data-grammar-field-skeleton="segmented"] {
@@ -161,6 +164,7 @@
     .starci-core-field-skeleton-control[data-grammar-field-skeleton="switch"] { flex: none; block-size: 1.25rem; inline-size: 2rem; }
     .starci-core-field-skeleton-control[data-grammar-field-skeleton="switch"] > .starci-core-skeleton { border-radius: 999px; }
     .starci-core-field-skeleton-control[data-grammar-field-skeleton="switch"][data-grammar-switch-size="lg"] { block-size: 2.25rem; inline-size: 4rem; }
+    .starci-core-field-skeleton-control[data-grammar-field-skeleton="switch"][data-grammar-switch-size="control"] { block-size: var(--starci-core-control-min-size, 2.75rem); inline-size: 4.875rem; }
 
     .starci-core-field-skeleton-choice-label {
         color: var(--foreground, CanvasText);
@@ -178,7 +182,6 @@
         }
     }
 
-    .starci-core-select-trigger,
     .starci-core-combo-box-group,
     .starci-core-search-field-group,
     .starci-core-number-field-group,
@@ -187,7 +190,6 @@
         min-width: 0;
     }
 
-    .starci-core-select-value,
     .starci-core-combo-box-input,
     .starci-core-search-field-input,
     .starci-core-number-field-input {
@@ -203,7 +205,6 @@
      * inside inherits the corner (no square right side behind the trigger) and stretches to the group's height.
      */
     .starci-core-input-field,
-    .starci-core-select-trigger,
     .starci-core-combo-box-group,
     .starci-core-search-field-group,
     .starci-core-number-field-group,
@@ -236,11 +237,6 @@
         }
     }
 
-    .starci-core-select-trigger {
-        align-items: center;
-        padding-inline: 0.75rem 1.75rem;
-    }
-
     .starci-core-combo-box-group {
         align-items: stretch;
     }
@@ -258,40 +254,6 @@
         padding-inline-end: 0.5rem;
     }
 
-    /*
-     * The selected value of a Select stays ONE line and keeps the field height: it ellipsizes (the trigger carries the
-     * full text as its title) and shows only the option's label, never its description. Popover options still wrap.
-     */
-    .starci-core-select-value {
-        flex: 1 1 0;
-        overflow: hidden;
-        overflow-wrap: normal;
-        text-overflow: ellipsis;
-        white-space: nowrap;
-    }
-
-    .starci-core-select-value-text {
-        display: block;
-        min-width: 0;
-        overflow: hidden;
-        text-overflow: ellipsis;
-    }
-
-    .starci-core-select-value .starci-core-list-option-copy {
-        display: block;
-        overflow: hidden;
-        text-overflow: ellipsis;
-    }
-
-    .starci-core-select-value .starci-core-list-option-label {
-        overflow-wrap: normal;
-    }
-
-    .starci-core-select-value .starci-core-list-option-description,
-    .starci-core-select-value [data-slot="list-box-item-indicator"] {
-        display: none;
-    }
-
     .starci-core-date-input {
         min-width: 0;
         flex: 1;
@@ -303,22 +265,14 @@
         color: var(--muted, GrayText);
     }
 
-    /* --- List popover (Select, ComboBox) --- */
-    .starci-core-list-option-copy {
+    /* --- List popover (Select, ComboBox) ---
+     * An option is HeroUI's own: a `Label`, with a `Description` under it inside one column when it has one, then the
+     * item indicator. The column is the only Grammar element; it lays out and paints nothing. */
+    [data-grammar-option-copy] {
         display: flex;
         min-width: 0;
         flex: 1;
         flex-direction: column;
-        gap: 0.25rem;
-    }
-
-    .starci-core-list-option-label {
-        overflow-wrap: anywhere;
-    }
-
-    .starci-core-list-option-description {
-        color: var(--muted, GrayText);
-        font-size: 0.75rem;
     }
 
     .starci-core-list-empty {
@@ -356,44 +310,75 @@
     }
 
     /*
-     * --- Switch size "lg": the StarCi look ---
-     * A 4rem by 2.25rem fully round track, a 1.75rem round thumb inset 0.25rem, an optional glyph centred in the thumb.
-     * Keyed on the stamps the component emits (`data-grammar-switch-size`, `data-grammar-switch-thumb`, `data-grammar-switch-icon`),
-     * never on vendor class names. The geometry is `!important` because consumers import this sheet on either side of
-     * `@heroui/styles`, so layer rank cannot decide against the vendor `.switch--*` size rules. The on position is a margin
-     * (as HeroUI's own thumb), the percentage resolving against the track: 100% - thumb - inset.
+     * --- Switch sizes "lg" (the StarCi look) and "control" ---
+     * `lg`: a 4rem by 2.25rem fully round track, a thumb the track height less 0.5rem inset 0.25rem, an optional glyph centred in the
+     * thumb. `control`: the same shape at the shared control height (2.75rem), so a theme switch lines up with the IconButtons and the
+     * avatar of a bar. Keyed on the stamps the component emits (`data-grammar-switch-size`, `data-grammar-switch-thumb`,
+     * `data-grammar-switch-icon`), never on vendor class names. The geometry is `!important` because consumers import this sheet on
+     * either side of `@heroui/styles`, so layer rank cannot decide against the vendor `.switch--*` size rules. The on position is a
+     * margin (as HeroUI's own thumb), the percentage resolving against the track: 100% - thumb - inset.
      */
-    [data-component="Switch"][data-grammar-switch-size="lg"] [data-grammar-choice-control="switch"] {
-        block-size: 2.25rem !important;
-        inline-size: 4rem !important;
+    [data-component="Switch"][data-grammar-switch-size="lg"] {
+        --grammar-switch-height: 2.25rem;
+        --grammar-switch-width: 4rem;
+    }
+
+    [data-component="Switch"][data-grammar-switch-size="control"] {
+        --grammar-switch-height: var(--starci-core-control-min-size, 2.75rem);
+        --grammar-switch-width: 4.875rem;
+    }
+
+    [data-component="Switch"]:is([data-grammar-switch-size="lg"], [data-grammar-switch-size="control"]) {
+        --grammar-switch-thumb: calc(var(--grammar-switch-height) - 0.5rem);
+    }
+
+    [data-component="Switch"]:is([data-grammar-switch-size="lg"], [data-grammar-switch-size="control"]) [data-grammar-choice-control="switch"] {
+        block-size: var(--grammar-switch-height) !important;
+        inline-size: var(--grammar-switch-width) !important;
         border-radius: 9999px !important;
     }
 
-    [data-component="Switch"][data-grammar-switch-size="lg"] [data-grammar-switch-thumb] {
-        block-size: 1.75rem !important;
-        inline-size: 1.75rem !important;
+    [data-component="Switch"]:is([data-grammar-switch-size="lg"], [data-grammar-switch-size="control"]) [data-grammar-switch-thumb] {
+        block-size: var(--grammar-switch-thumb) !important;
+        inline-size: var(--grammar-switch-thumb) !important;
         border-radius: 9999px !important;
         margin-inline-start: 0.25rem !important;
         align-items: center;
         justify-content: center;
     }
 
-    [data-component="Switch"][data-grammar-switch-size="lg"]:is([data-selected="true"], [aria-checked="true"]) [data-grammar-switch-thumb] {
-        margin-inline-start: calc(100% - 1.75rem - 0.25rem) !important;
+    [data-component="Switch"]:is([data-grammar-switch-size="lg"], [data-grammar-switch-size="control"]):is([data-selected="true"], [aria-checked="true"]) [data-grammar-switch-thumb] {
+        margin-inline-start: calc(100% - var(--grammar-switch-thumb) - 0.25rem) !important;
     }
 
     /* The description and error align under the label, past the wider track. */
-    [data-component="Switch"][data-grammar-switch-size="lg"] > [data-slot="description"],
-    [data-component="Switch"][data-grammar-switch-size="lg"] > [data-slot="field-error"] {
-        padding-inline-start: calc(4rem + 0.75rem);
+    [data-component="Switch"]:is([data-grammar-switch-size="lg"], [data-grammar-switch-size="control"]) > :is([data-slot="description"], [data-slot="field-error"]) {
+        padding-inline-start: calc(var(--grammar-switch-width) + 0.75rem);
     }
 
+    /*
+     * The thumb glyph box is the canon icon size, not whatever the vendor's thumb container leaves: 20px (size-5, `Icon` `leading`) on `lg`
+     * and `control`, 16px (`chip`) on `md`, whose thumb is 1rem tall. The glyph fills its box, centred in the thumb.
+     */
     .starci-core-switch-icon {
         display: inline-flex;
+        flex: none;
+        inline-size: 1.25rem;
+        block-size: 1.25rem;
         align-items: center;
         justify-content: center;
     }
 
+    [data-component="Switch"][data-grammar-switch-size="md"] .starci-core-switch-icon {
+        inline-size: 1rem;
+        block-size: 1rem;
+    }
+
+    .starci-core-switch-icon > .starci-core-icon {
+        inline-size: 100%;
+        block-size: 100%;
+    }
+
     /* A swapping pair shows the glyph of the current state only; a single glyph always shows. */
     [data-component="Switch"][data-grammar-switch-icons="swap"] [data-grammar-switch-icon="on"] { display: none; }
     [data-component="Switch"][data-grammar-switch-icons="swap"]:is([data-selected="true"], [aria-checked="true"]) [data-grammar-switch-icon="on"] { display: inline-flex; }
@@ -575,7 +560,7 @@
     }
 
     /* --- Read-only reads as settled, not as unavailable --- */
-    [data-grammar-field="true"][data-grammar-readonly="true"] :where(.starci-core-select-trigger, .starci-core-combo-box-group, .starci-core-search-field-group, .starci-core-number-field-group, .starci-core-date-group, .starci-core-textarea-control) {
+    [data-grammar-field="true"][data-grammar-readonly="true"] :where(.starci-core-combo-box-group, .starci-core-search-field-group, .starci-core-number-field-group, .starci-core-date-group, .starci-core-textarea-control) {
         background: var(--surface-secondary, var(--field-background, Canvas));
     }
 

package/dist/common/components-list-panel.css

@@ -0,0 +1,13 @@
+/* PADDING-0: align panel content through the container, retaining HeroUI item and header padding. */
+@layer starci-grammar-common {
+    .grammar-common-root .starci-core-list-box[data-grammar-list-inset="panel"] {
+        /* Row backgrounds extend into the gutter; vendor padding returns their content to the panel edge. */
+        inline-size: calc(100% + 1rem);
+        margin-inline: -0.5rem;
+        padding-inline: 0 !important;
+    }
+
+    .grammar-common-root .starci-core-list-box[data-grammar-list-inset="panel"] .starci-core-list-box-empty {
+        padding-inline: 0.5rem;
+    }
+}