fix(theme): preserve deprecated target compatibility

[cixzhang]

Why

Theme consumers may still use deprecated component target keys. Removing those aliases would silently break working themes, so this change keeps compatibility while steering new theme authoring to canonical keys.

What

• Keeps all deprecated runtime aliases and discovery entries supported, with exact canonical replacement metadata.
• Labels deprecated targets in CLI and docsite discovery, warns during theme builds, and excludes deprecated keys from copyable new examples.
• Canonicalizes maintained themes and templates while preserving both deprecated and canonical behavior through focused tests.

Risk

Non-breaking. Existing deprecated target keys continue to work; canonical keys remain the preferred path for new themes.

Testing

• pnpm check:knowledge
• Focused Core compatibility suites for all deprecated aliases
• CLI discovery, build-warning, and formatting suites
• Docsite test suite
• Full GitHub CI

[vercel]

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

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Sep 11, 2026 2:36am UTC

[github-actions]

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

Modified Components

Banner _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	428	-
Complexity	N/A	Very High (44)	-

CodeBlock _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	1569	-
Complexity	N/A	Very High (83)	-

DateInput _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	3305	-
Complexity	N/A	Very High (359)	-

DateRangeInput _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	539	-
Complexity	N/A	Very High (66)	-

DateTimeInput _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	3393	-
Complexity	N/A	Very High (530)	-

Field _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	819	-
Complexity	N/A	Very High (56)	-

FormLayout _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	93	-
Complexity	N/A	Low (3)	-

HoverCard _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	667	-
Complexity	N/A	Very High (95)	-

Indicator _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	563	-
Complexity	N/A	High (26)	-

MultiSelector _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	1655	-
Complexity	N/A	Very High (231)	-

NavIcon _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	50	-
Complexity	N/A	Low (1)	-

Popover _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	757	-
Complexity	N/A	Very High (82)	-

ProgressBar _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	397	-
Complexity	N/A	High (29)	-

Selector _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	1992	-
Complexity	N/A	Very High (218)	-

StatusDot _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	134	-
Complexity	N/A	Medium (7)	-

Table _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	1960	-
Complexity	N/A	Very High (112)	-

TextArea _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	435	-
Complexity	N/A	Very High (65)	-

TextInput _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	341	-
Complexity	N/A	Very High (59)	-

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.8KB	1.2KB

Accessibility Audit

Status: 2 accessibility violation(s) found — 1 critical, 1 serious.

DateRangeInput - 1 issue(s)

• 🔴 critical: Ensure an element's role supports its ARIA attributes
  • Rule: aria-allowed-attr · Affects 1/20 stories · Learn more
  • WCAG: 4.1.2 (Level A)

ProgressBar - 1 issue(s)

• 🟠 serious: Ensure the contrast between foreground and background colors meets WCAG 2 AA minimum contrast ratio thresholds
  • Rule: color-contrast · Affects 2/18 stories · Learn more
  • WCAG: 1.4.3 (Level AA)

Visual Regression

Status: Skipped — Broad stable scope is deferred to the daily release gate. It covers 382 trusted baseline shots instead of recapturing them for this PR. View the report

---

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

[cixzhang]

Semantic verdict: approve

Theme builders now get one canonical target vocabulary without losing the generic compatibility mechanisms needed for future staged aliases.

• All 21 retired keys have exact replacements shared by discovery, the codemod, diagnostics, and documentation; collisions preserve both declarations with an actionable TODO.
• Maintained published themes and bundled templates use canonical keys only, and build validation covers root, light/dark, and ordered adaptation rules.
• legacyNames, ThemePropsOptions, deprecatedFor, and InputClearButton.iconClassName remain available. The docsite labels staged aliases but excludes them from copyable examples.

Independent exact-head semantic review found no blocking issue. Local full repository and docsite builds, typechecks, generated-data checks, and focused mapping/runtime tests pass. Exact-head CI remains the merge gate.

[Reviewed by Robohands]

[cixzhang]

Semantic verdict: approve

Theme builders now get one canonical target vocabulary without losing the generic compatibility mechanisms needed for future staged aliases.

• All 21 retired keys have exact replacements shared by discovery, the codemod, diagnostics, and documentation; collisions preserve both declarations with an actionable TODO.
• Maintained published themes and bundled templates use canonical keys only, and build validation covers root, light/dark, and ordered adaptation rules.
• legacyNames, ThemePropsOptions, deprecatedFor, and InputClearButton.iconClassName remain available. The docsite labels staged aliases but excludes them from copyable examples.

Independent exact-head semantic review found no blocking issue. Local full repository and docsite builds, typechecks, generated-data checks, and focused mapping/runtime tests pass. Exact-head CI remains the merge gate.

[Reviewed by Robohands]

[cixzhang]

Semantic verdict: approve

Theme builders now get one canonical target vocabulary without losing the generic compatibility mechanisms needed for future staged aliases.

• All 21 retired keys have exact replacements shared by discovery, the codemod, diagnostics, and documentation; collisions preserve both declarations with an actionable TODO.
• Maintained published themes and bundled templates use canonical keys only, and build validation covers root, light/dark, and ordered adaptation rules.
• legacyNames, ThemePropsOptions, deprecatedFor, and InputClearButton.iconClassName remain available. The docsite labels staged aliases but excludes them from copyable examples.

Independent exact-head semantic review found no blocking issue. Local full repository and docsite builds, typechecks, generated-data checks, and focused mapping/runtime tests pass. Exact-head CI remains the merge gate.

[Reviewed by Robohands]

[cixzhang]

Semantic verdict: request changes

themeTargets() exposes inconsistent object shapes: parent/child canonicalization creates an own deprecatedFor: undefined property on five current targets, while JSON serialization removes it. Programmatic and JSON consumers therefore receive different projections of the stable schema.

Please assign deprecatedFor only when the child supplies a string, then add a direct-API regression asserting current rows do not own the field while deprecated rows carry their exact replacement. The compatibility-preserving aliases, Popover guidance, canonical first-party examples, changeset, RTL/a11y applicability, and exact-head CI otherwise look good.

[Reviewed by Robohands]

[astracat-bot]

AI review status for this pull request.

Review status	Updated
🟡 Reviewed (for maintainers only)	Sep 11, 2026, 2:46 AM UTC

[astracat-bot]

Theme builders using released bare prop or state selectors such as .primary, .sm, and .checked remain broken at this head: themeProps() still omits those classes, and its test requires that omission. Those selectors shipped in 0.5.4, while the current compatibility contract keeps them supported until 0.7.0.

Please restore same-element emission of the released bare value/state classes, including numeric level-* values, and add regression coverage from the 0.5.4 output. The 21 target-name aliases, exact replacement discovery, and build warnings otherwise check out.

[astracat-bot]

Thanks, this now preserves released selector compatibility through 0.7.0 while keeping canonical data attributes, target aliases, and exact migration warnings intact. The prior blocker is fixed.

[cixzhang]

/approve-spec 8ffba7b