feat(theme): add local tokens and refine Neutral color roles

[rubyycheung]

Summary

• implements the accepted AST-006 localTokens contract from docs(knowledge): specify theme-local tokens #5801 without changing existing tokens behavior
• preserves exact theme-local names through runtime CSS, static builds, inheritance, and built-theme metadata
• migrates Neutral's reusable status-fill and tint roles to the --astryx-theme-neutral-* namespace
• completes the Neutral warning mappings for Stepper and ProgressBar
• keeps tonal-palette metadata work in feat(theme): add approved tonal palette authoring contract #5668 and row-status infrastructure in Add Table row status theming target #5754

Theme-local token contract

• localTokens is optional; themes that omit it retain their previous object shape and behavior
• values accept the complete existing TokenValue contract: a CSS string or [light, dark] tuple
• declarations use one complete exact custom-property name
• enrolled inheritance preserves exact declarations and ownership metadata in source and built themes
• recursive validation rejects malformed or foreign declarations, undeclared references, cycles, and invalid lineage before CSS is emitted
• portable TokenName, token helpers, and Core component source remain unchanged

Neutral mappings

• Badge: info, success, warning, error fills
• StatusDot and AvatarStatusDot
• Stepper: accent, success, warning, error
• Table row status dots/icons
• Banner tint and interaction overlays
• ProgressBar: accent, success, warning, error

Contrast receipts

Filled status label pairs:

• accent: 4.57:1 light / 6.43:1 dark
• success: 5.02:1 light / 6.38:1 dark
• warning: 11.58:1 light / 11.58:1 dark
• error: 5.29:1 light / 6.34:1 dark

The repository Badge contrast guard resolves localTokens and passes for all Neutral semantic variants. Trusted exact-head screenshots are produced by the visual CI workflow for final Neutral ratification.

Validation

• pnpm -F @astryxdesign/core typecheck
• focused core theme tests: 155 passed
• focused CLI runtime/static/local-token tests: 6 passed
• Neutral, Badge contrast, and template-contract tests: 16 passed
• pnpm -F @astryxdesign/core build
• pnpm -F @astryxdesign/theme-neutral build
• pnpm -F @astryxdesign/cli typecheck:strict
• pnpm -F @astryxdesign/cli typecheck:authoring
• pnpm -F @astryxdesign/cli typecheck:template-docs
• pnpm bundle:cli-themes
• pnpm check:sync
• pnpm check:changesets
• pnpm check:package-boundaries
• Storybook production build

Notes

• The Neutral record remains draft pending exact-head visual review and explicit ratification.
• No selectable-card, token, chat-message, chat-tool, or Button behavior changes are included.

[vercel]

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

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Sep 1, 2026 7:56pm UTC

[xinzi-bot]

The new role-token direction looks good, but Stepper and ProgressBar warning still skip the warning fill mapping, and Stepper’s fallback is only about 1.9:1. This visual PR also needs exact-head light/dark screenshots. Please add both warning overrides and the required visual evidence.

[Automated review]

[cixzhang]

Neutral theme updates look good but here's some button updates mixed in that seem unintentional. Could we clean those up? Then the rest is good.

[rubyycheung]

Fixed — I removed the Button-specific diff from this PR so #5752 is back to Neutral theme color changes only. Thanks for catching that.

[rubyycheung]

Updated exact head ca71bc70:

• implemented AST-006 localTokens end to end (runtime, generated themes, CLI, docs, and tests)
• migrated Neutral’s local role tokens to the exact theme namespace
• added the missing Stepper and ProgressBar warning fill mappings
• removed the unrelated Button changes
• documented the light/dark contrast ratios in the PR body

Focused tests, typechecks, builds, sync checks, package-boundary checks, and the production Storybook build pass. The Vercel preview is also green.

This stacked PR does not target main, so the repository’s main-only visual CI does not run here. The Neutral record remains draft pending exact-head light/dark visual review and explicit ratification.

Could you please re-review this head?

[rubyycheung]

Closing this mixed PR in favor of focused replacements:

• feat(theme): add theme-local token support #5844 — standalone AST-006 localTokens implementation against main
• fix(theme-neutral): refine SegmentedControl inset #5846 — Neutral SegmentedControl inset/height/shadow styling

The remaining Neutral color-role adoption will be recreated as a focused PR after its prerequisites (#5668, #5754, and #5844) are available together. That PR will contain only the approved Neutral definitions and mappings, plus exact-head light/dark evidence and the updated colocated Neutral spec.

No work is being discarded. The exact current head is preserved at archive/pr-5752-mixed-ca71bc70 (ca71bc70).

This replacement also carries forward the completed warning mappings and the contrast work, while avoiding a single PR that mixes cross-theme infrastructure, Neutral design adoption, and SegmentedControl geometry.

[rubyycheung]

Final replacement map after removing the remaining inherited stack dependencies:

• feat(theme): add theme-local token support #5844 — AST-006 localTokens implementation, based on main
• Add Table row status theming target #5848 — Table row-status theming target, based on main
• fix(theme-neutral): refine SegmentedControl inset #5849 — Neutral SegmentedControl styling, stacked only on Add Table row status theming target #5848 and kept draft for visual review
• Rename built-in syntax theme identifiers #5847 — syntax-theme identifier cleanup, based on main

The focused Neutral status/color adoption will be recreated after #5668, #5844, and #5848 land. The preserved mixed head remains archive/pr-5752-mixed-ca71bc70.

[rubyycheung]

Updated after rebasing against the newly merged row-status contract #5830:

• feat(theme): add theme-local token support #5844 — AST-006 localTokens implementation, based on main
• Rename built-in syntax theme identifiers #5847 — syntax-theme identifier cleanup, based on main
• fix(theme-neutral): refine SegmentedControl inset #5851 — Neutral SegmentedControl styling, based on main and kept draft for visual review

The Table row-status theming target was not carried forward because #5830 explicitly requires a separate AST-002 proposal before that target or its selector axes can ship.

The future focused Neutral color-role adoption should therefore wait for #5668 and #5844, include the approved definitions/mappings and exact-head evidence, and omit row-status mappings unless that separate proposal is approved.

[rubyycheung]

Correction to the split: the preserved Neutral mapping work now has its own focused replacement in #5854, stacked on #5844. It excludes SegmentedControl styling, syntax renames, and the unapproved table-row-status target.