@astryxdesign/core 0.2.0-canary.8d64648 → 0.2.0-canary.8dfd7cf

package/src/FieldStatus/FieldStatus.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: 'FieldStatus',
   displayName: 'Field Status',
@@ -64,7 +64,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Validation feedback message for fields/custom controls. Supports error, warning, success and attached/detached variants. Announced via persistent live regions (assertive for errors, polite otherwise).',

package/src/FieldStatus/FieldStatus.tsx

@@ -11,7 +11,7 @@
  * - /packages/core/src/Field/Field.doc.mjs (compat docs when public API changes)
  * - /packages/core/src/FieldStatus/index.ts (exports if types change)
  * - /packages/core/src/Field/index.ts (compat re-export if public API changes)
- * - /packages/cli/templates/blocks/components/FieldStatus/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/FieldStatus/ (showcase blocks)
  */
 
 'use client';
@@ -33,6 +33,7 @@ import {useEntryAnimation} from '../hooks/useEntryAnimation';
 import {themeProps} from '../utils/themeProps';
 import {Icon} from '../Icon';
 import type {IconName} from '../Icon';
+import type {FieldStatusVariantMap} from './index';
 
 /**
  * Maps each status type to its status glyph. Mirrors the mapping the input
@@ -96,25 +97,6 @@ const colorStyles = stylex.create({
   },
 });
 
-/**
- * Extensible variant map for FieldStatus.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/FieldStatus' {
- *   interface FieldStatusVariantMap {
- *     'inline': true;
- *   }
- * }
- * ```
- */
-export interface FieldStatusVariantMap {
-  attached: true;
-  detached: true;
-  tooltip: true;
-}
-
 /**
  * FieldStatus variant type. Extensible via module augmentation of FieldStatusVariantMap.
  */

package/src/FieldStatus/index.ts

@@ -9,9 +9,24 @@
  * @position Entry point for @astryxdesign/core/FieldStatus subpath export
  */
 
+/**
+ * Extensible variant map for FieldStatus.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/FieldStatus' {
+ *   interface FieldStatusVariantMap {
+ *     'inline': true;
+ *   }
+ * }
+ * ```
+ */
+export interface FieldStatusVariantMap {
+  attached: true;
+  detached: true;
+  tooltip: true;
+}
+
 export {FieldStatus} from './FieldStatus';
-export type {
-  FieldStatusProps,
-  FieldStatusVariant,
-  FieldStatusVariantMap,
-} from './FieldStatus';
+export type {FieldStatusProps, FieldStatusVariant} from './FieldStatus';

package/src/FileInput/FileInput.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: 'FileInput',
@@ -170,7 +170,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'FileInput',
   displayName: 'File Input',
@@ -293,7 +293,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'File input w/ input/dropzone modes, validation, label, description, status.',
   usage: {

package/src/FileInput/FileInput.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/FileInput/FileInput.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/FileInput/index.ts (exports if types change)
  * - /apps/storybook/stories/FileInput.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/FileInput/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/FileInput/ (showcase blocks)
  */
 
 import {

package/src/FormLayout/FormLayout.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: 'FormLayout',
@@ -52,7 +52,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'FormLayout',
   displayName: 'Form Layout',
@@ -100,7 +100,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Layout container for form fields w/ consistent spacing + direction.',

package/src/FormLayout/FormLayout.tsx

@@ -12,17 +12,14 @@
  * - /packages/core/src/FormLayout/FormLayout.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/FormLayout/index.ts (exports if types change)
  * - /apps/storybook/stories/FormLayout.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/FormLayout/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/FormLayout/ (showcase blocks)
  */
 
 import {useMemo, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
-import {
-  FormLayoutContext,
-  type FormLayoutDirection,
-} from './FormLayoutContext';
+import {FormLayoutContext, type FormLayoutDirection} from './FormLayoutContext';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 

package/src/Grid/Grid.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: 'Grid',
@@ -101,7 +101,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -117,7 +117,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'CSS Grid-based layout w/ responsive column support.',
   usage: {

package/src/Grid/Grid.tsx

@@ -12,7 +12,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/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';

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',
@@ -68,7 +68,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Icon',
   displayName: 'Icon',
@@ -124,7 +124,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.',

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/globalIconRegistry.test.tsx

@@ -1,6 +1,9 @@
 // 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,
@@ -12,6 +15,13 @@ import {
 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 +38,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 +87,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');

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,7 +26,7 @@ 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'
@@ -57,12 +60,28 @@ export type IconName =
  */
 export type IconRegistry = Record<IconName, ReactNode>;
 
+export type IconRegistrySource = DefinedTheme | string | null | undefined;
+
 // =============================================================================
 // Global Registry
 // =============================================================================
 
 let globalRegistry: Partial<IconRegistry> = {};
 
+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
  * environments. Call once at app initialization (e.g. root layout).
@@ -78,6 +97,11 @@ let globalRegistry: Partial<IconRegistry> = {};
  * ```
  */
 export function registerIcons(icons: Partial<IconRegistry>): 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 +113,22 @@ 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[]) {
     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;
 }
 
@@ -105,8 +138,12 @@ export function getIconRegistry(): Readonly<IconRegistry> {
  * Works in both server and client environments.
  * Falls back to built-in default icons when no override is registered.
  */
-export function getIcon(name: IconName): ReactNode {
-  return globalRegistry[name] ?? defaultIcons[name];
+export function getIcon(
+  name: IconName,
+  source?: IconRegistrySource,
+): ReactNode {
+  const themeIcons = getThemeIconOverrides(source);
+  return themeIcons?.[name] ?? globalRegistry[name] ?? defaultIcons[name];
 }
 
 /**

package/src/Icon/index.ts

@@ -12,12 +12,8 @@
  */
 
 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 {
@@ -26,4 +22,8 @@ export {
   getIcon,
   resetIcons,
 } from './globalIconRegistry';
-export type {IconName, IconRegistry} from './globalIconRegistry';
+export type {
+  IconName,
+  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';