Skip to content

Docs: fix ornament-pattern legibility in arabic/indian/andalus/terminal themes - #191

Merged
testtest126 merged 2 commits into
mainfrom
fix/fleet-theme-legibility
Jul 18, 2026
Merged

Docs: fix ornament-pattern legibility in arabic/indian/andalus/terminal themes#191
testtest126 merged 2 commits into
mainfrom
fix/fleet-theme-legibility

Conversation

@testtest126

Copy link
Copy Markdown
Owner

Summary

The owner reported that text is hard to read against the background motif patterns in the indian, arabic, El-Andalus, and terminal themes on the-fleet pages. Confirmed and measured — not eyeballed.

Root cause: the four flagged themes all use small-repeat, high-density ornament tiles (hex6 66px, jaali 64px, star8 72px, scan 5px), versus the two themes that were never flagged (ensoFaint 150px, vine 130px). Pattern spatial frequency — not raw opacity — is what competes with glyph edges. Terminal's scan tile in particular repeated every 5px, close enough to a text stroke's own width to alias against it regardless of its already-low .1 opacity.

Fix, applied identically to docs/the-fleet/index.html, docs/the-fleet/night-two/index.html, and docs/architecture/index.html (all three share the same theme engine):

  • Cut --orn-opacity for the four themes: arabic .16→.07, indian .17→.07, andalus .17→.07, terminal .1→.05.
  • Widened the terminal scan tile 5×5 → 6×10, doubling the vertical gap between scanlines.
  • Added a ground-colored text-shadow halo, scoped to just these four themes via :root:is([data-theme="arabic"], ...), on the prose that has no opaque card behind it — section ledes, ledger rows, standdown/footer text on the-fleet pages; section intros/headings/provenance line on architecture. Everything inside .role/.chan/.callout/.manifest/.laws-sec (or .col/.stage/.surface on architecture) already sits on a solid --ground-2/--surface and didn't need it.

Measured, not eyeballed: worst-case contrast (dim body text against the pattern's own color blended at full local coverage) went from 5.6–7.2:1 before to 6.1–8.5:1 after, and to 6.5–9.4:1 at the glyph edge under the halo. All four themes now clear WCAG AA (4.5:1) with real margin — they were technically already passing on raw pixel-blend math, which is why the fix targets pattern density, the actual mechanism, not just a contrast-ratio number.

Verification

Visual before/after confirmed for all four flagged themes via a static isolation harness (same CSS/SVG/markup, headless Chrome screenshots) — the pattern is now visibly quieter directly behind prose while keeping its per-theme motif intact everywhere else (margins, cards). Also spot-checked the three untouched themes (default/japanese/codex): their computed CSS is provably unaffected, since both the opacity overrides and the halo rule are scoped to the four flagged themes' own data-theme selectors (confirmed via diff — no lines changed inside their theme blocks).

Not run / why

This is a docs-only CSS/SVG change — git diff --stat confirms zero Swift/server files touched. I did not run the ChessKit/server/iOS test suites locally since nothing in this diff can affect Swift build/test outcomes; the required ChessKit tests / Server tests CI checks will still run and gate the merge per branch protection as usual.

Not security-sensitive (no auth/token/crypto/session code). Does not touch ChessKit/Sources/ChessOnline/Messages.swift or any other shared file. Does not touch #116 or #185.

🤖 Generated with Claude Code

…al themes

Measured, not eyeballed: the four themes the owner flagged (indian, arabic,
El-Andalus, terminal) all use dense small-repeat ornament tiles (hex6 66px,
jaali 64px, star8 72px, scan 5px) versus the two unflagged themes' large
sparse ones (ensoFaint 150px, vine 130px) -- pattern spatial frequency, not
raw opacity, is what competes with glyph edges. Terminal's scan tile in
particular repeated every 5px, close enough to a text stroke's own width to
alias against it regardless of its already-low .1 opacity.

Fix, applied identically to docs/the-fleet/, docs/the-fleet/night-two/, and
docs/architecture/ (all three share the same theme engine):
- Cut --orn-opacity for the four themes (arabic .16->.07, indian .17->.07,
  andalus .17->.07, terminal .1->.05).
- Widened the terminal scan tile 5x5 -> 6x10, doubling the vertical gap
  between scanlines.
- Added a ground-colored text-shadow halo, scoped to just these four themes,
  on the prose that has no opaque card behind it (section ledes, ledger
  rows, standdown/footer text on the-fleet pages; section intros/headings/
  provenance line on architecture -- everything inside .role/.chan/.callout/
  .manifest/.laws-sec or .col/.stage/.surface already sits on solid ground
  and didn't need it).

Worst-case contrast (dim body text against the pattern's own color blended
at full coverage) went from 5.6-7.2:1 before to 6.1-8.5:1 after, and to
6.5-9.4:1 at the glyph edge under the halo -- all four themes now clear
WCAG AA (4.5:1) with real margin, up from already-passing-but-thin. Verified
visually before/after for all four themes plus a regression spot-check on
the three untouched themes (default/japanese/codex), which are provably
unaffected since the halo rule and the opacity overrides are both scoped to
the four themes' own data-theme selectors.

🤖 Generated with Claude Code

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
@testtest126

Copy link
Copy Markdown
Owner Author

Merge request: PR #191 @ a3f29eb
Verified locally: docs-only change, zero Swift/server files touched (confirmed via git diff --stat) — ChessKit/server/iOS suites not run locally since nothing in this diff can affect them; required CI checks will still gate the merge as usual.
Security-sensitive: no
App-touching: no
Shared files: none touched, not Messages.swift

Fix for the owner's report that indian/arabic/El-Andalus/terminal themes had illegible text against the background ornament patterns — reduces ornament opacity + tile density for those four themes and adds a scoped text-shadow halo behind unprotected prose, applied identically across docs/the-fleet/, docs/the-fleet/night-two/, and docs/architecture/. Full before/after visual verification and WCAG contrast math in the PR description. Does not touch #116 or #185.

…dependency)

Follow-up to #191. The Assayer's independent verification caught a real gap:
--bone-faint (used in .sig, footer, .inc .refs) was still only 2.98:1 in the
terminal theme against the worst-case pattern-blended background post-fix,
clearing AA only via the text-shadow halo -- whose real-world sufficiency
couldn't be confirmed empirically. Re-measuring myself found the gap was
wider than reported: all four fixed themes were short on the color math
alone (arabic 4.24:1, indian 4.25:1, andalus 3.66:1, terminal 2.98:1), not
just terminal.

Fix: lifted --bone-faint per theme by blending toward the theme's own
--bone-dim (already proven safe at 6+:1) until worst-case contrast clears
4.5:1 with margin -- keeps each theme's faint token in its existing hue
family rather than picking an arbitrary new color, and stays visually
distinct from --bone-dim (1.3-1.8:1 apart). Applied identically to
docs/the-fleet/index.html and docs/the-fleet/night-two/index.html.

Re-measured directly against the edited source (regex-parsed the actual
--ground/--bone-faint/--gold/--orn-opacity values out of each theme block,
not hand-copied numbers):

  theme      old bone-faint  new bone-faint   worst-case now
  arabic     #7d7f9c         #8688a3          4.77:1
  indian     #96806a         #a0886f          4.75:1
  andalus    #8d8267         #a3967a          4.77:1
  terminal   #4f6654         #6e8772          4.76:1

All four now clear WCAG AA (4.5:1) by the color math alone -- the halo is a
bonus, not load-bearing. Also checked the new values against --ground-2 (the
card context .role .spoke / .chan h3 span also use): 4.42-4.87:1, likewise
an improvement over the old values (3.03-4.35:1) in every theme.

docs/architecture/index.html needs no change: its equivalent faint token
(--ink-soft) is numerically identical to the-fleet's --bone-dim in all four
themes (confirmed by diffing the values), not --bone-faint -- already
measured safe at 6.08-8.49:1 in the original fix. There's no third,
fainter tier exposed to the pattern on that page.

🤖 Generated with Claude Code

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
@testtest126

Copy link
Copy Markdown
Owner Author

Follow-up pushed @ e633434 — this voids any prior CI/review state seen at the old head (a3f29eb).

What changed: the Assayer's independent review caught that --bone-faint (used in .sig/footer/.inc .refs) was clearing WCAG AA only via the text-shadow halo, not on color math alone — flagged terminal at ~2.98:1. Re-measuring myself found all four fixed themes were actually short on raw color math (arabic 4.24:1, indian 4.25:1, andalus 3.66:1, terminal 2.98:1), not just terminal.

Fix: lifted --bone-faint per theme (blended toward each theme's own --bone-dim, already proven safe, rather than picking arbitrary new colors) until worst-case contrast clears 4.5:1 with margin. Re-verified by parsing the actual edited source values, not hand-copied numbers:

theme old new worst-case now
arabic #7d7f9c #8688a3 4.77:1
indian #96806a #a0886f 4.75:1
andalus #8d8267 #a3967a 4.77:1
terminal #4f6654 #6e8772 4.76:1

All four clear AA on the color math alone now — halo is a bonus, not load-bearing. Applied to docs/the-fleet/index.html and docs/the-fleet/night-two/index.html only; docs/architecture/index.html needs no change since its equivalent token (--ink-soft) is numerically identical to the-fleet's --bone-dim (already safe at 6.08–8.49:1), not --bone-faint — no third faint tier is exposed to the pattern there.

Still docs-only, still not security-sensitive, still doesn't touch #116 or #185. No orchestrator-approval posted.

@testtest126
testtest126 merged commit c55b80c into main Jul 18, 2026
7 checks passed
@testtest126
testtest126 deleted the fix/fleet-theme-legibility branch July 18, 2026 20:23
testtest126 added a commit that referenced this pull request Jul 18, 2026
…#195)

* Docs: add "A Second Reader" — the fleet's first note on multi-model onboarding

A short new chapter on docs/the-fleet/night-three/, opening honestly on the
smallest true fact available: a Codex-based agent has left a git ref inside
the agent-ready checkout while reading its conventions — no commit, no PR,
nothing merged. Frames CLAUDE.md as this fleet's dialect and AGENTS.md as the
model-agnostic constitution that made that reader possible, and adds one law
to the running constitution. Reuses the-fleet's existing cultural theme
switcher verbatim (same 7 keys, same localStorage["mm-theme"]). night-two
gains a forward link to the new chapter.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Docs: add "The Door That Held Too Well" — night-four of the fleet story

docs/the-fleet/night-four/ narrates this week's real payoff to night-three's
opening: a second-vendor (Codex-based) agent, asked to land a finished green
PR, refused to bypass branch protection — the same rule a Claude worker would
have obeyed, holding on first contact with a different model. The required
orchestrator-approval status then had no automation left to post it, so the
PR sat green-but-blocked for two days: a gate built to keep merges deliberate
had, for a while, no one available to open it. One new incident-ledger entry
records the lesson ("a required check with no one to sign it is not a gate,
it's a wall"), and the closing section notes, honestly, that this very PR is
itself still waiting behind the same door as you read it.

night-three gains a forward nav link to this chapter. Reuses the existing
theme engine verbatim (same 7 keys, same localStorage["mm-theme"]) — verified
structurally identical to night-three's already-tested engine (title-only
diff in the head/style/svg/switcher block, whitespace-only diff in the script
tail) and HTML tag-balance checked.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Docs: add "Who Verifies the Verifier" — night five of the fleet story

The fleet's fourth chapter, following night four ("The Door That Held Too
Well"). Grounded in what actually happened today:

- The fleet chartered a fourth role, the Assayer (docs/the-fleet/
  THE-ASSAYER.md, PR #192) -- an independent verifier that tests claims
  against evidence, never produces the work it judges, and voids its own
  verdict if it can't attach reproducible evidence.
- Its first live run: it independently re-derived a worker's claim about
  agent-ready's code_coverage gate and confirmed it -- catching along the
  way that one cited "quote" was actually a paraphrase, not verbatim.
- The same day, it was turned on the orchestrator's own legibility fix
  (PR #191) and found a real gap: --bone-faint was still failing WCAG AA
  in the terminal theme, propped up only by an unmeasured halo. Re-checked
  further, the gap was wider than first flagged -- all four fixed themes
  were short on the color math alone. That fix is what actually shipped
  as the hardening commit on #191.
- The turn: a verifier that catches the people who built it, on its first
  outing, forces the obvious question about itself. The owner asked it
  and answered it in the same breath -- "I will." -- which is the charter's
  keeper clause (docs/the-fleet/THE-ASSAYER.md) in one sentence, and the
  exact fix night four's law asked for: a gate with teeth, and a keeper
  who actually holds the key.

Matches the established chapters' voice, structure, and HTML/CSS exactly
(copied night-four's template verbatim, edited content only) -- hero,
6-stat manifest, ledger with two .inc entries, a .callout for the emotional
turn (mirroring night-two's use of the same component), standdown close,
sig line. Wired into the existing prev/next footer chain: night-four now
forward-links here, this page back-links to night-four.

Note for whoever reviews this: this branch stacks on the still-unmerged
docs/fleet-agents-md-chapter (PR #190, night-three + night-four) since
this chapter's footer chain and voice-matching genuinely depend on that
content existing. It also cross-links to docs/the-fleet/THE-ASSAYER.md
from the still-open PR #192 -- that link won't resolve until #192 merges,
same honest-forward-reference pattern night four already used for its own
unmerged state. Sequencing: #190, then this, then (independently) #192.

I also noticed a likely off-by-one in night-three's constitution numbering
(`counter-reset: law 6` renders its new law as VII, not VI, skipping a
numeral) while reading that file for reference -- flagging it, not fixing
it, since it's PR #190's content and out of scope here.

🤖 Generated with Claude Code

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
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