@astryxdesign/core 0.2.0 → 0.3.0-canary.1b8b3f2

package/src/Grid/GridSpan.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: 'GridSpan',

package/src/Grid/GridSpan.tsx

@@ -10,7 +10,7 @@
  * - /packages/core/src/Grid/Grid.doc.mjs
  * - /packages/core/src/Grid/Grid.test.tsx
  * - /apps/storybook/stories/Grid.stories.tsx
- * - /packages/cli/templates/blocks/components/Grid/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Grid/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';

package/src/HStack/HStack.tsx

@@ -9,7 +9,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Stack/Stack.doc.mjs
  * - /packages/core/src/HStack/HStack.test.tsx
- * - /packages/cli/templates/blocks/components/HStack/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/HStack/ (showcase blocks)
  */
 
 import {Stack, type StackProps} from '../Stack/Stack';

package/src/Heading/Heading.tsx

@@ -13,8 +13,8 @@
  * - /packages/core/src/Heading/Heading.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Text/index.ts (exports if types change)
  * - /apps/storybook/stories/Text.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Heading/ (showcase blocks)
- * - /packages/cli/templates/blocks/components/Text/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Heading/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Text/ (showcase blocks)
  */
 
 import {lazy, Suspense, useRef, type ReactNode} from 'react';
@@ -41,6 +41,7 @@ import {
   truncationTooltipStyles,
 } from '../Text/text.stylex';
 import {useTruncation} from '../Text/useTruncation';
+import {resolveStyleColor} from '../Text/Text';
 import type {LayerPlacement} from '../Layer';
 import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
@@ -251,7 +252,7 @@ export function Heading({
         {...mergeProps(
           themeProps('heading', {level, color, ...(type && {type})}),
           stylex.props(
-            colorStyles[color],
+            colorStyles[resolveStyleColor(color)],
             type ? sizeByTypeStyles[type] : sizeByLevelStyles[level],
             type && defaultWeightByTypeStyles[type],
             // Display: use truncation styles when maxLines > 0

package/src/HoverCard/HoverCard.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: 'HoverCard',
@@ -125,7 +125,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'HoverCard',
   displayName: 'Hover Card',
@@ -234,7 +234,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Hover/focus triggered overlay for displaying rich, interactive content anchored to trigger element.',

package/src/HoverCard/HoverCard.tsx

@@ -12,7 +12,7 @@
  * - /packages/core/src/HoverCard/HoverCard.test.tsx
  * - /packages/core/src/HoverCard/index.ts
  * - /apps/storybook/stories/HoverCard.stories.tsx
- * - /packages/cli/templates/blocks/components/HoverCard/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/HoverCard/ (showcase blocks)
  */
 
 import {useCallback, useRef, type ReactElement, type ReactNode} from 'react';

package/src/HoverCard/useHoverCard.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: 'useHoverCard',
   displayName: 'useHoverCard',
@@ -43,7 +43,7 @@ export const docs = {
   category: 'interaction',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description: 'Headless hover-triggered floating cards. Builds on useLayer w/ hover/focus intent, delays, safe hover behavior, aria-describedby. Use for rich previews when trigger/content rendering needs full control.',
   paramDescriptions: {

package/src/Icon/Icon.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: 'Icon',
@@ -19,7 +19,7 @@ export const docs = {
     {
       name: 'icon',
       type: 'IconName | ComponentType<SVGProps>',
-      description: 'Semantic icon name or SVG component. Valid semantic names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For any icon not in this list, pass an SVG component directly (e.g. import from lucide-react or @heroicons/react). Note: this prop is called `icon`, not `name`.',
+      description: 'Semantic icon name or SVG component. Valid semantic names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For any icon not in this list, pass an SVG component directly (e.g. import from lucide-react or @heroicons/react). Note: this prop is called `icon`, not `name`.',
       required: true,
     },
     {
@@ -55,6 +55,7 @@ export const docs = {
     description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
     bestPractices: [
       { guidance: true, description: 'Use semantic icon names when available; they adapt to theme changes automatically.' },
+      { guidance: true, description: "Libraries can augment the icon map with their own keys: registerIcons({'richtext:bold': <MyIcon />}) accepts arbitrary extension keys (not just the built-in IconName set). Resolve them with getExtendedIcon(key, fallback), which prefers a theme-registered icon and falls back to a bundled default — the seam that makes library-shipped icons theme-overridable." },
       { guidance: true, description: 'Pair icons with text labels for accessibility; icon-only elements need an accessible label.' },
       { guidance: true, description: 'For a meaningful standalone icon (no adjacent text), give it an accessible name via the `label` prop: it sets role="img" + aria-label and unhides the icon.' },
       { guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },
@@ -68,7 +69,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Icon',
   displayName: 'Icon',
@@ -76,7 +77,7 @@ export const docsZh = {
     {
       name: 'icon',
       type: 'IconName | ComponentType<SVGProps>',
-      description: '语义图标名称或 SVG 组件。有效语义名称：close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone。列表之外的图标请直接传入 SVG 组件。',
+      description: '语义图标名称或 SVG 组件。有效语义名称：close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone。列表之外的图标请直接传入 SVG 组件。',
       required: true,
     },
     {
@@ -124,7 +125,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Renders icons w/ Astryx design system colors + sizes. Supports direct SVG icon components + semantic icon names that adapt to active theme.',
@@ -144,7 +145,7 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
+    icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
     color: 'Color variant mapped to Astryx icon color tokens.',
     size: 'Icon size.',
     label: 'Accessible name for a meaningful, standalone icon. Sets role="img" + aria-label and drops the default aria-hidden. Omit (default) for decorative icons (stays aria-hidden). Empty string = decorative. The accessible-name/alt-text prop for icons.',

package/src/Icon/Icon.test.tsx

@@ -13,7 +13,11 @@ import {describe, it, expect, vi} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import * as stylex from '@stylexjs/stylex';
 import {TestIcon} from '../__tests__/TestIcon';
+import {Theme} from '../theme/Theme';
+import {defineTheme} from '../theme/defineTheme';
+import {resetThemes} from '../theme/themeRegistry';
 import {Icon} from './Icon';
+import {resetIcons} from './globalIconRegistry';
 
 describe('Icon', () => {
   it('renders the icon component', () => {
@@ -169,6 +173,25 @@ describe('Icon', () => {
     expect(screen.getByTestId('icon')).toHaveAttribute('aria-hidden', 'true');
   });
 
+  it('resolves string-mode icons from the nearest Theme without leaking globally', () => {
+    resetIcons();
+    resetThemes();
+    const outer = defineTheme({name: 'outer', icons: {check: 'outer-check'}});
+    const inner = defineTheme({name: 'inner', icons: {check: 'inner-check'}});
+
+    render(
+      <Theme theme={outer}>
+        <Icon icon="check" data-testid="outer" />
+        <Theme theme={inner}>
+          <Icon icon="check" data-testid="inner" />
+        </Theme>
+      </Theme>,
+    );
+
+    expect(screen.getByTestId('outer')).toHaveTextContent('outer-check');
+    expect(screen.getByTestId('inner')).toHaveTextContent('inner-check');
+  });
+
   it('lets a string-mode icon be made meaningful by overriding aria-hidden', () => {
     render(
       <Icon

package/src/Icon/Icon.tsx

@@ -19,13 +19,14 @@
  * - /packages/core/src/Icon/Icon.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Icon/index.ts (exports if types change)
  * - /apps/storybook/stories/Icon.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Icon/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Icon/ (showcase blocks)
  */
 
 import React, {type ComponentType, type SVGProps} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
+import {useThemeName} from '../theme/useTheme';
 import {getIcon} from './globalIconRegistry';
 import type {IconName} from './globalIconRegistry';
 import {mergeProps} from '../utils';
@@ -379,7 +380,8 @@ function IconFromRegistry({
   xstyle?: StyleXStyles;
   spanProps?: Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'>;
 }) {
-  const resolvedIcon = getIcon(name);
+  const themeName = useThemeName();
+  const resolvedIcon = getIcon(name, themeName);
 
   if (resolvedIcon == null) {
     return null;

package/src/Icon/defaultIcons.tsx

@@ -82,6 +82,20 @@ export const defaultIcons: IconRegistry = {
     </svg>
   ),
 
+  /** « — double left chevron (first / jump to start) */
+  chevronsLeft: (
+    <svg {...svgProps}>
+      <path d="M18 6l-6 6 6 6M11 6l-6 6 6 6" />
+    </svg>
+  ),
+
+  /** » — double right chevron (last / jump to end) */
+  chevronsRight: (
+    <svg {...svgProps}>
+      <path d="M6 6l6 6-6 6M13 6l6 6-6 6" />
+    </svg>
+  ),
+
   /** ✓ — checkmark */
   check: (
     <svg {...svgProps}>

package/src/Icon/globalIconRegistry.test.tsx

@@ -1,17 +1,28 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect, beforeEach} from 'vitest';
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import {defineTheme} from '../theme/defineTheme';
+import {resetThemes} from '../theme/themeRegistry';
+import {__resetDevWarnings} from '../utils/devWarning';
 import {defaultIcons} from './defaultIcons';
 import {
   registerIcons,
   getIconRegistry,
   getIcon,
+  getExtendedIcon,
   resetIcons,
 } from './globalIconRegistry';
 
 describe('iconRegistry (global, RSC-compatible)', () => {
   beforeEach(() => {
     resetIcons();
+    resetThemes();
+    __resetDevWarnings();
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
   });
 
   it('returns a default icon registry snapshot', () => {
@@ -28,6 +39,18 @@ describe('iconRegistry (global, RSC-compatible)', () => {
     expect(icon).not.toBeNull();
   });
 
+  it('warns once that registerIcons applies global overrides', () => {
+    const warnSpy = vi.mocked(console.warn);
+
+    registerIcons({close: 'custom-close'});
+    registerIcons({check: 'custom-check'});
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0]?.[0]).toContain(
+      '`registerIcons()` applies icon overrides globally',
+    );
+  });
+
   it('returns registered icons over defaults', () => {
     const customClose = 'custom-close-icon';
     registerIcons({close: customClose});
@@ -65,6 +88,35 @@ describe('iconRegistry (global, RSC-compatible)', () => {
     expect(getIcon('close')).toBe('close-v2');
   });
 
+  it('resolves icons from an explicit theme object over global registrations', () => {
+    registerIcons({close: 'global-close'});
+    const theme = defineTheme({
+      name: 'brand',
+      icons: {close: 'theme-close'},
+    });
+
+    expect(getIcon('close', theme)).toBe('theme-close');
+    expect(getIconRegistry(theme).close).toBe('theme-close');
+  });
+
+  it('resolves icons from a registered theme name for SSR-friendly lookups', () => {
+    defineTheme({
+      name: 'brand',
+      icons: {close: 'theme-close'},
+    });
+
+    expect(getIcon('close', 'brand')).toBe('theme-close');
+    expect(getIconRegistry('brand').close).toBe('theme-close');
+  });
+
+  it('falls back through global registrations when a theme omits a name', () => {
+    registerIcons({close: 'global-close'});
+    const theme = defineTheme({name: 'brand', icons: {check: 'theme-check'}});
+
+    expect(getIcon('close', theme)).toBe('global-close');
+    expect(getIcon('check', theme)).toBe('theme-check');
+  });
+
   it('resetIcons clears the global registry', () => {
     registerIcons({close: 'custom'});
     expect(getIcon('close')).toBe('custom');
@@ -72,4 +124,38 @@ describe('iconRegistry (global, RSC-compatible)', () => {
     // Should fall back to default
     expect(getIcon('close')).not.toBe('custom');
   });
+
+  describe('extension keys', () => {
+    it('registers and resolves library-contributed keys', () => {
+      registerIcons({'richtext:bold': 'my-bold'});
+      expect(getIcon('richtext:bold')).toBe('my-bold');
+      expect(getExtendedIcon('richtext:bold')).toBe('my-bold');
+    });
+
+    it('getExtendedIcon returns the caller fallback when unregistered', () => {
+      expect(getExtendedIcon('richtext:bold', 'inline-svg')).toBe('inline-svg');
+    });
+
+    it('getExtendedIcon prefers a registered icon over the fallback', () => {
+      registerIcons({'richtext:bold': 'theme-bold'});
+      expect(getExtendedIcon('richtext:bold', 'inline-svg')).toBe('theme-bold');
+    });
+
+    it('getExtendedIcon still resolves built-in defaults', () => {
+      expect(getExtendedIcon('close', 'fallback')).toBe(defaultIcons.close);
+    });
+
+    it('extension keys do not leak into the built-in registry snapshot', () => {
+      registerIcons({'richtext:bold': 'my-bold'});
+      // getIconRegistry() is the built-in IconName snapshot; extension keys
+      // are resolved via getIcon/getExtendedIcon, not surfaced here.
+      expect(Object.keys(getIconRegistry())).toEqual(Object.keys(defaultIcons));
+    });
+
+    it('extension keys are cleared by resetIcons', () => {
+      registerIcons({'richtext:bold': 'my-bold'});
+      resetIcons();
+      expect(getExtendedIcon('richtext:bold', 'fallback')).toBe('fallback');
+    });
+  });
 });

package/src/Icon/globalIconRegistry.tsx

@@ -4,14 +4,17 @@
  * @file globalIconRegistry.tsx
  * @input None (pure module-level state)
  * @output Exports registerIcons, getIconRegistry, getIcon, resetIcons, IconName, IconRegistry
- * @position Global icon registry; works in both server and client environments
+ * @position Global and theme-scoped icon registry; works in server and client environments
  *
  * This module has NO 'use client' directive — it's importable from RSC.
- * All components use getIcon() to resolve icons from this global registry.
+ * Components resolve semantic icons through getIcon() or the client useIcon() hook.
  */
 
 import type {ReactNode} from 'react';
 import {defaultIcons} from './defaultIcons';
+import type {DefinedTheme} from '../theme/defineTheme';
+import {getRegisteredTheme} from '../theme/themeRegistry';
+import {warnOnce} from '../utils/devWarning';
 
 // =============================================================================
 // Types
@@ -23,12 +26,14 @@ import {defaultIcons} from './defaultIcons';
  * These represent the functional purpose of each icon, not a specific
  * visual representation. Themes provide the actual icon components.
  */
-// SYNC: packages/cli/docs/icons.doc.mjs — update USAGE_HINTS when adding names
+// SYNC: packages/cli/assets/docs/icons.doc.mjs — update USAGE_HINTS when adding names
 export type IconName =
   | 'close'
   | 'chevronDown'
   | 'chevronLeft'
   | 'chevronRight'
+  | 'chevronsLeft'
+  | 'chevronsRight'
   | 'check'
   | 'success'
   | 'error'
@@ -52,16 +57,43 @@ export type IconName =
   | 'stop'
   | 'microphone';
 
+/**
+ * A semantic icon name — either one of the built-in {@link IconName}s or an
+ * arbitrary string key contributed by a library/app.
+ *
+ * The `(string & {})` intersection keeps the built-in names available for
+ * autocomplete while still allowing any string, so downstream libraries can
+ * register and resolve their own keys (e.g. `'richtext:bold'`) without having
+ * to widen the core `IconName` union.
+ */
+export type ExtendedIconName = IconName | (string & {});
+
 /**
  * Icon registry mapping semantic names to React nodes.
  */
 export type IconRegistry = Record<IconName, ReactNode>;
 
+export type IconRegistrySource = DefinedTheme | string | null | undefined;
+
 // =============================================================================
 // Global Registry
 // =============================================================================
 
-let globalRegistry: Partial<IconRegistry> = {};
+let globalRegistry: Record<string, ReactNode> = {};
+
+function getThemeIconOverrides(
+  source: IconRegistrySource,
+): Partial<IconRegistry> | null {
+  if (source == null) {
+    return null;
+  }
+
+  if (typeof source === 'string') {
+    return getRegisteredTheme(source)?.icons ?? null;
+  }
+
+  return source.icons ?? null;
+}
 
 /**
  * Register icons at the module level. Works in both server and client
@@ -76,8 +108,24 @@ let globalRegistry: Partial<IconRegistry> = {};
  * import { brandIcons } from './brand-icons';
  * registerIcons(brandIcons);
  * ```
+ *
+ * Libraries may also register their own extension keys (any string), so a
+ * theme can override them the same way it overrides built-in icons:
+ * @example
+ * ```
+ * // In a library that ships its own icons:
+ * registerIcons({ 'richtext:bold': <MyBoldIcon /> });
+ * // resolve with getIcon('richtext:bold')
+ * ```
  */
-export function registerIcons(icons: Partial<IconRegistry>): void {
+export function registerIcons(
+  icons: Partial<Record<ExtendedIconName, ReactNode>>,
+): void {
+  warnOnce(
+    'icon-registry:global-register-icons',
+    'Icon',
+    '`registerIcons()` applies icon overrides globally. Prefer `defineTheme({ icons })` for theme-scoped icon overrides.',
+  );
   globalRegistry = {...globalRegistry, ...icons};
 }
 
@@ -89,13 +137,25 @@ export function registerIcons(icons: Partial<IconRegistry>): void {
  * to derive valid semantic icon-name options from the same registry Icon
  * resolves against.
  */
-export function getIconRegistry(): Readonly<IconRegistry> {
+export function getIconRegistry(
+  source?: IconRegistrySource,
+): Readonly<IconRegistry> {
   const registry = {...defaultIcons};
 
-  for (const name of Object.keys(globalRegistry) as IconName[]) {
+  // Only surface built-in IconName keys here — extension keys registered by
+  // libraries are resolved via getIcon/getExtendedIcon and intentionally kept
+  // out of the typed IconRegistry snapshot.
+  for (const name of Object.keys(defaultIcons) as IconName[]) {
     registry[name] = globalRegistry[name] ?? defaultIcons[name];
   }
 
+  const themeIcons = getThemeIconOverrides(source);
+  if (themeIcons != null) {
+    for (const name of Object.keys(themeIcons) as IconName[]) {
+      registry[name] = themeIcons[name] ?? registry[name];
+    }
+  }
+
   return registry;
 }
 
@@ -104,9 +164,51 @@ export function getIconRegistry(): Readonly<IconRegistry> {
  *
  * Works in both server and client environments.
  * Falls back to built-in default icons when no override is registered.
+ *
+ * Accepts extension keys (any string) in addition to the built-in
+ * {@link IconName}s — useful for library-contributed icons. For a
+ * caller-supplied fallback when a key isn't registered, use
+ * {@link getExtendedIcon}.
+ */
+export function getIcon(
+  name: ExtendedIconName,
+  source?: IconRegistrySource,
+): ReactNode {
+  const themeIcons = getThemeIconOverrides(source);
+  return (
+    themeIcons?.[name as IconName] ??
+    globalRegistry[name] ??
+    defaultIcons[name as IconName]
+  );
+}
+
+/**
+ * Resolve an extension icon by an arbitrary string key, falling back to a
+ * caller-supplied default when nothing is registered.
+ *
+ * This is the seam libraries use to make their own icons themeable: ship the
+ * inline SVG as `fallback`, resolve through this function, and a theme can
+ * override the key via {@link registerIcons} without the library having to
+ * widen the core {@link IconName} union.
+ *
+ * @example
+ * ```
+ * // Library default, overridable by a theme registering 'richtext:bold':
+ * getExtendedIcon('richtext:bold', <BoldGlyph />)
+ * ```
  */
-export function getIcon(name: IconName): ReactNode {
-  return globalRegistry[name] ?? defaultIcons[name];
+export function getExtendedIcon(
+  name: ExtendedIconName,
+  fallback?: ReactNode,
+  source?: IconRegistrySource,
+): ReactNode {
+  const themeIcons = getThemeIconOverrides(source);
+  return (
+    themeIcons?.[name as IconName] ??
+    globalRegistry[name] ??
+    defaultIcons[name as IconName] ??
+    fallback
+  );
 }
 
 /**

package/src/Icon/index.ts

@@ -12,18 +12,20 @@
  */
 
 export {Icon, renderIconSlot} from './Icon';
-export type {
-  IconProps,
-  IconColor,
-  IconSize,
-  IconType,
-} from './Icon';
+export {useIcon} from './useIcon';
+export type {IconProps, IconColor, IconSize, IconType} from './Icon';
 
 // Global registry (RSC-compatible, no 'use client')
 export {
   registerIcons,
   getIconRegistry,
   getIcon,
+  getExtendedIcon,
   resetIcons,
 } from './globalIconRegistry';
-export type {IconName, IconRegistry} from './globalIconRegistry';
+export type {
+  IconName,
+  ExtendedIconName,
+  IconRegistry,
+  IconRegistrySource,
+} from './globalIconRegistry';

package/src/Icon/useIcon.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useIcon.ts
+ * @input Semantic icon name
+ * @output Exports useIcon hook for theme-aware icon lookup
+ * @position Client hook for components that render registry icons directly
+ */
+
+import type {ReactNode} from 'react';
+import {useThemeName} from '../theme/useTheme';
+import {getIcon, type IconName} from './globalIconRegistry';
+
+/**
+ * Resolve a semantic icon name from the nearest Theme, falling back through
+ * root theme registration, global icon overrides, and built-in defaults.
+ */
+export function useIcon(name: IconName): ReactNode {
+  const themeName = useThemeName();
+  return getIcon(name, themeName);
+}

package/src/IconButton/IconButton.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: 'IconButton',
@@ -84,7 +84,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
   usage: {

package/src/IconButton/IconButton.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/IconButton/IconButton.test.tsx (tests)
  * - /packages/core/src/IconButton/index.ts (exports if types change)
  * - /apps/storybook/stories/IconButton.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/IconButton/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/IconButton/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';