name

add-contrast-check

description

Warn when a stylesheet's text would be hard to read

spec

style-topics

status

in-progress

date

2026-09-24

tags

ai, spec, openspec, change

Proposal

Why

An AI asked for "magenta text on dark green" will do exactly that, readable or not. The save reply should say when text and background are too close, so the AI can adjust before the user squints.

What Changes

• Saving a Style topic checks the contrast of --ink and --soft against --paper and --card, in light and dark mode.
• Below 4.5:1 (the usual guideline for body text) is a warning, not an error: the stylesheet can still be picked.
• The Styles page shows the warnings under the stylesheet.

Impact

• Affected specs: style-topics.
• Affected code: src/styles.ts, src/stylespage.ts.

Tasks

1. Build

• 1.1 Compute contrast ratios from hex colours
• 1.2 Add warnings to the save reply's style field
• 1.3 Show warnings on the Styles page
• 1.4 Tell the AI about it in Skill:diesel2

Design

• Only hex colours are checked; a named colour or rgb(…) is skipped rather than guessed.
• Warnings never block: taste is the user's call.

Spec delta

ADDED Requirements

Requirement: Readable text

The system SHALL warn, without refusing the stylesheet, when a Style topic's text colours have a contrast ratio below 4.5:1 against its backgrounds.

Scenario: Low contrast

• WHEN a Style topic sets --ink: #2a5c3a on --paper: #0b3d1e
• THEN the save reply's style.warnings names --ink on --paper and the ratio
• AND the stylesheet can still be picked

Scenario: Good contrast

• WHEN a Style topic sets --ink: #ffffff on --paper: #0b3d1e
• THEN there is no contrast warning