ReviewOS

stacks/uplink

fix(homepage): the amber focus ring is 2.06:1 and the wash surface is invisible

#28
Open glennmichael123 opened this 8 days ago ·
8 days ago

Part of #6.

Both failures are amber tokens carrying non-text meaning, declared four lines apart in the same :root block, and neither one is a styling judgement call: one is a WCAG 2.2 conformance failure and the other makes a bento cell and two icon chips render as nothing at all. The rest of the palette measures fine, so this is two token references and one decision about borders, not a restyle.

What is there today

  • resources/views/index.stx#L147 is the only focus style on the page: outline: 2px solid var(--accent); outline-offset: 3px on a:focus-visible and summary:focus-visible.
  • --accent is #f59e0b at resources/views/index.stx#L116, and the dark block at resources/views/index.stx#L120-L129 does not redefine it, so the ring is the same amber in both themes. --paper is #fafaf9 at index.stx#L111 and #0c0c0e at index.stx#L122.
  • #f59e0b on #fafaf9 is 2.06:1. WCAG 2.2 SC 1.4.11 sets a 3:1 floor for a focus indicator against the adjacent background. The same amber on #0c0c0e is 9.10:1, so dark mode already passes and light mode is the only failure.
  • outline-offset: 3px puts the ring in a gap that shows --paper, so even on the amber pill CTAs the ring is amber on paper, not amber on amber. The button fill does not help it.
  • Everything focusable is affected in light mode: the two nav links and the nav CTA at index.stx#L181-L183, the hero CTA at index.stx#L198, the download CTA at index.stx#L322, the two footer links at index.stx#L376, and all six FAQ summaries, rendered by the summary at index.stx#L362 from the faqs array at index.stx#L59-L84.
  • resources/views/404.stx#L27 carries the identical declaration over identical tokens at 404.stx#L20-L21, so the not-found page fails the same way and will not be fixed by a change to index.stx.
  • --accent-wash is #fffbeb at index.stx#L118 and #1c1508 at index.stx#L128, applied by .u-wash at index.stx#L138. Against --paper that is 1.01:1 in light mode and 1.08:1 in dark, which is below the point where a fill reads as a surface at all.
  • The bento cell at index.stx#L291 is p-6 rounded-2xl u-reveal u-wash with no border, while its two neighbours at index.stx#L285 and index.stx#L303 are p-6 border rounded-2xl u-line u-raised. So the cell reads as loose text on the page background in both themes while the cards around it read as cards, and the grid at index.stx#L267 is left with one photo, two cards and a gap.
  • The chips at index.stx#L250 and index.stx#L304 are size-11 rounded-full u-wash wrapping a single glyph, so the circle never appears and only the amber icon shows.
  • The rest of the palette needs no change and should not be touched: --muted is 7.40:1 light and 7.63:1 dark, --accent-ink as a text colour is 4.81:1 light and 11.71:1 dark, and #18181b on #f59e0b in .u-btn-primary at index.stx#L143 is 8.25:1.

Proposal

  1. In resources/views/index.stx#L147, change the outline colour from var(--accent) to var(--accent-ink). No theme-specific rule is needed, because --accent-ink is already redefined per theme: #b45309 at index.stx#L117 is 4.81:1 on light paper and #fbbf24 at index.stx#L127 is 11.71:1 on dark paper, so both themes clear the 3:1 floor with a one token change.
  2. Apply the same one token change to resources/views/404.stx#L27. That file defines --accent-ink in both themes at 404.stx#L20-L21, so nothing new has to be added to it.
  3. Make the wash read as a surface. Pick one of two routes. Either deepen --accent-wash at index.stx#L118 and index.stx#L128 until it separates from --paper by roughly 1.2:1 or more in both themes, or leave the token alone and give the cell at index.stx#L291 and the chips at index.stx#L250 and index.stx#L304 the same border u-line the rest of the system uses.
  4. Leave --accent, --muted, --accent-ink and .u-btn-primary as they are.

Requirements

  • Do not change --accent to fix the ring. It is the primary button fill at index.stx#L143, and darkening it enough to reach 3:1 as a ring would pull the #18181b button label down from 8.25:1 and shift the accent on every other surface that uses it.
  • Keep the fix in one declaration. Prefer swapping the token reference in the single rule at index.stx#L147 over adding a second a:focus-visible block inside the dark media query. If the exact #f59e0b hue is wanted for the dark ring specifically, introduce a --focus token defined in both blocks rather than duplicating the rule.
  • The ring has to contrast with --paper, not with the element. Because of outline-offset: 3px, the adjacent colour is the page background on both sides of the ring, including on the three amber CTAs.
  • Fix the wash one way, not both. Deepening the token and adding borders each solve it, and doing both makes the cell at index.stx#L291 visibly heavier than its neighbours.
  • Whichever wash route is chosen, the chips are part of it. index.stx#L250 and index.stx#L304 use the same token for a 44px circle, so a border added only to the bento cell leaves the step icons bare.
  • resources/views/404.stx needs its own edit. Its tokens and its focus rule are a separate inline block and do not inherit anything from index.stx.

Acceptance

  • Tabbing through / in light mode shows a focus ring measuring at least 3:1 against #fafaf9 on the nav links and nav CTA, the hero CTA, the download CTA, both footer links and all six FAQ summaries. The same check on /404.
  • Dark mode still measures at least 3:1 on the same elements, on both pages.
  • The bento cell at index.stx#L291 reads as a distinct card beside index.stx#L285 and index.stx#L303 in both light and dark mode, whether by surface or by border.
  • The circles behind the icons at index.stx#L250 and index.stx#L304 are visible in both themes.
  • --accent, --muted, .u-btn-primary and every text colour are byte for byte unchanged, and ./buddy lint passes.

Sign in to comment on this issue.