docs: split README into showcase + user/setup guide - #148
Merged
Conversation
Follow-up to b38e575, closing the gaps a two-axis review found against the issue's acceptance criteria. The swatch lied about non-hex colours. `<input type="color">` coerces anything it can't parse to #000000, so a `rebeccapurple` widget rendered a black swatch beside a purple canvas cell — and left an accidental confirm one click from clobbering the authored CSS string. Values the picker can't hold (named colours, `hsl(...)`, `#RRGGBBAA`) now show as a read-only preview of the real colour, with the text input as the escape hatch the any-CSS-string schema needs. `#RGB` shorthand expands rather than falling into that bucket, since the picker can represent it losslessly; an unset widget still gets the picker, which is the main way into it. A hand-authored `color:` on a non-button kind was stranded: ADR-0006 keeps the field button-only, but EditorCanvas still paints it, so the value was invisible to the panel and unclearable. The field now also appears on any kind that already carries a colour. AC4 (save round-trips the colour unchanged) had no test. Adds write-path coverage over hex, named and `hsl(...)` values — the hex case also pins that the writer quotes a leading `#` rather than emitting a YAML comment — plus the clear-to-unset case. Also: give the text input an accessible name (it had none, which is why the tests had reached for CSS-class selectors), drop a pass-through callback, rename `parseHexColor` to `toSwatchHex` since it formats rather than parses, fold the duplicated focus rule into the file's `:focus-visible` convention, and document the picker in the README. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The README had grown to ~1330 lines, mostly setup, per-platform install, configuration reference, and per-feature deep-dives. Move all of that into a new docs/GUIDE.md so the README is a ~180-line showcase (pitch, screenshots, status, comparison, architecture diagram, quick start, docs index). - README.md: trimmed to showcase; keeps the ASCII architecture diagram as the hero; in-page links to moved sections now point into docs/GUIDE.md. - docs/GUIDE.md: new — install/run, macOS + KDE + X11 setup, phone/tablet pairing, design tooling, PWA-over-Tailscale, client features, uinput/focus watcher, dev UX, production, full configuration reference, media surfaces. Relative file links fixed for the docs/ location (packaging/ -> ../packaging/). - Dedup: GUIDE's CLI and "Under the hood" sections collapsed to explicit pointers at the canonical REFERENCE.md / ARCHITECTURE.md sources. - Reverse links: REFERENCE.md, ARCHITECTURE.md, ONBOARDING.md now list GUIDE.md and describe the README as showcase-only. Co-Authored-By: Claude Opus 4.8 <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.
Why
The README had grown to ~1330 lines — mostly setup, per-platform install, configuration reference, and per-feature deep-dives (Now Playing alone was ~270 lines). That buried the showcase. This splits it so the README is a ~180-line showcase and everything technical lives in one guide.
What changed
README.md— trimmed to showcase (pitch, screenshots, status, comparison, architecture diagram, quick start, docs index). Keeps the ASCII architecture diagram as the hero. In-page links to moved sections now point intodocs/GUIDE.md.docs/GUIDE.md(new) — install/run, macOS + KDE Plasma Wayland + X11 setup, phone/tablet pairing, design tooling, PWA-over-Tailscale, client features (manual control, editor, tuning, a11y), uinput/focus watcher, dev UX, production, full configuration reference, and the media surfaces (VLC, Now Playing, running programs). Relative file links fixed for thedocs/location (packaging/→../packaging/).CLIandUnder the hoodsections collapse to explicit pointers at the canonicalREFERENCE.md/ARCHITECTURE.mdsources instead of restating them.REFERENCE.md,ARCHITECTURE.md, andONBOARDING.mdnow listGUIDE.mdand describe the README as showcase-only.Verification
#anchorverified to resolve.docs/GUIDE.md1181 lines.🤖 Generated with Claude Code