fix(theme-neutral): map tokens to reviewed palette

[rubyycheung]

Summary

• Maps Neutral's existing color roles to the approved palette from feat(theme-neutral): adopt approved palette #5987.
• Uses named palette-stop references in the maintained theme source and CLI template instead of duplicating generated hex values.
• Preserves alpha variants through one small helper and keeps intentional non-palette local values explicit.
• Covers core neutrals, semantic statuses, categorical families, syntax colors, and color-bearing inset effects.
• Keeps ordinary dark surfaces near-black; exact black remains an explicit choice.

Review boundary

This PR defines which approved palette value each existing Neutral color role uses. It preserves token names and does not change component structure, typography, spacing, motion, or radius.

The selected mappings include the adjustments made during visual review. Further component-level design changes remain separate from this palette-to-token mapping.

#5628 contained the original mapping work but merged into an intermediate stack branch rather than main. This PR carries the mapping forward against the final generated palette.

Stack

#5985 -> #5992 -> #5987 -> this PR -> #5649

Verification

• Neutral palette and mapping tests: 7 passed
• Neutral production build passes
• Theme source and CLI template are byte-for-byte synchronized
• Formatting, linting, knowledge, changeset, and repository checks pass

Changeset

Included for @astryxdesign/theme-neutral and @astryxdesign/cli.

[vercel]

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

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Sep 5, 2026 2:55pm UTC

[cixzhang]

Light-mode CodeBlock comments and operators now render at 4.478:1 against the Neutral syntax background, down from 4.543:1 at the parent, so this 14px text falls below AA. Please keep both roles at or above 4.5:1 in the rendered light theme and cover that pairing with a focused regression test.

[Reviewed by Robohands]

[rubyycheung]

Addressed the requested contrast fix.

• Light-mode --color-syntax-comment and --color-syntax-operator now use Neutral T45 (#6a6a6a) instead of T50 (#777777), raising contrast against the syntax background from 4.478:1 to 5.409:1.
• Dark-mode values and the general secondary text color are unchanged.
• Added focused regression coverage for both emitted syntax tokens.
• Fixed the package-boundary issue found by the first deployment; the theme package build now passes.

The latest Vercel deployment and all current checks are green. Please re-review.

[cixzhang]

Thanks—the rendered contrast is fixed at 5.409:1 light and 7.048:1 dark. The earlier ask also required a regression guard, but the latest commit removed the only ≥4.5 assertion; the remaining test still passes when T45 is changed back to failing #777777. Please keep a package-local threshold assertion for both roles.

[Reviewed by Robohands]

[rubyycheung]

Rebased onto the latest main, including the merged dark-palette-edge update from #6069. The selected-stop runtime module was regenerated from the current palette, and the Neutral source/template remain synchronized.

The palette-edge merge changes dark-mode colors, so please review the refreshed visual preview/screenshots again. Focused Neutral tests pass (18/18), and the Neutral production build passes. The built runtime source now minifies to ~13.0 kB / ~3.4 kB gzip, without bundling the complete authoring palette.

[rubyycheung]

The selected-stop runtime fix is now pushed on top of current main (including #6069). Neutral source/template synchronization, the complete token-mapping test suite, and the Neutral production build pass. The remaining review item—the full-palette bundle regression—is addressed by importing only the generated stops used by neutralTheme; the complete palette remains authoring/test data. Please re-review the refreshed visual preview and rerun the package-size check on this head.

[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

No component packages changed.

Accessibility Audit

Status: No accessibility violations detected.

Visual Regression

2 of 348 shot(s) changed. View the report

A repository maintainer can accept these exact frames: /accept-visual 33973084709/1 <why every changed frame is correct>

A change here is a question, not a failure: check whether the after is the
picture you intended. If it is, say so in the PR — the release gate's baseline
is updated deliberately, and this check never rewrites it.

component	story	theme	mode	pixels
ComplexSelector	Fruit ripeness selector	neutral	light	3,992
ComplexSelector	Fruit ripeness selector	neutral	dark	3,825

ComplexSelector — Fruit ripeness selector — neutral light

Before	After	Diff

ComplexSelector — Fruit ripeness selector — neutral dark

Before	After	Diff

---

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

[cixzhang]

Builders using astryx theme add neutral still get an uncompilable theme: the scaffolded neutralTheme.ts imports ./neutralPaletteRefs.generated, but packages/cli/assets/templates/themes/manifest.json omits that file, so themeAdd() never copies it. I reproduced the generated directory with the import present and file absent; the current add test passes because it only checks files already listed in the stale manifest. Please regenerate the manifest and make the test resolve or compile every scaffolded relative import.

Also update the current Neutral spec: its intro, compatibility, and build sections still say token remapping is outside this release, while this PR and DEC-4 ship it.

The source-bundle fix and CodeBlock guard now pass (13.0 kB minified / 3.38 kB gzip; 5.409:1 light, 7.048:1 dark).

[Reviewed by Robohands]

[rubyycheung]

Fixed in 6730e30.

• Regenerated the CLI theme manifest so neutralPaletteRefs.generated.ts is copied by theme add neutral.
• Added a regression test that resolves every relative import in scaffolded theme files.
• Updated the Neutral spec intro, compatibility/migration, and build/artifact sections to reflect the token mappings shipped by DEC-4.

Focused add/template tests pass (21/21), and repository checks pass locally.

[cixzhang]

The CLI manifest/import test now closes the scaffold break, and the prior CodeBlock contrast and source-bundle regressions remain fixed. One release-blocking contradiction remains in the current Neutral spec: the decision-log preface still says approval covers only the palette and token mappings remain for a later release, while the intro and DEC-4 say this PR approves and ships them. Please make lines 183–186 agree with DEC-4 and this release.

[Reviewed by Robohands]

[rubyycheung]

Addressed the remaining spec contradiction in 2d596b0. The Decision Log preface now states that DEC-2 approves the palette and DEC-4 approves the reviewed token mappings shipped in this release, while local-token and rendered-evidence gates remain governed by their specific decisions. Knowledge checks and focused template/add tests pass.

[cixzhang]

Thanks—the exact head now preserves the reviewed Neutral mapping across package and CLI source builds, keeps CodeBlock contrast guarded, and aligns the DEC-4 release record.

[Reviewed by Robohands]