From bf339ed28c5f75db55fdef614740a3995fe568c6 Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Tue, 6 Oct 2026 19:30:37 -0400 Subject: [PATCH] fix(ui): status text readable on its tint over a hovered row, a 3:1 outline on controls, contrast as a CI guard (#5096) An audit of 1,980 text/surface pairs (every steward.css rule and every inline template style, tints composited over page, card and hovered row) found: - Red, yellow and orange status text on its own 20% tint over a hovered row at 3.97-4.06:1 (badges, count badge, alert-error, btn-warn). --red and --yellow are lifted 15% toward the primary text, --orange 18%, as --blue already was: worst case now 4.54:1. - Inputs, selects, ghost and range buttons outlined in --border-mid at 1.4-1.9:1, on surfaces 1.1:1 apart, so the outline is what marks them. New --border-control (45% toward secondary text): 3.13:1 worst. The dashboard switcher and widget-drawer fields drop their inline styles for the shared .input class. - The breadcrumb separator painted in a border colour (1.4-1.9:1): now --text-dim (4.64:1) and aria-hidden, since it is decoration. tests/test_contrast.py resolves the tokens (color-mix and tints included) and holds every drawn pair to 4.5:1, status text on its tint to 4.5:1 and control outlines to 3:1, with a test that the guard catches the old pairs. Co-Authored-By: Claude Opus 5.5 --- steward/static/steward.css | 29 ++-- steward/templates/_macros.html | 4 +- .../templates/dashboard/_widget_drawer.html | 13 +- steward/templates/dashboard/index.html | 3 +- tests/test_contrast.py | 151 ++++++++++++++++++ 5 files changed, 174 insertions(+), 26 deletions(-) create mode 100644 tests/test_contrast.py diff --git a/steward/static/steward.css b/steward/static/steward.css index ddd1835..b86db83 100644 --- a/steward/static/steward.css +++ b/steward/static/steward.css @@ -3,9 +3,9 @@ * Values come from theme.css, the stylesheet design system 6 ("Steward", * inheriting FabledSword) generates. The short names below are Steward's * aliases onto those tokens, kept so templates written against them still - * render; new work writes the --fs-* token. Contrast measured 2026-10-06 - * (#5092): every text colour here is at least 4.5:1 on page, card, hover - * and its own 15-25% tint. + * render; new work writes the --fs-* token. Contrast is a CI guard + * (tests/test_contrast.py): text 4.5:1 and control outlines 3:1 on page, + * card and hover, and status text on its own tint over each of them. */ :root { --bg: var(--fs-surface-page); @@ -13,6 +13,9 @@ --bg-elevated: var(--fs-surface-hover); --border: color-mix(in srgb, var(--fs-border-color) 70%, var(--fs-surface-raised)); --border-mid: var(--fs-border-color); + /* The outline that marks a control (input, select, ghost button): 3:1 on + page, card and hover (WCAG 1.4.11), where --border-mid is ~1.4-1.9:1. */ + --border-control: color-mix(in srgb, var(--fs-text-secondary) 45%, var(--fs-border-color)); --text: var(--fs-text-primary); --text-muted: var(--fs-text-secondary); --text-dim: var(--fs-text-tertiary); @@ -21,15 +24,17 @@ --gold-dim: var(--fs-accent-soft); --accent: var(--fs-accent); --accent-hover: var(--gold-hover); - /* Status: the -fg colour is the text and indicator; the -dim tint sits behind it. */ + /* Status: the -fg colour is the text and indicator; the -dim tint sits behind it. + Warning, error and their mix are lifted toward the primary text: the house + -fg falls to ~4.0:1 on its own tint over a hovered row (#5096). */ --green: var(--fs-success-fg); --green-dim: color-mix(in srgb, var(--fs-success) 20%, transparent); - --yellow: var(--fs-warning-fg); + --yellow: color-mix(in srgb, var(--fs-warning-fg) 85%, var(--fs-text-primary)); --yellow-dim: color-mix(in srgb, var(--fs-warning) 20%, transparent); /* Between warning and error: the worse-than-warning band (slow, degraded). */ - --orange: color-mix(in srgb, var(--fs-warning-fg) 50%, var(--fs-error-fg)); + --orange: color-mix(in srgb, color-mix(in srgb, var(--fs-warning-fg) 50%, var(--fs-error-fg)) 82%, var(--fs-text-primary)); --orange-dim: color-mix(in srgb, var(--fs-warning) 20%, transparent); - --red: var(--fs-error-fg); + --red: color-mix(in srgb, var(--fs-error-fg) 85%, var(--fs-text-primary)); --red-dim: color-mix(in srgb, var(--fs-error) 20%, transparent); /* Info (acknowledged): lighter than the house --fs-info-fg (50%), which falls to 4.18:1 on its tint over a hovered row; 40% holds 5.09:1 there. */ @@ -181,7 +186,7 @@ strong, b, th { font-weight: 500; } .form-group { margin-bottom: 1rem; } label { display: block; margin-bottom: 0.3rem; font-size: 0.85rem; color: var(--text-muted); font-family: var(--fs-font-body); } input[type=text], input[type=email], input[type=password], input[type=number], input[type=url], select, textarea { - width: 100%; padding: 0.5rem 0.75rem; background: var(--bg); border: 1px solid var(--border-mid); + width: 100%; padding: 0.5rem 0.75rem; background: var(--bg); border: 1px solid var(--border-control); border-radius: 5px; color: var(--text); font-size: 0.9rem; font-family: inherit; transition: border-color .15s; } @@ -197,7 +202,7 @@ textarea { resize: vertical; } .field-label { display: block; margin-bottom: 0; font-size: 0.75rem; color: var(--text-muted); } .field-hint { font-size: 0.75rem; color: var(--text-dim); } .field-error { font-size: 0.85rem; color: var(--red); margin-bottom: 0.75rem; } -.input { width: 100%; padding: 0.4rem 0.65rem; background: var(--bg); border: 1px solid var(--border-mid); border-radius: var(--fs-radius-sm); color: var(--text); font-size: 0.88rem; font-family: inherit; } +.input { width: 100%; padding: 0.4rem 0.65rem; background: var(--bg); border: 1px solid var(--border-control); border-radius: var(--fs-radius-sm); color: var(--text); font-size: 0.88rem; font-family: inherit; } .input:focus { outline: none; border-color: var(--accent); } .input:disabled { opacity: var(--fs-disabled-opacity); } @@ -206,7 +211,7 @@ textarea { resize: vertical; } .btn:hover { background: var(--accent-hover); color: var(--fs-surface-page); } .btn-sm { padding: 0.3rem 0.65rem; font-size: 0.8rem; } .btn-icon { padding: 0.3rem 0.5rem; line-height: 1; } -.btn-ghost { background: transparent; color: var(--text-muted); border: 1px solid var(--border-mid); } +.btn-ghost { background: transparent; color: var(--text-muted); border: 1px solid var(--border-control); } .btn-ghost:hover { background: var(--bg-elevated); color: var(--text); } .btn-danger { background: var(--fs-action-destructive); color: var(--fs-text-on-action); } .btn-danger:hover { background: var(--fs-action-destructive-hover); color: var(--fs-text-on-action); } @@ -302,7 +307,7 @@ a.stat-tile:hover { border-color: var(--border-mid); background: var(--bg-elevat .breadcrumb { display:flex; align-items:center; flex-wrap:wrap; gap:0.35rem; font-size:0.78rem; color:var(--text-dim); margin:0 0 0.45rem; } .breadcrumb a { color:var(--text-muted); } .breadcrumb a:hover { color:var(--text); } -.breadcrumb-sep { color:var(--border-mid); } +.breadcrumb-sep { color:var(--text-dim); } .breadcrumb-cur { color:var(--text-muted); } /* Stat cards (dashboard) */ @@ -369,6 +374,6 @@ body.dash-editing .widget-drawer { transform:translateY(0); } .widget-link:hover { color:var(--text); } /* Time range selector */ -.range-btn { background:none; border:1px solid var(--border-mid); border-radius:4px; color:var(--text-muted); padding:0.18rem 0.5rem; cursor:pointer; font-size:0.75rem; font-family:inherit; transition:background .1s,color .1s,border-color .1s; } +.range-btn { background:none; border:1px solid var(--border-control); border-radius:4px; color:var(--text-muted); padding:0.18rem 0.5rem; cursor:pointer; font-size:0.75rem; font-family:inherit; transition:background .1s,color .1s,border-color .1s; } .range-btn:hover { background:var(--bg-elevated); color:var(--text); border-color:var(--accent); } .range-btn.active { background:var(--accent); border-color:var(--accent); color:var(--fs-surface-page); } diff --git a/steward/templates/_macros.html b/steward/templates/_macros.html index 3b3b470..a9b2716 100644 --- a/steward/templates/_macros.html +++ b/steward/templates/_macros.html @@ -9,9 +9,9 @@ {%- if loop.last -%} {{ label }} {%- elif href -%} - {{ label }}› + {{ label }} {%- else -%} - {{ label }}› + {{ label }} {%- endif -%} {%- endfor -%} diff --git a/steward/templates/dashboard/_widget_drawer.html b/steward/templates/dashboard/_widget_drawer.html index 47f9957..8af9711 100644 --- a/steward/templates/dashboard/_widget_drawer.html +++ b/steward/templates/dashboard/_widget_drawer.html @@ -33,26 +33,19 @@ - + {% for p in w.params %}
{% if p.type == "select" %} - {% for opt in p.options %} {% endfor %} {% elif p.type == "host" %} - {% for h in hosts %} diff --git a/steward/templates/dashboard/index.html b/steward/templates/dashboard/index.html index 5182d28..1198db5 100644 --- a/steward/templates/dashboard/index.html +++ b/steward/templates/dashboard/index.html @@ -18,8 +18,7 @@
{# Dashboard switcher — shown when more than one dashboard exists #} {% if all_dashboards | length > 1 %} - {% for d in all_dashboards %} {% endfor %} diff --git a/tests/test_contrast.py b/tests/test_contrast.py new file mode 100644 index 0000000..d6955b1 --- /dev/null +++ b/tests/test_contrast.py @@ -0,0 +1,151 @@ +"""Every text colour Steward draws is readable on the surfaces it can sit on. + +Tokens are resolved from theme.css (:root; nothing sets data-theme, so the +dark theme is the only one) and steward.css, color-mix() and transparent +tints included, the tints composited over each surface. Text is held to +4.5:1 (WCAG AA) on page, card and hovered row, and status text on its own +tint over each of them; a control's outline to 3:1 (WCAG 1.4.11). The pairs +come from every steward.css rule and every inline style in the templates +(#5096). +""" +import re +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +TEXT_FLOOR, CONTROL_FLOOR = 4.5, 3.0 +SURFACES = ("--bg", "--bg-card", "--bg-elevated") +TOKEN_VALUE = r"(var\(--[\w-]+\)|color-mix\([^;{}]*\)|#[0-9a-fA-F]{3,6})" + + +def _root_block(css: str) -> str: + i = css.index(":root {") + return re.sub(r"/\*.*?\*/", "", css[i:css.index("\n}", i)], flags=re.S) + + +def _tokens() -> dict[str, str]: + out: dict[str, str] = {} + for name in ("theme.css", "steward.css"): + css = (ROOT / "steward/static" / name).read_text() + out.update((k, v.strip()) for k, v in re.findall(r"(--[\w-]+)\s*:\s*([^;]+);", _root_block(css))) + return out + + +TOKENS = _tokens() + + +def _args(s: str) -> list[str]: + depth, cur, out = 0, "", [] + for ch in s: + depth += (ch == "(") - (ch == ")") + if ch == "," and depth == 0: + out.append(cur.strip()) + cur = "" + else: + cur += ch + return out + [cur.strip()] + + +def color(expr: str) -> tuple: + """(r, g, b, alpha) for a token expression.""" + expr = expr.strip() + if expr == "transparent": + return (0, 0, 0, 0.0) + if expr == "black": + return (0, 0, 0, 1.0) + if expr.startswith("#"): + h = expr[1:] if len(expr) == 7 else "".join(c * 2 for c in expr[1:]) + return (int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16), 1.0) + if m := re.fullmatch(r"var\((--[\w-]+)\)", expr): + return color(TOKENS[m.group(1)]) + if m := re.fullmatch(r"color-mix\(in srgb,(.*)\)", expr, re.S): + a, b = _args(m.group(1)) + pa, pb = re.search(r"\s([\d.]+)%$", a), re.search(r"\s([\d.]+)%$", b) + ca, cb = color(a[:pa.start()] if pa else a), color(b[:pb.start()] if pb else b) + wa = float(pa.group(1)) / 100 if pa else (1 - float(pb.group(1)) / 100 if pb else 0.5) + alpha = ca[3] * wa + cb[3] * (1 - wa) + if alpha == 0: + return (0, 0, 0, 0.0) + return (*( + (ca[i] * ca[3] * wa + cb[i] * cb[3] * (1 - wa)) / alpha for i in range(3)), alpha) + raise ValueError(f"cannot resolve {expr!r}") + + +def _over(fg: tuple, bg: tuple) -> tuple: + return (*(fg[i] * fg[3] + bg[i] * (1 - fg[3]) for i in range(3)), 1.0) + + +def _luminance(c: tuple) -> float: + def ch(v): + v /= 255 + return v / 12.92 if v <= 0.03928 else ((v + 0.055) / 1.055) ** 2.4 + return 0.2126 * ch(c[0]) + 0.7152 * ch(c[1]) + 0.0722 * ch(c[2]) + + +def ratio(a: tuple, b: tuple) -> float: + hi, lo = sorted((_luminance(a), _luminance(b)), reverse=True) + return (hi + 0.05) / (lo + 0.05) + + +def worst(fg: str, bg: str | None = None) -> tuple[float, str]: + """The lowest contrast of fg (on bg, if given) over page, card and hover.""" + lows = [] + for s in SURFACES: + back = _over(color(bg), color(f"var({s})")) if bg else color(f"var({s})") + lows.append((ratio(_over(color(fg), back), back), s)) + return min(lows) + + +def drawn_pairs(): + """(where, text colour, its own background or None) for every rule in + steward.css and every inline style in the templates that sets a colour.""" + sheet = (ROOT / "steward/static/steward.css").read_text() + body = re.sub(r"/\*.*?\*/", "", sheet[sheet.index("\n}"):], flags=re.S) + for sel, rule in re.findall(r"([^{}]+)\{([^{}]*)\}", body): + if fg := re.search(r"(? 200, "the pair scan found almost nothing: the parser broke" + assert below(TEXT_FLOOR, pairs) == [] + + +def test_status_text_reads_on_its_own_tint_over_a_hovered_row(): + for tok in ("green", "yellow", "orange", "red", "blue"): + r, surface = worst(f"var(--{tok})", f"var(--{tok}-dim)") + assert r >= TEXT_FLOOR, f"--{tok} on --{tok}-dim over {surface}: {r:.2f}" + + +def test_a_control_outline_marks_the_control(): + r, surface = worst("var(--border-control)") + assert r >= CONTROL_FLOOR, f"--border-control over {surface}: {r:.2f}" + for rule in ("input[type=text]", ".input {", ".btn-ghost {", ".range-btn {"): + sheet = (ROOT / "steward/static/steward.css").read_text() + decl = sheet[sheet.index(rule):sheet.index("}", sheet.index(rule))] + assert "var(--border-control)" in decl, rule + + +def test_the_guard_can_fail(): + # The divider colour as text, and the house error colour on its tint over + # a hovered row (the pair #5096 found at 4.05:1), must both be caught. + assert below(TEXT_FLOOR, [("probe", "var(--border-mid)", None)]) + assert below(TEXT_FLOOR, [("probe", "var(--fs-error-fg)", "var(--red-dim)")]) + assert worst("var(--border-mid)")[0] < CONTROL_FLOOR