Skip to content

Record the appearance switch as a component, not just a mechanism - #23

Merged
Babissimo merged 1 commit into
mainfrom
docs/brand-theme-control
Sep 15, 2026
Merged

Babissimo merged 1 commit into
mainfrom
docs/brand-theme-control

Conversation

@Babissimo

Copy link
Copy Markdown
Contributor

Stacked on #22, which documents the palette pair and the three-versus-two-state
divergence. This adds the part that was still missing: the control itself.

§3 described what the theme switch does to a surface and never described the
thing a person clicks. Read cold, the guide told you which half of the palette
you would get and left the control to be invented per surface. That is exactly
what happened: Tower Finder grew a two-state chip of its own before anyone
noticed dash already had a three-state radiogroup
(offworldlabs/tower-finder-service#35).

So §6 gains an entry for .theme-switch, and tokens.css gains its rules.

The styling is the easy half and not the point. Six declarations. What is
worth writing down is the markup contract underneath: the buttons hold a glyph
and no text, so without an aria-label and a matching title a screen reader
meets three unlabelled radios; and choosing role="radio" over three toggle
buttons obliges the radiogroup keyboard behaviour, one tab stop with the arrows
moving selection and focus together. Both are invisible in a screenshot and
neither survives being copied by eye, so both sit beside the CSS rather than
inside it.

Also recorded:

  • The switch wants a surface under it, not a canvas. Its ground is the sunk
    tier, and on the light half of these surfaces that is the canvas value (§3), so
    one dropped straight onto a page reads as three loose glyphs with only its
    hairline bounding it.
  • The map's control is a different object and predates the others: a
    role="menuitem" button in the toolbar overflow menu, two states, none of the
    radiogroup behaviour. §10's divergence bullet now says the controls differ as
    much as the behaviour does.
  • Tower Finder, as a fourth surface running the pair from outside
    retina-server. Deliberately with no column in the tables and no voice in §1:
    it is dash's look on another host, and a seventh column would imply a seventh
    personality it does not have.

No change to any palette value.

🤖 Generated with Claude Code

…mechanism

§3 described what the theme switch does to a surface and never described the
control. Read cold, the guide told you which half of the palette you would get
and left the thing a person clicks to be invented per surface — which is what
happened: tower-finder grew a two-state chip of its own before anyone noticed
dash already had a three-state radiogroup.

So §6 gains an entry for `.theme-switch`, and tokens.css gains its rules. The
part worth writing down is not the styling, which is six declarations: it is the
markup contract underneath it. The buttons hold a glyph and no text, so without
an aria-label and a matching title a screen reader meets three unlabelled
radios; and choosing role="radio" over three toggle buttons obliges the
radiogroup keyboard behaviour, one tab stop with the arrows moving selection and
focus together. Both are invisible in a screenshot and neither survives being
copied by eye, so both sit beside the CSS rather than in it.

Also recorded: the switch needs a surface under it rather than a canvas, since
its ground is the sunk tier and on the light half of these surfaces that is the
canvas value; and Tower Finder, which runs the pair and the control from outside
retina-server. It gets no column in the tables and no voice in §1 on purpose —
it is dash's look on another host, and a seventh column would imply a seventh
personality it does not have.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@Babissimo
Babissimo changed the base branch from docs/brand-six-surfaces to main September 15, 2026 14:17
@Babissimo
Babissimo force-pushed the docs/brand-theme-control branch from 31ecb15 to eacfd1c Compare September 15, 2026 14:17
@Babissimo
Babissimo merged commit a1bb1d0 into main Sep 15, 2026
2 checks passed
@Babissimo
Babissimo deleted the docs/brand-theme-control branch September 15, 2026 14:19
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