diff --git a/docs/brand/brand-guide.md b/docs/brand/brand-guide.md index fe7da0a..e20f7fb 100644 --- a/docs/brand/brand-guide.md +++ b/docs/brand/brand-guide.md @@ -31,6 +31,13 @@ otherwise (§3). The other three are light only. `admin.retina.fm` is dash's own bundle behind a role check rather than a seventh surface, so it themes with it and is not listed separately anywhere below. +**A fourth surface runs the pair from outside `retina-server`.** Tower Finder +(`tower-finder-service/frontend`, the standalone illuminator search) took dash's +palette, token names and appearance switch wholesale rather than growing a look +of its own. It has no column in the tables below, and gets no voice of its own +in §1: it is dash's, on another host. Where §3 and §6 count the themed surfaces +or describe the switch, it is one of them. + owl-os is the odd repository as well as the odd surface. The UI is authored in [`retina-gui`](https://github.com/offworldlabs/retina-gui) but shipped by [`owl-os`](https://github.com/offworldlabs/owl-os), which clones it at a pinned @@ -173,27 +180,33 @@ console's slate ramp (`#94a3b8` / `#64748b` recur), and its hairlines are a blue-tinted translucent white rather than a solid grey. **The map's column above is its dark theme, which is the default there.** These -are not two palettes but one pair, and three surfaces now run it. The map's +are not two palettes but one pair, and four surfaces now run it. The map's light theme takes dash's values almost wholesale (§10 has the one exception), -and dash and data carry the same pair with the halves the other way up. - -**What decides which half you get is not the same question on the two**, and it -is the part most easily got wrong. dash and data **follow the OS**: their -control has three states, and the third, `system`, is the default and the one a -viewer who has never touched the control is on. It stamps no attribute at all +and dash, data and tower-finder carry the same pair with the halves the other +way up. tower-finder is the newest of them and the only one outside +`retina-server`, taking the pair and the control together from dash. + +**What decides which half you get is not the same question on all four**, and +it is the part most easily got wrong. dash, data and tower-finder **follow the +OS**: their control has three states, and the third, `system`, is the default +and the one a viewer who has never touched the control is on. It stamps no attribute at all and lets a `prefers-color-scheme` block answer, so the preference keeps working when the OS changes its mind mid-session — where stamping a resolved value would pin the surface to whatever the OS happened to be at load. The map **never asks the OS**: its control is a boolean, and dark is what a first visit gets on a machine set to light. -What all three do share is the cascade rule. A surface puts on its bare selector +What all four share is the cascade rule. A surface puts on its bare selector the half it must be able to paint before any JavaScript runs, and spends -`data-theme` on the other: dark on the map, light on dash and data. The +`data-theme` on the other: dark on the map, light on the three consoles. The attribute is stamped from JavaScript, so whichever half depends on it is the one -that can flash the other before first paint. On dash and data the media query is +that can flash the other before first paint. On the three the media query is guarded `:not([data-theme="light"])`, which is what lets an explicit light -choice beat a dark OS. Everything on all three is written against the custom +choice beat a dark OS. The cost of the third state is the dark half written +twice, once per selector, since CSS cannot share a declaration block across a +media query boundary; dash and tower-finder each guard the two copies against +drifting with a test rather than with the stylesheet. Everything on all four is +written against the custom properties, so the whole chrome inverts from one block. Two tokens exist because of that sharing. @@ -452,6 +465,7 @@ pattern, check it exists on the surface you are building for. | Icons | 36px, part-filled | Unicode glyphs | 24px, stroke 2 | 15px inline SVG | inline SVG | 24px, stroke 1.6 | | Framework | none | none | none | none | none | Bootstrap 5.3 | | Custom properties | yes | yes | yes, themed | yes, themed | yes, themed | yes | +| Theme control | none | none | `.theme-switch`, 3 states | `.theme-switch`, 3 states | a menu item, 2 states | none | | `:focus` styling | none | none | **none** | inputs | whole surface | inputs only | The two marketing sites have no `