From 77e4b47b0867cfb0352b2ca286a871ab751d0138 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Farca=C8=99?= Date: Sun, 12 Jul 2026 23:50:15 +0300 Subject: [PATCH 01/71] =?UTF-8?q?docs(spec):=20UX=20overhaul=20design=20?= =?UTF-8?q?=E2=80=94=20onboarding,=20auth,=20join,=20channel=20browser,=20?= =?UTF-8?q?cmd-k,=20a11y?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Newcomer-first redesign grounded in a cited competitive study (Slack/Discord/ Teams/Element/Zulip/The Lounge) and the /design mock system. Decomposes the work into 9 workstreams, each closing with a visual+a11y+interaction parity loop. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../2026-07-12-bool-ux-overhaul-design.md | 305 ++++++++++++++++++ 1 file changed, 305 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-12-bool-ux-overhaul-design.md diff --git a/docs/superpowers/specs/2026-07-12-bool-ux-overhaul-design.md b/docs/superpowers/specs/2026-07-12-bool-ux-overhaul-design.md new file mode 100644 index 0000000..e0ba85d --- /dev/null +++ b/docs/superpowers/specs/2026-07-12-bool-ux-overhaul-design.md @@ -0,0 +1,305 @@ +# bool — UX Overhaul Design Spec + +**Date:** 2026-07-12 +**Status:** Draft for approval +**North star:** _the user-friendly IRC client — bringing IRC to everyone._ + +--- + +## 0. Framing + +bool's color/theme system (14 themes, density tokens, swatch cards) is already excellent. The +`/design` study (Directions A/B/C/Shimmer + Cmd-K & Search overlays + 27 reference screenshots) +is a strong, high-fidelity target. **Everything between those two — onboarding, registration, +joining a network, channel browsing, the account menu, and general shell polish — lags far +behind.** This spec closes that gap. + +**Audience:** newcomers first. bool is designed to make IRC approachable for people who have never +used it — the default experience optimizes for that. Longtime IRC users are welcome and well served: +a one-click terminal theme and full keyboard/command depth are there for anyone who wants them. The +distinction is about the *default posture*, not about excluding anyone. + +**Locked product decisions (from brainstorming):** + +| Decision | Choice | +| --------------- | ----------------------------------------------------------------------------------------------------------------- | +| Auth model | First-run admin setup → invite-only afterward | +| Join a server | Curated network **directory + auto-connect**, advanced/custom path behind it | +| Layout language | Direction A "Terminal-Modern" as the component/structure language; all 14 themes swappable | +| Default face | **No single default** — onboarding "pick your vibe" step (Friendly/Aurora · Terminal · Editorial), saved per user | +| Docker | **Single container, embedded SQLite, one volume** → `docker compose up` | +| Verification | Every UI workstream closes with the **Ralph loop**: visual parity + a11y + real interaction | +| v1 scope | 7 core asks + responsive/mobile + empty/loading/error states + shortcut cheatsheet | + +--- + +## 1. Competitive study → design principles + +Derived from a deep-research pass (6 angles, 28 sources, 24 claims verified 3-0 via adversarial +voting). Each principle below is backed by a verified claim; sources cited inline. + +### 1.1 Onboarding + +- **The Lounge's fatal miss (verified):** no in-app first-run admin/registration — the operator + edits a config file. We beat exactly this. +- **Zulip's win (verified):** automated install → **web-based** admin/org creation as discrete + steps. [zulip.readthedocs.io/en/stable/production/install.html] +- **Principle: wizard, never CLI.** The first user never edits a config file. `docker compose up` + → browser → guided `/setup` creates the admin. + +### 1.2 Registration & sign-in + +- **Inline validation on blur**, not only on submit. [nngroup.com/articles/errors-forms-design-guidelines, smashingmagazine.com/2022/09/inline-validation-web-forms-ux] +- **Never signal errors by color alone** — icon + text (WCAG 1.4.1 Use of Color). [nngroup] +- **Error message adjacent to its field**, wired via `aria-describedby`. [reform.app/blog/accessible-form-validation-best-practices] +- Production-grade feel: branded card, single column, real `