feat(theme): add theme-local token support

[rubyycheung]

Summary

• implement the accepted AST-006 localTokens authoring contract from docs(knowledge): specify theme-local tokens #5801
• preserve exact theme-local names through runtime CSS, static builds, inheritance, and generated built-theme metadata
• validate enrolled declarations, references, namespaces, lineage, and cycles without changing legacy tokens behavior
• document the API for theme authors and keep the generated theme template synchronized

Scope

This is infrastructure only. It does not adopt local tokens in Neutral or change any shipped theme colors or component styling. Neutral adoption remains separate from the cross-theme API review.

An inheritance-only descendant keeps its existing theme name, including legacy names that are not lower-kebab-case. The stricter name rule applies only when a theme explicitly supplies localTokens.

Validation

• pnpm -F @astryxdesign/core build
• pnpm -F @astryxdesign/core typecheck
• focused Core/CLI/template tests: 129 passed
• 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 check:sync
• pnpm check:changesets
• pnpm check:package-boundaries
• repository pre-commit validation suite

Extracted from #5752 so the reusable API can be reviewed independently from Neutral's visual design decisions.

[vercel]

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

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Sep 2, 2026 7:54am 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.

No new or modified components detected.

Bundle Size Summary

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

Accessibility Audit

Status: No accessibility violations detected.

Visual Regression

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

---

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

[cixzhang]

Theme authors who opt into localTokens can currently receive invalid or contradictory output even though the build succeeds.

• CSS_VAR_PATTERN only recognizes lowercase var(. Valid CSS such as VAR(--astryx-theme-foo-color-fill) bypasses undeclared-reference and cycle validation, so an enrolled static build can emit a broken reference. Please parse the function case-insensitively and add runtime/static undeclared + cycle regressions for uppercase/mixed-case spelling.
• A key duplicated in legacy tokens and localTokens is accepted and emitted twice. CSS uses the later local declaration, while resolveThemeToken() reads the portable tokens value. Please reject cross-map duplicate names before output and test CSS/helper parity.
• This is a settled implementation of AST-006, so the implementation PR also needs to update the canonical shipped records required by AST-006’s current-state impact and completion criteria: AST-006’s phase plus theme-authoring-contract, theme-compilation, and theme-tokens. The Neutral theme record is not involved because this PR adds infrastructure without an adopted Neutral local-token mapping.

[rubyycheung]

Addressed the requested changes in 747d9c0b5:

• made CSS var() detection case-insensitive while preserving the exact custom-property name, with runtime and static regressions for uppercase and mixed-case undeclared references and cycles
• reject names duplicated across tokens and localTokens after inheritance/override resolution, before output; added legacy CSS/resolveThemeToken() parity coverage and static atomic-output coverage
• moved AST-006 to shipped and updated theme-authoring-contract, theme-compilation, and theme-tokens to describe the shipped contract and cite the deciding spec decisions

Local validation passed: 218 focused tests, Core build/typecheck, CLI strict/authoring/template-doc typechecks, Neutral build, ESLint, and pnpm check:repo.

[cixzhang]

Thanks, this addresses the validation and contract-sync issues from my prior review. No new concerns.

[Reviewed by Robohands]