docs(theme): define approved palette authoring contract

[rubyycheung]

Summary

• Defines AST-018 as the authoring contract for optional, private, theme-owned palettes.
• Keeps palette data outside defineTheme(), Core runtime APIs, generated CSS, and generic theme builds.
• Allows a theme to use literal CSS values or explicitly reference exact values from its committed palette file.
• Requires missing references to fail and palette changes to be reviewed as theme changes.
• Allows any non-empty author-defined numeric stop layout.
• Allows accepted palettes to include or omit black and white endpoints; exact black and white remain available as ordinary theme values.
• Separates structural validation, Neutral adoption, palette generation, and future diagnostics into follow-up work.

Why

This replaces the mixed scope in #5668 with a specification-only foundation. It establishes ownership and lifecycle boundaries without adding palette behavior to defineTheme() or runtime theming.

Verification

• Knowledge templates and records are aligned.
• Full pre-commit repository checks
• git diff --check

No Changeset: specification only.

[vercel]

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

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Sep 4, 2026 3:40pm UTC

[rubyycheung]

Split follow-ups are now open:

• feat(theme-neutral): adopt approved palette #5987 adopts the approved palette and explicit color remap in Neutral. It is stacked on this contract.
• docs(spec): define authoring-time palette generation #5986 defines the separate candidate-generation contract.

The next implementation order is production generator first, then the palette-reading and diagnostic CLI features proposed by Joey.

[cixzhang]

Theme authors get a reviewable palette reference without coupling runtime themes to palette data. Neutral adoption and generation stay independently reviewable.

[Reviewed by Robohands]

[rubyycheung]

Follow-up implementation is now open as #5992. It keeps defineTheme unchanged and generates standalone, reviewable palette files.

[cixzhang]

Theme-package validators could accept different palette shapes because “ordered numeric stop labels” does not define what makes a label valid.

Please align accepted palette structure with AST-008’s generated output boundary: stop labels are finite JSON numbers from 0 through 100, unique and strictly increasing; integer and decimal stops are valid; equivalent spellings such as 5 and 5.0 are the same stop; endpoints are optional; and a one-stop ramp is valid. Keep this independent from the generator’s default 21-stop layout.

Direct references from a committed palette remain allowed under FR5: changing a referenced value is an intentional theme change that requires rendered review.

[Reviewed by Robohands]

[rubyycheung]

Addressed in 0930d3b: AST-018 now defines palette stop labels as finite JSON numbers in 0..100, unique after numeric normalization, strictly increasing, with optional endpoints and valid one-stop ramps. The 21-stop layout remains a generator/theme choice, and FR5 direct references remain allowed.

[cixzhang]

Thanks, this resolves our stop-label request: palette validation and generation now share one numeric shape without making the 21-stop generator default universal.

[Reviewed by Robohands]