Skip to content

Fix AA contrast on the vertical bands, not in the palette (4.9.0) - #105

Merged
jasperf merged 2 commits into
mainfrom
fix/vertical-band-contrast
Aug 18, 2026
Merged

jasperf merged 2 commits into
mainfrom
fix/vertical-band-contrast

Conversation

@jasperf

@jasperf jasperf commented Aug 18, 2026

Copy link
Copy Markdown
Contributor

Replaces #104, which fixed the wrong half of the problem. Follow-on from Aludra #33.

Problem

Three verticals put light text on a brand colour too light to carry it — in their bands, their buttons, and their contact forms:

before after
Nail Salon stats bar (base on primary) 3.30:1 4.93:1 ✅
Nail Salon CTA gradient 3.30–4.93:1 4.93–6.76:1 ✅
Home Improvement stats bar (white on primary) 2.85:1 6.36:1 ✅
Home Improvement top bar + header CTA pill 2.85:1 6.36:1 ✅
Spa booking CTA (base on primary) 2.19:1 9.54:1 ✅
Default filled button — Nail Salon 3.30:1 4.93:1 ✅
Default filled button — Home Improvement 2.85:1 6.36:1 ✅
Default filled button — Spa & Wellness 2.19:1 9.54:1 ✅
Spa CTA buttons (button-light / fill) 2.19:1 9.54:1 / 6.03:1 ✅
CF7 submit — Nail Salon / Home Improvement 3.40 / 2.85:1 5.08 / 6.36:1 ✅
Home Improvement focus ring (needs 3:1) 2.85:1 3.59:1 ✅

Why the bands and buttons, not the palette

#104 darkened primary in these three variations. That fixed text on a primary background and broke primary as text on the dark surfaces, which is where these sites use it most:

on light base on dark main
Nail Salon 3.30 → 4.93 ✅ 4.70 → 3.14
Home Improvement 2.42 → 4.52 ✅ 6.36 → 3.41
Spa & Wellness 2.19 → 4.50 ✅ 4.37 → 2.12

Home Improvement's site is overwhelmingly dark navy, so that was a net loss.

No single value can satisfy both. Each variation's base and main sit 15.49:1, 15.39:1 and 9.54:1 apart, so the best any one colour can score against both is 3.94:1, 3.92:1 and 3.09:1 — all under 4.5:1. One token cannot serve a light surface and a dark one.

The palettes are untouched here. git diff main -- styles/ shows only styles.elements.button; no palette entry moves.

Approach

Every fix uses a colour that variation already defines:

  • Nail Salon — stats bar, CTA gradient, buttons and CF7 submit step to primary-alt / primary-alt-accent.
  • Home Improvement — keeps its signature orange everywhere and darkens the labels to main. Only the two orange regions of the header are retargeted; the nav bar sits on secondary navy where the white site title is correct. It had no elements.button of its own and now gets one, so the fix stays scoped to this variation instead of theme.json's shared default.
  • Spa & Wellness — booking CTA and buttons move onto main, the deep teal its palette already defines. With the band on main, the CTA's two buttons needed explicit colours: white and primary-alt mint, both with a main label, each distinct from the band.

Verified on the demo

Synced to demo.imagewize.test, global styles restored to the original palettes and updated with the new button element, all three subsites rebuilt from patterns, caches flushed. Computed styles read back off the rendered pages confirm every pairing above.

Reading the rendered pages is what caught the buttons: they set their colours explicitly in the patterns and so override elements.button, which the band fix alone did not reach.

Known limitation

The shared button-light block style still resolves to text: primary, unreadable on base under a light-primary variation wherever it is used outside the patterns fixed here. Same for the 18 patterns that set backgroundColor: primary and are shared across all variations — correct under the six variations whose primary is dark enough, and unused by these three verticals' pages. Solving that generally needs the palette to separate its light-surface and dark-surface roles, which is exactly what #104 showed cannot be done by moving one token.

Version

4.8.14.9.0 in style.css, readme.txt (stable tag + entry), package.json, package-lock.json, CHANGELOG.md.

Three verticals placed light text on a brand-coloured band too light to
carry it: Nail Salon's stats bar and CTA at 3.30:1, Home Improvement's stats
bar, top bar and header pill at 2.85:1, and the Spa booking CTA at 2.19:1.
WCAG 2.1 AA asks 4.5:1. They now reach 4.93:1, 6.36:1 and 9.54:1.

Every fix uses a colour already in that variation's palette. Nail Salon's
band steps down to primary-alt and its gradient to primary-alt ->
primary-alt-accent. Home Improvement keeps its signature orange and switches
the label to main. The Spa CTA moves onto main, the deep teal its palette
already defines.

Also fixes the contact-form submit buttons in both variation stylesheets
(white labels at 3.40:1 and 2.85:1) and Home Improvement's focus ring, which
at 2.85:1 sat under the 3:1 WCAG 1.4.11 wants of a control boundary.

The palettes are deliberately untouched. Darkening `primary` fixes text on a
primary background and breaks primary as text on the dark surfaces, which is
where these sites use it most — Home Improvement would go from 6.36:1 to
3.41:1 on its navy. No single value satisfies both: each variation's `base`
and `main` are 15.49:1, 15.39:1 and 9.54:1 apart, capping any one colour at
3.94:1, 3.92:1 and 3.09:1 against both. One token cannot serve a light and a
dark surface, so the fix belongs where light text meets the brand colour.

Only the plumbing header's two orange regions are retargeted; its navigation
bar sits on `secondary` navy, where the white site title is correct.
Checking the rendered pages turned up the same failure in the buttons, which
the band fix did not reach: the filled button paired a light `primary`
background with light text at 3.30:1, 2.85:1 and 2.19:1.

Fixed per variation in styles.elements.button, and in the patterns that set
the colours explicitly and so override it. Nail Salon's buttons move to
primary-alt (4.93:1), Home Improvement keeps its orange and darkens the label
to main (6.36:1), Spa moves to main (9.54:1). Home Improvement had no
elements.button of its own and now gets one, keeping the change scoped to
that variation rather than every theme sharing theme.json's default.

The Spa booking CTA needed explicit button colours too: with the band on
`main`, the shared button-light style put cyan on white at 2.19:1 and the
filled button would have matched the band exactly. They are now white and
primary-alt mint, both with a main label, at 9.54:1 and 6.03:1.

Palettes remain untouched.
@jasperf
jasperf merged commit cf36b07 into main Aug 18, 2026
3 checks passed
@jasperf
jasperf deleted the fix/vertical-band-contrast branch August 18, 2026 08:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant