[MannXo]

Reader impact

useIcon has no HookDoc, so it has no docsite page and astryx hook useIcon finds nothing. After this change it has a page with its parameter, its return value and the fallback order, and an example. A custom status row draws the success, warning and error icons with useIcon. The same row renders under the current theme and under a Theme that overrides those three icons, and its icons follow the theme with no change to the row. astryx template useIconHookUsage <path> copies it.

Source of truth

• packages/core/src/Icon/useIcon.ts, and getIcon / selectIconEntry in globalIconRegistry.tsx for the fallback order (the nearest Theme's icons, or the registered theme the document root names when there is no Theme above, then registerIcons(), then the built-in default) and the {size: 'md'} read of a function entry.
• useThemeName in packages/core/src/theme/useTheme.ts for where the theme name comes from.
• architecture:knowledge-contracts INV28.

Correction

• Adds packages/core/src/Icon/useIcon.doc.mjs (docs + docsDense, group: 'Icon', importPath: '@astryxdesign/core/Icon'), in the shape useLightbox.doc.mjs uses.
• Adds blocks/components/Icon/useIconHookUsage (exampleFor: 'useIcon'). StatusRow calls useIcon('success'), useIcon('warning') and useIcon('error'). The block renders it once as is and once inside <Theme theme={statusIconTheme}>, where defineTheme({icons}) sets those three names to the heroicons solid CheckBadgeIcon, ExclamationCircleIcon and NoSymbolIcon. These differ in shape from both the built-in icons and the docsite theme's, so the change shows under either. The block's icons field maps them to success, warning and error.
• Updates the recorded module resolution for useIcon in packages/cli/api/component/__fixtures__/resolutions/modules.txt (it now opens Icon/useIcon.doc.mjs instead of falling back to Icon/Icon.doc.mjs), as test: main is green again: Tokenizer's sheet-row test passes presentation, and the recorded module resolutions follow core #9851 did for useLightbox.
• Updates the four packages/cli/test/__golden__/no-icon-set/search-icon* goldens. A search for "icon" now also finds the new hook (225 matches become 227), which moves it into the first 20 results and moves the last template out.

Evidence

• Real Chromium (Playwright against the docsite dev server, /components/useIcon, 1280x900). The first row draws the docsite theme's stroked status icons (fill="none" stroke="currentColor", 16px). The second row draws the solid heroicons from the overriding Theme, at the same 16px. No page errors.
• Test (packages/cli/api/template/use-icon-hook-usage.test.tsx, 2 cases), rendered under a root Theme as on the docsite. It asserts the built-in icons in the first row and the overriding Theme's icons (heroicons' data-slot="icon") in the second. With the three useIcon calls replaced by getIcon, which reads no Theme, the second case fails.
• node packages/cli/clients/cli/bin/astryx.mjs hook useIcon prints the new doc.

Scope

• This PR changes documentation only, or names every necessary generated artifact. The generated artifacts are the block's route and the hook's route in internal/shadcn-registry/routes.lock.json, the block's sandbox route in apps/sandbox/scripts/next-export-routes.json, and the recorded resolution and search goldens above.
• Runtime, API, visual, and policy changes were removed or split.
• Public text and artifacts contain no internal Meta context.

Testing

• vitest run --project node packages/cli/foundation/discovery packages/cli/api/template packages/cli/assets/templates internal/shadcn-registry apps/sandbox/src/route-manifest.test.ts packages/cli/api/build/tree.test.mjs packages/cli/test/experimental-isolation.test.mjs packages/cli/api/component/resolution-compat.test.mjs packages/cli/api/docs packages/cli/api/hook: 1473 passed, 0 failed.
• vitest run --project ui packages/core/src/docPropLiterals.test.ts packages/core/src/docPropReferences.test.ts: 22 passed.
• apps/docsite: pnpm generate, then vitest run src/__tests__/data-extraction.test.ts src/__tests__/example-coverage.test.ts: 136 passed, 0 failed. The route lock check is clean after UPDATE_SHADCN_ROUTE_LOCK=1 added the two routes.
• pnpm -F @astryxdesign/cli typecheck: clean.
• node scripts/release/changeset-coverage.mjs pr --base upstream/main --head HEAD --released v0.7.7: passes. Changeset names @astryxdesign/core and @astryxdesign/cli, patch, [docs].
• The full vitest run --project node here: the two files this PR affects (experimental-isolation, resolution-compat) pass after the updates above. Eight other files fail the same 28 tests on main with nothing applied (setup, postinstall, global-local and release handoff tests that depend on this machine's home folder, case-insensitive file system, cp flavour and git remotes).
• pnpm lint:strict: clean (0 errors).
• .github/scripts/check-public-text.mjs over this commit, title and description: no findings.

Notes for reviewers

Outside any Theme, useIcon reads the theme the document root names, and the first Theme in the tree becomes that root. So in an app with no root Theme of its own, the overriding Theme in this example would become the root, and both rows would show its icons. The example assumes the app has a root Theme, as the docsite does, and the test wraps it in one for the same reason.

Fixes #9563

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Nov 5, 2026 10:27am UTC

[astracat-bot]

AI review status for this pull request.

Review status	Updated
🟢 Reviewed (for maintainers only)	Nov 5, 2026, 10:52 AM UTC

[github-actions]

PR Analysis Report

🔎 Preview · aa9b9e9

Storybook · Sandbox · built from this PR's head

Modified components

Component	Size	LoC	Visual · A11y · RTL
Icon · Storybook	7.8 kB (0) · 681 B CSS (0)	713 (0)	✓ · ✓ · —

Package size:

• @astryxdesign/cli 3.36 MB packed (+710 B); no new dependencies
• @astryxdesign/core 6.57 MB packed (+995 B); no new dependencies

API changes: none in this pull request

Committed API report behind this build: cli 9 rows, core 4 rows; run pnpm api:report.

Touched components checked; add ci:run-visual, ci:run-a11y or ci:run-rtl to run the full suites.

---

_{Generated by PR Enrichment workflow | View full report}

[astracat-bot]

Changes requested: one line in the new example block needs a fix. The hook doc and the example otherwise meet the hook-example rule, and the documented fallback order matches the code.

• The nested <Theme theme={statusIconTheme}> in useIconHookUsage.tsx has no mode, so its row follows the OS color scheme instead of the page's: in dark mode on a light-mode OS the second row is black on dark gray (1.39:1), and in light mode on a dark-mode OS it is white on white; pass the surrounding mode, for example const {mode} = useTheme(); and <Theme theme={statusIconTheme} mode={mode}>.

CI has not run on this head yet; it starts once a maintainer adds the ci:run label.

[Automated review]

[astracat-bot]

This nested Theme defaults to mode="system", so this row follows the OS color scheme rather than the page's. On the docsite in dark mode with a light-mode OS, the row renders black on dark gray (1.39:1); in light mode with a dark-mode OS, white on white. Passing the surrounding mode fixes it:

const {mode} = useTheme(); // '@astryxdesign/core/theme'
<Theme theme={statusIconTheme} mode={mode}>

[astracat-bot]

Approved pending CI: CI has not run on this head yet. A maintainer adds the ci:run label so the required checks run.

The earlier issue is fixed: the nested Theme in the example now takes the page's color mode, and the new test covers it. The hook doc's fallback order matches the resolver, and the example meets the hook-example rule.

• Optional: the brace-only edit in internal/interaction-harness/src/busy.ts is unrelated to this docs change; drop it, or mention it in the description.

[Automated review]