@teamblind-chorus/ui 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,896 @@
+// AUTO-GENERATED by packages/ui/scripts/build-types.mjs.
+// Source of truth: schema/components/<family>/<sub>.spec.json.
+// Do not edit by hand — re-run the script after spec changes.
+
+import * as React from "react";
+
+// ── Badge (multi-sub: update, role) ──
+interface BadgeUpdatePropsOwn {
+  variant?: "update";
+  /** Four rungs split across the two types. **Numeric** — `medium` / `small` carry the count label. **Dot** — `dot-md` (8×8) / `dot-sm` (6×6) drop the label entirely and paint the labelless update dot. The dot rungs ignore `count` and `children`. */
+  size?: "medium" | "small" | "dot-md" | "dot-sm";
+  /** Numeric type only. If provided, the badge formats the value: 1–99 render as the literal number, 100+ renders as `99+`. Pass children instead for non-numeric content (e.g. `NEW`). Ignored on the Dot rungs. */
+  count?: number;
+  /** Numeric type only — custom label, overrides count formatting. Ignored on the Dot rungs. */
+  children?: React.ReactNode;
+}
+export interface BadgeUpdateProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, keyof BadgeUpdatePropsOwn>, BadgeUpdatePropsOwn {}
+
+interface BadgeRolePropsOwn {
+  variant: "role";
+  /** `default` — tonal primaryContainer pair for ordinary role marks (Channel owner, Verified). `inverse` — high-contrast inverseSurface pair, reserved for the paid-expert PRO mark. */
+  appearance?: "default" | "inverse";
+  /** Required role / title label — short, single line, English display (Channel owner, Verified, Moderator). */
+  children: React.ReactNode;
+}
+export interface BadgeRoleProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, keyof BadgeRolePropsOwn>, BadgeRolePropsOwn {}
+
+export type BadgeProps =
+  | BadgeUpdateProps
+  | BadgeRoleProps;
+
+// ── Banner (banner/banner) ──
+interface BannerPropsOwn {
+  appearance?: "default" | "accent" | "destructive";
+  /** A 16 × 16 (`sys.icon.md`) glyph at the container's leading edge. Inherits the banner's foreground (`currentColor`) so the mark reads as part of the body copy. The slot occupies the body.sm line-box height so the glyph centers on the **first line** of the body — multi-line bodies keep the icon anchored to the first-line cap, not the block center. Ignored when `thumbnail` is also passed. */
+  icon?: React.ReactNode;
+  /** A leading visual rendered by [Thumbnail](../thumbnail/thumbnail.md) — used when the aside is anchored to a channel, author, or sub-brand image rather than to a glyph. Takes precedence over `icon`. */
+  thumbnail?: React.ReactNode;
+  /** { label, href? , onClick? } — a follow-through link rendered as a block child below the body. */
+  action?: Record<string, unknown>;
+  /** Body text — the explanation copy. */
+  children: React.ReactNode;
+}
+export interface BannerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof BannerPropsOwn>, BannerPropsOwn {}
+
+// ── BottomSheet (bottom-sheet/bottom-sheet) ──
+interface BottomSheetPropsOwn {
+  open: boolean;
+  onClose: (...args: any[]) => any;
+  title?: React.ReactNode;
+  body?: React.ReactNode;
+  /** { label, onClick } — delegates to Button appearance='primary', size='large', fullWidth. */
+  primaryAction?: Record<string, unknown>;
+  /** { label, onClick } — delegates to Button appearance='secondary', size='large', fullWidth. */
+  secondaryAction?: Record<string, unknown>;
+  /** When supplied, the sheet is a nested step inside its host flow — a back chevron (Icon Button → ChevronLeftIcon, sys.icon.lg, sys.layout.inline.md gap to the title) is rendered at the title's leading edge and invokes onBack on click. Consumer owns step state; the component only paints the chevron. */
+  onBack?: (...args: any[]) => any;
+  /** Accessible name on the back Icon Button. Only consulted when onBack is set. */
+  backLabel?: string;
+  children?: React.ReactNode;
+  /** When true, scopes the scrim and card to the nearest positioned ancestor instead of portaling to document.body. */
+  inline?: boolean;
+}
+export interface BottomSheetProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof BottomSheetPropsOwn>, BottomSheetPropsOwn {}
+
+// ── Bubble (bubble/bubble) ──
+interface BubblePropsOwn {
+  /** Bubble copy. Single line by default — overflow truncates with an ellipsis. */
+  children: React.ReactNode;
+  /** Which edge of the bubble grows a tail. `top` (default) places the tail on the bubble's top edge, pointing UP toward an anchor that sits above the bubble. `bottom` mirrors for anchors below the bubble. */
+  tailSide?: "top" | "bottom";
+  /** Where along the tail edge the tail sits. `center` (default) parks it dead-centre; `start` and `end` shift it toward the leading / trailing corner so the tail lines up with an off-centre anchor. */
+  tailAlign?: "start" | "center" | "end";
+  /** Composes with the bubble's own class. Operations colour overrides should land on inline style as `--bubble-fill` / `--bubble-ink` rather than re-skinning via className. */
+  className?: string;
+  /** Standard inline style. The two custom properties consumers most often set here are `--bubble-fill` (background tone) and `--bubble-ink` (label tone) for runtime tinting. */
+  style?: Record<string, unknown>;
+}
+export interface BubbleProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof BubblePropsOwn>, BubblePropsOwn {}
+
+// ── Button (multi-sub: standard, icon, text, check, toggle, toolbar) ──
+interface ButtonStandardPropsOwn {
+  appearance?: "primary" | "secondary" | "outlined" | "tertiary";
+  size?: "large" | "medium" | "small";
+  leadingIcon?: React.ReactNode;
+  fullWidth?: boolean;
+  truncate?: boolean;
+  disabled?: boolean;
+}
+export interface ButtonStandardProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof ButtonStandardPropsOwn>, ButtonStandardPropsOwn {}
+
+interface ButtonIconPropsOwn {
+  variant: "icon";
+  size?: "large" | "medium";
+  appearance?: "default" | "inverse";
+  /** The glyph. Required. */
+  icon: React.ReactNode;
+  /** Accessible name — required because Icon Button carries no visible text. */
+  "aria-label": string;
+  disabled?: boolean;
+}
+export interface ButtonIconProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof ButtonIconPropsOwn>, ButtonIconPropsOwn {}
+
+interface ButtonTextPropsOwn {
+  variant: "text";
+  size?: "medium" | "small" | "xsmall";
+  appearance?: "default" | "accent" | "onPrimary" | "inverse";
+  /** Optional context glyph rendered before the label (e.g. a back chevron next to a 'Back' label, an external-link glyph next to 'Open'). Sized 16px on every rung — the glyph stays legible on the dense `xsmall` rung where the label drops to 12-rank type. */
+  leadingIcon?: React.ReactNode;
+  /** Optional directional / destination glyph rendered after the label (e.g. a chevron-right next to 'Continue', an external-link glyph next to 'Open in new tab'). Same per-size footprint as the leading slot. For the **dropdown** pattern (see `useCases.dropdown`), pass `<ChevronDownIcon />` at rest and flip to `<ChevronUpIcon />` while the menu is expanded — the chevron is a state signal tied to `aria-expanded`, never decorative. */
+  trailingIcon?: React.ReactNode;
+  disabled?: boolean;
+}
+export interface ButtonTextProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof ButtonTextPropsOwn>, ButtonTextPropsOwn {}
+
+interface ButtonCheckPropsOwn {
+  variant: "check";
+  size?: "medium" | "small";
+  appearance?: "default" | "accent" | "inverse";
+  /** Toggle state. `true` paints the leading checkbox glyph as a filled square; `false` paints it as an outline. The component itself renders the checkbox glyph — consumers do NOT pass a checkbox icon node, only the `checked` state. */
+  checked?: boolean;
+  /** Optional context glyph rendered between the checkbox and the label (e.g. a coin glyph next to 'Use 1 perk'). Sized 16px on every rung — matches the optional middle icon footprint to `button/text` so the row reads at one density. */
+  icon?: React.ReactNode;
+  disabled?: boolean;
+}
+export interface ButtonCheckProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof ButtonCheckPropsOwn>, ButtonCheckPropsOwn {}
+
+interface ButtonTogglePropsOwn {
+  variant: "toggle";
+  /** Whether the action has been committed. Maps to aria-pressed. */
+  active?: boolean;
+  leadingIcon?: React.ReactNode;
+  trailingIcon?: React.ReactNode;
+  disabled?: boolean;
+}
+export interface ButtonToggleProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof ButtonTogglePropsOwn>, ButtonTogglePropsOwn {}
+
+interface ButtonToolbarPropsOwn {
+  variant: "toolbar";
+  appearance?: "default" | "accent" | "inverse";
+  leadingIcon?: React.ReactNode;
+  trailingIcon?: React.ReactNode;
+  disabled?: boolean;
+}
+export interface ButtonToolbarProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof ButtonToolbarPropsOwn>, ButtonToolbarPropsOwn {}
+
+export type ButtonProps =
+  | ButtonStandardProps
+  | ButtonIconProps
+  | ButtonTextProps
+  | ButtonCheckProps
+  | ButtonToggleProps
+  | ButtonToolbarProps;
+
+// ── Fab (button/fab) ──
+interface FabPropsOwn {
+  variant?: "fab";
+  appearance?: "primary" | "secondary";
+  icon?: React.ReactNode;
+  label?: React.ReactNode;
+}
+export interface FabProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof FabPropsOwn>, FabPropsOwn {}
+
+// ── SuggestionList (suggestion-list/suggestion-list) ──
+interface SuggestionListPropsOwn {
+  /** Composition mode flag. When `true` (or when SuggestionList is a direct child of `.chorus-carousel` / `.chorus-feed`), the list enters **embedded mode**: zeroes its own `background` + `padding` so chrome defers to the host. Pass explicitly inside `<Carousel>` / `<Feed>` for the contract to be visible in JSX; the DOM-ancestry safety net in styles.css also activates the mode when omitted. See `compositionModes` in `suggestion-list.family.json`. */
+  embedded?: boolean;
+  /** Section title. */
+  label: string;
+  /** { label, href? , onClick? } — trailing text link in the header. */
+  headerAction?: Record<string, unknown>;
+  /** Array of channel descriptors: { value, name, followers, description, thumbnail, active?, onToggle? }. */
+  items: React.ReactNode;
+}
+export interface SuggestionListProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof SuggestionListPropsOwn>, SuggestionListPropsOwn {}
+
+// ── AvatarRail (avatar-rail/avatar-rail) ──
+interface AvatarRailPropsOwn {
+  /** Accessible name for the rail. */
+  "aria-label": string;
+  /** Array of channel entries: { value, label, href, thumbnail }. */
+  items: React.ReactNode;
+  /** { label, href? , onClick? } — trailing [Text Button](../button/text.md) (`size={'small'}`, `appearance={'accent'}`) at the end of the rail (typically 'View all' / 'Manage'). Link-affordance rule: link-shaped Text Buttons take `accent` for chromatic emphasis. */
+  trailingAction?: Record<string, unknown>;
+  /** Composition mode flag. When `true` (or when the AvatarRail is a direct child of `.chorus-carousel` / `.chorus-feed`), the rail enters **embedded mode**: zeroes its own `background` + `padding` so chrome defers to the host. Pass explicitly inside `<Carousel>` / `<Feed>` for the contract to be visible in JSX; the DOM-ancestry safety net in styles.css also activates the mode when omitted. See `compositionModes` in `avatar-rail.family.json`. */
+  embedded?: boolean;
+}
+export interface AvatarRailProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof AvatarRailPropsOwn>, AvatarRailPropsOwn {}
+
+// ── Chip (multi-sub: filter, tag) ──
+interface ChipFilterPropsOwn {
+  variant?: "filter";
+  selected?: boolean;
+  leadingIcon?: React.ReactNode;
+  trailingIcon?: React.ReactNode;
+  disabled?: boolean;
+}
+export interface ChipFilterProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof ChipFilterPropsOwn>, ChipFilterPropsOwn {}
+
+interface ChipTagPropsOwn {
+  variant: "tag";
+  /** Dismiss glyph (×); when present, chip becomes interactive. */
+  trailingIcon?: React.ReactNode;
+}
+export interface ChipTagProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, keyof ChipTagPropsOwn>, ChipTagPropsOwn {}
+
+export type ChipProps =
+  | ChipFilterProps
+  | ChipTagProps;
+
+// ── Dialog (dialog/dialog) ──
+interface DialogPropsOwn {
+  open: boolean;
+  onClose: (...args: any[]) => any;
+  title: React.ReactNode;
+  body?: React.ReactNode;
+  /** { src, alt } — illustrative image between the title and the actions. */
+  image?: Record<string, unknown>;
+  /** When true (default), the image sits directly under the title; when false, under the body. */
+  imageFirst?: boolean;
+  /** { label, onClick } — delegates to Button appearance='primary', size='large', fullWidth. */
+  primaryAction?: Record<string, unknown>;
+  /** { label, onClick } — delegates to Button appearance='tertiary', size='large', fullWidth. */
+  secondaryAction?: Record<string, unknown>;
+  /** When true, scopes the scrim and card to the nearest positioned ancestor instead of portaling to document.body. */
+  inline?: boolean;
+}
+export interface DialogProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof DialogPropsOwn>, DialogPropsOwn {}
+
+// ── Divider (divider/divider) ──
+interface DividerPropsOwn {
+  /** Defaults to `true`. The band is decorative chrome — screen readers should not announce it as a thematic break. Override to `false` only when the divider genuinely marks a semantic section change (rare; prefer a heading instead). */
+  "aria-hidden"?: boolean;
+  /** Composes with the component's own class. Use sparingly — Divider exposes no tokens to override and any sizing / colour override breaks the surface-agnostic contract. */
+  className?: string;
+}
+export interface DividerProps extends Omit<React.HTMLAttributes<HTMLElement>, keyof DividerPropsOwn>, DividerPropsOwn {}
+
+// ── DirectoryList (directory-list/directory-list) ──
+interface DirectoryListPropsOwn {
+  /** Composition mode flag. When `true` (or when DirectoryList is a direct child of `.chorus-carousel` / `.chorus-feed`), the list enters **embedded mode**: zeroes its own `background` + `padding` so chrome defers to the host. */
+  embedded?: boolean;
+  /** Section title. */
+  label: string;
+  /** { label, href?, onClick? } — trailing accent Text Button in the header. Extend the header when there's an index page to route to. */
+  headerAction?: Record<string, unknown>;
+  /** Array of entity descriptors: { value, name, followers, description, thumbnail, active?, onToggle? }. */
+  items: React.ReactNode;
+}
+export interface DirectoryListProps extends Omit<React.HTMLAttributes<HTMLElement>, keyof DirectoryListPropsOwn>, DirectoryListPropsOwn {}
+
+// ── Feed (feed/post) ──
+interface FeedPropsOwn {
+  /** Editorial label — 'HOT', 'NEW', 'PINNED'. Opt-in; most posts render without one. */
+  flag?: string;
+  /** Forwarded to Thumbnail verbatim at size 32. */
+  avatar?: Record<string, unknown>;
+  channel: string;
+  /** Destination URL for the channel link. Defaults to '#' (preview-stub). */
+  channelHref?: string;
+  timestamp: string;
+  /** When present, renders an inline text affordance after the timestamp. */
+  followAction?: boolean;
+  /** Array of independently-linked metadata items. Pass plain strings for stub links, or `{ label, href }` objects to route. */
+  meta?: React.ReactNode;
+  /** Controlled active state for the Like toggle. Omit (uncontrolled) and the component manages its own active state. */
+  liked?: boolean;
+  /** Fires with the next `liked` value when the Like Text Button is tapped. */
+  onLikeChange?: (...args: any[]) => any;
+  title?: string;
+  body?: string;
+  /** 80×80 trailing image; { src, alt, stacked? }. **Agents must always pass this slot at scaffold / generation time** — fill `src` with a real subject photo when implied, the bundled `/placeholder.png` otherwise. The `optional` flag and the `slotOmissionCollapses` rule are RUNTIME contracts (a Feed still reflows cleanly when a downstream consumer drops thumbnail for a verified text-only post); they are NOT a license for agents to omit the slot. See `forbidden` below — omission at scaffold time is forbidden. When `stacked === true` (2+ images attached), the thumbnail overlays a `SquareStackIcon` glyph at its top-right corner — see `sizing.thumbnailMultipleBadge` for the full anatomy. */
+  thumbnail?: Record<string, unknown>;
+  /** { label, participants } — inline poll banner. `label` is constrained to the literal `"Poll"` (the banner is editorial — see `tagBanner.labelEnum`); `participants` is the participant count shown after the divider. */
+  poll?: Record<string, unknown>;
+  /** { label, participants } — inline offer-evaluation banner. Same chrome as `poll` (surfaceVariant slab, leading glyph + label + divider + participant count), but the leading icon is `CompensationFillIcon` and the glyph + label paint in `sys.color.success` (resolves to `ref.palette.green.500`). Surfaces a 'compensation / offer evaluation' post — the author publishes their current salary or a competing offer and asks the community for better-option signals. `label` is constrained to the literal `"Offer"` (see `tagBanner.labelEnum`); `participants` is the participant count shown after the divider. */
+  offer?: Record<string, unknown>;
+  /** { title, source, src? } — inline link-share card. */
+  citation?: Record<string, unknown>;
+  mention?: string;
+  /** { likes, comments, views } — footer counters. */
+  engagement?: Record<string, unknown>;
+  /** Whole-card navigation. When present the card surface becomes the click target (an <article role="button">), and interior affordances (channel link, Follow, Like, Comments, citation, mention) route independently — a click originating on any inner <a>/<button> is ignored. This is the in-contract way to make a post navigable; do NOT wrap Feed in an external <Link>/<a> — that re-pays the page rail as a gutter and misaligns the card with NavigationBar / TabBar. */
+  onClick?: (...args: any[]) => any;
+}
+export interface FeedProps extends Omit<React.HTMLAttributes<HTMLElement>, keyof FeedPropsOwn>, FeedPropsOwn {}
+
+// ── FeedAd (feed/ad) ──
+interface FeedAdPropsOwn {
+  /** { name, subtitle?, avatar? } — leading brand row. `name` is **required** — every sponsored placement MUST carry an explicit brand name; never render the row with an empty / missing name (the row exists specifically to attribute the ad to a buyer). `avatar` is forwarded to Thumbnail verbatim at size 32. `subtitle` defaults to the literal `Sponsored`; override but cannot omit. */
+  brand: Record<string, unknown>;
+  /** Fires when the trailing close (X) is tapped. Omit to render the card without a dismiss affordance. */
+  onDismiss?: (...args: any[]) => any;
+  /** Accessible label for the trailing close button. Defaults to 'Dismiss ad'. */
+  dismissLabel?: string;
+  /** Ad headline. heading.sm (16 / Semibold) / onSurface. Single line; truncates with ellipsis. */
+  title?: string;
+  /** Ad body copy. body.sm (14 / Regular) / onSurfaceVariant. Two-line clamp with trailing ellipsis. */
+  body?: string;
+  /** { src, alt } — hero media block. **Required** for every FeedAd placement: an ad without a hero image collapses to a brand row + text wall, which is not a shipped FeedAd shape. Renders at 16:10 inside the cta-group's `radius.md` clip. When generating mock / scaffold placements without a real ad creative, fill `src` with `/placeholder.png` rather than omitting `media` — the `surfaceContainerHigh` fallback is a runtime safety net for load failures, not a design-time omission. */
+  media: Record<string, unknown>;
+  /** { label, onClick?, color? } — the single full-width Standard Button at the foot. `color` accepts a free-form Hex supplied by the ad client; only the button fill and border swap, every other Standard Button token binding stays intact. */
+  cta?: Record<string, unknown>;
+  className?: string;
+}
+export interface FeedAdProps extends Omit<React.HTMLAttributes<HTMLElement>, keyof FeedAdPropsOwn>, FeedAdPropsOwn {}
+
+// ── FormField (multi-sub: input, textarea, search, select) ──
+interface FormFieldInputPropsOwn {
+  variant?: "input";
+  appearance?: "default" | "error";
+  value?: string;
+  defaultValue?: string;
+  placeholder?: string;
+  /** Visible label rendered above the field box and associated with it (`<label htmlFor>`). */
+  label?: React.ReactNode;
+  /** Assistive text rendered below the field box, left-aligned. **Optional on every appearance** — omit the prop to render the field without an assistive rung; the box and label keep their footprint. On the `error` appearance the helper re-tones to `sys.color.error` so the message reads as the error caption; an error field may still be shown without a helper, in which case only the field box re-tones. Mutually exclusive with `maxLength` — if both are given, the character count is shown and `helper` is ignored. */
+  helper?: React.ReactNode;
+  /** Caps the input length and renders a `current/max` character count below the field box, right-aligned. Mutually exclusive with `helper`. */
+  maxLength?: number;
+  disabled?: boolean;
+}
+export interface FormFieldInputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, keyof FormFieldInputPropsOwn>, FormFieldInputPropsOwn {}
+
+interface FormFieldTextareaPropsOwn {
+  variant: "textarea";
+  appearance?: "default" | "error";
+  value?: string;
+  defaultValue?: string;
+  placeholder?: string;
+  /** Visible label rendered above the field box and associated with it (`<label htmlFor>`). */
+  label?: React.ReactNode;
+  /** Assistive text rendered below the field box, left-aligned. Same rules as [input.helper](./input.md): mutually exclusive with `maxLength`, optional on every appearance, re-tones to `sys.color.error` on the error appearance. */
+  helper?: React.ReactNode;
+  /** Caps the value length and renders a `current/max` character count below the box, right-aligned. Mutually exclusive with `helper`. */
+  maxLength?: number;
+  /** Minimum visible rows. The textarea is `resize: vertical` so the user can pull it taller; the value never shrinks below `rows`. */
+  rows?: number;
+  disabled?: boolean;
+}
+export interface FormFieldTextareaProps extends Omit<React.HTMLAttributes<HTMLElement>, keyof FormFieldTextareaPropsOwn>, FormFieldTextareaPropsOwn {}
+
+interface FormFieldSearchPropsOwn {
+  variant: "search";
+  /** Search Bar carries only the `default` appearance — there is no `error` form (error reporting belongs to a labelled Input). */
+  appearance?: "default";
+  value?: string;
+  defaultValue?: string;
+  placeholder?: string;
+  disabled?: boolean;
+}
+export interface FormFieldSearchProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, keyof FormFieldSearchPropsOwn>, FormFieldSearchPropsOwn {}
+
+interface FormFieldSelectPropsOwn {
+  variant: "select";
+  appearance?: "default" | "error";
+  value?: string;
+  defaultValue?: string;
+  placeholder?: string;
+  label?: React.ReactNode;
+  helper?: React.ReactNode;
+  /** Optional 16px (`sys.icon.md`) decorative glyph pinned at the inner-left edge of the field. Tracks the field's active text colour (`sys.color.onSurface` on the default appearance, `sys.color.onErrorContainer` on `error`) so the glyph reads as part of the typed content. */
+  leadingIcon?: React.ReactNode;
+  /** Fired when the field box or the trailing chevron is clicked. Consumers use this to raise a `BottomSheet` with the option list. */
+  onOpen?: (...args: any[]) => any;
+  disabled?: boolean;
+}
+export interface FormFieldSelectProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof FormFieldSelectPropsOwn>, FormFieldSelectPropsOwn {}
+
+export type FormFieldProps =
+  | FormFieldInputProps
+  | FormFieldTextareaProps
+  | FormFieldSearchProps
+  | FormFieldSelectProps;
+
+// ── Header (header/main) ──
+interface HeaderPropsOwn {
+  /** Label typography rung. `large` (default) — `sys.typo.heading.md` (20 / Semibold) — the canonical section heading used by Section and other top-level page regions. `medium` — `sys.typo.heading.sm` (16 / Semibold) — denser host surfaces (in-sheet sub-section, bounded card, drawer column heading, secondary regions inside an already-headed page). */
+  size?: "large" | "medium";
+  /** Leading heading text. Single line; the consumer truncates upstream if the host width is too narrow. */
+  label?: string;
+  /** Trailing Text Button binding. Object: `{ label, href, onClick }`. Rendered as a Text Button at `size="xsmall"`, `appearance="accent"`. The link-affordance rule keeps the navigational intent in the accent tone across hosts. Mutually exclusive with `trailingIcon`. */
+  headerAction?: Record<string, unknown>;
+  /** Drill-in [Icon Button](../button/icon.md) mode. Pass `true` to render the canonical chevron-right glyph inside a Button `variant="icon"` `size="medium"` (32 × 32 capsule, 16-glyph), or pass any 16px icon node to override the glyph. The trailing Icon Button owns its own tap target via `onClick` / `href`; the surrounding `<header>` element stays non-interactive. Supply an `aria-label` for the icon-only button (defaults to `"Open <label>"` when `label` is a string). Mutually exclusive with `headerAction` and `headerDropdown`. */
+  trailingIcon?: React.ReactNode;
+  /** Trailing [Text Button dropdown](../button/text.md#dropdown) binding. Object: `{ label, onClick, open, 'aria-haspopup'?, 'aria-controls'? }`. Rendered as a Text Button at `size="xsmall"` with the default appearance — label IS the current selected value ('Top', 'Last 7 days', 'All time'), and the trailing chevron flips between `ChevronDownIcon` (when `open` is falsy) and `ChevronUpIcon` (when `open` is true) as a state signal. Consumer owns the menu surface and the `open` state. Mutually exclusive with `headerAction` and `trailingIcon` — priority `trailingIcon` > `headerAction` > `headerDropdown` when more than one is set. */
+  headerDropdown?: Record<string, unknown>;
+  /** Click handler. Honored when `trailingIcon` is set — wired to the trailing Icon Button's `onClick`. */
+  onClick?: (...args: any[]) => any;
+  /** Link href. Honored when `trailingIcon` is set — wired to the trailing Icon Button. */
+  href?: string;
+  /** Wrapping element. Defaults to `<header>` for top-level / labelled-region hosts; use `as="div"` when the surrounding host already carries the section semantics. The wrapper itself is never interactive — in `trailingIcon` mode the click target sits on the trailing Icon Button, not the wrapper. */
+  as?: "header" | "div";
+}
+export interface HeaderProps extends Omit<React.HTMLAttributes<HTMLElement>, keyof HeaderPropsOwn>, HeaderPropsOwn {}
+
+// ── SubHeader (header/sub) ──
+interface SubHeaderPropsOwn {
+  /** The section label text ("Following", "More Topics to follow"). Single line; the consumer keeps it short. `children` may be passed instead and takes precedence — `label` is the canonical string form. */
+  label?: string;
+  /** Trailing Text Button binding. Object: `{ label, href, onClick }`. Rendered as a Text Button at `size="xsmall"`, `appearance="accent"` — the one trailing affordance SubHeader carries, for a quiet region-level commit ("See all", "Edit", "Manage"). When set, the wrapper becomes a full-bleed flex row and the label is nested as the heading (`as`) on the leading edge so the heading's accessible name never absorbs the button. Mirrors Header's `headerAction` binding; SubHeader supports no icon or dropdown mode (those stay Header's, where the louder heading tone belongs). */
+  action?: Record<string, unknown>;
+  /** Wrapping element for the label. Defaults to `<h3>` so the muted label still registers as a heading for the group beneath it; use a different heading level to fit the host's document outline, or `as="div"` when the surrounding host already carries the section semantics. The label element is never interactive — in `action` mode the click target sits on the trailing Text Button, and the flex-row wrapper that holds both is a non-semantic `<div>`. */
+  as?: "h2" | "h3" | "h4" | "div";
+  /** Label content — overrides `label` when both are set. Use the `label` string for the canonical case; `children` is the escape hatch for inline composition. */
+  children?: React.ReactNode;
+  /** Composes with the component's own class. Use sparingly — SubHeader exposes its tone and inset through the spec; overriding them breaks the alignment-with-rows and muted-divider contracts. */
+  className?: string;
+}
+export interface SubHeaderProps extends Omit<React.HTMLAttributes<HTMLElement>, keyof SubHeaderPropsOwn>, SubHeaderPropsOwn {}
+
+// ── List (multi-sub: standard, radio, entry, accordion) ──
+interface ListStandardPropsOwn {
+  /** Composition mode flag. When `true` (or when the List is a direct child of `.chorus-carousel` / `.chorus-feed`), enters **embedded mode**: zeroes its own `background` + `padding` so chrome defers to the host. Pass explicitly inside `<Carousel>` / `<Feed>` for the contract to be visible in JSX; the DOM-ancestry safety net in styles.css also activates the mode when omitted. See `compositionModes` in `list.family.json`. */
+  embedded?: boolean;
+  /** Array of row descriptors. A row carrying `thumbnail` props forwards them verbatim to the leading Thumbnail (the image type). */
+  items: React.ReactNode;
+}
+export interface ListStandardProps extends Omit<React.HTMLAttributes<HTMLUListElement>, keyof ListStandardPropsOwn>, ListStandardPropsOwn {}
+
+interface ListRadioPropsOwn {
+  /** Composition mode flag. When `true` (or when the List is a direct child of `.chorus-carousel` / `.chorus-feed`), enters **embedded mode**: zeroes its own `background` + `padding` so chrome defers to the host. Pass explicitly inside `<Carousel>` / `<Feed>` for the contract to be visible in JSX; the DOM-ancestry safety net in styles.css also activates the mode when omitted. See `compositionModes` in `list.family.json`. */
+  embedded?: boolean;
+  /** Array of row descriptors. */
+  items: React.ReactNode;
+  /** Selected value. Controlled. */
+  value?: string;
+  /** Commits the next value when a row is selected. */
+  onChange?: (...args: any[]) => any;
+}
+export interface ListRadioProps extends Omit<React.HTMLAttributes<HTMLUListElement>, keyof ListRadioPropsOwn>, ListRadioPropsOwn {}
+
+interface ListEntryPropsOwn {
+  /** Composition mode flag. When `true` (or when the List is a direct child of `.chorus-carousel` / `.chorus-feed`), enters **embedded mode**: zeroes its own `background` + `padding` so chrome defers to the host. Pass explicitly inside `<Carousel>` / `<Feed>` for the contract to be visible in JSX; the DOM-ancestry safety net in styles.css also activates the mode when omitted. See `compositionModes` in `list.family.json`. */
+  embedded?: boolean;
+  /** Thumbnail rung shared by every row in the list — `small` = 32, `medium` = 40, `large` = 48, `xlarge` = 56. The row's inline padding (16), block padding (8), and the family-wide row min-height (48) stay constant across sizes; only the leading Thumbnail footprint changes. Pick `small` for compact directories where the avatar reads as a mark, `medium` for the canonical channel / source directory, `large` for member-directory rows where the avatar carries identity weight, `xlarge` for the canonical follow-suggestion rung used by [SuggestionList](../suggestion-list/suggestion-list.md). */
+  size?: "small" | "medium" | "large" | "xlarge";
+  /** Array of row descriptors. Each item passes `thumbnail` props forwarded verbatim to the Thumbnail component. */
+  items: React.ReactNode;
+}
+export interface ListEntryProps extends Omit<React.HTMLAttributes<HTMLUListElement>, keyof ListEntryPropsOwn>, ListEntryPropsOwn {}
+
+interface ListAccordionPropsOwn {
+  /** `single` allows one open item at a time; `multiple` allows any number. Affects how `value` and `defaultValue` are typed. */
+  type?: "single" | "multiple";
+  /** Controlled open-state. `string` for `type='single'`, `string[]` for `type='multiple'`. Pair with `onValueChange`. */
+  value?: unknown;
+  /** Uncontrolled initial open-state. Ignored when `value` is also passed. */
+  defaultValue?: unknown;
+  /** Called with the next open-state (`string | null` for single, `string[]` for multiple) when the user toggles an item. */
+  onValueChange?: (...args: any[]) => any;
+  /** Single-mode only. When `false`, an open item cannot be collapsed by clicking its own trigger — one item is always open. Ignored when `type='multiple'`. */
+  collapsible?: boolean;
+  /** Composition mode flag inherited from the List family. When `true` (or when the Accordion is a direct child of `.chorus-carousel` / `.chorus-feed`), enters embedded mode — chrome defers to the host. See `compositionModes` in `list.family.json`. */
+  embedded?: boolean;
+  /** One or more `Accordion.Item` children. */
+  children: React.ReactNode;
+}
+export interface ListAccordionProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof ListAccordionPropsOwn>, ListAccordionPropsOwn {}
+
+export type ListProps =
+  | ListStandardProps
+  | ListRadioProps
+  | ListEntryProps
+  | ListAccordionProps;
+
+// ── Metadata (multi-sub: standard, compact) ──
+interface MetadataStandardPropsOwn {
+  /** Forwarded to [Thumbnail](../thumbnail/thumbnail.md) verbatim at `size={32}`. When omitted, the Thumbnail renders its image-area fallback over `surfaceContainerHigh`. */
+  avatar?: Record<string, unknown>;
+  /** Primary line entity name — channel topic (Post) or brand (Ad). Single line; truncates with ellipsis. */
+  name: string;
+  /** Destination URL for the entity name. When present, the name renders as an `<a>`; otherwise as a `<span>`. */
+  nameHref?: string;
+  /** Inline timestamp painted after the name on the primary line, in `label.sm` / `sys.color.outline` — one tonal step further than the name. Reach for it on Feed Post; omit on Feed Ad. */
+  timestamp?: string;
+  /** Whether to paint the inline follow toggle after the timestamp. When `true`, a dot separator + Follow/Following text toggle render at the primary line's trailing edge. State is controlled via `followed` + `onFollowChange`. */
+  followAction?: boolean;
+  /** Whether the viewer follows this entity. Drives the inline follow toggle's label and `aria-pressed`. */
+  followed?: boolean;
+  /** Fires with the next `followed` value when the inline follow toggle is tapped. */
+  onFollowChange?: (...args: any[]) => any;
+  /** Secondary line plain text — canonical use is 'Sponsored' on Feed Ad. Mutually exclusive with `meta` (when both are passed, `meta` wins). */
+  subtitle?: string;
+  /** Array of independently-linked metadata items rendered on the secondary line. Each entry is either a string (renders as a stub-href link) or a `{ label, href, badge }` object — `badge` is an optional SINGLE presentational mark node rendered AFTER the item's link, outside the <a> (canonical fill: Badge variant="role" on the trailing nickname item; at most one badge rides the nickname). The last item is canonically the user's nickname, displayed bare (no @ prefix). Items separate by middot. Reach for it on Feed Post; omit on Feed Ad. */
+  meta?: React.ReactNode;
+  /** Trailing-edge slot. Canonical fill: the Feed Ad dismiss × button. The slot's hit target is its own — taps on it never propagate to the entity-name link. */
+  trailing?: React.ReactNode;
+}
+export interface MetadataStandardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof MetadataStandardPropsOwn>, MetadataStandardPropsOwn {}
+
+interface MetadataCompactPropsOwn {
+  variant: "compact";
+  /** Array of independently-linked identity items — canonical fill is `[company name, nickname]`, the nickname canonically last, displayed bare (no @ prefix). Each entry is either a string (renders as a stub-href link) or a `{ label, href, badge }` object — `badge` is an optional SINGLE presentational mark node rendered AFTER the item's link, outside the <a> (canonical fill: Badge variant="role" on the trailing nickname item). Items separate by middot. Same grammar as the standard sub's `meta`; here it is the whole cluster, so it is required. */
+  meta: React.ReactNode;
+  /** Posting time at the line's trailing edge — plain text (never a link), preceded by a middot, in `label.sm` / `sys.color.outline` so it recedes behind the identity links. Required: the timestamp is what distinguishes a compact attribution from a bare identity row. */
+  timestamp: string;
+}
+export interface MetadataCompactProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof MetadataCompactPropsOwn>, MetadataCompactPropsOwn {}
+
+export type MetadataProps =
+  | MetadataStandardProps
+  | MetadataCompactProps;
+
+// ── NavCard (nav-card/nav-card) ──
+interface NavCardPropsOwn {
+  /** Trailing affordance. `default` ships NO trailing icon — the card reads as a labelled tile (settings entry, scope card, informational drill-target). `nav` auto-renders the right-pointing chevron — the explicit drill-in form. A consumer-supplied `trailingIcon` prop still overrides on either variant (e.g. an external-link arrow, an expand-down chevron). */
+  variant?: "default" | "nav";
+  /** Primary card text. Single line; truncates with ellipsis. */
+  label: string;
+  /** Secondary line under the label. Single line; truncates with ellipsis. */
+  supportingText?: string;
+  /** Optional leading slot — a 16px icon glyph (renders in `currentColor`) or a 32-rung [Thumbnail](../thumbnail/thumbnail.md). Block-centred on the row's vertical midline — both icon and thumbnail share the same contract regardless of one-line / two-line body. When omitted the label sits flush at the inline padding edge. */
+  leading?: React.ReactNode;
+  /** Overrides the variant's trailing affordance. Pass a custom 16px glyph when the action isn't a navigation drill-in (inline expand-down arrow, external-link arrow). On `variant="default"` no trailing renders unless `trailingIcon` is supplied; on `variant="nav"` the auto-chevron is replaced. */
+  trailingIcon?: React.ReactNode;
+  /** Container fill. `default` is transparent — the card's identity is the outlined chrome (hairline + radius + label + chevron) and the host surface tone reads through. `surface` paints `sys.color.surface` so the card reads as its own opaque tier; reach for it when the card sits on a transparent / non-`surface` host (between bare-surface sections, on a tonal band the card needs to break out of). */
+  appearance?: "default" | "surface";
+  /** When provided, renders as `<a href>` instead of `<button>`. Mutually exclusive with `onClick` as the primary commit, though either may be combined for analytics. */
+  href?: string;
+  onClick?: (...args: any[]) => any;
+  disabled?: boolean;
+  /** Docs-only — pins the card to a single visual state via `data-force-state`. Not for production use. */
+  forcedState?: "hovered" | "pressed" | "focused";
+}
+export interface NavCardProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof NavCardPropsOwn>, NavCardPropsOwn {}
+
+// ── NavList (nav-list/nav-list) ──
+interface NavListPropsOwn {
+  /** Composition mode flag. When `true` (or when NavList is a direct child of `.chorus-carousel` / `.chorus-feed`), the list enters **embedded mode**: zeroes its own `background` + `padding` so chrome defers to the host. */
+  embedded?: boolean;
+  /** Section title. */
+  label: string;
+  /** { label, href?, onClick? } — trailing accent Text Button in the header. Extend the header when there's an index page to route to. */
+  headerAction?: Record<string, unknown>;
+  /** Array of nav row descriptors forwarded to [List](../list/entry.md) `variant="entry"` as label-only rows: { value, label, supportingText?, href?, onClick?, trailingIcon? }. `supportingText` is mapped to the entry sub's `description` slot (caption-tone supporting line under the label). `thumbnail` is intentionally NOT exposed — the leading column is always collapsed. */
+  items: React.ReactNode;
+}
+export interface NavListProps extends Omit<React.HTMLAttributes<HTMLElement>, keyof NavListPropsOwn>, NavListPropsOwn {}
+
+// ── NavigationBar (multi-sub: main, sub, search) ──
+interface NavigationBarMainPropsOwn {
+  variant?: "main";
+  /** Default: brand logotype `<img>` rendered at a fixed 24px height (width auto). Fallback: plain string rendered as `heading.lg` text that truncates with ellipsis. */
+  title: React.ReactNode;
+  /** Tab-root case — fires when the leading menu / hamburger is tapped (opens the app drawer). Mutually exclusive with `onBack`. */
+  onMenuClick?: (...args: any[]) => any;
+  /** Drill-in (content-detail) case — passing `onBack` swaps the leading menu glyph for a back chevron wired to it (route to the previous screen). Takes precedence over `onMenuClick` when both are passed. */
+  onBack?: (...args: any[]) => any;
+  /** Accessible label for the back chevron in the drill-in case. Defaults to "Back". */
+  backLabel?: string;
+  /** Up to four { icon, 'aria-label' } entries; laid out left-to-right with no inter-icon gap. Three is the conventional ceiling on a tab root; the drill-in (content-detail) cluster uses up to four (share / notify / bookmark / more). */
+  trailingActions?: React.ReactNode;
+}
+export interface NavigationBarMainProps extends Omit<React.HTMLAttributes<HTMLElement>, keyof NavigationBarMainPropsOwn>, NavigationBarMainPropsOwn {}
+
+interface NavigationBarSubPropsOwn {
+  variant: "sub";
+  /** Container fill and foreground tone. `surface` (default) — opaque `sys.color.surface` fill, `onSurface` icons and title; the canonical page-chrome treatment. `overlay` — transparent container with **fixed white** icons (`ref.palette.white.1000`), used when the bar floats over a hero/cover image (e.g. inside [Profile header](../profile-header/profile-header.md)). In `overlay`, the title slot is intentionally muted — pass `title=""` (empty string) when the host already carries page identity below the bar. */
+  appearance?: "surface" | "overlay";
+  /** Page name. Optional — omit it for bars whose side actions say everything (canonical: the composer text-button pair, Cancel / Post). A title-less bar renders a non-heading placeholder in the centre cell so the side slots stay in their 1fr/auto/1fr columns. Pass an empty string in `overlay` appearance when the host (e.g. ProfileHeader) carries the identity directly below the bar. */
+  title?: string;
+  /** Optional leading affordance. Accepts the { icon, 'aria-label' } descriptor (renders the 24px Icon Button internally — typically a back-arrow), a { label, href } link descriptor, or a node. Text Button and Icon Button are both first-class fills: pick per side independently of the trailing slot — e.g. a default-appearance Text Button (Cancel) on composer bars. */
+  leading?: Record<string, unknown>;
+  /** Optional trailing affordance — Icon Button / Toolbar Button / Text Button, chosen independently of the leading slot. **Prefer the object form `{ icon, 'aria-label' }` for the icon case** — the component then renders the 24px Icon Button internally and the `sys.icon.lg` contract is guaranteed. If a raw `<Button variant="icon" />` node is passed instead, it MUST carry `size="large"` (= `sys.icon.lg` / 24); `size="medium"` resolves to `sys.icon.md` (16) and breaks symmetry with the leading slot. */
+  trailing?: React.ReactNode;
+}
+export interface NavigationBarSubProps extends Omit<React.HTMLAttributes<HTMLElement>, keyof NavigationBarSubPropsOwn>, NavigationBarSubPropsOwn {}
+
+interface NavigationBarSearchPropsOwn {
+  variant: "search";
+  /** Controlled value. Omit (and pass `defaultValue` instead) for an uncontrolled field. */
+  value?: string;
+  defaultValue?: string;
+  /** Faint guide text shown when the value is empty. Sentence case, typically a one-line invitation (`Search by keyword`, `Search channels`). */
+  placeholder?: string;
+  /** Called on every keystroke with the new value. Host owns the typeahead / submit pipeline. */
+  onChange?: (...args: any[]) => any;
+  /** Called when the user commits the query (Enter / form submit). Host wires the route or query side-effect. */
+  onSubmit?: (...args: any[]) => any;
+  /** Wires the leading back-arrow to the host's back action — the bar does not own routing. */
+  onBack: (...args: any[]) => any;
+  /** aria-label for the leading back-arrow icon button. */
+  backLabel?: string;
+  /** aria-label for the trailing clear (×) button. */
+  clearLabel?: string;
+  /** Defaults to true because the bar is the search page's primary surface — the user arrived here to type. Set to false when the field receives a hydrated query that the user is reviewing rather than editing. */
+  autoFocus?: boolean;
+}
+export interface NavigationBarSearchProps extends Omit<React.HTMLAttributes<HTMLElement>, keyof NavigationBarSearchPropsOwn>, NavigationBarSearchPropsOwn {}
+
+export type NavigationBarProps =
+  | NavigationBarMainProps
+  | NavigationBarSubProps
+  | NavigationBarSearchProps;
+
+// ── ProfileHeader (profile-header/profile-header) ──
+interface ProfileHeaderPropsOwn {
+  /** Entity name — channel topic, person, or company. Renders as the page-level `<h1>` at `sys.typo.heading.lg` / Semibold / `onSurface`. Single line; truncates with ellipsis at narrow widths. */
+  name: string;
+  /** Forwarded to [Thumbnail](../thumbnail/thumbnail.md) verbatim at `size={56}` with `outlined={true}`. Object: `{ src, alt, updateDot?, logoBadge? }`. The avatar overlaps the cover band's bottom edge by half its height; the 2-token `surface`-tone halo that separates the circle from the cover comes from Thumbnail's `outlined` case (see [Thumbnail § With surface outline](../thumbnail/thumbnail.md#with-surface-outline)). */
+  avatar: Record<string, unknown>;
+  /** { src?, alt? } — image-area override for the cover band. `src` accepts any URL; falls back to `/placeholder.png` (the universal Chorus image-area placeholder) when omitted. Same contract as `Thumbnail.src` / `ProfileCarousel.cover` — `object-fit: cover` preserves aspect ratio and crops to the band's intrinsic `375 / 120` ratio. */
+  cover?: Record<string, unknown>;
+  /** Visibility class. `public` paints the [GlobeIcon](../../icons/svg/Globe.svg) + the `visibilityLabel` (default 'Public'); `private` paints the [LockIcon](../../icons/svg/Lock.svg) + the `visibilityLabel` (default 'Private'). Consumers override the label text via `visibilityLabel`. */
+  visibility?: "public" | "private";
+  /** Override the visibility label text — used for localisation (e.g. '공개' / '비공개'). When omitted, defaults to 'Public' / 'Private' based on `visibility`. */
+  visibilityLabel?: string;
+  /** Follower count line — formatted by the consumer so the unit / locale stays in their hands (e.g. '999 followers', '12.4K followers', '999 팔로워'). Paints in `sys.typo.body.sm` / `sys.color.onSurfaceVariant` to the right of a bullet separator on the meta row. */
+  followers: string;
+  /** Whether the viewer is following this entity. Drives the trailing [Toggle Button](../button/toggle.md): false → 'Follow' (primary fill); true → 'Following' (transparent fill + hairline outline so the committed state recedes against any host surface tier). */
+  followed?: boolean;
+  /** Fires when the follow toggle commits — receives the next `followed` boolean. Consumer owns persistence. */
+  onFollowChange?: (...args: any[]) => any;
+  /** Inactive follow-button label. Defaults to 'Follow'. */
+  followLabel?: string;
+  /** Active follow-button label. Defaults to 'Following'. */
+  followingLabel?: string;
+  /** Whether to render the overlay [Navigation bar/page](../navigation-bar/sub.md) at the cover's top edge. Defaults to `true` (back-arrow leading + search trailing, transparent + fixed-white icons). Pass `false` when the host route already paints its own top chrome and the cover should be clean. */
+  nav?: boolean;
+  /** Paint an iOS-style app status bar (time + cellular / Wi-Fi / battery glyphs) above the overlay nav at the cover's top edge — transparent fill, fixed-white (`ref.palette.white.1000`) glyphs, so the cover image shows through the OS-chrome zone (edge-to-edge / immersive screen). Off by default. Pass `true` for the canonical 9:41 time, or `statusBar={{ time: '…' }}` to override. Decorative OS-chrome mimicry: `aria-hidden`, intentionally off-token (raw px + `-apple-system` font). When present it pays `env(safe-area-inset-top)` and the overlay nav collapses its own inset so the two never double-stack below the notch. */
+  statusBar?: unknown;
+  /** Click handler for the overlay nav's leading back chevron. */
+  onBack?: (...args: any[]) => any;
+  /** Click handler for the overlay nav's trailing search icon. */
+  onSearch?: (...args: any[]) => any;
+  /** Accessible label for the overlay nav's back chevron. Defaults to 'Back'. */
+  backLabel?: string;
+  /** Accessible label for the overlay nav's search icon. Defaults to 'Search'. */
+  searchLabel?: string;
+}
+export interface ProfileHeaderProps extends Omit<React.HTMLAttributes<HTMLElement>, keyof ProfileHeaderPropsOwn>, ProfileHeaderPropsOwn {}
+
+// ── Progress (progress/progress) ──
+interface ProgressPropsOwn {
+  /** Progress value. When `max` is omitted, this is the ratio 0..1; with `max`, it is the raw count and the ratio is `value / max`. Clamped to 0..1. */
+  value?: number;
+  /** Upper bound for `value`. Defaults to 1 so a `value` of 0.4 reads as 40%. */
+  max?: number;
+  /** Accessible label describing what is in progress. Required when the bar is not paired with a visible label next to it. */
+  "aria-label"?: string;
+}
+export interface ProgressProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof ProgressPropsOwn>, ProgressPropsOwn {}
+
+// ── PostCarousel (carousel/post) ──
+interface PostCarouselPropsOwn {
+  /** Array of up to 5 compact post cards. Each item: { id?, avatar, channel, verified?, followAction?, followed?, onFollowChange?, title, body, mention?, views, moreLabel?, onClick? }. Items beyond index 4 are dropped — the section enforces the 5-card maximum. */
+  items: React.ReactNode;
+}
+export interface PostCarouselProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof PostCarouselPropsOwn>, PostCarouselPropsOwn {}
+
+// ── ProfileCarousel (carousel/profile) ──
+interface ProfileCarouselPropsOwn {
+  /** Array of profile-card descriptors. Each item: { id?, avatar, cover?, name, followers, metrics?, description?, followed?, onFollowChange?, followLabel?, followingLabel?, onClick? }. `metrics` and `description` are mutually exclusive — when `description` is present, it replaces the metrics row. Items beyond index 4 are dropped — the rail enforces a hard 5-card maximum. */
+  items: React.ReactNode;
+}
+export interface ProfileCarouselProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof ProfileCarouselPropsOwn>, ProfileCarouselPropsOwn {}
+
+// ── SideSheet (side-sheet/side-sheet) ──
+interface SideSheetPropsOwn {
+  /** Controlled open state. */
+  open: boolean;
+  /** Fired on backdrop tap, Escape key, or any consumer-triggered close. */
+  onClose: (...args: any[]) => any;
+  /** Edge the card sits flush against. `left` (default) — the off-canvas navigation / channel directory pattern. `right` — filter rail, settings pane, or sub-nav overlay on right-handed surfaces. */
+  anchor?: "left" | "right";
+  /** Card width. Number → pixels; string → any CSS length (`'80vw'`, `'min(320px, 80vw)'`). Mobile-first: defaults to 320 so the trailing 40-ish px peek lets the user see the page underneath at a glance. */
+  width?: unknown;
+  /** Pinned bottom action rail. Hosts a single Text Button or any compact action node (e.g. "Browse all channels"). Stays flush at the card bottom while the body scrolls. */
+  footer?: React.ReactNode;
+  /** Body content. Free-form composition; the canonical fill is one or more Header (size="medium") + embedded [list/entry](../list/entry.md) directory stack pairs (40 avatar + label + inline count Badge + optional trailing icon toggle). */
+  children: React.ReactNode;
+  /** Docs-only — renders the sheet inline (no portal, no fixed positioning, no body scroll lock) so the card can be shown next to other primitives in a documentation preview without occluding the page. Never use in production. */
+  inline?: boolean;
+}
+export interface SideSheetProps extends Omit<React.HTMLAttributes<HTMLElement>, keyof SideSheetPropsOwn>, SideSheetPropsOwn {}
+
+// ── Skeleton (skeleton/skeleton) ──
+interface SkeletonPropsOwn {
+  /** Selects the default footprint and corner radius. `text` and `block` paint at `sys.radius.xs`; `circle` paints at `sys.radius.full`. */
+  shape?: "text" | "block" | "circle";
+  /** Overrides the default inline footprint. Numbers are coerced to `px`; strings pass through (`100%`, `'12rem'`, …). When omitted, `text` and `block` stretch to 100% of the host; `circle` keeps a `ref.space.500` (40 × 40) footprint. */
+  width?: unknown;
+  /** Overrides the default block footprint. Numbers are coerced to `px`. When omitted, `text` is `ref.space.200` (16px), `block` is `ref.space.1000` (80px), `circle` is `ref.space.500` (40px). */
+  height?: unknown;
+  /** Accessible label announced by screen readers. Defaults to `'Loading'`. */
+  "aria-label"?: string;
+}
+export interface SkeletonProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, keyof SkeletonPropsOwn>, SkeletonPropsOwn {}
+
+// ── StatusTag (status-tag/status-tag) ──
+interface StatusTagPropsOwn {
+  /** Tonal fill / foreground pair. `neutral` is the quiet informational default; `error` is the rejection / blocked / failed state. */
+  appearance?: "neutral" | "error";
+  /** Tag label text. Single line; should be a short word or phrase (≤ 6 chars in Latin, ≤ 4 in CJK). Wraps would push the pill onto two lines and break the inline-with-label rhythm — keep it short instead. */
+  children: React.ReactNode;
+}
+export interface StatusTagProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, keyof StatusTagPropsOwn>, StatusTagPropsOwn {}
+
+// ── Switch (switch/switch) ──
+interface SwitchPropsOwn {
+  /** Controlled value. When provided, the consumer owns the state; pair with `onCheckedChange`. */
+  checked?: boolean;
+  /** Uncontrolled initial value. Ignored when `checked` is also passed. */
+  defaultChecked?: boolean;
+  /** Called with `(nextChecked, event)` the moment the user flips the switch. */
+  onCheckedChange?: (...args: any[]) => any;
+  disabled?: boolean;
+  /** Accessible label. Required when the Switch is not paired with a visible label via `aria-labelledby` or a wrapping `<label>`. */
+  "aria-label"?: string;
+  /** ID of the element that names this Switch. Mutually exclusive with `aria-label`. */
+  "aria-labelledby"?: string;
+  /** Docs-only — pins the switch to a single visual state via `data-force-state`. Not for production use. */
+  forcedState?: "hovered" | "pressed" | "focused";
+}
+export interface SwitchProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof SwitchPropsOwn>, SwitchPropsOwn {}
+
+// ── TabBar (tab-bar/tab-bar) ──
+interface TabBarPropsOwn {
+  /** Array of destinations: { value, label, icon, activeIcon?, href?, onClick?, appearance? }. */
+  items: React.ReactNode;
+  /** Currently active destination's `value`. The matching item renders with the active treatment (filled icon + onSurface). */
+  value?: string;
+  /** (value) => void. Fires when an item is tapped, after the item's own onClick (suppressed if the click was default-prevented). */
+  onChange?: (...args: any[]) => any;
+  /** Accessible name for the nav landmark. Defaults to 'Primary'. */
+  "aria-label"?: string;
+}
+export interface TabBarProps extends Omit<React.HTMLAttributes<HTMLElement>, keyof TabBarPropsOwn>, TabBarPropsOwn {}
+
+// ── Tabs (multi-sub: underline, rounded, segmented) ──
+interface TabsUnderlinePropsOwn {
+  variant?: "underline";
+  /** The active tab's value. */
+  value: string;
+  /** Fired with the next value when a tab is selected. */
+  onChange: (...args: any[]) => any;
+  /** Accessible name for the tablist. */
+  "aria-label": string;
+  /** Composition mode flag. When `true` (or when Tabs is a direct child of `.chorus-carousel` / `.chorus-feed`), enters **embedded mode**: zeroes its own `background` + `padding` so chrome defers to the host. Pass explicitly inside `<Carousel>` / `<Feed>` for the contract to be visible in JSX; the DOM-ancestry safety net in styles.css also activates the mode when omitted. See `compositionModes` in `tabs.family.json`. */
+  embedded?: boolean;
+}
+export interface TabsUnderlineProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof TabsUnderlinePropsOwn>, TabsUnderlinePropsOwn {}
+
+interface TabsRoundedPropsOwn {
+  variant: "rounded";
+  /** The active tab's value. */
+  value: string;
+  /** Fired with the next value when a tab is selected. */
+  onChange: (...args: any[]) => any;
+  /** Accessible name for the tablist. */
+  "aria-label": string;
+  /** Composition mode flag. When `true` (or when Tabs is a direct child of `.chorus-carousel` / `.chorus-feed`), enters **embedded mode**: zeroes its own `background` + `padding` so chrome defers to the host. Pass explicitly inside `<Carousel>` / `<Feed>` for the contract to be visible in JSX; the DOM-ancestry safety net in styles.css also activates the mode when omitted. See `compositionModes` in `tabs.family.json`. */
+  embedded?: boolean;
+}
+export interface TabsRoundedProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof TabsRoundedPropsOwn>, TabsRoundedPropsOwn {}
+
+interface TabsSegmentedPropsOwn {
+  variant: "segmented";
+  /** The active segment's value. */
+  value: string;
+  /** Fired with the next value when a segment is selected. */
+  onChange: (...args: any[]) => any;
+  /** Accessible name for the tablist. */
+  "aria-label": string;
+  /** Composition mode flag. When `true` (or when Tabs is a direct child of `.chorus-carousel` / `.chorus-feed`), enters **embedded mode**: zeroes its own `background` + `padding` so chrome defers to the host. Pass explicitly inside `<Carousel>` / `<Feed>` for the contract to be visible in JSX; the DOM-ancestry safety net in styles.css also activates the mode when omitted. See `compositionModes` in `tabs.family.json`. */
+  embedded?: boolean;
+}
+export interface TabsSegmentedProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof TabsSegmentedPropsOwn>, TabsSegmentedPropsOwn {}
+
+export type TabsProps =
+  | TabsUnderlineProps
+  | TabsRoundedProps
+  | TabsSegmentedProps;
+
+// ── Thumbnail (thumbnail/thumbnail) ──
+interface ThumbnailPropsOwn {
+  size?: 56 | 48 | 40 | 32 | 24 | 20 | 16;
+  /** URL of the image asset that fills the circular slot — a raster (PNG / JPG / WebP) or vector (SVG) source. Required for the rendered form; the prop is technically optional because the Thumbnail also has a defined `surfaceContainerHigh` fallback, but any production composition is expected to pass a real asset. When generating mock or scaffold compositions without a real channel / author image, use the bundled placeholder asset at `/placeholder.png` rather than omitting `src` — the empty-surface fallback is for runtime load failures, not for design-time scaffolding. */
+  src?: string;
+  alt: string;
+  updateDot?: boolean;
+  /** { src, alt } — 16×16 circular badge at the bottom-right. */
+  logoBadge?: Record<string, unknown>;
+  /** When `true`, paints a 2-token-wide `sys.color.surface` outline around the Thumbnail container as an outset halo. The outline reads as an isolation ring that separates the Thumbnail's circular edge from anything visually noisy underneath it. Painted as `box-shadow: 0 0 0 sys.borderWidth.thin sys.color.surface` so it never reflows the slot's intrinsic diameter — same no-layout-stroke idiom the rest of the system uses. Pair with hosts whose chrome reads as a `surface*` tier (so the halo blends in) and whose backdrop differs from that tier (so the halo actually separates). */
+  outlined?: boolean;
+}
+export interface ThumbnailProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof ThumbnailPropsOwn>, ThumbnailPropsOwn {}
+
+// ── Toast (toast/toast) ──
+interface ToastPropsOwn {
+  /** Body text — short confirmation phrase. Single line by intent; wraps within the toast when the viewport forces it. */
+  children: React.ReactNode;
+  /** A Button node rendered at the trailing edge. The canonical bindings are `<Button variant="text" size="small" appearance="inverse">` for an action (Undo, View, Retry) or `<Button variant="icon" size="medium" appearance="inverse">` for explicit dismissal. Accepts a node (rather than a shorthand object) so the call site spells out the sub-component composition — including its `appearance="inverse"` binding — instead of hiding it inside the Toast. */
+  trailing?: React.ReactNode;
+}
+export interface ToastProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof ToastPropsOwn>, ToastPropsOwn {}
+
+// ── Tooltip (tooltip/tooltip) ──
+interface TooltipPropsOwn {
+  /** Body text — a short, essential hint or label. The bubble's width is content-driven (it hugs the body) and capped at 300; copy should stay brief and intuitive at a glance — a fragment, a one-line hint, an action label. The 300 cap is a safety backstop, not a target; if the message routinely fills it, it likely belongs in a Banner or Dialog. */
+  children: React.ReactNode;
+  /** `default` paints the bubble in `primary` with an `onPrimary` foreground — the brand-blue tooltip. `inverse` paints in the inverse cluster (`inverseSurface` / `inverseOnSurface`) for use on screens already saturated with primary tone, where the brand-blue bubble would compete with the surrounding chrome. */
+  appearance?: "default" | "inverse";
+  /** Where the bubble sits relative to its trigger. The `<edge>` axis (top / bottom) chooses whether the bubble floats above or below the trigger and which edge the caret renders on. The `<align>` axis (start / center / end) shifts the caret along the parallel axis so it lines up with an off-centre trigger — pick `-start` when the trigger sits near the leading edge of the viewport, `-end` when it sits near the trailing edge, and the bare edge name when the trigger is comfortably centred. Left/right placements are intentionally not in the enum — Tooltip is a top/bottom affordance; for side-anchored disclosure surfaces reach for a popover-style host instead. */
+  placement?: "top-start" | "top" | "top-end" | "bottom-start" | "bottom" | "bottom-end";
+  /** Optional Button node rendered after the body. Canonical bindings: `<Button variant="text" size="small" appearance="onPrimary">` for the `default` (primary) tooltip, or `<Button variant="text" size="small" appearance="inverse">` for the `inverse` tooltip — so the label paints in the correct on-host token in either theme. Layout: inline-trailing when the body fits on one line; stacks below the body once the body wraps. */
+  action?: React.ReactNode;
+}
+export interface TooltipProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof TooltipPropsOwn>, TooltipPropsOwn {}
+
+// ── Exports without a spec ── (wrappers/groups; permissive until specced)
+export interface TabProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
+export interface FeedGroupProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
+export interface FormFieldGroupProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
+export interface PageShellProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
+export interface NavCardGroupProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
+export interface CarouselProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
+export interface SideSheetGroupProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
+export interface SkeletonGroupProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
+export interface AccordionProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
+
+export const Badge: React.ForwardRefExoticComponent<BadgeProps & React.RefAttributes<HTMLSpanElement>>;
+export const Banner: React.ForwardRefExoticComponent<BannerProps & React.RefAttributes<HTMLDivElement>>;
+export const BottomSheet: React.ForwardRefExoticComponent<BottomSheetProps & React.RefAttributes<HTMLDivElement>>;
+export const Bubble: React.ForwardRefExoticComponent<BubbleProps & React.RefAttributes<HTMLDivElement>>;
+export const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export const Fab: React.ForwardRefExoticComponent<FabProps & React.RefAttributes<HTMLButtonElement>>;
+export const SuggestionList: React.ForwardRefExoticComponent<SuggestionListProps & React.RefAttributes<HTMLDivElement>>;
+export const AvatarRail: React.ForwardRefExoticComponent<AvatarRailProps & React.RefAttributes<HTMLDivElement>>;
+export const Chip: React.ForwardRefExoticComponent<ChipProps & React.RefAttributes<HTMLElement>>;
+export const Dialog: React.ForwardRefExoticComponent<DialogProps & React.RefAttributes<HTMLDivElement>>;
+export const Divider: React.ForwardRefExoticComponent<DividerProps & React.RefAttributes<HTMLElement>>;
+export const DirectoryList: React.ForwardRefExoticComponent<DirectoryListProps & React.RefAttributes<HTMLElement>>;
+export const Feed: React.ForwardRefExoticComponent<FeedProps & React.RefAttributes<HTMLElement>>;
+export const FeedAd: React.ForwardRefExoticComponent<FeedAdProps & React.RefAttributes<HTMLElement>>;
+export const FormField: React.ForwardRefExoticComponent<FormFieldProps & React.RefAttributes<HTMLElement>>;
+export const Header: React.ForwardRefExoticComponent<HeaderProps & React.RefAttributes<HTMLElement>>;
+export const SubHeader: React.ForwardRefExoticComponent<SubHeaderProps & React.RefAttributes<HTMLElement>>;
+export const List: React.ForwardRefExoticComponent<ListProps & React.RefAttributes<HTMLElement>>;
+export const Metadata: React.ForwardRefExoticComponent<MetadataProps & React.RefAttributes<HTMLDivElement>>;
+export const NavCard: React.ForwardRefExoticComponent<NavCardProps & React.RefAttributes<HTMLButtonElement>>;
+export const NavList: React.ForwardRefExoticComponent<NavListProps & React.RefAttributes<HTMLElement>>;
+export const NavigationBar: React.ForwardRefExoticComponent<NavigationBarProps & React.RefAttributes<HTMLElement>>;
+export const ProfileHeader: React.ForwardRefExoticComponent<ProfileHeaderProps & React.RefAttributes<HTMLElement>>;
+export const Progress: React.ForwardRefExoticComponent<ProgressProps & React.RefAttributes<HTMLDivElement>>;
+export const PostCarousel: React.ForwardRefExoticComponent<PostCarouselProps & React.RefAttributes<HTMLDivElement>>;
+export const ProfileCarousel: React.ForwardRefExoticComponent<ProfileCarouselProps & React.RefAttributes<HTMLDivElement>>;
+export const SideSheet: React.ForwardRefExoticComponent<SideSheetProps & React.RefAttributes<HTMLElement>>;
+export const Skeleton: React.ForwardRefExoticComponent<SkeletonProps & React.RefAttributes<HTMLSpanElement>>;
+export const StatusTag: React.ForwardRefExoticComponent<StatusTagProps & React.RefAttributes<HTMLSpanElement>>;
+export const Switch: React.ForwardRefExoticComponent<SwitchProps & React.RefAttributes<HTMLButtonElement>>;
+export const TabBar: React.ForwardRefExoticComponent<TabBarProps & React.RefAttributes<HTMLElement>>;
+export const Tabs: React.ForwardRefExoticComponent<TabsProps & React.RefAttributes<HTMLDivElement>>;
+export const Thumbnail: React.ForwardRefExoticComponent<ThumbnailProps & React.RefAttributes<HTMLDivElement>>;
+export const Toast: React.ForwardRefExoticComponent<ToastProps & React.RefAttributes<HTMLDivElement>>;
+export const Tooltip: React.ForwardRefExoticComponent<TooltipProps & React.RefAttributes<HTMLDivElement>>;
+export const Tab: React.ForwardRefExoticComponent<TabProps & React.RefAttributes<HTMLElement>>;
+export const FeedGroup: React.ForwardRefExoticComponent<FeedGroupProps & React.RefAttributes<HTMLElement>>;
+export const FormFieldGroup: React.ForwardRefExoticComponent<FormFieldGroupProps & React.RefAttributes<HTMLElement>>;
+export const PageShell: React.ForwardRefExoticComponent<PageShellProps & React.RefAttributes<HTMLElement>>;
+export const NavCardGroup: React.ForwardRefExoticComponent<NavCardGroupProps & React.RefAttributes<HTMLElement>>;
+export const Carousel: React.ForwardRefExoticComponent<CarouselProps & React.RefAttributes<HTMLElement>>;
+export const SideSheetGroup: React.ForwardRefExoticComponent<SideSheetGroupProps & React.RefAttributes<HTMLElement>>;
+export const SkeletonGroup: React.ForwardRefExoticComponent<SkeletonGroupProps & React.RefAttributes<HTMLElement>>;
+export const Accordion: React.ForwardRefExoticComponent<AccordionProps & React.RefAttributes<HTMLElement>>;
+
+// ── Aliases ── (additional export names declared via spec.exportAlias).
+// Each alias drops the `variant` discriminator — the runtime wrapper locks it,
+// so consumers don't need to repeat the variant in JSX.
+export type AlertProps = Omit<BannerProps, "variant">;
+export const Alert: React.ForwardRefExoticComponent<AlertProps & React.RefAttributes<HTMLDivElement>>;
+export type SheetProps = Omit<BottomSheetProps, "variant">;
+export const Sheet: React.ForwardRefExoticComponent<SheetProps & React.RefAttributes<HTMLDivElement>>;
+export type DrawerProps = Omit<BottomSheetProps, "variant">;
+export const Drawer: React.ForwardRefExoticComponent<DrawerProps & React.RefAttributes<HTMLDivElement>>;
+export type ChannelListProps = Omit<SuggestionListProps, "variant">;
+export const ChannelList: React.ForwardRefExoticComponent<ChannelListProps & React.RefAttributes<HTMLDivElement>>;
+export type ChannelRailProps = Omit<AvatarRailProps, "variant">;
+export const ChannelRail: React.ForwardRefExoticComponent<ChannelRailProps & React.RefAttributes<HTMLDivElement>>;
+export type InputProps = Omit<FormFieldInputProps, "variant">;
+export const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement>>;
+export type TextareaProps = Omit<FormFieldTextareaProps, "variant">;
+export const Textarea: React.ForwardRefExoticComponent<TextareaProps & React.RefAttributes<HTMLElement>>;
+export type SearchBarProps = Omit<FormFieldSearchProps, "variant">;
+export const SearchBar: React.ForwardRefExoticComponent<SearchBarProps & React.RefAttributes<HTMLInputElement>>;
+export type SelectProps = Omit<FormFieldSelectProps, "variant">;
+export const Select: React.ForwardRefExoticComponent<SelectProps & React.RefAttributes<HTMLDivElement>>;
+export type AppBarProps = Omit<NavigationBarMainProps, "variant">;
+export const AppBar: React.ForwardRefExoticComponent<AppBarProps & React.RefAttributes<HTMLElement>>;
+export type SideDrawerProps = Omit<SideSheetProps, "variant">;
+export const SideDrawer: React.ForwardRefExoticComponent<SideDrawerProps & React.RefAttributes<HTMLElement>>;
+export type BottomNavProps = Omit<TabBarProps, "variant">;
+export const BottomNav: React.ForwardRefExoticComponent<BottomNavProps & React.RefAttributes<HTMLElement>>;
+export type AvatarProps = Omit<ThumbnailProps, "variant">;
+export const Avatar: React.ForwardRefExoticComponent<AvatarProps & React.RefAttributes<HTMLDivElement>>;