Document contextual text colours and cover them end to end (#911) * Document contextual text colours and cover them end to end Implements Part 5 of #899. Docs: the Colour guide gains a "Text on a background" section with the resolution table, the compiler guarantee, nesting and colour-mode rules, and custom-surface guidance that separates Box backgrounds from CSS, image, gradient, and translucent backgrounds. Text gets a live colour example. Heading, Kbd, LoadingSpinner, Icon, Box, and Styling point to the contract instead of restating it. Examples: the role-colour and responsive-layout examples use Box backgrounds and Text colours instead of hand-picked `onSolid` tokens. The docs preview and colour-mode example drop an inert `color` attribute Box passed to the DOM, and so does the reference app's settings nav. Tests: axe checks every Text colour on every Box background in Paper and Tactile, light and dark, and the solid-fill tests for Button, Link, Code, Kbd, and fields. Forced colours give Text on a solid fill the system colours. A container-query background hands its context to descendant Text in every appearance. The packed consumer renders a solid Box with a danger Text on the server and checks the on-solid colour after hydration with the published theme stylesheet. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FeWXANoWLbCivQugFPWY3v * Record papercut: an agent discarded its own uncommitted task changes Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FeWXANoWLbCivQugFPWY3v * Require measured contrast passes and test low Link cues Contrast: `expectEveryTextToPassContrast` runs axe's colour-contrast rule alone and requires no violations, no incomplete results, and a pass for every visible text element, so text axe cannot measure fails the test instead of passing silently. The Text, Code, Kbd, Link, and field contrast checks use it. Button text is measured in every interaction state: ghost and subtle fills in Paper and Tactile, and solid fills in the flat appearances, because axe cannot measure text over the control finish's gradient. Low Links: a low-prominence Link inline in body text is at least 100 heavier than the text on a standard surface, a subtle fill, and a solid fill, where its colour matches the text. It has no underline at rest and underlines on hover, press, and focus. In forced colours it keeps the weight and takes `LinkText`. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FeWXANoWLbCivQugFPWY3v * Recognise the contrast helper as an assertion in lint `vitest/expect-expect` needs each assertion helper named, as `expectNoAxeViolations` is. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FeWXANoWLbCivQugFPWY3v * Clarify the colour and Link presentation examples * Document stable private property names for browser tests * Keep solid Button text readable over Tactile's control finish Tactile's light finish laid up to 20% white over solid fills, so the neutral high Button's label measured 4.35:1 at rest and 4.24:1 on hover. The light resting and raised highlights drop to 8% and 12% in the published input and its fixture, and the label now measures at least 4.62:1. A new test helper screenshots an element with its text hidden and measures each text colour against every pixel behind it. A Button test uses it for every fill and state in every appearance, so solid Buttons are measured with their finish instead of being left out. The authoring guide notes that contrast validation does not see the finish. The axe contrast helper is renamed expectAxeContrastPasses, and the browser test drops an ESLint suppression for a rule that is already off for browser tests. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01762M2sN43hWUmyAsnF8U7m * Record papercut: a browser test suppressed lint with an ESLint directive Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01762M2sN43hWUmyAsnF8U7m * Narrow the rendered contrast helper to HTML text elements Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01762M2sN43hWUmyAsnF8U7m * Require the theme fixtures to match the published solid controls The browser suite renders React-owned copies of Paper and Tactile, so its measurement of text over the control finish covered the published themes only while the copies happened to agree. The packed-consumer harness now compiles each fixture and requires the published stylesheet to declare the same solid fills, on-solid text colours, and control finish. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01762M2sN43hWUmyAsnF8U7m * Name the convention checks reviews keep catching before commit The review-pr easy-to-miss list now covers cx, semantic test locators, example context, and generated JSDoc, and work-on-issue applies that whole list before committing. work-on-issue names the Git commands that must not undo edits in a task checkout. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01762M2sN43hWUmyAsnF8U7m * Triage the papercut log The log reached 12 entries. Each is now fixed, transferred, or rejected: Fixed by guidance in the previous commit, which adds each rule to review-pr's easy-to-miss list and has work-on-issue apply that list before committing: - Generated scaffold JSDoc names the recipe class. - New layout tests locate named controls with DOM selectors. - Prose example adds unnecessary application context. - Class names joined with a template string instead of `cx`. - An agent ran destructive Git commands on its own uncommitted task changes: work-on-issue now names the commands and says to undo an edit by path. Fixed by #894: Theme builds refresh tracked dependency metadata. The manifests record @capsizecss/metrics 4.4.0, the installed version, and builds on the #899 stack leave them unchanged. Transferred to #912: A browser test suppressed lint with an ESLint directive. Oxlint can report directives that suppress nothing, but enabling that flags five unrelated directives on main. Rejected: - The README rendering summary omits React Aria's supported render API. CONVENTIONS.md, Element choice, keeps React Aria's `render` only as Link's MDX integration exception, so the README's list of Luke UI composition APIs matches the documented intent. - New feature documentation follows Accessibility. `check:docs` enforces the page order and rejected the change before commit. - Production settings API adds a control used only by tests, and Search test comments narrate investigation history. review-pr already lists both checks, work-on-issue applies them before commit, and review caught both. - Docs watcher tests cannot find type-source modules. The tests pass in CI and locally on df4fb8c (5 of 5), so the earlier failures depended on the environment that ran them. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01762M2sN43hWUmyAsnF8U7m * State the label weight a low-prominence Link relies on The theme authoring guide asks for a label weight at least 100 heavier than body text, which a low-prominence Link needs as its resting cue. Two comments are rewrapped or no longer cite an issue number. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01762M2sN43hWUmyAsnF8U7m * Keep two papercuts whose guidance already sat at the point of use The triage rejected "Production settings API adds a control used only by tests" and "Search test comments narrate investigation history" because review-pr and work-on-issue already name both checks. Those pointers existed before both failures, so they are evidence that a pointer did not prevent them, not a reason to close the entries. Both return to the log until a stronger remedy exists. The comment entry is renamed to cover any history narration and records a second occurrence: a Link test comment that cited #899 to justify its rule. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01762M2sN43hWUmyAsnF8U7m * Sort StoryWrapper layout keys and move a Heading test comment to its assertion * Require label weight at least 100 heavier than body A low-prominence text Link relies on the label weight as its resting cue. The check runs on the resolved foundation, so it also covers weights inherited from an extended theme. * Narrow contrast and hue claims to what the code checks * Derive contrast test counts instead of hard-coding them --------- Co-authored-by: Claude