origam 2.5.0 → 2.6.1

package/dist/src/interfaces/List/list-item.interface.d.ts

@@ -1,6 +1,6 @@
-import type { IActiveProps, IAdjacentEmits, IAdjacentProps, IBgColorProps, IBorderProps, IClickEmits, IColorProps, ICommonsComponentProps, IDensityProps, IDimensionProps, IElevationProps, IHoverProps, ILinkProps, IMarginProps, IPaddingProps, IRippleProps, IRoundedProps, ITagProps } from '../../interfaces';
+import type { IActiveProps, IAdjacentEmits, IAdjacentProps, IBgColorProps, IBorderProps, IClickEmits, IColorProps, ICommonsComponentProps, IDensityProps, IDimensionProps, IElevationProps, IHoverProps, ILinkProps, IMarginProps, IPaddingProps, IRippleProps, IRoundedProps, ITagProps, ITypographyProps } from '../../interfaces';
 import type { TLines } from '../../types';
-export interface IListItemProps extends IBorderProps, ICommonsComponentProps, IDensityProps, IDimensionProps, IElevationProps, IRoundedProps, ITagProps, ILinkProps, IColorProps, IBgColorProps, IRippleProps, IPaddingProps, IMarginProps, IAdjacentProps, IActiveProps, IHoverProps {
+export interface IListItemProps extends IBorderProps, ICommonsComponentProps, IDensityProps, IDimensionProps, IElevationProps, IRoundedProps, ITagProps, ILinkProps, IColorProps, IBgColorProps, IRippleProps, IPaddingProps, IMarginProps, IAdjacentProps, IActiveProps, IHoverProps, ITypographyProps {
     active?: boolean;
     activeClass?: string;
     disabled?: boolean;

package/dist/src/interfaces/List/list-subheader.interface.d.ts

@@ -1,5 +1,5 @@
-import type { IBorderProps, IBgColorProps, IColorProps, ICommonsComponentProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps } from '../../interfaces';
-export interface IListSubheader extends ICommonsComponentProps, ITagProps, IColorProps, IBgColorProps, IPaddingProps, IMarginProps, IBorderProps, IRoundedProps {
+import type { IBorderProps, IBgColorProps, IColorProps, ICommonsComponentProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps, ITypographyProps } from '../../interfaces';
+export interface IListSubheader extends ICommonsComponentProps, ITagProps, IColorProps, IBgColorProps, IPaddingProps, IMarginProps, IBorderProps, IRoundedProps, ITypographyProps {
     inset?: boolean;
     sticky?: boolean;
     title?: string;

package/dist/src/interfaces/Media/media-scrubber.interface.d.ts

@@ -87,16 +87,24 @@ export interface IMediaScrubberProps extends ICommonsComponentProps, IColorProps
      */
     formatHoverTooltip?: (value: number) => string;
     /**
-     * Required accessibility label — read by screen readers when the
+     * Accessibility label — read by screen readers when the
      * scrubber gains focus. Always pass a translated string here.
+     * Declared optional to allow Volar to map the kebab-case `:aria-label`
+     * attribute from parent templates without a required-prop error.
      */
-    ariaLabel: string;
+    ariaLabel?: string;
     /**
      * Optional human-readable representation of the current value
      * (e.g. `"1:23"` for a timestamp, `"45 %"` for a volume).
      * Mapped to `aria-valuetext`.
      */
     ariaValueText?: string;
+    /**
+     * Optional `data-cy` test selector forwarded by the parent
+     * (`OrigamMediaController`, `OrigamMediaVolumeControl`) as a
+     * camelCase Vue prop. Passed through `$attrs` to the host element.
+     */
+    dataCy?: string;
 }
 /**
  * Emits for `<OrigamMediaScrubber>`.

package/dist/src/interfaces/Messages/messages.interface.d.ts

@@ -1,5 +1,5 @@
-import type { IBorderProps, IColorProps, ICommonsComponentProps, IDensityProps, IElevationProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps, ITransitionComponentProps } from '../../interfaces';
-export interface IMessagesProps extends ICommonsComponentProps, ITagProps, ITransitionComponentProps, IColorProps, IBorderProps, IPaddingProps, IMarginProps, IRoundedProps, IDensityProps, IElevationProps {
+import type { IBorderProps, IColorProps, ICommonsComponentProps, IDensityProps, IElevationProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps, ITransitionComponentProps, ITypographyProps } from '../../interfaces';
+export interface IMessagesProps extends ICommonsComponentProps, ITagProps, ITransitionComponentProps, IColorProps, IBorderProps, IPaddingProps, IMarginProps, IRoundedProps, IDensityProps, IElevationProps, ITypographyProps {
     active?: boolean;
     messages?: Array<string> | string;
 }

package/dist/src/interfaces/NumberField/number-field.interface.d.ts

@@ -33,7 +33,7 @@ export interface INumberFieldSlots extends IFieldSlots, Omit<IInputSlots, 'defau
         id: string;
         isDisabled: boolean;
         isDirty: boolean;
-        isValid: boolean;
+        isValid: boolean | undefined;
         isReadonly: boolean;
     }) => any;
     increment?: (data: {

package/dist/src/interfaces/Nuxt/nuxt-module.interface.d.ts

@@ -1,37 +1,68 @@
+import type { IOrigamTheme } from '../Theme/origam-theme.interface';
 /**
  * Options passed by a consumer in `nuxt.config.ts` under the `origam` key.
  *
  * All fields are optional — the module applies sensible defaults (see
- * `DEFAULTS` in `src/nuxt/module.ts`). Themes are auto-injected as CSS
- * imports; the active theme is resolved SSR-side via cookie and the
- * `Sec-CH-Prefers-Color-Scheme` client hint to avoid FOUC and hydration
- * mismatches.
+ * `DEFAULTS` in `src/nuxt/module.ts`). Themes are installed as runtime OBJECTS
+ * (ADR-004): the module passes the `themes` array straight through to the
+ * runtime config and on to `createOrigam` in the plugins, which inject each as
+ * a name×mode scoped `--origam-*` block. The theme-invariant `primitive` +
+ * `utilities` sheets are still loaded as CSS. Two orthogonal axes are resolved
+ * SSR-side to avoid FOUC: the brand `theme` (cookie) and the color `mode`
+ * (cookie + `Sec-CH-Prefers-Color-Scheme` hint).
+ *
+ * ADR-004 (Implemented): the DS ships exactly ONE neutral identity (the origam
+ * baseline). Brand themes live in the consuming app (e.g. the marketing
+ * package) and are passed here as `IOrigamTheme[]` objects authored in
+ * semantic JSON — the DS no longer resolves preset names or ships brand
+ * token sheets.
  */
 export interface IOrigamNuxtModuleOptions {
     /**
-     * Theme names whose CSS file must be loaded. Each name must match a
-     * generated `dist/src/assets/css/tokens/{theme}.css` exposed via
-     * `origam/tokens/css/{theme}`.
+     * Themes to install, as `IOrigamTheme` objects (one per brand×mode). The
+     * objects are passed verbatim to `createOrigam`, which injects each as a
+     * scoped CSS-var block — no pre-generated per-theme CSS file is loaded.
+     * When omitted, `createOrigam` installs the DS built-in baseline (neutral identity).
+     */
+    themes?: IOrigamTheme[];
+    /**
+     * Theme (brand) applied when no cookie is set. Use `'auto'` to render no
+     * `data-theme` attribute (the default brand).
+     *
+     * @default 'auto'
+     */
+    defaultTheme?: string;
+    /**
+     * Color modes supported by the loaded token sheets. Used to validate the
+     * resolved mode before applying it.
      *
      * @default ['light', 'dark']
      */
-    themes?: string[];
+    modes?: string[];
     /**
-     * Theme applied when no cookie is set and no usable
+     * Color mode applied when no cookie is set and no usable
      * `Sec-CH-Prefers-Color-Scheme` hint is sent. Use `'auto'` to let the
      * server fall back to the client hint (or `'light'` if absent).
      *
      * @default 'auto'
      */
-    defaultTheme?: string;
+    defaultMode?: string;
     /**
-     * Cookie name used to persist the user's chosen theme across sessions.
+     * Cookie name used to persist the user's chosen theme (brand) across
+     * sessions.
      *
      * @default 'origam-theme'
      */
     cookieName?: string;
     /**
-     * Cookie `max-age` in seconds.
+     * Cookie name used to persist the user's chosen color mode across
+     * sessions.
+     *
+     * @default 'origam-mode'
+     */
+    modeCookieName?: string;
+    /**
+     * Cookie `max-age` in seconds (shared by the theme and mode cookies).
      *
      * @default 31_536_000 (1 year)
      */
@@ -62,12 +93,21 @@ export interface IOrigamNuxtModuleOptions {
 }
 /**
  * Shape of the public runtime config exposed by the module on
- * `useRuntimeConfig().public.origam`. The plugins read this at boot to
- * resolve the active theme and configure the cookie.
+ * `useRuntimeConfig().public.origam`. The plugins read this at boot to install
+ * the theme objects, resolve the active theme/mode, and configure the cookies.
  */
 export interface IOrigamNuxtRuntimeConfig {
-    themes: string[];
+    /**
+     * Installed `IOrigamTheme` objects, in install order. The plugins pass
+     * these straight to `createOrigam` (no preset-name resolution — ADR-004).
+     * A switcher derives its brand list from `useInstalledThemes()` rather than
+     * from this payload.
+     */
+    themes: IOrigamTheme[];
     defaultTheme: string;
+    modes: string[];
+    defaultMode: string;
     cookieName: string;
+    modeCookieName: string;
     cookieMaxAge: number;
 }

package/dist/src/interfaces/OtpInputField/otp-input-field.interface.d.ts

@@ -17,12 +17,14 @@ export interface IOtpInputFieldEmits extends IFieldEmits, IInputEmits {
     (e: 'mousedown:control', event: MouseEvent): void;
     (e: 'click:clear', event: MouseEvent): void;
 }
-export interface IOtpInputFieldSlots extends IFieldSlots, Omit<IInputSlots, 'default'> {
+export interface IOtpInputFieldSlots extends Omit<IFieldSlots, 'default'>, Omit<IInputSlots, 'default'> {
+    /** Generic slot — no slot props. */
+    default?: () => any;
     field?: (data: {
         id: string;
         isDisabled: boolean;
         isDirty: boolean;
-        isValid: boolean;
+        isValid: boolean | undefined;
         isReadonly: boolean;
     }) => any;
 }

package/dist/src/interfaces/Pagination/pagination.interface.d.ts

@@ -1,6 +1,6 @@
-import type { IBorderProps, IBgColorProps, IColorProps, ICommonsComponentEmits, ICommonsComponentProps, IDensityProps, IElevationProps, IMarginProps, IPaddingProps, ISizeProps, ITagProps } from "../../interfaces";
-import type { TIcon } from "../../types";
-export interface IPaginationProps extends ICommonsComponentProps, ITagProps, IColorProps, IBgColorProps, IBorderProps, IPaddingProps, IMarginProps, IElevationProps, ISizeProps, IDensityProps {
+import type { IBorderProps, IBgColorProps, IColorProps, ICommonsComponentEmits, ICommonsComponentProps, IDensityProps, IElevationProps, IMarginProps, IPaddingProps, ISizeProps, ITagProps, ITypographyProps } from "../../interfaces";
+import type { TColor, TIcon } from "../../types";
+export interface IPaginationProps extends ICommonsComponentProps, ITagProps, IColorProps, IBgColorProps, IBorderProps, IPaddingProps, IMarginProps, IElevationProps, ISizeProps, IDensityProps, ITypographyProps {
     start?: number;
     modelValue?: number;
     disabled?: boolean;
@@ -56,6 +56,21 @@ export interface IPaginationProps extends ICommonsComponentProps, ITagProps, ICo
      * (`"Next"` in English).
      */
     nextText?: string;
+    /**
+     * aria-label for the compact mode page number `<input>`. Falls back to
+     * the `origam.pagination.ariaLabel.pageNumber` i18n key.
+     *
+     * @default 'origam.pagination.ariaLabel.pageNumber'
+     */
+    pageNumberAriaLabel?: string;
+    /** @deprecated Use the `hover` object prop instead. Kept for back-compat. */
+    hoverColor?: TColor;
+    /** @deprecated Use the `hover` object prop instead. Kept for back-compat. */
+    hoverBgColor?: TColor;
+    /** @deprecated Use the `active` object prop instead. Kept for back-compat. */
+    activeColor?: TColor;
+    /** @deprecated Use the `active` object prop instead. Kept for back-compat. */
+    activeBgColor?: TColor;
 }
 /** Emits fired by `<OrigamPagination>` — current page v-model + the four
  *  navigation shortcuts (first / prev / next / last). */

package/dist/src/interfaces/Parallax/parallax.interface.d.ts

@@ -1,7 +1,7 @@
-import type { IAudioProps, IBorderProps, IBox, IBgColorProps, IColorProps, ICommonsComponentProps, IDimensionProps, IElevationProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps, IParallaxLayerRegistry } from '../../interfaces';
+import type { IAudioProps, IBorderProps, IBox, IBgColorProps, IColorProps, ICommonsComponentProps, IDimensionProps, IElevationProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps, IParallaxLayerRegistry, IUseAudioProps } from '../../interfaces';
 import type { TParallaxDirection, TParallaxEasing, TParallaxEvent, TPoint } from '../../types';
 import type { Ref } from 'vue';
-export interface IParallaxProps extends ICommonsComponentProps, ITagProps, IColorProps, IBgColorProps, IPaddingProps, IMarginProps, IBorderProps, IRoundedProps, IElevationProps, IDimensionProps, IAudioProps {
+export interface IParallaxProps extends ICommonsComponentProps, ITagProps, IColorProps, IBgColorProps, IPaddingProps, IMarginProps, IBorderProps, IRoundedProps, IElevationProps, IDimensionProps, IAudioProps, IUseAudioProps {
     /**
      * @deprecated Use `duration` instead. `animationDuration` is kept as a
      * silent alias for backwards-compat and will be removed in v3.0.0.

package/dist/src/interfaces/PasswordField/password-field.interface.d.ts

@@ -99,7 +99,7 @@ export interface IPasswordFieldSlots extends IFieldSlots, Omit<IInputSlots, 'def
         id: string;
         isDisabled: boolean;
         isDirty: boolean;
-        isValid: boolean;
+        isValid: boolean | undefined;
         isReadonly: boolean;
     }) => any;
 }

package/dist/src/interfaces/Picker/picker-title.interface.d.ts

@@ -1,4 +1,4 @@
-import type { IBgColorProps, IColorProps, ICommonsComponentProps, ITagProps } from "../../interfaces";
-export interface IPickerTitleProps extends ICommonsComponentProps, ITagProps, IColorProps, IBgColorProps {
+import type { IBgColorProps, IColorProps, ICommonsComponentProps, ITagProps, ITypographyProps } from "../../interfaces";
+export interface IPickerTitleProps extends ICommonsComponentProps, ITagProps, IColorProps, IBgColorProps, ITypographyProps {
     title?: string;
 }

package/dist/src/interfaces/Progress/progress.interface.d.ts

@@ -1,9 +1,9 @@
-import type { IColorProps, ICommonsComponentProps, IMarginProps, IPaddingProps, IProgressCircularProps, IProgressLinearProps, ITagProps } from '../../interfaces';
+import type { IBgColorProps, IColorProps, ICommonsComponentProps, IMarginProps, IPaddingProps, IProgressCircularProps, IProgressLinearProps, ITagProps } from '../../interfaces';
 import type { TProgressType } from '../../types';
 export interface IProgressProps extends IProgressLinearProps, IProgressCircularProps {
     type?: TProgressType;
 }
-export interface IProgressTypeProps extends ITagProps, ICommonsComponentProps, IColorProps, IPaddingProps, IMarginProps {
+export interface IProgressTypeProps extends ITagProps, ICommonsComponentProps, IColorProps, IBgColorProps, IPaddingProps, IMarginProps {
     indeterminate?: boolean;
     modelValue?: string | number;
     thickness?: string | number;
@@ -11,4 +11,10 @@ export interface IProgressTypeProps extends ITagProps, ICommonsComponentProps, I
     absolute?: boolean;
     max?: number | string;
     striped?: boolean;
+    /**
+     * Accessible label for the progress bar (aria-label). When omitted,
+     * defaults to `'Loading'`. Pass a localised string via your i18n
+     * provider or the parent component's `labels` mechanism.
+     */
+    label?: string;
 }

package/dist/src/interfaces/RatingField/rating-field-item.interface.d.ts

@@ -5,6 +5,7 @@ export interface IRatingFieldItemProps extends ICommonsComponentProps, ITagProps
     index?: number;
     value: number;
     label?: string;
+    itemAriaLabel?: string;
     showStar?: boolean;
     isFilled?: boolean;
     isHovered?: boolean;
@@ -15,7 +16,7 @@ export interface IRatingFieldItemProps extends ICommonsComponentProps, ITagProps
     emptyIcon?: TIcon;
     halfIncrements?: boolean;
     checked?: boolean;
-    length?: number;
+    length?: number | string;
 }
 /** Emits fired by `<OrigamRatingFieldItem>` — click + hover surface
  *  (pointer enter / leave drive the half-rating preview). */

package/dist/src/interfaces/SelectionControl/selection-control-group.interface.d.ts

@@ -3,7 +3,8 @@ import type { TIcon } from '../../types';
 import { Ref } from 'vue';
 export interface ISelectionControlGroupProps extends ICommonsComponentProps, IColorProps, IDensityProps, IRippleProps {
     disabled?: boolean;
-    error?: boolean;
+    /** Error state. Accepts `boolean` or a `string` error message (same contract as `IValidationProps`). */
+    error?: string | boolean;
     inline?: boolean;
     falseIcon?: TIcon;
     trueIcon?: TIcon;

package/dist/src/interfaces/SelectionControl/selection-control.interface.d.ts

@@ -1,17 +1,35 @@
-import type { IActiveProps, IBgColorProps, IColorProps, ICommonsComponentEmits, ICommonsComponentProps, ISelectionControlGroupProps, IHoverProps } from '../../interfaces';
-import type { TIcon } from '../../types';
-export interface ISelectionControlProps extends ICommonsComponentProps, Partial<Omit<ISelectionControlGroupProps, 'items'>>, IColorProps, IBgColorProps, IActiveProps, IHoverProps {
+import type { IActiveProps, IBgColorProps, IColorProps, ICommonsComponentEmits, ICommonsComponentProps, IDensityProps, ISelectionControlGroupProps, IHoverProps } from '../../interfaces';
+import type { TColor, TIcon } from '../../types';
+export interface ISelectionControlProps extends ICommonsComponentProps, Partial<Omit<ISelectionControlGroupProps, 'items'>>, IColorProps, IBgColorProps, IActiveProps, IHoverProps, IDensityProps {
     label?: string;
     trueValue?: any;
     falseValue?: any;
     value?: any;
     required?: boolean;
+    /** @deprecated Use the `active` object prop instead. Kept for back-compat. */
+    activeColor?: TColor;
+    /** @deprecated Use the `active` object prop instead. Kept for back-compat. */
+    activeBgColor?: TColor;
 }
 export interface ISelectionControlEmits extends ICommonsComponentEmits {
     (e: 'click:label', event: MouseEvent): void;
 }
 export interface ISelectionControlSlots {
-    default?: (model: any, icon: TIcon, props: any) => any;
+    default?: (data: {
+        model: any;
+        color?: TColor;
+        bgColor?: TColor;
+        icon?: TIcon;
+        props: any;
+    }) => any;
     label?: () => any;
-    input?: (props: any, icon: TIcon, model: any) => any;
+    input?: (data: {
+        model: any;
+        color?: TColor;
+        bgColor?: TColor;
+        icon?: TIcon;
+        props: any;
+        textColorStyles?: any;
+        backgroundColorStyles?: any;
+    }) => any;
 }

package/dist/src/interfaces/Sheet/sheet.interface.d.ts

@@ -1,6 +1,6 @@
-import type { IActiveProps, IBorderProps, IColorProps, ICommonsComponentProps, IDimensionProps, IElevationProps, IHoverProps, ILocationProps, IMarginProps, IPaddingProps, IPositionProps, IRoundedProps, ITagProps } from '../../interfaces';
+import type { IActiveProps, IBgColorProps, IBorderProps, IColorProps, ICommonsComponentProps, IDimensionProps, IElevationProps, IHoverProps, ILocationProps, IMarginProps, IPaddingProps, IPositionProps, IRoundedProps, ITagProps } from '../../interfaces';
 import type { TDirectionBoth, TSheetSnapId, TSheetSnapPoint } from '../../types';
-export interface ISheetProps extends ITagProps, ICommonsComponentProps, IPaddingProps, IMarginProps, IColorProps, IBorderProps, IRoundedProps, IElevationProps, IDimensionProps, ILocationProps, IPositionProps, IActiveProps, IHoverProps {
+export interface ISheetProps extends ITagProps, ICommonsComponentProps, IPaddingProps, IMarginProps, IColorProps, IBgColorProps, IBorderProps, IRoundedProps, IElevationProps, IDimensionProps, ILocationProps, IPositionProps, IActiveProps, IHoverProps {
     /**
      * Edge the sheet is anchored to. Drives the bottom-swipe gesture
      * (only `'bottom'` activates the touch-drag handle today; the other

package/dist/src/interfaces/Snackbar/snackbar-item.interface.d.ts

@@ -1,4 +1,4 @@
-import type { ICommonsComponentProps } from '../../interfaces';
+import type { ICommonsComponentProps, ITypographyProps } from '../../interfaces';
 import type { TIcon, TIntent } from '../../types';
 import type { ISnackbarGroupItemAction } from '../../interfaces';
 /**
@@ -17,7 +17,7 @@ import type { ISnackbarGroupItemAction } from '../../interfaces';
  * Both `OrigamSnackbar` and `OrigamSnackbarGroup` consume this component
  * so all visual intent / layout logic lives in one place only.
  */
-export interface ISnackbarItemProps extends ICommonsComponentProps {
+export interface ISnackbarItemProps extends ICommonsComponentProps, ITypographyProps {
     /**
      * Semantic intent — drives icon defaults and surface colouring via
      * `--origam-color__feedback--{intent}---*` tokens.

package/dist/src/interfaces/SystemBar/system-bar.interface.d.ts

@@ -1,4 +1,4 @@
-import type { IBorderProps, IBgColorProps, IColorProps, ICommonsComponentProps, IDimensionProps, IElevationProps, ILayoutItemProps, IRoundedProps, ITagProps } from "../../interfaces";
-export interface ISystemBarProps extends ICommonsComponentProps, ITagProps, IElevationProps, IColorProps, IBgColorProps, ILayoutItemProps, IRoundedProps, IBorderProps, IDimensionProps {
+import type { IBorderProps, IBgColorProps, IColorProps, ICommonsComponentProps, IDimensionProps, IElevationProps, ILayoutItemProps, IRoundedProps, ITagProps, ITypographyProps } from "../../interfaces";
+export interface ISystemBarProps extends ICommonsComponentProps, ITagProps, IElevationProps, IColorProps, IBgColorProps, ILayoutItemProps, IRoundedProps, IBorderProps, IDimensionProps, ITypographyProps {
     window?: boolean;
 }

package/dist/src/interfaces/Table/table.interface.d.ts

@@ -1,5 +1,5 @@
-import type { IBorderProps, ICommonsComponentProps, IDensityProps, IDimensionProps, IElevationProps, IHoverProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps } from '../../interfaces';
-export interface ITableProps extends ICommonsComponentProps, IBorderProps, IRoundedProps, IElevationProps, IPaddingProps, IMarginProps, IHoverProps, IDimensionProps, IDensityProps, ITagProps {
+import type { IBorderProps, ICommonsComponentProps, IDensityProps, IDimensionProps, IElevationProps, IHoverProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps, ITypographyProps } from '../../interfaces';
+export interface ITableProps extends ICommonsComponentProps, IBorderProps, IRoundedProps, IElevationProps, IPaddingProps, IMarginProps, IHoverProps, IDimensionProps, IDensityProps, ITagProps, ITypographyProps {
     fixedHeader?: boolean;
     fixedFooter?: boolean;
     caption?: string;

package/dist/src/interfaces/Tabs/tab.interface.d.ts

@@ -1,4 +1,4 @@
-import type { ICommonsComponentProps, IGroupItemProps, ITagProps } from '../../interfaces';
+import type { ICommonsComponentProps, IGroupItemProps, ITagProps, ITypographyProps } from '../../interfaces';
 import type { TIcon } from '../../types';
 /**
  * Props for `<OrigamTab>` — a single registered tab inside an
@@ -10,8 +10,13 @@ import type { TIcon } from '../../types';
  * ARIA wiring (`role="tab"`, `aria-selected`, `aria-controls`, `id`,
  * `tabindex`) is computed inside the component — consumers only
  * provide `value` (the canonical identifier) and `disabled`.
+ *
+ * Typography props (`fontSize`, `fontWeight`, `letterSpacing`) override
+ * the matching `--origam-tabs__item---*` variables on the tab element.
+ * `lineHeight` is intentionally excluded — the SCSS hard-codes `line-height: 1`
+ * with no CSS-var hook.
  */
-export interface ITabProps extends ICommonsComponentProps, ITagProps, IGroupItemProps {
+export interface ITabProps extends ICommonsComponentProps, ITagProps, IGroupItemProps, ITypographyProps {
     tag?: string;
     icon?: TIcon;
     appendIcon?: TIcon;

package/dist/src/interfaces/TextField/text-field.interface.d.ts

@@ -53,7 +53,7 @@ export interface ITextFieldSlots extends IFieldSlots, Omit<IInputSlots, 'default
         id: string;
         isDisabled: boolean;
         isDirty: boolean;
-        isValid: boolean;
+        isValid: boolean | undefined;
         isReadonly: boolean;
     }) => any;
 }

package/dist/src/interfaces/TextMask/text-mask.interface.d.ts

@@ -1,4 +1,4 @@
-import type { ICommonsComponentProps, IGradient, ITagProps } from '../../interfaces';
+import type { ICommonsComponentProps, IGradient, ITagProps, ITypographyProps } from '../../interfaces';
 import type { TBlockquoteAlign, TTextMaskAnimation } from '../../types';
 /**
  * Props for `<OrigamTextMask>` — typographic "window" component.
@@ -16,8 +16,13 @@ import type { TBlockquoteAlign, TTextMaskAnimation } from '../../types';
  *
  * The text content is preserved in the DOM (visible to screen readers
  * and search engines) — the visual transform is purely CSS.
+ *
+ * Typography is handled via the shared {@link ITypographyProps} surface:
+ * pass token keys (`fontSize="5xl"`, `fontWeight="black"`, …) to override
+ * the component's default values; when a prop is unset the SCSS fallback
+ * token (`--origam-text-mask---font-size-default`, …) stays in control.
  */
-export interface ITextMaskProps extends ICommonsComponentProps, ITagProps {
+export interface ITextMaskProps extends ICommonsComponentProps, ITagProps, ITypographyProps {
     /**
      * Text to mask. Ignored when the `default` slot is provided.
      *
@@ -64,37 +69,6 @@ export interface ITextMaskProps extends ICommonsComponentProps, ITagProps {
      * @default 'pan'
      */
     animationType?: TTextMaskAnimation;
-    /**
-     * `font-size` of the masked text. Numbers are interpreted as `px`.
-     *
-     * @default 'inherit'
-     */
-    fontSize?: string | number;
-    /**
-     * `font-weight` of the masked text. Accepts numeric weights (100–900)
-     * or keywords (`'bold'`, `'normal'`, …).
-     *
-     * @default 'inherit'
-     */
-    fontWeight?: string | number;
-    /**
-     * `font-family` stack applied to the masked text.
-     *
-     * @default 'inherit'
-     */
-    fontFamily?: string;
-    /**
-     * `line-height` applied to the masked text. Tight by default so the
-     * glyph baseline aligns nicely on large display text.
-     *
-     * @default 1.1
-     */
-    lineHeight?: string | number;
-    /**
-     * `letter-spacing` applied to the masked text. Optional — defaults to
-     * the CSS initial value (i.e. inherits from the document).
-     */
-    letterSpacing?: string;
     /**
      * `text-align` of the masked content.
      *

package/dist/src/interfaces/TextareaField/textarea-field.interface.d.ts

@@ -1,6 +1,6 @@
-import type { IAdjacentInnerProps, IBorderProps, IColorProps, ICommonsComponentProps, IDensityProps, IElevationProps, IFieldEmits, IFieldProps, IFieldSlots, IInputEmits, IInputProps, IInputSlots, IMarginProps, IPaddingProps, IRoundedProps, ITextareaToolbarSlotProps } from '../../interfaces';
+import type { IAdjacentInnerProps, IBorderProps, IColorProps, ICommonsComponentProps, IDensityProps, IElevationProps, IFieldEmits, IFieldProps, IFieldSlots, IInputEmits, IInputProps, IInputSlots, IMarginProps, IPaddingProps, IRoundedProps, ITextareaToolbarSlotProps, ITypographyProps } from '../../interfaces';
 import type { TTextareaMode, TTextareaOutput, TTextareaToolbarCommand, TTextareaToolbarPosition } from '../../types';
-export interface ITextareaFieldProps extends ICommonsComponentProps, IColorProps, IDensityProps, IFieldProps, IInputProps, IPaddingProps, IMarginProps, IBorderProps, IRoundedProps, IElevationProps, IAdjacentInnerProps {
+export interface ITextareaFieldProps extends ICommonsComponentProps, IColorProps, IDensityProps, IFieldProps, IInputProps, IPaddingProps, IMarginProps, IBorderProps, IRoundedProps, IElevationProps, IAdjacentInnerProps, ITypographyProps {
     autoGrow?: boolean;
     autofocus?: boolean;
     counter?: boolean | number | string;
@@ -65,7 +65,7 @@ export interface ITextareaFieldSlots extends IFieldSlots, Omit<IInputSlots, 'def
         id: string;
         isDisabled: boolean;
         isDirty: boolean;
-        isValid: boolean;
+        isValid: boolean | undefined;
         isReadonly: boolean;
     }) => any;
     /** Replace the rich-text toolbar entirely (rich mode only). */

package/dist/src/interfaces/Theme/origam-theme.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Theme/origam-theme.interface.d.ts

@@ -0,0 +1,114 @@
+import type { IThemeVars, TThemeVars } from '../../types';
+import type { TMode } from '../../types/Theme/theme.type';
+import type { IDefault } from '../DefaultProvider/default-provider.interface';
+/**
+ * Runtime theme object ingested by `createOrigam({ themes })`. At install time
+ * the DS resolves it to a block of `--origam-*` CSS variables injected into
+ * `<head>`, scoped to `:root` (or `[data-theme="<name>"]` when `name` is set,
+ * optionally narrowed by `[data-mode]` when `mode` is set).
+ *
+ * ## A theme has exactly THREE authoring surfaces
+ *
+ * 1. **`vars`** — the design tokens (the normal path). Plain nested JSON keyed
+ *    by token GROUP (`color` / `rounded` / `border` / `typo` / `shadow` /
+ *    `spacing` / `motion`). No `--origam-*` prefixes, no DTCG ceremony: the DS
+ *    walks each tree and derives the CSS-variable name from the leaf path, so a
+ *    hand-written theme resolves to the EXACT same `--origam-*` names as the
+ *    published token sheets.
+ *
+ * 2. **`cssVars`** — the escape hatch. A flat map of raw `--origam-*` custom
+ *    properties, for the rare var that has no group slot in `vars`.
+ *
+ * 3. **`component`** — per-component DEFAULT PROPS (not CSS): `{ global, 'origam-btn', … }`.
+ *
+ * ```ts
+ * {
+ *   name: 'sobre', mode: 'light', label: 'Sobre',
+ *   vars: {
+ *     color:   { surface: { default: '#ffffff' }, text: { primary: '#171717', secondary: '#525252' },
+ *                action: { primary: { bg: '#7c3aed', fg: '#ffffff' } } },
+ *     rounded: { md: '10px', lg: '14px' },
+ *     typo:    { family: { sans: 'Inter, sans-serif' } },
+ *     shadow:  { md: '0 2px 8px rgba(0,0,0,.12)' }
+ *   },
+ *   components: { 'origam-btn': { variant: 'flat', color: 'primary' } }
+ * }
+ * ```
+ *
+ * A COLOR slot accepts any CSS color OR a gradient (a gradient is an ordinary
+ * color value). Everything is plain JSON so a Theme Builder export round-trips
+ * without loss.
+ */
+export interface IOrigamTheme {
+    /**
+     * Brand name. When set, the injected variables are scoped to
+     * `[data-theme="<name>"]` instead of `:root`, so the theme activates only
+     * when `data-theme` matches (set it via `useTheme().setTheme(name)`).
+     */
+    name?: string;
+    /**
+     * Color mode this variable block applies to. When set alongside `name`,
+     * the selector becomes `[data-theme="<name>"][data-mode="<mode>"]`. When
+     * set without `name`, it becomes `[data-mode="<mode>"]`.
+     */
+    mode?: TMode;
+    /**
+     * Human-readable brand label for UI (e.g. a theme switcher). Falls back to
+     * `name` when absent. Surfaced through `useInstalledThemes()`.
+     */
+    label?: string;
+    /**
+     * Short brand description for UI (e.g. a switcher subtitle). Surfaced
+     * through `useInstalledThemes()`.
+     */
+    description?: string;
+    /**
+     * CSS background value for a brand swatch preview (a solid color or a
+     * `linear-gradient(...)`). Surfaced through `useInstalledThemes()` so a
+     * switcher can render a preview without a hard-coded metadata map.
+     */
+    swatch?: string;
+    /**
+     * THE token-configuration bucket — the normal way to author a theme's
+     * design tokens. Nested JSON keyed by token GROUP; each group's tree
+     * resolves to its `--origam-*` namespace via the shared naming grammar
+     * (see `IThemeVars`):
+     *   - `color`   → `--origam-color-*`   (`color.surface.default`, `color.action.primary.bg`, …)
+     *   - `rounded` → `--origam-radius-*`  (`rounded.md`, `rounded.lg`, …)
+     *   - `border`  → `--origam-border-*`  (`border.width.thin`, …)
+     *   - `typo`    → `--origam-font-*`    (`typo.family.sans`, `typo.size.md`, …)
+     *   - `shadow`  → `--origam-shadow-*`  (`shadow.md`, …)
+     *   - `spacing` → `--origam-space-*`   (`spacing.4`, …)
+     *   - `motion`  → `--origam-motion-*`  (`motion.duration.fast`, …)
+     *
+     * A color leaf accepts any CSS color OR a gradient (no dedicated gradient group).
+     */
+    vars?: IThemeVars;
+    /**
+     * ESCAPE HATCH — pre-resolved raw `--origam-*` custom-property map. Keys
+     * with or without the leading `--` are accepted. Use ONLY for a raw var
+     * that has no group slot in `vars`. Wins over `vars` on key collision.
+     *
+     *   cssVars: { '--origam-some-unmapped-var': '...' }
+     */
+    cssVars?: TThemeVars;
+    /**
+     * Per-component DEFAULT PROPS layer. Keyed by `global` (applies to every
+     * component) or by a component's kebab-case instance name (e.g.
+     * `'origam-btn'`, `'origam-card'`), exactly like `<OrigamDefaultsProvider>`.
+     *
+     * `createOrigam` collapses the `component` maps of the ACTIVE brand×mode
+     * themes into a single `IDefault` and provides it under
+     * `ORIGAM_DEFAULTS_KEY`, so a component rendered with no explicit prop
+     * inherits the theme's default. This is the "look comes from the theme,
+     * not from hard-coded `withDefaults`" mechanism.
+     *
+     * @example
+     * components: {
+     *   global:        { density: 'comfortable' },
+     *   'origam-btn':  { color: 'primary', rounded: 0 },
+     *   'origam-card': { rounded: 'lg', elevation: 2 }
+     * }
+     */
+    components?: IDefault;
+}

package/dist/src/interfaces/Timeline/timeline.interface.d.ts

@@ -37,7 +37,7 @@ export interface ITimelineProps extends ICommonsComponentProps, ITagProps, IColo
     truncateLine?: boolean;
     ariaLabel?: string;
 }
-export interface ITimelineItemProps extends ICommonsComponentProps, IColorProps {
+export interface ITimelineItemProps extends ICommonsComponentProps, IColorProps, IDensityProps, ISizeProps {
     title?: string;
     subtitle?: string;
     icon?: TIcon;