docs(spec): define authoring-time palette generation

[rubyycheung]

Summary

• Defines the supported authoring-time palette generation contract.
• Pins the current Sandbox OKLCH result as the astryx-oklch-v1 recipe and specifies its production behavior independently from mutable Sandbox code.
• Accepts a pure generateTonalPalette() API and the theme palette generate CLI adapter.
• Uses TypeScript as the primary committed output, with JSON available for interoperable tooling.
• Defaults to 21 stops while accepting any explicit non-empty, ordered numeric stop layout.
• Keeps generated output a candidate until an author reviews and saves it as a private, theme-owned palette.
• Keeps generation, validation, semantic mapping, and contextual contrast evaluation separate.

Follow-up boundaries

• PR 4 extracts the production engine, adds canonical fixtures, and implements the API and generation command.
• PR 5 can add Joeys palette-reading and diagnostic features such as list, show, stop, and check.
• Nearest matching and contextual contrast analysis can follow independently.

Related work

• Foundational accepted-palette contract: docs(theme): define approved palette authoring contract #5985
• Supersedes the direction discussed in docs(spec): define authoring-time palette generation #5800 while preserving its candidate-to-review boundary.

Verification

• pnpm check:knowledge -- --base origin/main
• 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 2:48am UTC

[cixzhang]

Palette authors could otherwise receive a production recipe whose behavior is defined by mutable Sandbox code, while standalone consumers still cannot require accessible foreground/background relationships.

Before this contract is ready:

• Replace the Sandbox source reference with explicit normative recipe requirements in this specification. Enumerate the profiles, anchor behavior, light/dark treatment, gamut mapping, precision, rounding, serialization, and failure behavior that production must preserve. Add version-pinned conformance fixtures that lock canonical requests, exact outputs or digests, and pass/fail thresholds for hue drift, adjacent-stop distinction, family distinction, and color-vision simulations. The Sandbox can demonstrate the behavior, but it must not own it.
• Add pairwise contrast constraints for standalone palette use: exact foreground/background stop references, mode, minimum ratio, and opacity/compositing assumptions. A hard constraint that cannot be satisfied should fail the whole request without a candidate; the receipt should report the exact pair and measured result. Keep contextual component states and non-color cues outside the palette-level guarantee.
• Define valid custom stop layouts separately from accepted-palette validity: minimum cardinality, finite values, bounds, uniqueness, ordering, endpoint requirements, and decimal representation. “Any non-empty numeric list” currently admits inputs the referenced generator rejects.

The separate-export boundary is otherwise aligned: generated palettes remain outside defineTheme, and authors explicitly select and save theme values.

[Reviewed by Robohands]

[rubyycheung]

I addressed the actionable parts of this review in d4c6bd0:

• The production recipe is now defined normatively in AST-008 rather than owned by mutable Sandbox code. It specifies profiles, tone/chroma behavior, dark-mode treatment, gamut mapping, anchors, rounding, serialization, failures, and three canonical SHA-256 fixtures.
• Custom stops now explicitly require one or more finite, unique, strictly increasing values from 0 through 100. Decimal stops are valid and endpoints are optional.

I am intentionally not adding palette-level foreground/background contrast guarantees. The palette is a set of authoring candidates and does not know the component context, text size, state, opacity, or composited background. Contextual contrast measurement is separate follow-up work; this generator does not claim accessibility for isolated colors.

[rubyycheung]

The implementation described here is now open as #5992. It includes the pure authoring API, TypeScript/JSON CLI output, overwrite protection, receipts, canonical digest fixtures, and Sandbox parity coverage.

[rubyycheung]

Thanks for the detailed review, Cindy. I updated the contract to address the actionable items:

• The production recipe is now defined independently of the Sandbox, with version-pinned fixtures and deterministic behavior.
• Custom stop validation is explicit, including bounds, ordering, uniqueness, decimal handling, and endpoint behavior.
• The default remains the full 21-stop 0–100 range, while authors can intentionally request custom layouts.

I kept pairwise contrast out of this foundational generator contract because a palette alone does not know which colors will be used together, at what opacity, or in which component state. We are not making an accessibility claim here; contextual contrast analysis will be a separate follow-up once that usage information is available.

I also aligned the anchor terminology on exact, bounded, and flexible. Could you take another look when you have time?

[cixzhang]

/approve-spec

[cixzhang]

The recipe is now specified independently from the Sandbox, custom stop semantics are explicit, and the separate authoring-time palette boundary is clear. Approved at this exact head.