@trinityui/design-system 2.11.1 → 2.13.0

package/dist/color-contrast.d.ts

@@ -0,0 +1,35 @@
+/** An sRGB color: channels 0-255, alpha 0-1. */
+export interface RgbaColor {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** Parse a CSS color, or return null when it is not one of the supported formats. */
+export declare function parseColor(input: string): RgbaColor | null;
+/** Composite a translucent color over an opaque one (source-over). */
+export declare function composite(foreground: RgbaColor, background: RgbaColor): RgbaColor;
+/** WCAG 2.x relative luminance of an opaque sRGB color. */
+export declare function relativeLuminance({ r, g, b }: Pick<RgbaColor, 'r' | 'g' | 'b'>): number;
+/** Contrast ratio of two opaque colors. */
+export declare function contrastOfOpaque(first: Pick<RgbaColor, 'r' | 'g' | 'b'>, second: Pick<RgbaColor, 'r' | 'g' | 'b'>): number;
+export interface ContrastOptions {
+    /**
+     * The opaque surface under a translucent background. Defaults to white, the light paper.
+     * Pass the dark surface when you check a dark-mode wash.
+     */
+    over?: string;
+}
+/**
+ * Test-only: forget which colors have warned.
+ *
+ * @internal
+ */
+export declare function __resetContrastWarnings(): void;
+/**
+ * Contrast ratio of `foreground` on `background`. A translucent background is composited over
+ * `options.over` (default white); a translucent foreground is then composited over that result.
+ * Returns NaN, with a one-time development warning, when a color cannot be read.
+ */
+export declare function contrast(foreground: string, background: string, options?: ContrastOptions): number;
+//# sourceMappingURL=color-contrast.d.ts.map

package/dist/color-contrast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-contrast.d.ts","sourceRoot":"","sources":["../src/color-contrast.ts"],"names":[],"mappings":"AAYA,gDAAgD;AAChD,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AASD,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAiB1D;AAED,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,GAAG,SAAS,CASjF;AAOD,2DAA2D;AAC3D,wBAAgB,iBAAiB,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,SAAS,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC,GAAG,MAAM,CAEvF;AAED,2CAA2C;AAC3C,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC,EACvC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC,GACvC,MAAM,CAIR;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAgBD;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,CAiBtG"}

package/dist/commonjs-helpers.js

@@ -0,0 +1,8 @@
+var o = typeof globalThis < "u" ? globalThis : typeof window < "u" ? window : typeof global < "u" ? global : typeof self < "u" ? self : {};
+function l(e) {
+  return e && e.__esModule && Object.prototype.hasOwnProperty.call(e, "default") ? e.default : e;
+}
+export {
+  o as c,
+  l as g
+};

package/dist/component-color-references.d.ts

@@ -0,0 +1,175 @@
+import type { TrinityIndicatorRoles } from './theme-augmentation.js';
+import type { TrinityIndicatorStatus } from './tokens';
+/**
+ * Component color roles that inherit from the semantic color tier.
+ *
+ * Both CSS generators consume this contract. A reference is only applied when
+ * the component and semantic literals still match, so tiering cannot silently
+ * alter light-mode output.
+ */
+export declare const componentSemanticColorReferences: readonly [readonly ["card.background", "surface.elevated"], readonly ["card.border", "border.subtle"], readonly ["input.background.default", "surface.elevated"], readonly ["input.background.disabled", "background.tertiary"], readonly ["input.borderColor.default", "border.default"], readonly ["input.borderColor.hover", "border.strong"], readonly ["input.borderColor.focus", "border.focus"], readonly ["input.borderColor.error", "border.error"], readonly ["tooltip.background", "background.inverse"], readonly ["tooltip.text", "text.inverse"], readonly ["modal.background", "surface.elevated"]];
+export declare function componentColorCssVariable(path: string, channel: 'static' | 'runtime'): string;
+export declare function semanticColorCssVariable(path: string, channel: 'static' | 'runtime'): string;
+/**
+ * The reference rule both CSS generators share. `values` maps custom-property names to their
+ * emitted values; each reference is `[target, source]` by name.
+ *
+ * - Target equals source: the target becomes `var(source)`, so a dark or brand override of the
+ *   source reaches the target.
+ * - Target differs from source: `onMismatch: 'throw'` fails (the static generator's invariant
+ *   for the shipped CSS); `onMismatch: 'literal'` keeps the target's own value (the runtime
+ *   generator, where a consumer token set may override a member on purpose).
+ * - A missing endpoint throws or is skipped, per `onMissing`.
+ */
+export declare function applyCssColorReferences(values: Map<string, string>, references: ReadonlyArray<readonly [target: string, source: string]>, options: {
+    onMismatch: 'throw' | 'literal';
+    onMissing: 'throw' | 'skip';
+    context: string;
+}): void;
+/** The component references as custom-property names for one CSS channel. */
+export declare function componentReferenceNames(channel: 'static' | 'runtime'): Array<readonly [target: string, source: string]>;
+/**
+ * Semantic roles defined as references to other semantic roles: [target, source], both paths
+ * under `semantic.colors`. A source may be a group (`status.success`), which maps each of its
+ * keys, or a single color.
+ *
+ * The confidence and verification groups exist only here: no token object holds their values
+ * (ADR-03), the CSS variables are `var()` aliases of the status variables, and the palette
+ * builder resolves them per mode. The mapping is the Step 5 record's D2 decision (ADR-03-R1).
+ *
+ * @internal
+ */
+export declare const semanticRoleReferences: readonly [readonly ["confidence.high", "status.success"], readonly ["confidence.medium", "status.info"], readonly ["confidence.low", "status.warning"], readonly ["verification.verified", "status.success"], readonly ["verification.golden", "status.success"], readonly ["verification.pending", "status.info"], readonly ["verification.flagged", "status.warning"], readonly ["verification.rejected", "status.error"], readonly ["ai.primary", "brand.secondary"], readonly ["ai.primaryFill", "brand.secondary"], readonly ["ai.typingIndicator", "brand.secondary"], readonly ["ai.accent", "brand.accent"], readonly ["ai.presence.purple", "brand.secondary"], readonly ["ai.presence.coral", "brand.accent"], readonly ["ai.avatarFill.start", "brand.accent"], readonly ["ai.avatarFill.end", "brand.secondary"], readonly ["favorite", "status.warning.text"]];
+/**
+ * Dark roles defined as references to other dark roles: [target, source], both paths under
+ * `darkMode.colors`. `resolveTrinityTokens` keeps a target equal to its resolved source unless
+ * the target itself is overridden, and both CSS generators emit an equal target as
+ * `var(source)` in the dark blocks.
+ *
+ * @internal
+ */
+export declare const darkSemanticRoleReferences: readonly [readonly ["favorite", "status.warning.text"]];
+/** The dark role references as custom-property names for one CSS channel. */
+export declare function darkRoleReferenceNames(channel: 'static' | 'runtime'): Array<readonly [target: string, source: string]>;
+/**
+ * Semantic roles derived from another role with an alpha (E-03): [target, source, alpha], paths
+ * under `semantic.colors`. `resolveTrinityTokens` recomputes a target from its resolved source
+ * unless the target itself is overridden.
+ *
+ * @internal
+ */
+export declare const semanticDerivedRoles: readonly [readonly ["ai.surface", "brand.secondary", 0.05], readonly ["ai.border", "brand.secondary", 0.2], readonly ["ai.badgeBackground", "brand.secondary", 0.15]];
+/** Role groups that exist only as references: no token object holds their values. */
+export declare const referenceOnlyRoleGroups: readonly ["confidence", "verification"];
+/**
+ * The role references expanded to single colors against a colors object (for example
+ * `semanticTokens.colors`): a group source maps each of its string keys.
+ */
+export declare function expandSemanticRoleReferences(colors: unknown, references?: ReadonlyArray<readonly [string, string]>): Array<readonly [target: string, source: string]>;
+/** The first reference cycle in a [target, source] table, as a path, or null. */
+export declare function findReferenceCycle(references: ReadonlyArray<readonly [string, string]>): string[] | null;
+/**
+ * Resolve the reference-only role groups against a colors object: `{ confidence: { high:
+ * { text, background, border }, ... }, verification: { ... } }`. The palette builder passes the
+ * light semantic colors, or `{ status: <dark status set> }` in dark mode.
+ */
+export declare function resolveReferenceRoleGroups<T = Record<string, Record<string, Record<string, string>>>>(colors: unknown): T;
+/**
+ * The role references as custom-property names for one CSS channel, expanded against
+ * `colors` (static: `--trinity-confidence-high-text` -> `--trinity-status-success-text`;
+ * runtime: `--trinity-semantic-confidence-high-text` -> `--trinity-semantic-status-success-text`).
+ */
+export declare function semanticRoleReferenceNames(colors: unknown, channel: 'static' | 'runtime'): Array<readonly [target: string, source: string]>;
+/**
+ * Apply the role references to a name -> value map. A target already emitted by a token walk
+ * (for example `ai.primary`) follows {@link applyCssColorReferences}: equal values become
+ * `var(source)`. A target with no token (confidence, verification) is added as one new
+ * `var(source)` entry. Adding a name twice throws.
+ *
+ * Returns the names this call added, in table order.
+ */
+export declare function applySemanticRoleReferences(values: Map<string, string>, references: ReadonlyArray<readonly [target: string, source: string]>, options: {
+    onMismatch: 'throw' | 'literal';
+    context: string;
+}): string[];
+/**
+ * The StatusIndicator catalog's families. A family decides which existing role a status takes as
+ * its dark on-surface colour (ADR-03-R6, Step 5 record section 5).
+ *
+ * @internal
+ */
+export declare const indicatorFamilies: {
+    readonly error: readonly ["error", "critical", "failed", "rejected"];
+    readonly warning: readonly ["warning", "caution", "pending"];
+    readonly success: readonly ["success", "complete", "approved", "active", "enabled"];
+    readonly info: readonly ["info", "new", "updated"];
+    readonly neutral: readonly ["neutral", "draft", "inactive", "disabled", "cancelled", "unknown"];
+    readonly progress: readonly ["inProgress", "running"];
+    readonly beta: readonly ["beta", "experimental"];
+};
+/** @internal */
+export type IndicatorFamily = keyof typeof indicatorFamilies;
+type IndicatorEntry = {
+    fg: string;
+    bg: string;
+    outline?: string;
+};
+/**
+ * Build `palette.trinity.indicator` from a catalog (the merged light entries), the mode's fill
+ * overrides (`darkMode.colors.indicator`) and one on-surface colour per family. With no family
+ * colours (light), a status's on-surface colour is the catalog's own `outline ?? fill`, so the
+ * light group is a bit-identical reference to the catalog.
+ *
+ * @internal
+ */
+export declare function buildIndicatorRoles(catalog: Record<TrinityIndicatorStatus, IndicatorEntry>, overrides?: Partial<Record<TrinityIndicatorStatus, Partial<IndicatorEntry>>>, onSurfaceByFamily?: Record<IndicatorFamily, string>): TrinityIndicatorRoles;
+/** The var() names a declaration value reads. */
+export declare function referencedNames(value: string): string[];
+/**
+ * The aliases (values that read another variable) whose resolved value depends on a
+ * theme-overridden name, directly or through other aliases, in declaration order (E-37).
+ * Both generators re-declare exactly these in each theme block: a custom property's var() is
+ * substituted on the element that declares it, so an alias declared only in :root would keep
+ * the page's theme inside a themed subtree.
+ */
+export declare function themeDependentAliases(names: string[], values: ReadonlyMap<string, string>, overridden: ReadonlySet<string>): string[];
+/** The AI roles a gradient reads: colors in React, `var()` references in CSS. */
+export interface AIGradientInputs {
+    accent: string;
+    primaryFill: string;
+    surface: string;
+    avatarFill: {
+        start: string;
+        end: string;
+    };
+    canvasFill: {
+        start: string;
+        end: string;
+    };
+}
+/**
+ * The AI gradients, built from the resolved accent, primaryFill, surface and avatarFill. The
+ * resolver passes colors and both CSS generators pass `var(--trinity-ai-*)` references, so
+ * React and CSS give the same gradient in both modes and a brand override reaches both.
+ * `avatar` is AIAvatar's fill (owner decision 2026-10-08), from its own stops: the dark accent
+ * and primaryFill are too light under a white icon. `brandDiagonal` is the same pair at 135deg,
+ * AIFab's and AICircularAction (gradient)'s fill (owner decision 2026-10-09). `canvas` is
+ * AIChatWelcome's canvas wash, from `canvasFill`; its transparent start lets the paper show.
+ *
+ * @internal
+ */
+export declare function aiGradients({ accent, primaryFill, surface, avatarFill, canvasFill }: AIGradientInputs): {
+    primary: string;
+    horizontal: string;
+    diagonal: string;
+    subtle: string;
+    text: string;
+    border: string;
+    avatar: string;
+    brandDiagonal: string;
+    canvas: string;
+};
+/** The AI gradient custom properties for one CSS channel, as [name, value]. */
+export declare function aiGradientDeclarations(channel: 'static' | 'runtime'): Array<readonly [string, string]>;
+export {};
+//# sourceMappingURL=component-color-references.d.ts.map

package/dist/component-color-references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-color-references.d.ts","sourceRoot":"","sources":["../src/component-color-references.ts"],"names":[],"mappings":"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"}

package/dist/components/AI/AIActions.d.ts

@@ -21,10 +21,11 @@
  */
 import React from 'react';
 import { SxProps, Theme } from '@mui/material';
+import { type TrinityRootProps, type TrinitySlotProps } from '../shared/rootProps';
 /**
- * Props for AISuggestedAction component.
+ * AISuggestedAction's own props.
  */
-export interface AISuggestedActionProps {
+export interface AISuggestedActionOwnProps {
     /** Action label */
     label: string;
     /** Action description (for card variant only) */
@@ -37,9 +38,20 @@ export interface AISuggestedActionProps {
     disabled?: boolean;
     /** Variant - 'list' matches screenshot design with arrow icons */
     variant?: 'default' | 'primary' | 'outlined' | 'list';
-    /** Custom sx props */
+    /**
+     * Added to the root's own class names.
+     * @since 2.13.0
+     */
+    className?: string;
+    /** Custom sx props, applied after the action's own styles (object, array or function). */
     sx?: SxProps<Theme>;
 }
+/**
+ * Props for AISuggestedAction: its own props, plus the HTML attributes of its root `button`
+ * (`id`, `data-*`, `aria-*`), which reach the root (ADR-04, WI-40).
+ */
+export interface AISuggestedActionProps extends AISuggestedActionOwnProps, TrinityRootProps<HTMLButtonElement, AISuggestedActionOwnProps> {
+}
 /**
  * AI Suggested Action - Actionable suggestion button.
  *
@@ -51,10 +63,10 @@ export interface AISuggestedActionProps {
  */
 export declare const AISuggestedAction: React.ForwardRefExoticComponent<AISuggestedActionProps & React.RefAttributes<HTMLButtonElement>>;
 /**
- * Props for AICircularAction component.
+ * AICircularAction's own props.
  */
-export interface AICircularActionProps {
-    /** Tooltip label */
+export interface AICircularActionOwnProps {
+    /** The action's name: the tooltip text and the start of the button's accessible name. */
     label: string;
     /** Icon name - use approved icons: close, search, sparkles, etc. */
     icon: string;
@@ -68,10 +80,43 @@ export interface AICircularActionProps {
     variant?: 'default' | 'primary' | 'gradient';
     /** Whether to show badge */
     showBadge?: boolean;
-    /** Badge content */
+    /** Badge content. Without content the badge is a dot. */
     badgeContent?: React.ReactNode;
-    /** Custom sx props */
+    /**
+     * How the badge reads in the button's accessible name, after the label
+     * (`ai.circularAction.nameWithBadge`): `"Notifications, 3"` by default for text or number content. A
+     * function receives the badge content (`(n) => \`${n} unread\`` gives
+     * `"Notifications, 3 unread"`). Give one for a dot or non-text content,
+     * which add nothing to the name otherwise.
+     *
+     * @since 2.13.0
+     */
+    badgeLabel?: string | ((content: React.ReactNode) => string);
+    /**
+     * Added to the root's own class names: the wrapper that holds the button and its badge (the
+     * ref's element).
+     * @since 2.13.0
+     */
+    className?: string;
+    /**
+     * Custom sx props for the button (object, array or function), applied after its own styles.
+     * The wrapper takes `slotProps.root.sx`.
+     */
     sx?: SxProps<Theme>;
+    /**
+     * Props for the component's slots (ADR-04 (6)). `root`: the wrapper `div` around the button
+     * and its badge, the ref's element (its `sx`, `className` and attributes).
+     * @since 2.13.0
+     */
+    slotProps?: {
+        root?: TrinitySlotProps<HTMLDivElement>;
+    };
+}
+/**
+ * Props for AICircularAction: its own props, plus the HTML attributes of its root, the wrapper
+ * `div` (`id`, `data-*`, `aria-*`), which reach it (ADR-04, WI-40). `sx` keeps styling the button.
+ */
+export interface AICircularActionProps extends AICircularActionOwnProps, TrinityRootProps<HTMLDivElement, AICircularActionOwnProps> {
 }
 /**
  * AI Circular Action - Circular action button with icon.
@@ -85,18 +130,33 @@ export interface AICircularActionProps {
  */
 export declare const AICircularAction: React.ForwardRefExoticComponent<AICircularActionProps & React.RefAttributes<HTMLDivElement>>;
 /**
- * Props for AIActionsGroup component.
+ * AIActionsGroup's own props.
  */
-export interface AIActionsGroupProps {
+export interface AIActionsGroupOwnProps {
     /** List of actions */
     actions: AISuggestedActionProps[];
-    /** Layout direction */
+    /**
+     * Layout direction. A `'row'` wraps: actions that do not fit the width move to the next line,
+     * and one action wider than the row shrinks and wraps its own text (WCAG 1.4.10, a docked AI
+     * panel at 320 to 360px).
+     */
     direction?: 'row' | 'column';
     /** Spacing between actions */
     spacing?: number;
-    /** Custom sx props */
+    /**
+     * Added to the root's own class names.
+     * @since 2.13.0
+     */
+    className?: string;
+    /** Custom sx props, applied after the group's own styles (object, array or function). */
     sx?: SxProps<Theme>;
 }
+/**
+ * Props for AIActionsGroup: its own props, plus the HTML attributes of its root `div` (`id`,
+ * `data-*`, `aria-*`), which reach the root (ADR-04, WI-40).
+ */
+export interface AIActionsGroupProps extends AIActionsGroupOwnProps, TrinityRootProps<HTMLDivElement, AIActionsGroupOwnProps> {
+}
 /**
  * AI Actions Group - Group of suggested actions.
  */

package/dist/components/AI/AIActions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AIActions.d.ts","sourceRoot":"","sources":["../../../src/components/AI/AIActions.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAQL,OAAO,EACP,KAAK,EACN,MAAM,eAAe,CAAC;AASvB;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,mBAAmB;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,kEAAkE;IAClE,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;IACtD,sBAAsB;IACtB,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,kGAoL7B,CAAC;AAMF;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB;IACpB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW;IACX,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpC,cAAc;IACd,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;IAC7C,4BAA4B;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,oBAAoB;IACpB,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC/B,sBAAsB;IACtB,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,8FAsG5B,CAAC;AAMF;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,sBAAsB;IACtB,OAAO,EAAE,sBAAsB,EAAE,CAAC;IAClC,uBAAuB;IACvB,SAAS,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IAC7B,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACrB;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,4FAU1B,CAAC"}
+{"version":3,"file":"AIActions.d.ts","sourceRoot":"","sources":["../../../src/components/AI/AIActions.tsx"],"names":[],"mappings":"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"}

package/dist/components/AI/AIAvatar.d.ts

@@ -12,21 +12,49 @@
  */
 import React from 'react';
 import { SxProps, Theme } from '@mui/material';
+import { type TrinityRootProps } from '../shared/rootProps';
 /**
- * Props for AIAvatar component.
+ * AIAvatar's own props.
  */
-export interface AIAvatarProps {
+export interface AIAvatarOwnProps {
     /** Size of the avatar */
     size?: 'xs' | 'small' | 'medium' | 'large';
     /** Whether to show animated pulse */
     animated?: boolean;
     /** Custom icon name */
     icon?: string;
-    /** Custom sx props */
+    /**
+     * Added to the root's own class names.
+     * @since 2.13.0
+     */
+    className?: string;
+    /** Custom sx props, applied after the avatar's own styles (object, array or function). */
     sx?: SxProps<Theme>;
 }
+/**
+ * Props for AIAvatar: its own props, plus the HTML attributes of its root `div` (`id`,
+ * `data-*`, `aria-*`), which reach the root (ADR-04). An `aria-label` or `aria-labelledby`
+ * makes the avatar a named `role="img"`; without one it is decorative (`aria-hidden`).
+ */
+export interface AIAvatarProps extends AIAvatarOwnProps, TrinityRootProps<HTMLDivElement, AIAvatarOwnProps> {
+}
+/**
+ * @internal — not part of the public API; see ADR-02. The avatar diameters in px, the one source
+ * of truth for the message avatar column (`small`, 32px) that thread-level items align to (G-13,
+ * G-OD4; I-lead approval recorded as the owner's).
+ */
+export declare const AI_AVATAR_SIZE_PX: {
+    xs: number;
+    small: number;
+    medium: number;
+    large: number;
+};
 /**
  * AI Avatar - Visual representation of the AI assistant.
+ *
+ * Decorative by default: the root is `aria-hidden="true"`, because the message or region it
+ * marks names the author. Pass `aria-label` (or `aria-labelledby`) only where the avatar is
+ * the sole signal of AI authorship; it then becomes `role="img"` with that name.
  */
 export declare const AIAvatar: React.ForwardRefExoticComponent<AIAvatarProps & React.RefAttributes<HTMLDivElement>>;
 //# sourceMappingURL=AIAvatar.d.ts.map

package/dist/components/AI/AIAvatar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AIAvatar.d.ts","sourceRoot":"","sources":["../../../src/components/AI/AIAvatar.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAU,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAQvD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,yBAAyB;IACzB,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC3C,qCAAqC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uBAAuB;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sBAAsB;IACtB,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACrB;AAiBD;;GAEG;AACH,eAAO,MAAM,QAAQ,sFAgCnB,CAAC"}
+{"version":3,"file":"AIAvatar.d.ts","sourceRoot":"","sources":["../../../src/components/AI/AIAvatar.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAU,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAQvD,OAAO,EAAgB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAM1E;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yBAAyB;IACzB,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC3C,qCAAqC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uBAAuB;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAc,SAAQ,gBAAgB,EAAE,gBAAgB,CAAC,cAAc,EAAE,gBAAgB,CAAC;CAAG;AAa9G;;;;GAIG;AAEH,eAAO,MAAM,iBAAiB;;;;;CAAc,CAAC;AAmB7C;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,sFA2DnB,CAAC"}