Skip to content

docs(brand): describe the map as a themed surface on dash's system - #21

Merged
Babissimo merged 3 commits into
mainfrom
docs/map-theme-brand-guide
Sep 10, 2026
Merged

Babissimo merged 3 commits into
mainfrom
docs/map-theme-brand-guide

Conversation

@Babissimo

@Babissimo Babissimo commented Sep 10, 2026

Copy link
Copy Markdown
Contributor

map.retina.fm has been restyled on dash.retina.fm's design system, and the brand guide still described the surface that replaced. This brings docs/brand/brand-guide.md and docs/brand/tokens.css back in step with it.

Land this after the retina-server stack

The map's restyle is a four-PR stack, open and unmerged at the time of writing:

Everything here is written against the tip of that stack. It should not merge before the stack does, or the guide will describe a surface that is not yet live. If the stack changes shape in review, this needs re-reading against what actually lands.

What changed in the guide

The map is no longer dark-only, no longer without custom properties, and no longer without focus or reduced-motion handling, so every blanket claim resting on those has been narrowed to the surfaces it still describes rather than rewritten as a before-and-after.

  • §1, §2, §3 record the map as themed: dark is the default and unchanged, light is opt-in and takes dash's values. The mechanism is recorded once, in §3, because it is the transferable part: the base selector carries dark and the attribute carries light, so the default cannot flash the other theme before first paint.
  • §3 gains the reason the map needs a sunk tier that the light surfaces do without, a Tint (hover) row for --accent-tint, and a corrected border value (.12 to .14, drifted when the hardcoded hex was consolidated into tokens).
  • §3 and §8: the data palette was rechosen by measurement, against a contrast floor and a CIEDE2000 separation between marks. Truth now wears no hue in either theme, so the old teal/cyan description was not merely stale but contradicted the surface.
  • §5, §6, §10 drop the map from the no-prefers-reduced-motion and no-:focus-visible gaps, and the shared-control and token-drift bullets narrow to dash. The map and dash are now the only pair in the estate sharing a vocabulary.
  • §6's map entries went stale wholesale: the gradient header, the two ad-hoc search boxes, the near-invisible empty state, the backdrop-blurred panels and the unstyled Leaflet controls are each now one thing rather than several.

tokens.css gains --accent-tint and a .map[data-theme=\"light\"] block. The attribute variant mirrors the live selector exactly and stays keyed on .map, so it fits the one-class-per-surface structure rather than fighting it. --data-adsb is dropped: the ground-truth dot and truth are one colour now, and the pair is replaced by --data-truth / --data-truth-dark.

Two things worth flagging

preview.html carried two captions this PR deletes from the guide. It annotated the map with "Two search boxes, one job", a defect the map stack fixed by giving the surface one form-control rule in its token layer, and led with "the dark operational picture" when dark is now the default rather than the whole surface. Both are rewritten.

No light-theme section was added. It would be dash's values rendered a second time, since the map's light theme takes them wholesale. The two console tags now say which mode each one is, and the guide carries the pairing in full.

§5's radius numbers are now recorded. The map's radius scale is dash's: 8px default, 4px small, 12px large. It reached the guide late because the three geometry tokens were briefly declared only inside the light-theme block, so the default theme rendered none of them; that is fixed on feat/map-4-theme and verified in the built bundle.

Conflict risk

Low, now. The worktree-docs+owl-os-brand-surface work merged as #20 before this branch was cut, so this is based on a main that already contains the owl-os column and the expanded §6. It was that expansion that put most of the stale map claims in §6 here in the first place.

🤖 Generated with Claude Code

Babissimo and others added 3 commits September 10, 2026 16:13
The guide is a description to build against, so it is wrong the moment the
surface moves. map.retina.fm has been restyled on dash.retina.fm's design
system in offworldlabs/retina-server#343, #345, #346 and #347, and the guide
still described the surface those PRs replaced: dark-only, no custom
properties, no focus treatment, no reduced-motion guard, and a teal/cyan
truth colour that no longer exists.

The substantive changes on the map, and so here:

- It themes. Dark stays the default and is unchanged; light is opt-in and
  takes dash's values. The base selector carries dark and the attribute
  carries light, so the default cannot flash the other theme before first
  paint, and that is the part worth copying rather than the values.
- It has a full custom-property layer under dash's names, which makes the two
  consoles the only pair in the estate that share a vocabulary. §10's naming
  drift and shared-control bullets narrow to dash accordingly.
- The data palette was rechosen by measurement, against a contrast floor and
  a CIEDE2000 separation between marks. Truth now wears no hue in either
  theme, which the old teal/cyan description in §3, §8 and tokens.css
  contradicted outright.
- Focus and reduced motion are now handled on the map, so the blanket
  "none of the surfaces" claims in §5 and §10 are narrowed to the surfaces
  they still describe. owl's /learn page already carried a reduced-motion
  guard, so that claim was too broad before this change as well.

§6's map entries went stale along with the rest: the gradient header, the two
ad-hoc search boxes, the near-invisible empty state, the backdrop-blurred
panels and the unstyled Leaflet controls are all now one thing rather than
several. Recorded as they stand, not as a before-and-after.

tokens.css gains --accent-tint and a .map[data-theme="light"] block mirroring
the live selector, and drops --data-adsb, which no longer names anything: the
ground-truth dot and truth are one colour now.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The map's three geometry tokens were declared only inside its light-theme
block, so the default theme rendered none of them and 8px/4px was the intent
rather than the result. That is fixed in the map stack, so the scale can be
stated: the map takes dash's, 8 / 4 / 12, rather than the 6 / 3 / 10 it had
before the restyle.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The preview annotated the map with "Two search boxes, one job", a defect the
map stack removed by giving the surface one form-control rule in its token
layer, and led with "the dark operational picture" when dark is now the
default rather than the whole surface.

Rather than add a second map section for the light theme, which would be
dash's values rendered twice, the two console tags now say which mode each
one is. The guide already records that the map's light theme takes dash's
values wholesale, so the preview points at the pairing instead of restating
it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@Babissimo
Babissimo merged commit 1cc3dc9 into main Sep 10, 2026
1 of 2 checks passed
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