`describe` reports "dark on dark" for text that passes WCAG AA, and contradicts the `color-contrast` lint rule

Author: danikobeissiCreated Sep 20, 2026Updated Sep 20, 2026

What happens

describe reports an issue with severity error"Label" dark on dark (#14101F on #FF5FA2) — for near-black text on a mid-pink background. That pair is 6.60:1, which passes WCAG 2 AA for body text (4.5:1) and AAA for large text. Nothing is wrong with the design.

The check behind it is not a contrast ratio. It compares the relative luminance of the text and of the nearest ancestor background against one threshold, 0.35, and reports an error when both are below it. Two colours can both be under 0.35 and still be far apart in luminance, which is this case: the pink's luminance is 0.3205, just under the threshold, and the ink's is 0.0062.

The check is also silent about every failing pair that is not dark on dark, since it reports only when both sides are below the threshold. #949494 text on a #FFFFFF background is 3.03:1, a clear AA failure, and raises nothing.

The message gives no number, so an agent reading the result cannot tell whether the pair is a genuine failure or how far from a threshold it is. An agent told this pair is an error either changes a colour that did not need changing, or measures the ratio itself.

This also disagrees with OpenPencil's own accessibility lint. The color-contrast rule computes the WCAG 2 ratio and reports "Contrast ratio N:1 is below WCAG AA" under 4.5:1, so on the same document openpencil lint --rule color-contrast says nothing while describe reports an error.

Reproduction

  1. In OpenPencil, make a frame with a solid fill #FF5FA2 and auto layout, and put a text child inside it with a solid fill #14101F at 17px bold — for example the label of a button in a hover state.
  2. Ask the built-in AI, or an agent connected to the MCP server, to run describe on the frame.
  3. The frame's issues contain {"message": "\"Label\" dark on dark (#14101F on #FF5FA2)", "suggestion": "Use a light color", "severity": "error"}.
  4. Save the document and run openpencil lint --rule color-contrast over it: the lint reports nothing, because the pair is 6.60:1.
  5. For the silent half: change the text to #949494 and the background to #FFFFFF and run both again. The lint reports the AA failure at 3.03:1; describe reports no contrast issue.

What was expected

describe judges a text-on-background pair by its WCAG 2 contrast ratio, as color-contrast already does, and says in the message what the ratio is and which threshold it missed — 4.5:1, or 3:1 where the text is large (18pt, or 14pt bold). Text that meets the threshold raises no issue.

Where

  • packages/core/src/tools/describe/layout-issues.tsDARK_BG_LUMINANCE = 0.35 at line 12, and checkTextVisibility at lines 203–226, which reports the issue at lines 217 and 220.
  • The ratio the project already computes, for comparison: packages/core/src/lint/utils.ts (contrastRatio) and packages/core/src/lint/rules/color-contrast.ts.
  • Seen at commit e2de247.