[wemra3]

Motivation

Part of tailor-inc/platform-planning#2208. #641 listed one open item: in light mode, text on surface-hover is below 4.5:1 for danger (4.22:1) and success (4.34:1 over --background). It said that choosing another step was a visible change for a later PR. This PR records the decision instead.

Decision

Keep surface at a3 and surface-hover at a4. I compared three ways to reach 4.5:1:

Option	Text on hover (danger / success)	Cost
Lighter surfaces: surface a2, surface-hover a3	4.70–4.90 / 4.71–4.91	The tint is hard to see. Danger surface vs --card: 1.16:1 with a3, 1.06:1 with a2. The hover step also gets smaller: 1.16:1 with a3→a4, 1.10:1 with a2→a3.
Darker text on hover only (step 12)	9.04 / 9.52–9.89	Needs a new role, and the text changes from red to dark brown on hover.
Darker text in every state (step 12, as warning does)	9.04 / 9.52–9.89	Every text-danger-text and text-success-text changes from red or green to a dark brown or dark green.

The hover state is short, and the text stays above 4.2:1. This does not meet WCAG 1.4.3 for the hover state, so it stays in the styling guide's list of exceptions, and the test keeps the 4.2:1 floor.

Changes

• decisions/semantic-color-roles.md: new section "Update 2026-10-30: the hover step stays", with the comparison and the reasons.
• Styling guide: the exception now says why it is on purpose.
• No changeset: consumers do not need to do anything. No colour value changes.

Checks

• docs:check and fmt:check pass.
• The numbers come from the default palette on main (light mode), composited over --card and --background.

🤖 Generated with Claude Code

[github-actions]

Code Metrics Report

	main (9f68121)	#661 (0a94472)	+/-
Coverage	89.5%	89.5%	0.0%
Test Execution Time	2m56s	3m25s	+29s

Details

  |                     | main (9f68121) | #661 (0a94472) | +/-  |
  |---------------------|----------------|----------------|------|
  | Coverage            |          89.5% |          89.5% | 0.0% |
  |   Files             |            236 |            236 |    0 |
  |   Lines             |           7517 |           7517 |    0 |
  |   Covered           |           6732 |           6732 |    0 |
- | Test Execution Time |          2m56s |          3m25s | +29s |

---

Reported by octocov