@astryxdesign/core 0.2.0-canary.ea693ac → 0.2.0-canary.ebed74f

package/src/hooks/useInputStatusIcon.test.tsx

@@ -160,3 +160,62 @@ describe('useInputStatusIcon — no dangling aria-describedby (WCAG 1.3.1)', ()
     expectNoDanglingDescribedBy(container);
   });
 });
+
+describe('useInputStatusIcon — input-status-icon theme target', () => {
+  // The stable theme target lands on the on-field status glyph itself, so a
+  // theme can restyle (e.g. resize) just this icon via `defineTheme`. It is
+  // rendered by the attached and tooltip variants; detached suppresses the
+  // on-field icon in favour of the detached message box's leading glyph.
+  const getStatusIcon = (root: HTMLElement): HTMLElement => {
+    const icon = root.querySelector('.astryx-input-status-icon');
+    if (icon == null) {
+      throw new Error('status icon not found');
+    }
+    return icon as HTMLElement;
+  };
+
+  for (const variant of ['attached', 'tooltip'] as const) {
+    it(`renders the target on the on-field icon (statusVariant="${variant}")`, () => {
+      const {container} = render(
+        <TextInput
+          label="Field"
+          value=""
+          onChange={() => {}}
+          status={{type: 'warning', message: 'Message'}}
+          statusVariant={variant}
+        />,
+      );
+      const icon = getStatusIcon(container);
+      expect(icon).toHaveClass('astryx-input-status-icon');
+      expect(icon).toHaveClass('astryx-icon');
+      expect(icon).toHaveAttribute('data-size', 'md');
+      expect(icon).toHaveAttribute('data-status', 'warning');
+    });
+  }
+
+  it('reflects the status type per status', () => {
+    const {container} = render(
+      <TextInput
+        label="Field"
+        value=""
+        onChange={() => {}}
+        status={{type: 'success', message: 'Message'}}
+        statusVariant="attached"
+      />,
+    );
+    expect(getStatusIcon(container)).toHaveAttribute('data-status', 'success');
+  });
+
+  it('does not render the on-field target for the detached variant', () => {
+    const {container} = render(
+      <TextInput
+        label="Field"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Message'}}
+        statusVariant="detached"
+      />,
+    );
+    expect(container.querySelector('.astryx-input-status-icon')).toBeNull();
+  });
+});

package/src/hooks/useInputStatusIcon.tsx

@@ -41,6 +41,7 @@ import type {InputStatus, InputStatusType} from '../Field/types';
 import {useTooltip} from '../Tooltip';
 import {useTranslator} from '../i18n';
 import {colorVars, radiusVars} from '../theme/tokens.stylex';
+import {themeProps} from '../utils/themeProps';
 
 /**
  * Maps each status type to its glyph. Shared so every input shows the same icon
@@ -194,7 +195,17 @@ export function useInputStatusIcon({
   }
 
   const icon = (
-    <Icon icon={STATUS_ICON[status.type]} size={size} color={status.type} />
+    <Icon
+      icon={STATUS_ICON[status.type]}
+      size={size}
+      color={status.type}
+      // Stable theme target on the status glyph itself, so a theme can restyle
+      // just this icon (color, size) — and each status — via `defineTheme`.
+      // Same-element rules in @layer astryx-theme win over the icon's own base
+      // width/height/fontSize, which a field-level target could not reach.
+      // Shared by the attached and tooltip variants across all bordered inputs.
+      {...themeProps('input-status-icon', {size, status: status.type})}
+    />
   );
 
   // Attached (and tooltip-without-message) variants: plain, non-interactive

package/src/hooks/useKeyboardHint.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useKeyboardHint',
   displayName: 'useKeyboardHint',
@@ -72,7 +72,7 @@ export const docs = {
   category: 'focus',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Ephemeral "← → to navigate" hint anchored to the focused item on first keyboard focus of a roving-tabindex composite (Toolbar/TabList/SegmentedControl). Teaches sighted keyboard users that arrows move within the group. Kbd-rendered arrows in a top-layer popover="manual", CSS-anchor-positioned (never clipped by overflow), aria-hidden. Auto-dismisses on first arrow press, timeout, or blur; never re-shows for that instance.',

package/src/hooks/useKeyboardHint.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/hooks/index.ts
  * - /packages/core/src/hooks/useKeyboardHint.doc.mjs
  * - /apps/storybook/stories/useKeyboardHint.stories.tsx
- * - /packages/cli/templates/blocks/components/Hooks/useKeyboardHintHookUsage.tsx
+ * - /packages/cli/assets/templates/blocks/components/Hooks/useKeyboardHintHookUsage.tsx
  */
 
 import React, {useCallback, useEffect, useRef, type ReactNode} from 'react';

package/src/hooks/useListFocus.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useListFocus',
   displayName: 'useListFocus',
@@ -135,7 +135,7 @@ export const docs = {
   category: 'focus',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Manages keyboard navigation within linear list following WAI-ARIA menu/listbox/toolbar patterns. Supports arrow key navigation (vertical / horizontal), Home/End for boundaries, optional wrap-around, Escape to close. Suitable for dropdown menus, toolbars, any 1D focusable list.',

package/src/hooks/useListFocus.ts

@@ -82,14 +82,15 @@ export interface UseListFocusOptions {
   hasHomeEnd?: boolean;
 
   /**
-   * Whether the list is in a right-to-left context. When true, ArrowLeft and
-   * ArrowRight are swapped so horizontal navigation follows visual direction.
-   * Only affects horizontal (`'horizontal'`/`'both'`) navigation.
+   * @deprecated Direction is auto-detected from the container's computed
+   * `direction` — omit this. The explicit override is redundant (there's no
+   * valid reason to force RTL arrows in an LTR context) and will be removed in
+   * an upcoming major.
    *
-   * When omitted, the direction is auto-detected from the container's computed
-   * `direction` (read lazily on keydown, only for horizontal arrow keys), so
-   * lists inside `dir="rtl"` subtrees flip automatically. Pass an explicit
-   * boolean to override detection.
+   * When set, forces whether the list is right-to-left: ArrowLeft/ArrowRight
+   * are swapped so horizontal navigation follows visual direction. When
+   * omitted (preferred), the direction is auto-detected from the container's
+   * computed `direction` (read lazily on keydown, horizontal arrows only).
    * @default undefined (auto-detect from the container)
    */
   isRtl?: boolean;

package/src/hooks/useMediaQuery.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useMediaQuery',
   displayName: 'useMediaQuery',
@@ -34,7 +34,7 @@ export const docs = {
   category: 'media',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description: 'SSR-safe media query hook subscribing to window.matchMedia changes. Returns whether given media query matches. Always returns false on first render for SSR compatibility.',
   paramDescriptions: {

package/src/hooks/useOverflow.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useOverflow',
   displayName: 'useOverflow',
@@ -84,7 +84,7 @@ export const docs = {
   category: 'layout',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Measures children rendered in hidden container to determine how many fit in available width w/o flickering. Uses ResizeObserver to react to container size changes. Measurement container should hold all items plus optional overflow indicator element (identified by data-overflow-indicator attribute).',

package/src/hooks/useScrollLock.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useScrollLock',
   displayName: 'useScrollLock',
@@ -29,7 +29,7 @@ export const docs = {
   category: 'layout',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Locks body scroll when active by pinning body w/ position: fixed. Prevents background scrolling behind modals + dialogs, necessary for iOS Safari where overscroll-behavior: contain does not work. Restores original scroll position when unlocked.',

package/src/hooks/useScrollOverflow.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useScrollOverflow',
   displayName: 'useScrollOverflow',
@@ -43,7 +43,7 @@ export const docs = {
   category: 'layout',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Tracks scroll overflow state for horizontally scrollable container. Returns ref callback + state booleans that update as user scrolls / container resizes. Uses scroll event listeners + ResizeObserver for reactive updates. Tolerance of 1px applied to avoid sub-pixel false positives.',

package/src/hooks/useStreamingText.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useStreamingText',
   displayName: 'useStreamingText',
@@ -55,7 +55,7 @@ export const docs = {
   category: 'streaming',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Smooths bursty streamed text into steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word + syntax boundaries to avoid slicing mid-markdown / mid-word, preventing visual glitches w/ markdown renderers. Animation timing derives from Astryx motion tokens via useTheme when available, w/ sensible fallbacks outside theme provider. Snaps to full text when isStreaming becomes false.',

package/src/hooks/useTreeFocus.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useTreeFocus',
   displayName: 'useTreeFocus',
@@ -106,7 +106,7 @@ export const docs = {
   category: 'focus',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Manages roving-tabindex focus + WAI-ARIA tree keyboard model. ArrowUp/Down/Home/End roam linearly over visible treeitems (skip disabled); ArrowRight/Left carry tree semantics (expand/collapse, move to first-child/parent). Enter/Space activate; printable chars trigger typeahead.',

package/src/hooks/useTreeFocus.test.tsx

@@ -35,10 +35,12 @@ function Tree({
   collapsed = NO_NODES,
   expanded = NO_NODES,
   onActivate,
+  dir,
 }: {
   collapsed?: Node[];
   expanded?: Node[];
   onActivate?: (id: string | undefined) => boolean | undefined;
+  dir?: 'ltr' | 'rtl';
 }) {
   const [isOpen, setIsOpen] = useState(false);
   const nodes = isOpen && expanded.length > 0 ? expanded : collapsed;
@@ -47,7 +49,7 @@ function Tree({
     onActivate: onActivate ? (_item, id) => onActivate(id) : undefined,
   });
   return (
-    <ul ref={treeRef} role="tree" onKeyDown={handleKeyDown}>
+    <ul ref={treeRef} role="tree" dir={dir} onKeyDown={handleKeyDown}>
       {nodes.map(n => (
         <li
           key={n.id}
@@ -172,6 +174,56 @@ describe('useTreeFocus tree semantics (Arrow Left/Right)', () => {
   });
 });
 
+describe('useTreeFocus RTL tree semantics (WAI-ARIA Tree View)', () => {
+  const COLLAPSED: Node[] = [
+    {id: 'p', label: 'Parent', level: 1, expanded: false},
+  ];
+  const EXPANDED: Node[] = [
+    {id: 'p', label: 'Parent', level: 1, expanded: true},
+    {id: 'c1', label: 'Child 1', level: 2},
+    {id: 'c2', label: 'Child 2', level: 2},
+  ];
+
+  it('auto-detects dir="rtl": ArrowLeft expands a collapsed parent, then enters the first child', () => {
+    render(<Tree collapsed={COLLAPSED} expanded={EXPANDED} dir="rtl" />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('p').focus();
+
+    expect(screen.queryByTestId('c1')).not.toBeInTheDocument();
+    fireEvent.keyDown(tree, {key: 'ArrowLeft'}); // RTL: descend → expand
+    expect(screen.getByTestId('c1')).toBeInTheDocument();
+    expect(screen.getByTestId('p')).toHaveFocus();
+
+    fireEvent.keyDown(tree, {key: 'ArrowLeft'}); // RTL: descend → into first child
+    expect(screen.getByTestId('c1')).toHaveFocus();
+  });
+
+  it('auto-detects dir="rtl": ArrowRight moves to parent, then collapses', () => {
+    render(<Tree collapsed={COLLAPSED} expanded={EXPANDED} dir="rtl" />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('p').focus();
+    fireEvent.keyDown(tree, {key: 'ArrowLeft'}); // expand
+    fireEvent.keyDown(tree, {key: 'ArrowLeft'}); // into child 1
+    expect(screen.getByTestId('c1')).toHaveFocus();
+
+    fireEvent.keyDown(tree, {key: 'ArrowRight'}); // RTL: ascend → child leaf → parent
+    expect(screen.getByTestId('p')).toHaveFocus();
+
+    fireEvent.keyDown(tree, {key: 'ArrowRight'}); // RTL: ascend → expanded parent → collapse
+    expect(screen.queryByTestId('c1')).not.toBeInTheDocument();
+  });
+
+  it('vertical keys (ArrowDown/ArrowUp) are unaffected by RTL', () => {
+    render(<Tree collapsed={FLAT} dir="rtl" />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('a').focus();
+    fireEvent.keyDown(tree, {key: 'ArrowDown'});
+    expect(screen.getByTestId('b')).toHaveFocus();
+    fireEvent.keyDown(tree, {key: 'ArrowUp'});
+    expect(screen.getByTestId('a')).toHaveFocus();
+  });
+});
+
 describe('useTreeFocus activation + typeahead', () => {
   it('Enter/Space call onActivate for the focused item', () => {
     const onActivate = vi.fn(() => true);

package/src/hooks/useTreeFocus.ts

@@ -4,7 +4,7 @@
 
 /**
  * @file useTreeFocus.ts
- * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect
+ * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect, isRtlElement
  * @output Exports useTreeFocus hook for WAI-ARIA tree keyboard navigation
  * @position Core hook; used by TreeList for roving tabindex + APG tree keyboard model
  *
@@ -16,6 +16,7 @@
 
 import {useCallback, useRef} from 'react';
 import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
+import {isRtlElement} from './isRtlElement';
 
 /** Keys handled by the tree keyboard model (used to gate typeahead). */
 const NAVIGATION_KEYS = new Set([
@@ -429,7 +430,17 @@ export function useTreeFocus<T extends HTMLElement = HTMLElement>(
         return;
       }
 
-      switch (e.key) {
+      // Under RTL, swap the horizontal arrows to a logical key so the
+      // expand/collapse case bodies (written LTR-first) stay unchanged.
+      let key = e.key;
+      if (key === 'ArrowLeft' || key === 'ArrowRight') {
+        const rtl = isRtlElement(treeRef.current);
+        if (rtl) {
+          key = key === 'ArrowLeft' ? 'ArrowRight' : 'ArrowLeft';
+        }
+      }
+
+      switch (key) {
         case 'ArrowDown': {
           e.preventDefault();
           focusEnabledFrom(items, currentIndex < 0 ? 0 : currentIndex + 1, 1);

package/src/i18n/InternationalizationProvider.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'InternationalizationProvider',
@@ -128,7 +128,7 @@ export function AppI18n({children}: {children: ReactNode}) {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Wraps app to set active locale and (optionally) merge translation catalogs + per-locale overrides. Astryx components resolve strings against this context; missing keys fall back to shipped English.',

package/src/i18n/useTranslator.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useTranslator',
   displayName: 'useTranslator',
@@ -31,7 +31,7 @@ export const docs = {
   importPath: '@astryxdesign/core',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Hook returning a translator function bound to the current InternationalizationProvider context. Call with an ICU MessageFormat key and values to get the formatted string for the active locale.',

package/src/index.ts

@@ -168,25 +168,29 @@ export * from './hooks';
 export * from './utils';
 
 // Theme
+export type {TextColorMap} from './Text';
 export * from './theme';
 
 // Internationalization
 export * from './i18n';
 
-// Doc types — for external library authors writing .doc.mjs files
+// Doc types — for external library authors writing .doc.mjs files.
+// @deprecated Import these from `@astryxdesign/cli/authoring` instead. These
+// re-exports are kept for one release cycle and will be removed; `astryx upgrade`
+// repoints them automatically.
 export type {
   ComponentDoc,
   SingleComponentDoc,
   MultiComponentDoc,
-  PropDoc,
+  ComponentPropDoc,
   ComponentEntry,
-  ThemingTarget,
-  ComponentVar,
-  DerivedVar,
-  TranslationDoc,
-  GroupDoc,
+  ComponentThemingTarget,
+  ComponentThemingVar,
+  ComponentThemingDerivedVar,
+  ComponentTranslationDoc,
+  ComponentGroupDoc,
   ReferenceDoc,
   ReferenceSection,
-  ContentBlock,
-  TokenPreviewType,
-} from './docs-types';
+  ReferenceContentBlock,
+  ReferenceTokenPreviewType,
+} from '@astryxdesign/cli/authoring';

package/src/theme/MediaTheme.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'MediaTheme',
@@ -100,7 +100,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   usage: {
     description:

package/src/theme/SyntaxTheme.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'SyntaxTheme',
@@ -74,7 +74,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   usage: {
     description:

package/src/theme/Theme.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Theme',
@@ -86,7 +86,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   usage: {
     description:

package/src/theme/Theme.tsx

@@ -41,8 +41,8 @@ import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import * as stylex from '@stylexjs/stylex';
 import type {ThemeMode} from './types';
 import {colorVars, typographyVars} from './tokens.stylex';
-import {registerIcons} from '../Icon/globalIconRegistry';
 import {generateThemeCSS, type DefinedTheme} from './defineTheme';
+import {registerTheme} from './themeRegistry';
 import {dataAttr} from '../naming';
 import {ThemeContext} from './useTheme';
 import {warnOnce} from '../utils/devWarning';
@@ -243,6 +243,8 @@ export function Theme({
 }: ThemeProps): React.ReactElement {
   const isNested = use(ThemeNestingContext);
 
+  registerTheme(theme);
+
   useThemeStyleInjection(theme);
   useRootThemeSync(isNested, mode, theme.name);
 
@@ -254,12 +256,6 @@ export function Theme({
         ? wrapperStyles.light
         : wrapperStyles.system;
 
-  // Icons — register globally (works in both server and client environments)
-  const icons = theme.icons;
-  if (icons != null) {
-    registerIcons(icons);
-  }
-
   // Memoize the context value to prevent unnecessary re-renders
   const ctxValue = useMemo(() => ({theme, mode}), [theme, mode]);
 

package/src/theme/defineTheme.ts

@@ -63,6 +63,7 @@ import {expandColorScale, type ColorScaleConfig} from './expandColorScale';
 import type {DomainTokenName} from './domainTokens';
 import {domainTokenDefaults} from './domainTokens';
 import type {SyntaxThemeDefinition} from './syntax';
+import {registerTheme} from './themeRegistry';
 
 // =============================================================================
 // Types
@@ -239,9 +240,15 @@ export interface DefineThemeInput {
    * categorical hues, and fixed tokens (on-dark/on-light) use defaults.
    * Explicit `tokens` entries always take precedence.
    *
+   * `accent` is optional — omit it for a neutral-only theme, which keeps
+   * the default accent tokens and only themes the neutrals.
+   *
    * @example
    * ```tsx
    * color: { accent: '#0064E0', neutralStyle: 'cool', contrast: 'standard' }
+   *
+   * // Neutral-only — accent tokens stay at their defaults
+   * color: { neutralStyle: 'warm' }
    * ```
    */
   color?: ColorScaleConfig;
@@ -618,7 +625,7 @@ export function defineTheme(input: DefineThemeInput): DefinedTheme {
       ? {...base.icons, ...input.icons}
       : (input.icons ?? base?.icons);
 
-  return {
+  const theme: DefinedTheme = {
     name: input.name,
     tokens,
     components,
@@ -627,6 +634,9 @@ export function defineTheme(input: DefineThemeInput): DefinedTheme {
     __onDark,
     __onLight,
   };
+
+  registerTheme(theme);
+  return theme;
 }
 
 // =============================================================================