docs(brand): capture owl-os as the fifth surface, and the control layer across all five - #20
Merged
Merged
Conversation
The brand guide described four surfaces and missed the one an actual customer touches most: the web UI served off the node itself, at owl.local. It is easy to overlook because the repository boundary hides it. The UI is authored in retina-gui, but it is owl-os that clones it at a pinned tag into the SD-card image and brands it OWL-OS, so an audit that starts from owl-os finds Ansible and no CSS, and concludes there is nothing to capture. There is a good deal to capture. owl-os is the only surface authored in OKLCH, the only one with a real elevation scale, the only one on a CSS framework, and the only one that defines no keyframes at all. It is also the only place in the estate where anything checks prefers-reduced-motion before it animates, which corrects a claim §5 made about all four of the others. Read from retina-gui main rather than the pinned tag, since the guide records how the surfaces look rather than what a given image shipped; §10 records the gap so nobody assumes a field node has a component described here. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…surfaces §6 was a nine-bullet sketch that mostly described the two marketing sites and then generalised. Audited against the source of all five surfaces, three of its entries were wrong rather than merely thin: dash has a 250px sidebar, not the fixed top bar with a hamburger; dash's card grids use a real 16px gap, not the 1px-gap-over-a-tinted-ground trick that is retina's; and the "badges are a 12px tinted pill with a dot" line describes one surface's take on a component that exists in at least seven shapes. Restructured around control families rather than a flat list, because the useful question turned out to be which surfaces have a given control at all. The answer is lopsided: owl and retina have no form controls, no tables and no :focus rule between them, so the entire control story belongs to dash, map and owl-os, and only owl-os defines an input, a select and a switch once and reuses them. Four findings that look like defects rather than divergence are recorded in §10: dash colours its error banners with an undefined custom property and so always renders a red found nowhere else; owl-os's calibration spinner carries a Bootstrap class its override block misses, so it renders Bootstrap blue; dash's sidebar vanishes under 768px with nothing in its place; and dash confirms destructive actions with window.confirm(). Recorded, not filed, in keeping with the section's remit. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The components §6 now documents were prose only: preview.html still showed a button, a card, fact rows and swatches, which is what it showed before any of the control work. Adds a controls block to all five columns covering the things that were missing, a text field with its help line, an invalid field with its error, a select, a switch and a segmented control. owl and retina ship no form controls at all, so their columns label the block as tokens-only rather than pretending otherwise. Rendering it in all five is still worth it: the point of this page is that one set of markup, driven only by the surface class, should come out looking like each surface. Building it surfaced something the audit could not. The raised-pill segmented control reads from the step between --surface and --canvas-sunk, and those two sit within 1.2:1 on owl, retina, dash and map: only owl-os separates them, with a shadow scale the other four do not have. The pill was invisible on four columns until it got a token-driven hairline. Recorded in §6 and §10, since it generalises to any component that works by raising one layer above another. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds owl-os (the node's own web UI, at
owl.local) to the brand guide as a fifth surface, then deepens §6 from a nine-bullet sketch into a survey of the component and control layer across all five.Three commits, each readable on its own:
docs(brand): capture owl-os as the fifth surface— a sixth column in every table, an.owl-osblock intokens.css, a fifth panel inpreview.html.docs(brand): capture the component and control layer across all five surfaces— §6 restructured around control families.docs(brand): render the control layer in preview.html— the controls block, so the page shows what §6 describes.Why owl-os was missed
The repository boundary hides it. The UI is authored in
retina-guibut shipped byowl-os, which clones it at a pinned tag into the SD-card image and brands itOWL-OS. An audit starting from owl-os finds Ansible and no CSS.retnode.comis the same app on the same port, so there was nothing separate to capture there either; §Intro now records both facts.Style is read from retina-gui
main, not the pinned tag, since the guide records how the surfaces look rather than what a given image shipped. §10 records the gap.Corrections, not just additions
Auditing all five against source found three §6 entries that were wrong:
§5's claim that no surface honours
prefers-reduced-motionis also corrected: owl-os's flight-path simulator does, and is the only thing in the estate that checks.Findings recorded in §10
Recorded, not filed, in keeping with that section's remit:
:focusrule between them. dash's stylesheet has noinput,selectortextareaselector at all, so its controls are inline per call site and have split into three incompatible text-input variants.var(--accent-warning, #c0392b)and never defines--accent-warning, so both always render a red found nowhere else in the palette..text-primary, which its override block misses, so it renders#0d6efdrather than the surface accent.display: noneunder 768px with no replacement, so navigation is unreachable on a phone. Worth confirming against real usage before treating it as intentional.--surfaceand--canvas-sunksit within 1.2:1 on all of them.Verification
preview.htmlwas rendered and checked in a browser, not assumed: all five columns resolve their own tokens, the map inverts correctly, owl-os keeps its OKLCH values through, no console errors. The load-bearing audit claims (no forms and no:focuson the marketing sites, dash's missing selectors and undefined property, the dead-CSS blocks, the map's radius spread) were each verified againstorigin/maindirectly.🤖 Generated with Claude Code