at main
3 folders
2 files
Fix the theming and styling docs that no longer match the code (#276)
* Fix the theming and styling docs that no longer match the code
Every entry point into the theme and styling layers misled a reader,
because the docs were written before the colour engine was rewritten.
AGENTS.md tells agents to read these docs before changing code, so a wrong
doc generates wrong code.
foundation.ts and define-theme.ts both said the background input is not
consumed and that the canvas still comes from neutral. buildTheme now
takes background directly as the canvas anchor for every family's ramp and
for the elevation surfaces, so anyone tracing the canvas was sent to the
wrong module. The same overclaim had also leaked into the public JSDoc in
theme/index.tsx, which promised a single-value-accent throw and listed an
incomplete set of gates for ThemeContrastError. Internal stage numbers are
gone repo-wide, per the documentation guide.
The authoring page told theme authors that non-text pairs must reach 3:1.
That is not what the compiler does. It now separates what is guaranteed
from what is only measured: text and on-solid pairs are hard-gated at
4.5:1, border.focus and border.control at 3:1, the five intent border
pairs are measured but cannot fail the build, and decorative borders are
never checked at all. An advisory border must never be the only cue for a
state, so the page says so. color.background and ThemeGenerationError are
documented for the first time.
The page no longer promises a "no accessible lightness" error for a
single-value accent. A sweep of the on-solid gate at the accent adaptation
targets found no failing hue or chroma, so the search loop and its throw
are unreachable under the current constants and the error cannot fire.
Authors are pointed at the reachable path instead. Whether to keep that
search as defence-in-depth or delete it is an accent-policy decision,
left alone here.
The styling guide told authors to call recipeInLayer, which no longer
exists, and never documented the recipe engine they actually have to use.
It now covers single-part and slotted recipes, how variant types are
derived rather than hand-maintained, and the shared input-state selectors.
The testing guide's visual test example used a Button tone that does not
exist, so the canonical template did not compile.
Docs and comments only: no non-comment source line changed.
* Make theming and styling copy easier to read