@hirobius/design-system 0.11.0 → 0.13.0

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

@@ -6,7 +6,12 @@
  * @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';
-type TextVariant = 'display' | 'heading1' | 'heading2' | 'heading3' | 'body' | 'ui' | 'eyebrow' | 'caption' | 'technical' | 'badge' | 'docLede' | 'docBody' | 'docSmall' | 'docCode';
+import { type VariantProps } from 'class-variance-authority';
+declare const textVariants: (props?: {
+    variant?: "display" | "caption" | "body" | "heading1" | "heading2" | "heading3" | "ui" | "eyebrow" | "technical" | "badge" | "docLede" | "docBody" | "docSmall" | "docCode";
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+type TextVariantProps = VariantProps<typeof textVariants>;
+type TextVariant = NonNullable<TextVariantProps['variant']>;
 type TextTag = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'div';
 /** @public */
 export type TextProps = {
@@ -23,4 +28,5 @@ export declare const Text: import("react").ForwardRefExoticComponent<{
     className?: string;
     style?: CSSProperties;
 } & HTMLAttributes<HTMLElement> & import("react").RefAttributes<HTMLElement>>;
-export {};
+/** @internal — CVA variant helper; compose via Text props instead. */
+export { textVariants };

package/dist/types/src/app/components/time-input.d.ts

@@ -0,0 +1,24 @@
+/**
+ * TimeInput — token-skinned time field on a native <input type="time">.
+ * @category Inputs
+ * @tier primitive
+ * @public
+ *
+ * The time-only member of the date/time family (ADR-020). It deliberately does
+ * NOT pull in the calendar dependency — a native `<input type="time">` gives the
+ * platform time picker, keyboard entry, and locale formatting for free, skinned
+ * with the same chrome as `Input`.
+ */
+import * as React from 'react';
+import { type VariantProps } from 'class-variance-authority';
+declare const hdsTimeInputVariants: (props?: {
+    size?: "sm" | "md" | "lg";
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+type TimeInputVariantProps = VariantProps<typeof hdsTimeInputVariants>;
+/** @public */
+export interface TimeInputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type' | 'size'>, TimeInputVariantProps {
+}
+/** A native time field skinned with HDS input chrome. Value is a `HH:mm` string. */
+export declare const TimeInput: React.ForwardRefExoticComponent<TimeInputProps & React.RefAttributes<HTMLInputElement>>;
+/** @internal — CVA variant helper; compose via TimeInput props instead. */
+export { hdsTimeInputVariants };

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

@@ -0,0 +1,24 @@
+/**
+ * Timestamp — renders a date/time as a semantic <time> element.
+ * @category Display
+ * @tier primitive
+ */
+import * as React from 'react';
+/** @public */
+export type TimestampFormat = 'date' | 'time' | 'datetime' | 'relative';
+/** @public */
+export interface TimestampProps extends Omit<React.TimeHTMLAttributes<HTMLTimeElement>, 'children'> {
+    /** The moment to render — a Date, epoch millis, or an ISO string. */
+    date: Date | string | number;
+    /** How to present it. Defaults to `datetime`. */
+    format?: TimestampFormat;
+    /** BCP-47 locale override; defaults to the runtime locale. */
+    locale?: string;
+    /**
+     * Reference point for `relative` formatting. Defaults to the current time;
+     * pass an explicit value for deterministic rendering/tests.
+     */
+    now?: Date | string | number;
+}
+/** Presents a date/time with a machine-readable `dateTime` for accessibility. */
+export declare const Timestamp: React.ForwardRefExoticComponent<TimestampProps & React.RefAttributes<HTMLTimeElement>>;

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

@@ -19,8 +19,13 @@
  */
 import * as React from 'react';
 import * as ToastPrimitive from '@radix-ui/react-toast';
+import { type VariantProps } from 'class-variance-authority';
+declare const toastIconVariants: (props?: {
+    tone?: "success" | "danger" | "warning" | "info" | "neutral";
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+type ToastIconVariantProps = VariantProps<typeof toastIconVariants>;
 /** @public */
-export type ToastTone = 'neutral' | 'info' | 'success' | 'danger' | 'warning';
+export type ToastTone = NonNullable<ToastIconVariantProps['tone']>;
 /** @public */
 export interface ToastOptions {
     /** Headline line — the primary message. */
@@ -53,4 +58,5 @@ export interface ToastProviderProps {
  * @public
  */
 export declare function ToastProvider({ children, duration, swipeDirection, }: ToastProviderProps): import("react/jsx-runtime").JSX.Element;
-export {};
+/** @internal — CVA variant helper; compose via ToastOptions.tone instead. */
+export { toastIconVariants };

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

@@ -0,0 +1,32 @@
+/**
+ * ToggleButton — a two-state (on/off) pressable button on Radix Toggle.
+ * @category Actions
+ * @tier primitive
+ *
+ * Radix Toggle (@radix-ui/react-toggle) themed as a button-shaped control with
+ * a native aria-pressed contract, keyboard support, and data-[state=on] active
+ * styling. Use for a single independent toggle (bold, mute, pin); for a set of
+ * mutually-related toggles reach for the segmented control instead.
+ *
+ *   <ToggleButton aria-label="Bold" pressed={bold} onPressedChange={setBold}>
+ *     <Bold />
+ *   </ToggleButton>
+ */
+import * as React from 'react';
+import * as TogglePrimitive from '@radix-ui/react-toggle';
+import { type VariantProps } from 'class-variance-authority';
+declare const hdsToggleButtonVariants: (props?: {
+    variant?: "secondary" | "ghost";
+    size?: "sm" | "md" | "lg";
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+type ToggleButtonVariantProps = VariantProps<typeof hdsToggleButtonVariants>;
+/** @public */
+export interface ToggleButtonProps extends React.ComponentPropsWithoutRef<typeof TogglePrimitive.Root>, ToggleButtonVariantProps {
+}
+/**
+ * A single two-state toggle button exposing a native `aria-pressed` contract —
+ * use for one independent on/off control such as bold, mute, or pin.
+ */
+export declare const ToggleButton: React.ForwardRefExoticComponent<ToggleButtonProps & React.RefAttributes<HTMLButtonElement>>;
+/** @internal — CVA variant helper; compose via ToggleButton props instead. */
+export { hdsToggleButtonVariants };

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

@@ -2,8 +2,32 @@
  * Token - reflective token specimen for unified node-based token views.
  * @category Display
  * @tier primitive
+ *
+ * The `variant` axis (node | diagram — diagram is a deprecated alias that
+ * resolves to the same node treatment) plus the `selected` / `fullWidth` /
+ * `asButton` / `nowrap` / `sourceNode` states used to be a
+ * Token.module.css `[data-*]` attribute stylesheet, with a duplicate
+ * `isSelected` branch re-painted inline on top of it. Both now live as one
+ * `cva` variant set — same `--semantic-*`/`--component-*`/`--primitive-*`
+ * custom properties, same pixels, no CSS module.
  */
 import React from 'react';
+declare const tokenShellVariants: (props?: {
+    variant?: "node" | "diagram";
+    sourceNode?: boolean;
+    selected?: boolean;
+    fullWidth?: boolean;
+    asButton?: boolean;
+    nowrap?: boolean;
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+declare const tokenNodeInlineVariants: (props?: {
+    sourceNode?: boolean;
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+declare const tokenLabelVariants: (props?: {
+    sourceNode?: boolean;
+    truncateFromStart?: boolean;
+    selected?: boolean;
+} & import("class-variance-authority/dist/types").ClassProp) => string;
 type TokenBaseProps = {
     className?: string;
     fullWidth?: boolean;
@@ -56,4 +80,5 @@ type TokenProps = TokenNodeSurfaceProps | TokenDiagramProps;
  */
 /** @public */
 export declare function Token(props: TokenProps): import("react/jsx-runtime").JSX.Element;
-export {};
+/** @internal — CVA variant helpers; compose via Token props instead. */
+export { tokenShellVariants, tokenNodeInlineVariants, tokenLabelVariants };

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

@@ -0,0 +1,24 @@
+/**
+ * Tokenizer — free-text token/chip input where committed entries render as
+ * removable Tag chips ahead of the live text field. Enter commits the typed
+ * draft as a new token; Backspace on an empty draft removes the trailing one.
+ * @category Inputs
+ * @tier pattern
+ * @public
+ */
+import * as React from 'react';
+/** @public */
+export interface TokenizerProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange'> {
+    /** Committed tokens rendered as chips. */
+    value: string[];
+    /** Called with the next token list whenever tokens are added or removed. */
+    onChange: (next: string[]) => void;
+    /** Placeholder shown in the trailing text field when empty. */
+    placeholder?: string;
+    /** Disable the field and all token interactions. */
+    disabled?: boolean;
+    /** Class hook for the outer wrapper. */
+    className?: string;
+}
+/** A bordered field of Tag chips followed by a text input for adding more. */
+export declare const Tokenizer: React.ForwardRefExoticComponent<TokenizerProps & React.RefAttributes<HTMLInputElement>>;

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

@@ -0,0 +1,36 @@
+/**
+ * Toolbar — horizontal container that groups related controls (buttons,
+ * toggles, separators) with a single roving tab-stop, built on Radix Toolbar.
+ * @category Actions
+ * @tier pattern
+ * @public
+ *
+ *   <Toolbar aria-label="Formatting">
+ *     <Toolbar.ToggleGroup type="single">
+ *       <Toolbar.ToggleItem value="bold">Bold</Toolbar.ToggleItem>
+ *     </Toolbar.ToggleGroup>
+ *     <Toolbar.Separator />
+ *     <Toolbar.Button>Share</Toolbar.Button>
+ *   </Toolbar>
+ */
+import * as React from 'react';
+import * as ToolbarPrimitive from '@radix-ui/react-toolbar';
+declare const ToolbarButton: React.ForwardRefExoticComponent<Omit<ToolbarPrimitive.ToolbarButtonProps & React.RefAttributes<HTMLButtonElement>, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+declare const ToolbarSeparator: React.ForwardRefExoticComponent<Omit<ToolbarPrimitive.ToolbarSeparatorProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const ToolbarToggleGroup: React.ForwardRefExoticComponent<(Omit<ToolbarPrimitive.ToolbarToggleGroupSingleProps & React.RefAttributes<HTMLDivElement>, "ref"> | Omit<ToolbarPrimitive.ToolbarToggleGroupMultipleProps & React.RefAttributes<HTMLDivElement>, "ref">) & React.RefAttributes<HTMLDivElement>>;
+declare const ToolbarToggleItem: React.ForwardRefExoticComponent<Omit<ToolbarPrimitive.ToolbarToggleItemProps & React.RefAttributes<HTMLButtonElement>, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+declare const ToolbarLink: React.ForwardRefExoticComponent<Omit<ToolbarPrimitive.ToolbarLinkProps & React.RefAttributes<HTMLAnchorElement>, "ref"> & React.RefAttributes<HTMLAnchorElement>>;
+interface ToolbarComponent extends React.FC<React.ComponentProps<typeof ToolbarPrimitive.Root>> {
+    Button: typeof ToolbarButton;
+    Separator: typeof ToolbarSeparator;
+    ToggleGroup: typeof ToolbarToggleGroup;
+    ToggleItem: typeof ToolbarToggleItem;
+    Link: typeof ToolbarLink;
+}
+/**
+ * Toolbar root. Groups related controls with a single roving tab-stop.
+ * Supports the native `orientation` prop (`horizontal` | `vertical`).
+ * @public
+ */
+export declare const Toolbar: ToolbarComponent;
+export {};

package/dist/types/src/app/components/top-nav.d.ts

@@ -0,0 +1,21 @@
+/**
+ * TopNav — top-of-page navigation bar with brand, nav links, and trailing
+ * actions rendered as a semantic <header> row, optionally sticky to the top.
+ * @category Navigation
+ * @tier pattern
+ * @public
+ */
+import * as React from 'react';
+/** @public */
+export interface TopNavProps extends React.HTMLAttributes<HTMLElement> {
+    /** Leading brand slot (e.g. logo/wordmark). */
+    brand?: React.ReactNode;
+    /** Nav links, placed left after the brand and wrapped in a <nav>. */
+    children?: React.ReactNode;
+    /** Trailing actions, pushed to the far right. */
+    trailing?: React.ReactNode;
+    /** Pins the bar to the top of its scroll container. */
+    sticky?: boolean;
+}
+/** Top navigation bar with brand, nav, and trailing action slots. */
+export declare const TopNav: React.ForwardRefExoticComponent<TopNavProps & React.RefAttributes<HTMLElement>>;

package/dist/types/src/app/components/tree-list.d.ts

@@ -0,0 +1,28 @@
+/**
+ * TreeList - a hierarchical, expandable list with correct tree ARIA semantics
+ * for browsing nested navigation, file, or content structures.
+ * @category Navigation
+ * @tier pattern
+ * @public
+ */
+import * as React from 'react';
+/** @public */
+export interface TreeNode {
+    /** Stable identifier for the node, passed to `onSelect` when its label is clicked. */
+    id: string;
+    /** Rendered label content for the node's row. */
+    label: React.ReactNode;
+    /** Nested child nodes. A non-empty array renders a toggle and a nested group. */
+    children?: TreeNode[];
+}
+/** @public */
+export interface TreeListProps extends Omit<React.HTMLAttributes<HTMLUListElement>, 'onSelect'> {
+    /** Root-level nodes to render. */
+    items: TreeNode[];
+    /** Node ids expanded on mount. */
+    defaultExpandedIds?: string[];
+    /** Called with a node's id when its label row is clicked. */
+    onSelect?: (id: string) => void;
+}
+/** Renders a hierarchical `role="tree"` list; nodes with children get an expand/collapse toggle. */
+export declare const TreeList: React.ForwardRefExoticComponent<TreeListProps & React.RefAttributes<HTMLUListElement>>;

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

@@ -0,0 +1,17 @@
+/**
+ * VisuallyHidden — content available to assistive tech but hidden visually.
+ * @category Utility
+ * @tier primitive
+ */
+import * as React from 'react';
+/** @public */
+export interface VisuallyHiddenProps extends React.HTMLAttributes<HTMLElement> {
+    /** Element rendered as the wrapper. Defaults to 'span'. */
+    as?: React.ElementType;
+}
+/**
+ * Renders its children off-screen (Tailwind `sr-only`) so they are announced by
+ * screen readers without occupying visual space — e.g. a text label for an
+ * icon-only control.
+ */
+export declare const VisuallyHidden: React.ForwardRefExoticComponent<VisuallyHiddenProps & React.RefAttributes<HTMLElement>>;

package/dist/types/src/app/context/TenantContext.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from 'react';
-export type TenantSlug = 'hirobius' | 'concrete-creations' | (string & {});
+export type TenantSlug = 'hirobius' | 'concrete-creations' | 'lilac-bonds' | (string & {});
 interface TenantCtx {
     /** Active tenant slug, or null in single-tenant mode. */
     tenantSlug: TenantSlug | null;

package/dist/types/src/app/data/nav-model.d.ts

@@ -0,0 +1,39 @@
+/** Per-page navigation metadata a docs page module exports (Phase 2 target). */
+export interface HdsPageMeta {
+    /** Canonical, root-relative route (no `/hds/` prefix). */
+    path: string;
+    /** Human label shown in the sidebar / search / breadcrumb. */
+    title: string;
+    /** Sidebar section heading this page groups under. */
+    section: string;
+    /** Sort order within the section. */
+    order: number;
+    /** Short description — used by the Cmd-K search corpus. */
+    description?: string;
+    /** Lifecycle status — drives a metadata slot, never a decorative badge. */
+    status?: 'stable' | 'beta' | 'draft' | 'internal';
+}
+/** A single sidebar link in the derived model. */
+export interface NavLink {
+    path: string;
+    label: string;
+    /** Short description — surfaced by the Cmd-K search corpus (not the sidebar). */
+    description?: string;
+    /** Match this route exactly (not by prefix) for active state. */
+    exact?: boolean;
+    /** Render with sub-item indentation. */
+    indent?: boolean;
+}
+/** A labelled group of sidebar links. */
+export interface NavSection {
+    label: string;
+    items: NavLink[];
+}
+/** The full derived navigation model. */
+export interface NavModel {
+    /** Generator provenance marker. */
+    $generated?: string;
+    sections: NavSection[];
+}
+/** The generated docs navigation model (see `scripts/generate-nav-model.mjs`). */
+export declare const navModel: NavModel;

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

@@ -61,6 +61,19 @@ export declare const tokenRefs: {
                 readonly "700": "var(--primitive-color-violet-700)";
                 readonly "950": "var(--primitive-color-violet-950)";
             };
+            readonly lilac: {
+                readonly "50": "var(--primitive-color-lilac-50)";
+                readonly "100": "var(--primitive-color-lilac-100)";
+                readonly "200": "var(--primitive-color-lilac-200)";
+                readonly "300": "var(--primitive-color-lilac-300)";
+                readonly "400": "var(--primitive-color-lilac-400)";
+                readonly "450": "var(--primitive-color-lilac-450)";
+                readonly "500": "var(--primitive-color-lilac-500)";
+                readonly "600": "var(--primitive-color-lilac-600)";
+                readonly "700": "var(--primitive-color-lilac-700)";
+                readonly "800": "var(--primitive-color-lilac-800)";
+                readonly "900": "var(--primitive-color-lilac-900)";
+            };
             readonly amber: {
                 readonly "50": "var(--primitive-color-amber-50)";
                 readonly "400": "var(--primitive-color-amber-400)";

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

@@ -62,6 +62,19 @@ export declare const tokenValues: {
                 readonly "700": "#6d28d9";
                 readonly "950": "#2e1065";
             };
+            readonly lilac: {
+                readonly "50": "#f7f4fe";
+                readonly "100": "#efe9fd";
+                readonly "200": "#ddd0fb";
+                readonly "300": "#c3aef6";
+                readonly "400": "#a585ee";
+                readonly "450": "#9a6fe8";
+                readonly "500": "#6f3fd4";
+                readonly "600": "#5f33c0";
+                readonly "700": "#4f2aa3";
+                readonly "800": "#3a1f78";
+                readonly "900": "#2a1659";
+            };
             readonly amber: {
                 readonly "50": "#fffbeb";
                 readonly "400": "#fbbf24";
@@ -122,7 +135,7 @@ export declare const tokenValues: {
         readonly typography: {
             readonly family: {
                 readonly primary: readonly ["Satoshi", "system-ui", "-apple-system", "BlinkMacSystemFont", "Segoe UI", "sans-serif"];
-                readonly display: readonly ["Clash Display", "system-ui", "-apple-system", "BlinkMacSystemFont", "Segoe UI", "sans-serif"];
+                readonly display: readonly ["Satoshi", "system-ui", "-apple-system", "BlinkMacSystemFont", "Segoe UI", "sans-serif"];
                 readonly mono: readonly ["Geist Mono", "Courier New", "monospace"];
             };
             readonly size: {

package/dist/types/src/app/{pages/hds → layouts}/HdsSystemDocLayout.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import { type DocLayoutContentMaxWidth } from '../../layouts/DocLayout';
+import { type DocLayoutContentMaxWidth } from './DocLayout';
 /** @public */
 export declare function HdsSystemDocLayout({ contentSlot, contentMaxWidth, }: {
     contentSlot: ReactNode;

package/dist/types/src/app/lib/hds-search.d.ts

@@ -0,0 +1,45 @@
+/** @internal — search engine behind the CommandPalette; not part of the public API. */
+/**
+ * hds-search — the manifest search engine extracted from CommandPalette.
+ *
+ * A dependency-free subsequence + position scorer (think micro-fzf) over four
+ * corpora drawn from `virtual:hds-manifest`: component specs, utilities, role
+ * tokens, and curated foundation sections. Pure and side-effect-free — the
+ * manifest is passed in, never read from a module global — so it is unit-tested
+ * directly (see scripts/../tests/hds-search.test.ts) rather than through a
+ * component test hook.
+ *
+ * Lifted from command-palette.tsx per ADR-011's review (deep module behind a
+ * narrow interface): the UI shell now imports { buildIndex, rank } and owns no
+ * search logic.
+ */
+import type { ManifestSpec, RoleToken, SystemManifest } from '../data/manifest-types';
+export type { ManifestSpec, RoleToken, SystemManifest };
+export type ResultKind = 'component' | 'pattern' | 'template' | 'utility' | 'token' | 'section';
+export interface PaletteResult {
+    id: string;
+    label: string;
+    description: string;
+    kind: ResultKind;
+    /** Where Enter/click navigates — relative React Router path. */
+    to: string;
+    /** Source string used for fuzzy matching (lowercased). */
+    haystack: string;
+}
+export declare const KIND_LABEL: Record<ResultKind, string>;
+export declare const MAX_RESULTS = 30;
+export declare function sanitize(text: string): string;
+/** Build the searchable index from a manifest. Pure — pass the manifest in. */
+export declare function buildIndex(manifest: SystemManifest): PaletteResult[];
+/**
+ * Subsequence + position scorer:
+ *   - Every char in `query` must appear in order inside `haystack`.
+ *   - Earlier matches score higher (heavy weight on first hit).
+ *   - Adjacent-char streaks score higher (clustered matches).
+ *   - Word-start hits get a bonus.
+ *
+ * Returns -Infinity if `query` is not a subsequence of `haystack`.
+ */
+export declare function fuzzyScore(query: string, haystack: string): number;
+/** Rank items against a query. Empty query → a stable starter set. */
+export declare function rank(query: string, items: PaletteResult[]): PaletteResult[];

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

@@ -0,0 +1,9 @@
+/**
+ * @hirobius/design-system/brand — palette → HDS-semantic overlay bridge.
+ *
+ * Framework-free helpers that theme any render target (static Astro, SSR, email)
+ * from a small brand palette while inheriting the HDS semantic contract. Imports
+ * no React and no Node built-ins, so it is safe to pull into a build step or an
+ * edge runtime. See ./overlay.ts and docs on the Astro consumption path.
+ */
+export { brandOverlayVars, brandOverlayStyle, brandOverlayCss, type BrandPalette } from './overlay';

package/dist/types/src/brand/overlay.d.ts

@@ -0,0 +1,71 @@
+/**
+ * overlay.ts — pure palette → HDS-semantic overlay bridge.
+ *
+ * The seam that lets a downstream render target (a static Astro site, an email,
+ * an SSR shell) theme itself from a small brand palette while inheriting HDS's
+ * semantic contract — contrast-checked pairs, accent states, density, dark mode.
+ *
+ * A consumer resolves a brand palette (six colours + optional font/radius) and
+ * this module maps it onto the HDS semantic custom properties. Everything HDS
+ * ships downstream of those semantics (component tokens, utilities) then reads
+ * the brand automatically via the `var()` reference chain — the same strategy
+ * as the checked-in `[data-brand]` tenant overlays (`src/styles/tenants.css`),
+ * but computed at the consumer instead of at HDS build time, so HDS never has
+ * to know the client roster.
+ *
+ * Deliberately dependency-free (no React, no Node) so it runs in any render
+ * target and is unit-testable in isolation. Mirrors the zero-dependency idiom
+ * of `box-sx.ts`.
+ *
+ * Interactive accent states (hover/pressed/subtle) are derived from the primary
+ * with CSS `color-mix()` — no colour-math dependency, resolved by the browser.
+ * `color-mix()` is Baseline-supported (all evergreen engines since 2023); the
+ * factory ships new sites, so this is a safe floor.
+ *
+ * @packageDocumentation
+ */
+/** A resolved brand palette — the minimal input needed to theme a surface. */
+export interface BrandPalette {
+    /** Primary brand colour — accent rest, key surfaces, links. */
+    primary: string;
+    /** Text/icon colour that sits on top of `primary`. */
+    onPrimary: string;
+    /** Page background. */
+    bg: string;
+    /** Body/foreground text colour. */
+    fg: string;
+    /** Muted surface — raised cards, subtle fills. */
+    muted: string;
+    /** Optional secondary accent. Kept brand-level (HDS has one accent ramp). */
+    accent?: string;
+    /** Optional corner radius as a CSS length (e.g. `'8px'`). */
+    radius?: string;
+    /** Optional heading font stack. */
+    fontHeading?: string;
+    /** Optional body font stack. */
+    fontBody?: string;
+}
+/**
+ * Map a brand palette onto HDS semantic (and a few primitive) custom
+ * properties. Returns a flat `--var` → value record; the caller decides how to
+ * apply it (inline style string via {@link brandOverlayStyle} or a scoped CSS
+ * rule via {@link brandOverlayCss}).
+ *
+ * Only the accent ramp, page/content colours, and — when provided — radius and
+ * font families are overridden. All other semantics inherit HDS defaults
+ * unchanged, so a partial palette still yields a coherent theme.
+ */
+export declare function brandOverlayVars(palette: BrandPalette): Record<string, string>;
+/**
+ * Serialize a palette to an inline `style` string (`k:v;k:v`) for the `<html>`
+ * element. Inline element styles beat stylesheet rules, so this is the most
+ * direct per-surface theming path (the model the clients factory already uses).
+ */
+export declare function brandOverlayStyle(palette: BrandPalette): string;
+/**
+ * Serialize a palette to a scoped CSS rule (`<selector>{ --var: value; }`) for
+ * a static stylesheet — e.g. `[data-brand="acme"]` blocks in an Astro layout,
+ * mirroring the checked-in tenant overlays. `selector` is emitted verbatim; the
+ * caller owns its trust (typically a slug it controls).
+ */
+export declare function brandOverlayCss(selector: string, palette: BrandPalette): string;