---
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: [[OpenSpec:style-topics]].
- Affected code: `src/styles.ts`, `src/stylespage.ts`.

# Tasks

## 1. Build

- [x] 1.1 Compute contrast ratios from hex colours
- [x] 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