@hirobius/design-system 0.18.0 → 0.19.0

package/dist/types/src/app/components/metric-tiles.d.ts

@@ -0,0 +1,40 @@
+/**
+ * MetricTiles - the default row of headline numbers on a screen.
+ * @category Display
+ * @tier pattern
+ */
+import * as React from 'react';
+/** Fixed feedback vocabulary for the value colour. */
+export type MetricTileTone = 'neutral' | 'success' | 'warning' | 'danger' | 'info';
+/** @public */
+export interface MetricTileProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** Eyebrow label (for example "Open tasks"). */
+    label: React.ReactNode;
+    /** The headline number, set in the `heading2` type style. */
+    value: React.ReactNode;
+    /** Caption beneath the value. Its line is reserved even when this is absent. */
+    sub?: React.ReactNode;
+    /** Colours the value from the feedback vocabulary. Defaults to neutral. */
+    tone?: MetricTileTone;
+}
+/**
+ * One metric tile: eyebrow label, `heading2` value, caption sub line, on a raised
+ * surface at one fixed min-height. Wraps `Card.Metric` (the sibling with the
+ * eyebrow / h2 / caption scale) and adds the surface and the fixed height, so a
+ * tile needs no enclosing `Card`.
+ */
+export declare const MetricTile: React.ForwardRefExoticComponent<MetricTileProps & React.RefAttributes<HTMLDivElement>>;
+/** @public */
+export interface MetricTilesProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** `MetricTile` children. Fragments are looked through when counting tiles. */
+    children: React.ReactNode;
+}
+/**
+ * A row of `MetricTile`s. The grid has `min(tiles, 4)` columns, so three tiles
+ * fill three columns and never leave an empty fourth. The default for any row of
+ * headline numbers on a screen; use `Stat` only for an inline number inside prose
+ * or a dense list, `Card.Metric` only inside an existing `Card`, and `StatusTile`
+ * for state with notes (never a number).
+ * @screenPattern
+ */
+export declare const MetricTiles: React.ForwardRefExoticComponent<MetricTilesProps & React.RefAttributes<HTMLDivElement>>;

package/dist/types/src/app/components/page-header.d.ts

@@ -0,0 +1,34 @@
+/**
+ * PageHeader - the one header every screen opens with.
+ * @category Layout
+ * @tier pattern
+ */
+import * as React from 'react';
+/** @public */
+export type PageHeaderLevel = 1 | 2 | 3 | 4 | 5 | 6;
+/** @public */
+export interface PageHeaderProps extends Omit<React.HTMLAttributes<HTMLElement>, 'title'> {
+    /** Trail above the title (a `Breadcrumb`). Omit on a top-level screen. */
+    breadcrumb?: React.ReactNode;
+    /** The screen title. Always set in the `heading2` type style; there is no size prop. */
+    title: React.ReactNode;
+    /** Status marker beside the title (a `Badge`). One marker, not a row of them. */
+    status?: React.ReactNode;
+    /** Screen-level actions, right-aligned; they wrap below the title on narrow widths. */
+    actions?: React.ReactNode;
+    /**
+     * Heading element for the title. Changes only the DOM element, never the size:
+     * the size is fixed at `heading2` so every screen reads at the same scale.
+     * Defaults to 1; a screen has exactly one `PageHeader`.
+     */
+    level?: PageHeaderLevel;
+}
+/**
+ * Screen header: breadcrumb slot, the title at the one canonical page-title size
+ * (`heading2`), a status slot and an actions slot. Every screen has exactly one.
+ * `display` and `h1` type are reserved for marketing and landing surfaces.
+ *
+ * Distinct from the docs-only page header in `src/docs-tooling`.
+ * @screenPattern
+ */
+export declare const PageHeader: React.ForwardRefExoticComponent<PageHeaderProps & React.RefAttributes<HTMLElement>>;

package/dist/types/src/app/components/pagination.d.ts

@@ -2,6 +2,9 @@
  * Pagination - paged navigation control with truncation.
  * @category Navigation
  * @tier pattern
+ * @usage Move between pages of a long result set, with truncated page numbers.
+ * @whenNot A hierarchy trail, or a short list that fits on one page.
+ * @useInstead Breadcrumb a hierarchy trail
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=86-194
  */
 import * as React from 'react';

package/dist/types/src/app/components/popover.d.ts

@@ -28,8 +28,20 @@ declare const PopoverTrigger: React.ForwardRefExoticComponent<PopoverPrimitive.P
 declare const PopoverAnchor: React.ForwardRefExoticComponent<PopoverPrimitive.PopoverAnchorProps & React.RefAttributes<HTMLDivElement>>;
 declare const PopoverClose: React.ForwardRefExoticComponent<PopoverPrimitive.PopoverCloseProps & React.RefAttributes<HTMLButtonElement>>;
 /** @public */
-export type PopoverContentProps = React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>;
-declare const PopoverContent: React.ForwardRefExoticComponent<Omit<PopoverPrimitive.PopoverContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export type PopoverContentProps = React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content> & {
+    /**
+     * Element to portal into. Defaults to the nearest `data-hds` scope, so the
+     * overlay inherits its theme; pass `null` to use `document.body`.
+     */
+    container?: HTMLElement | null;
+};
+declare const PopoverContent: React.ForwardRefExoticComponent<Omit<PopoverPrimitive.PopoverContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
+    /**
+     * Element to portal into. Defaults to the nearest `data-hds` scope, so the
+     * overlay inherits its theme; pass `null` to use `document.body`.
+     */
+    container?: HTMLElement | null;
+} & React.RefAttributes<HTMLDivElement>>;
 interface PopoverComponent extends React.FC<React.ComponentProps<typeof PopoverPrimitive.Root>> {
     Trigger: typeof PopoverTrigger;
     Anchor: typeof PopoverAnchor;

package/dist/types/src/app/components/progress.d.ts

@@ -2,6 +2,10 @@
  * Progress - linear progress bar (determinate or indeterminate).
  * @category Feedback
  * @tier primitive
+ * @usage Show how far a task has got, as a bar that is determinate or indeterminate.
+ * @whenNot A wait of unknown length with no bar, or content that is still loading.
+ * @useInstead Spinner a wait of unknown length
+ * @useInstead Skeleton placeholder shapes for loading content
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-91
  */
 import * as React from 'react';

package/dist/types/src/app/components/radio.d.ts

@@ -2,6 +2,11 @@
  * Radio — radio button with animated selection indicator.
  * @category Inputs
  * @tier primitive
+ * @usage Choose exactly one option from a small set that should stay visible together.
+ * @whenNot Independent yes/no options, or a long list of options.
+ * @useInstead Checkbox independent options that can be ticked together
+ * @useInstead Select a long list that can collapse into a dropdown
+ * @useInstead SegmentedControl a compact switch between two to five views or modes
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=36-17
  */
 import type { InputHTMLAttributes } from 'react';

package/dist/types/src/app/components/select.d.ts

@@ -2,6 +2,17 @@
  * Select — dropdown selector built on Radix Select.
  * @category Inputs
  * @tier primitive
+ * @usage Choose one value from a short list of options in a form field.
+ * @whenNot Firing actions, or choosing from a list long enough to need search.
+ * @useInstead Menu firing actions from a trigger
+ * @useInstead Combobox a long list that needs search
+ * @keyboard Enter/Space/ArrowDown Opens the listbox from the trigger with the selected option highlighted.
+ * @keyboard ArrowDown/ArrowUp Moves the highlight.
+ * @keyboard Home/End Jumps to the first or last option.
+ * @keyboard Character Highlights the option that matches the typed letters.
+ * @keyboard Enter Commits the highlighted option and returns focus to the trigger.
+ * @keyboard Escape Closes the listbox and returns focus to the trigger.
+ * @keyboard Tab Does not leave the open listbox.
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=82-49
  */
 /**
@@ -25,5 +36,10 @@ export interface SelectProps {
     value: string;
     /** Called when the user picks a different option. */
     onChange: (v: string) => void;
+    /**
+     * Element to portal into. Defaults to the nearest `data-hds` scope, so the
+     * overlay inherits its theme; pass `null` to use `document.body`.
+     */
+    container?: HTMLElement | null;
 }
 export declare const Select: import("react").ForwardRefExoticComponent<SelectProps & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/types/src/app/components/skeleton.d.ts

@@ -2,6 +2,10 @@
  * Skeleton - placeholder shimmer for content that is still loading.
  * @category Feedback
  * @tier primitive
+ * @usage Reserve the shape of content that is still loading, so the layout does not jump.
+ * @whenNot A task with measurable progress, or a wait with no layout to reserve.
+ * @useInstead Progress a task with measurable progress
+ * @useInstead Spinner a short wait with no layout to reserve
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-95
  */
 import * as React from 'react';

package/dist/types/src/app/components/slider.d.ts

@@ -2,6 +2,9 @@
  * Slider — range slider with label and value display.
  * @category Inputs
  * @tier primitive
+ * @usage Pick a number within a known range by dragging, when the exact value matters less than the position.
+ * @whenNot A precise number the person must type or read exactly.
+ * @useInstead Input a precise typed value (type="number")
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=82-265
  */
 /** Slider — range slider with label and value display. */

package/dist/types/src/app/components/spinner.d.ts

@@ -2,6 +2,10 @@
  * Spinner - indeterminate loading indicator.
  * @category Feedback
  * @tier primitive
+ * @usage Show that something is loading when the wait is short or has no measurable end.
+ * @whenNot A task with measurable progress, or a region whose layout is known.
+ * @useInstead Progress a task with measurable progress
+ * @useInstead Skeleton a region whose layout is known
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-106
  */
 import * as React from 'react';

package/dist/types/src/app/components/stack.d.ts

@@ -2,6 +2,10 @@
  * Stack — one-dimensional layout primitive.
  * @category Layout
  * @tier primitive
+ * @usage Space a row or column of content with token gaps and simple flex alignment.
+ * @whenNot Multi-column layout, or giving content a background or padding.
+ * @useInstead Grid multi-column layout
+ * @useInstead Surface content that needs a background or padding
  * @ai-intent Solves vertical and horizontal rhythm with tokenized flex gaps so agents can compose sequences of content without inventing ad hoc spacer divs or margin-based stacking.
  * @ai-rules Use Stack for flow spacing and simple flex alignment only. Do NOT use Stack to create card chrome, internal surface padding, or page-width constraints. Do NOT apply arbitrary margins to Stack to fake spacing between children when the gap prop should own that rhythm. Do NOT use Stack for true two-dimensional layouts that require Grid.
  */

package/dist/types/src/app/components/stat.d.ts

@@ -17,6 +17,10 @@ export interface StatProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'c
 }
 /**
  * Headline metric — large value, uppercase caption label, optional sub-line.
+ * @usage Show one standalone headline figure with its label and an optional sub-line.
+ * @whenNot A figure inside a Card, or a status with a trailing badge.
+ * @useInstead Card.Metric a figure inside a Card (hds#254 folds Stat into the Card slot)
+ * @useInstead StatusTile a titled status with notes and a trailing badge
  */
 export declare const Stat: React.ForwardRefExoticComponent<StatProps & React.RefAttributes<HTMLDivElement>>;
 /** @internal — CVA variant helper; compose via Stat props instead. */

package/dist/types/src/app/components/status-tile.d.ts

@@ -19,5 +19,9 @@ export interface StatusTileProps extends Omit<React.HTMLAttributes<HTMLDivElemen
  * Status colour belongs in the trailing slot, never as a left rule on the tile
  * — every tile should look the same so feedback signals stay reserved for
  * genuinely interrupting states.
+ * @usage Show a titled status block with optional notes and a trailing badge or affordance.
+ * @whenNot A single headline figure, or a row inside a list.
+ * @useInstead Card.Metric a headline figure (hds#254 folds StatusTile into the Card slot)
+ * @useInstead StatusListItem a status row inside a list
  */
 export declare const StatusTile: React.ForwardRefExoticComponent<StatusTileProps & React.RefAttributes<HTMLDivElement>>;

package/dist/types/src/app/components/table.d.ts

@@ -2,12 +2,16 @@
  * Table - structured data table primitive for documentation and compact UI matrices.
  * @category Display
  * @tier primitive
+ * @usage Show rows of structured data in aligned columns, with optional sorting.
+ * @whenNot A single record, a short list of links, or content that reflows as cards.
+ * @useInstead Field one record as label and value pairs
+ * @useInstead Stack a short list of items
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=89-300
  */
 import { type ReactNode } from 'react';
 declare const tableHeaderCellVariants: (props?: ({
     align?: "center" | "left" | "right" | null | undefined;
-    density?: "compact" | "comfortable" | null | undefined;
+    density?: "compact" | "comfortable" | "follow" | null | undefined;
     sticky?: boolean | null | undefined;
 } & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
 declare const tableSortButtonVariants: (props?: ({
@@ -15,7 +19,7 @@ declare const tableSortButtonVariants: (props?: ({
 } & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
 declare const tableDataCellVariants: (props?: ({
     align?: "center" | "left" | "right" | null | undefined;
-    density?: "compact" | "comfortable" | null | undefined;
+    density?: "compact" | "comfortable" | "follow" | null | undefined;
     divider?: boolean | null | undefined;
 } & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
 /** @public */
@@ -34,7 +38,25 @@ export type TableColumn = {
     /** Called when the sort button is activated (click, Enter, or Space). */
     onSort?: () => void;
 };
-export type TableCellSlot = 'label' | 'value' | 'description' | 'token' | 'code' | 'custom' | 'icon' | 'badge' | 'action';
+export type TableCellSlot = 
+/** UI text: the row label. */
+'label'
+/** Renders in monospace: a literal value. */
+ | 'value'
+/** Secondary-colour caption text explaining the row. */
+ | 'description'
+/** Renders in monospace: a token name. */
+ | 'token'
+/** Renders in monospace: a code snippet. */
+ | 'code'
+/** UI text: arbitrary content you supply. */
+ | 'custom'
+/** Caption-size text: an icon or glyph. */
+ | 'icon'
+/** Caption-size text: a status badge. */
+ | 'badge'
+/** UI text: a button or link. */
+ | 'action';
 export type TableCell = {
     slot: TableCellSlot;
     content: ReactNode;
@@ -47,14 +69,24 @@ export type TableRow = {
     cells: TableCell[];
 };
 type TableDensity = 'compact' | 'comfortable';
-export declare function Table({ columns, rows, caption, captionAction, description, minWidth, density, flush, stickyHeader, }: {
+export declare function Table({ columns, rows, caption, captionAction, description, labelledBy, minWidth, density, flush, stickyHeader, }: {
     columns: TableColumn[];
     rows: TableRow[];
     caption?: ReactNode;
     /** Optional action rendered to the right of the caption. */
     captionAction?: ReactNode;
     description?: ReactNode;
+    /**
+     * Id of an element that names the table when there is no `caption`. Applied to
+     * the `role="table"` element, and to the scroll region together with its own
+     * label so two tables on one screen keep distinct region names.
+     */
+    labelledBy?: string;
     minWidth?: number | string;
+    /**
+     * Row density. Omit it to follow the ancestor `data-density` dial (comfortable by
+     * default, compact inside `[data-density="compact"]`); pass a value to fix it.
+     */
     density?: TableDensity;
     flush?: boolean;
     stickyHeader?: boolean;

package/dist/types/src/app/components/tabs.d.ts

@@ -25,6 +25,10 @@ import * as TabsPrimitive from '@radix-ui/react-tabs';
  * The tab set itself. Tagged here rather than in the file block because
  * TabsList and TabsContent share this module and have no Figma node of their
  * own — a file-level @figma would silently claim this node for all four.
+ * @usage Switch between panels of related content in the same place, one visible at a time.
+ * @whenNot A compact mode switch with no panels, or content that must all be visible.
+ * @useInstead SegmentedControl a compact switch with no panels
+ * @useInstead Disclosure optional content that expands in place
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=86-89
  */
 export declare const Tabs: import("react").ForwardRefExoticComponent<TabsPrimitive.TabsProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/types/src/app/components/tag.d.ts

@@ -2,6 +2,9 @@
  * Tag — interactive filter and category chip.
  * @category Inputs
  * @tier primitive
+ * @usage Show an interactive filter or category chip that people can toggle.
+ * @whenNot A read-only status or count label.
+ * @useInstead Badge a read-only status or count
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=32-11
  *
  * The outer <button> carries the accessible 44px hit target directly via the

package/dist/types/src/app/components/text.d.ts

@@ -3,6 +3,10 @@
  *
  * @category Typography
  * @tier primitive
+ * @usage Set any text on the type ramp, with the element chosen by `as`.
+ * @whenNot Navigation links, or a keyboard hint.
+ * @useInstead InlineLink a link inside body copy
+ * @useInstead Kbd a keyboard key hint
  * @doc-exempt: typography primitive is documented through the Typography ramp page (TypographyPage), not as a standalone component card
  */
 import { type CSSProperties, type ElementType, type HTMLAttributes, type ReactNode } from 'react';

package/dist/types/src/app/components/textarea.d.ts

@@ -2,6 +2,9 @@
  * Textarea — multi-line text field primitive with label, helper, and error slots.
  * @category Inputs
  * @tier primitive
+ * @usage Collect multi-line free text such as a message, note or description.
+ * @whenNot A single line of text, or choosing from a list.
+ * @useInstead Input a single line of text
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=85-14
  *
  * Mirrors Input's shell + token skin as a native `<textarea>`. Figma parity:

package/dist/types/src/app/components/toast.d.ts

@@ -2,6 +2,10 @@
  * Toast — transient feedback notifications (Radix Toast).
  * @category Feedback
  * @tier pattern
+ * @usage Confirm an action with a brief message that appears and dismisses itself, through useToast.
+ * @whenNot A message people must act on or that must stay next to its content.
+ * @useInstead Alert a message that stays next to its content
+ * @useInstead Dialog a message that needs a decision
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=93-367
  * @doc-exempt: no Overlays/Feedback-overlay doc page yet — add demo when created
  *

package/dist/types/src/app/components/toggle.d.ts

@@ -2,6 +2,10 @@
  * Toggle — boolean on/off toggle with animated thumb.
  * @category Inputs
  * @tier primitive
+ * @usage Switch one setting on or off, with the effect applying immediately.
+ * @whenNot A choice that only takes effect after submitting a form, or picking from several options.
+ * @useInstead Checkbox a form option confirmed on submit
+ * @useInstead Radio one choice from a set
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=37-19
  */
 import type { InputHTMLAttributes } from 'react';

package/dist/types/src/app/components/tooltip.d.ts

@@ -29,5 +29,5 @@ interface TooltipProps {
     /** Cursor Y position in client coordinates. */
     y?: number;
 }
-export declare function ExpandTooltip({ visible, mode, label, x, y }: TooltipProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ExpandTooltip({ visible, mode, label, x, y }: TooltipProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/types/src/app/components/visually-hidden.d.ts

@@ -2,6 +2,9 @@
  * VisuallyHidden — content available to assistive tech but hidden visually.
  * @category Utility
  * @tier primitive
+ * @usage Give assistive technology a label or description that sighted people do not need to see.
+ * @whenNot Text everyone should read, or hiding an element from assistive technology too.
+ * @useInstead Text text that everyone should read
  */
 import * as React from 'react';
 /** @public */

package/dist/types/src/app/context/hds-portal.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Portal container resolver for HDS overlay parts (hds#335). Internal — not
+ * exported from the package entry points.
+ *
+ * Radix `Portal` appends to `document.body`, which sits outside a
+ * `<div data-hds data-theme="dark">` scope, so overlays would render with light
+ * tokens on a dark page. Every portalled part goes through `HdsPortal` (or the
+ * `withHdsPortal` factory) so its container resolves, in order, to:
+ *
+ *   1. the caller's explicit `container` (`null` means `document.body`);
+ *   2. the element of the nearest `HdsThemeProvider`;
+ *   3. the nearest `[data-hds]` ancestor of a hidden in-place anchor, resolved
+ *      in a layout effect (covers a bare `<div data-hds>` with no provider);
+ *   4. `undefined`, which the portal treats as `document.body`.
+ *
+ * Nothing is portalled until the container is known, so an overlay never
+ * flashes into `body` first and never remounts (which would break the focus trap).
+ * The hidden anchor (`<span hidden data-hds-portal-anchor>`) stays in place, also
+ * while the overlay is closed, until a provider or explicit container makes it
+ * unnecessary. It renders on the server too so the first client render hydrates
+ * cleanly. It takes no space, but is one extra child for `:last-child` / `> *`
+ * selectors and is not valid directly inside `ul`, `table` or `tr`.
+ * A scope on `<html>` or `<body>` resolves to `undefined`: `body` already
+ * inherits it, and a node appended to `<html>` would sit outside `<body>`.
+ */
+import * as React from 'react';
+type PortalContainer = Element | DocumentFragment | null;
+interface ResolvedPortal {
+    /** False until the container is known; render no portal while false. */
+    ready: boolean;
+    /** Element to portal into, or `undefined` for `document.body`. */
+    container: HTMLElement | undefined;
+    /** Hidden in-place node the layout effect measures from; render it beside the portal. */
+    anchor: React.ReactNode;
+}
+/** Resolve where a portalled part should mount. @internal */
+export declare function useHdsPortalContainer(explicit?: HTMLElement | null): ResolvedPortal;
+/**
+ * Wrap a Radix `*.Portal` so it mounts into the resolved scope. The wrapped
+ * component keeps the original props, including `container` (explicit wins) and
+ * `forceMount`.
+ * @internal
+ */
+export declare function withHdsPortal<P extends {
+    container?: PortalContainer;
+}>(Portal: React.ComponentType<P>): React.FC<P>;
+/** Plain `createPortal` with the same container contract, for non-Radix overlays. */
+export declare const hdsDomPortal: React.FC<{
+    container?: PortalContainer;
+    children?: React.ReactNode;
+}>;
+export {};

package/dist/types/src/app/context/hds-theme.d.ts

@@ -2,6 +2,9 @@
  * HdsThemeProvider — framework-agnostic theming contract for HDS.
  * @category Theming
  * @tier primitive
+ * @usage Wrap an app or region once to set theme, density and other root attributes for everything inside it.
+ * @whenNot Styling a single component, or per-component overrides.
+ * @useInstead Surface a single region with its own background
  * @doc-exempt: API/contract primitive, documented in README (no doc page yet)
  *
  * HDS theming is driven entirely by root attributes + CSS custom properties, so
@@ -46,6 +49,13 @@ export interface HdsThemeValue {
     /** Monospace font-family override (`--hds-font-family-mono`). */
     fontFamilyMono?: string;
 }
+/**
+ * The nearest HdsThemeProvider's `data-hds` wrapper element, for overlay parts
+ * to portal into (hds#335). `null` until the wrapper mounts, and outside any
+ * provider.
+ * @internal
+ */
+export declare function useHdsScope(): HTMLElement | null;
 /**
  * Read the nearest HdsThemeProvider's active dial values. Returns an empty
  * object when no provider is present (styles still work off the defaults).

package/dist/types/src/app/data/manifest-types.d.ts

@@ -24,9 +24,25 @@ export type ManifestPropSpec = {
     default?: string | number | boolean;
     optional?: boolean;
 };
+/** Contract parsed from the @usage / @whenNot / @useInstead JSDoc tags (hds#339). */
+export type ManifestUsage = {
+    when?: string;
+    whenNot?: string;
+    useInstead?: Array<{
+        component: string;
+        reason?: string;
+    }>;
+};
+/** One @keyboard JSDoc line: the keys and what they do. */
+export type ManifestKeyboardEntry = {
+    keys: string;
+    effect: string;
+};
 /** A named slot declared on a component spec. */
 export type ManifestSlot = {
     name?: string;
+    description?: string;
+    source?: 'jsdoc';
     figmaSlotName?: string;
     tokenBinding?: Record<string, string>;
 };
@@ -74,6 +90,9 @@ export type ManifestComponentSpec = {
     propConstraints?: Record<string, ManifestPropSpec | Record<string, unknown>>;
     requiredProps?: string[];
     slots?: ManifestSlot[];
+    usage?: ManifestUsage;
+    keyboard?: ManifestKeyboardEntry[];
+    aiRules?: string;
 };
 /**
  * Alias of ManifestComponentSpec for hds-search.ts back-compat.
@@ -109,8 +128,16 @@ export type ManifestApiComponent = {
     hidden?: boolean;
     figmaUrl?: string | null;
     description?: string;
+    usage?: ManifestUsage;
+    keyboard?: ManifestKeyboardEntry[];
+    aiRules?: string;
     /** Documentation prop rows — array, not a Record. */
     props?: ManifestApiPropRow[];
+    /** Table only: what each `TableCellSlot` value renders. */
+    cellSlots?: Array<{
+        name: string;
+        description: string;
+    }>;
     guides?: Array<{
         label: string;
         text: string;

package/dist/types/src/app/design-system/generated-token-refs.d.ts

@@ -259,6 +259,7 @@ export declare const tokenRefs: {
                 readonly page: "var(--semantic-color-surface-page)";
                 readonly raised: "var(--semantic-color-surface-raised)";
                 readonly overlay: "var(--semantic-color-surface-overlay)";
+                readonly scrim: "var(--semantic-color-surface-scrim)";
                 readonly inverse: "var(--semantic-color-surface-inverse)";
                 readonly accent: "var(--semantic-color-surface-accent)";
                 readonly accentSubtle: "var(--semantic-color-surface-accentSubtle)";
@@ -639,6 +640,7 @@ export declare const tokenRefs: {
         readonly card: "var(--role-card)";
         readonly "card-foreground": "var(--role-card-foreground)";
         readonly popover: "var(--role-popover)";
+        readonly scrim: "var(--role-scrim)";
         readonly "popover-foreground": "var(--role-popover-foreground)";
         readonly primary: "var(--role-primary)";
         readonly "primary-foreground": "var(--role-primary-foreground)";

package/dist/types/src/icons.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @hirobius/design-system/icons
+ *
+ * A curated subset of Lucide (canonical 0.487.0 names) so a consumer can get
+ * an `icon` for IconButton / Icon with nothing extra to install. Bare
+ * re-export from 'lucide-react' (external in the lib build, so it tree-shakes).
+ * Legacy aliases (MoreHorizontal, MoreVertical, AlertTriangle, Home, Filter)
+ * are intentionally not exported; use Ellipsis, EllipsisVertical,
+ * TriangleAlert, House, Funnel. Add new icons one line each (hds#342).
+ * The manifest `iconSet` list is generated from this file.
+ */
+export { Ellipsis, EllipsisVertical, Plus, Minus, Pencil, Trash2, Archive, Copy, Download, Upload, Search, X, Check, ChevronDown, ChevronUp, ChevronLeft, ChevronRight, ArrowLeft, ArrowRight, ArrowUp, ArrowDown, ExternalLink, Settings, Info, TriangleAlert, CircleAlert, CircleCheck, CircleHelp, Eye, EyeOff, Funnel, Calendar, Mail, User, House, Menu, Bell, Star, Heart, Link, Lock, Share, Save, RefreshCw, LogOut, LogIn, Bookmark, Clock, FileText, Image, } from 'lucide-react';
+export type { LucideIcon } from 'lucide-react';

package/dist/types/src/index.d.ts

@@ -1123,6 +1123,18 @@ export declare const tokens: {
                         };
                     };
                 };
+                scrim: {
+                    $value: string;
+                    $description: string;
+                    $extensions: {
+                        "com.figma.variables": {
+                            modes: {
+                                Light: string;
+                                Dark: string;
+                            };
+                        };
+                    };
+                };
                 inverse: {
                     $value: string;
                     $description: string;
@@ -2590,6 +2602,11 @@ export declare const tokens: {
             $value: string;
             $description: string;
         };
+        scrim: {
+            $type: string;
+            $value: string;
+            $description: string;
+        };
         "popover-foreground": {
             $type: string;
             $value: string;
@@ -2695,7 +2712,9 @@ export declare const Carousel: import("react").ForwardRefExoticComponent<import(
 /** @deprecated Import from `@hirobius/design-system/patterns` instead — the root re-export is kept for one minor (hds#254) and removed at the next major once ops has a codemod. */
 export declare const CodeBlock: typeof _CodeBlock254;
 /** @deprecated Import from `@hirobius/design-system/patterns` instead — the root re-export is kept for one minor (hds#254) and removed at the next major once ops has a codemod. */
-export declare const CommandPalette: import("react").ForwardRefExoticComponent<import("./app/components/command-palette.js").CommandPaletteProps & import("react").RefAttributes<HTMLInputElement>>;
+export declare const CommandPalette: import("react").ForwardRefExoticComponent<import("./app/components/command-palette.js").CommandPaletteProps & import("react").RefAttributes<HTMLInputElement>> & {
+    displayName: string;
+};
 /** @deprecated Import from `@hirobius/design-system/patterns` instead — the root re-export is kept for one minor (hds#254) and removed at the next major once ops has a codemod. */
 export declare const DocLinkCard: typeof _DocLinkCard254;
 /** @deprecated Import from `@hirobius/design-system/patterns` instead — the root re-export is kept for one minor (hds#254) and removed at the next major once ops has a codemod. */

package/dist/types/src/patterns.d.ts

@@ -35,3 +35,8 @@ export * from './app/components/toolbar.js';
 export * from './app/components/command-palette.js';
 export * from './app/components/image-lightbox.js';
 export * from './app/components/reveal.js';
+export * from './app/components/page-header.js';
+export * from './app/components/metric-tiles.js';
+export * from './app/components/form-actions.js';
+export * from './app/components/destructive-section.js';
+export * from './app/components/data-table-section.js';