fix(theme-neutral): remap colors to the approved palette

[rubyycheung]

Summary

• Define and export the complete Neutral light/dark tonal palettes.
• Use the approved higher-chroma ramps selected in visual review.
• Map semantic, categorical, syntax, selection, and shared color tokens to exact numbered palette tones.
• Preserve released shared-border appearances while moving their values onto named palette stops.
• Keep the maintained source and CLI Neutral template synchronized.
• Document how theme authors and agents should choose semantic tokens or exact palette tones.

Why

This gives people and agents one exact, versioned source of color truth instead of independently inventing nearby hex values. Palette metadata remains opt-in, while the default runtime theme stays lean.

Component-specific behavior and contrast treatments are intentionally excluded and reviewed separately in #5690.

WCAG scope

This PR establishes contrast-aware color mappings. Component-specific pairings and exceptions are validated in #5690.

Stack

#5627 → #5668 → this PR → #5690 → #5649 → #5667

Verification

• 9 focused palette, Badge contrast, and syntax contrast tests pass.
• Neutral theme build passes with no unknown component-target warning.
• Repository checks and source/CLI parity pass.

@rubyycheung

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview	Aug 30, 2026 8:59am

[rubyycheung]

Coordination note: #5671 owns the semantic status glyph mapping for ChatToolCalls and table-row statuses. This PR remains the source of the Neutral semantic status colors those glyphs consume. Commit 23150a9 adds a regression guard for the independent success, warning, and error palette mappings.

[xinzi-bot]

Automated review found one visual regression: the Neutral dark ProgressBar track drops from 2.20:1 to 1.54:1 against body and 1.94:1 to 1.35:1 against surface, while the parent-visibility test remains todo. Preserving current track visibility would avoid the regression.

[Automated review]

[rubyycheung]

Thanks for flagging the lower track-to-parent ratios. Those ratios are useful diagnostic data, but they do not determine conformance by themselves.

WCAG 1.4.11 applies to the graphical parts required to understand the component, measured against their adjacent colors. For ProgressBar, that depends on its presentation:

• Without a visible value, the graphic carries the progress information. We measure fill against track and the endpoint indicator against the surrounding surface.
• With an equivalent visible value such as “65%” or “3 of 5,” the surrounding text also communicates the progress. That text must meet 4.5:1 against its background, while the quieter track can be supplemental. A label such as “Uploading” alone is not an equivalent value.

The endpoint identifies the total extent of the standalone bar, so the entire track does not additionally need 3:1 against the page or card surface. Requiring that relationship would make every track visually prominent without adding information.

The remaining todo should still be replaced with tests for the relationships that matter: fill/track, endpoint/surface, and visible value text/background. That coverage depends on the explicit standalone/supplemental ProgressBar contract in #5645. Therefore, the reduced track/parent ratio is intentional and is not by itself a WCAG regression.

[xinzi-bot]

Re-reviewed exact head: the prior ProgressBar track regression is resolved, palette metadata stays opt-in, and changed-file TODO coverage is clean. @imdreamrunner, this looks ready for your approval.

[Automated review]