From 378705dd7354facc851757522f01536fcea767af Mon Sep 17 00:00:00 2001 From: simoleo89 Date: Fri, 17 Jul 2026 17:53:15 +0200 Subject: [PATCH] Add admin UX cleanup Phase 1 design spec. Co-authored-by: Cursor --- .../2026-07-17-admin-ux-cleanup-design.md | 155 ++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-17-admin-ux-cleanup-design.md diff --git a/docs/superpowers/specs/2026-07-17-admin-ux-cleanup-design.md b/docs/superpowers/specs/2026-07-17-admin-ux-cleanup-design.md new file mode 100644 index 00000000..ea5b7756 --- /dev/null +++ b/docs/superpowers/specs/2026-07-17-admin-ux-cleanup-design.md @@ -0,0 +1,155 @@ +# Admin UX Cleanup — Design Spec + +**Date:** 2026-07-17 +**Status:** Approved in chat (Phase 1); Phases 2–3 queued after Phase 1 ships +**Scope:** Admin panel (`/admin/*`) — EpicNext-cms + +## Context + +The admin already has hub chrome (`AdminHubChrome` + `AdminPageShell` + `AdminSectionTabs`), a condensed sidebar, theme/language switchers, and ACL. Remaining pain is inconsistency: double headers, orphan routes, duplicated chrome controls, crowded Radio tabs, and identical icons for Access vs Moderation. + +This document covers a **three-phase** program. **Only Phase 1 is in scope for the next implementation plan.** + +--- + +## Goals + +1. One clear page hierarchy under each hub (no stacked titles). +2. Every useful admin route reachable from hub tabs (no orphan pages). +3. Theme/language controls in one primary place (no desktop duplicate). +4. Radio hub usable on smaller widths without losing URLs. +5. Access vs Moderation visually distinct in the sidebar. + +## Non-goals (Phase 1) + +- Full admin i18n (Phase 2). +- Full design-token / shadcn unification (Phase 3). +- New features, new pages, or permission model changes. +- Changing public-site chrome or avatar/imager behavior. + +--- + +## Phase 1 — UX cleanup + +### 1.1 Single hub header + +**Current:** `AdminHubChrome` renders hub `title` + `subtitle` + tabs; many child pages also render `h1` / intro copy (often `text-3xl font-bold`), producing double titles. + +**Rule:** + +| Page type | Hub shell title | Page-level `h1` | +|-----------|-----------------|-----------------| +| Hub list / overview (matches a hub tab) | Keep | Remove (or demote to section heading if needed for a11y only when content blocks require it) | +| Nested create / edit / show (`…/new`, `…/[id]`, `…/create`, `…/show/[id]`) | Keep hub title | Keep entity-specific title (e.g. poll name, “Create Event”) | +| Dashboard `/admin` (no hub) | N/A | Keep its own header | + +**Implementation approach:** + +- Prefer removing redundant page chrome blocks (icon + `h1` + muted description that duplicates hub subtitle). +- Keep action rows (Create buttons, filters, search) that sit next to the old `h1`; restructure to a toolbar without a second page title. +- Do not strip semantic headings inside content cards/tables. + +**Acceptance:** Opening any hub tab shows exactly one primary title (from `AdminPageShell`). Detail pages still show the entity/create title below the hub chrome. + +### 1.2 Wire orphan routes into hub tabs + +Add tabs (English labels for Phase 1; i18n keys in Phase 2): + +| Hub | New / adjusted tabs | Hrefs | +|-----|---------------------|-------| +| **Users** | Multi-accounts | `/admin/users/multi-accounts` | +| **Engagement** | Event types, Templates | `/admin/events/types`, `/admin/tickets/templates` | +| **Observability** | Chat, Commands, Trades | `/admin/logs/chat`, `/admin/logs/commands`, `/admin/logs/trades` | +| **Observability** | Activity, Economy (under analytics) | `/admin/analytics/activity`, `/admin/analytics/economy` | +| **Observability** | Errors (under devops) | `/admin/devops/errors` | + +**Tab matching notes:** + +- Users “Directory” must keep `match` that includes `/admin/users` but **not** steal active state from `/admin/users/multi-accounts` (exact / longest-prefix matching already in `AdminSectionTabs` — verify Directory `match` does not list multi-accounts; multi-accounts gets its own tab with `href` only or explicit `match`). +- Logs “Logs” tab (`/admin/logs`) must not stay active on `/admin/logs/chat` etc. Prefer exact match for the main Logs index, or give sub-log tabs longer prefixes so they win (existing scorer prefers longer / exact — verify). +- Analytics “Analytics” vs Activity/Economy: same longest-match rule. +- Engagement Event types: `/admin/events/types` must win over Events `match: ["/admin/events"]` — longest prefix already favors `/admin/events/types` if that tab is listed. + +**Acceptance:** Every orphan page above is one click from its hub tab strip. No new routes required. + +### 1.3 Theme / language control placement + +**Decision:** Primary controls stay in the **sidebar** (desktop). **Topbar** keeps theme + language only on **mobile** (when the sidebar is not persistently visible), or remove from topbar entirely if `AdminMobileWrapper` already exposes sidebar controls on mobile. + +**Preferred behavior:** + +- Desktop (`lg+`): switchers **only in sidebar** header row; remove from `Topbar`. +- Mobile: switchers remain reachable via the mobile sidebar drawer (already present). If the drawer is hard to discover, keep a compact pair in the topbar **only below `lg`**. + +**Acceptance:** On desktop, theme/language appear once. Mobile users can still change theme and locale without hunting. + +### 1.4 Radio hub tab grouping + +URLs unchanged. UI presents two rows (or a primary row + overflow “More” row): + +**Primary:** Overview, History, Moderation, Monitoring, Settings + +**Tools:** Banners, Embed, API keys, Points, Ranks, Auto DJ + +**Implementation options (pick one in plan):** + +- **A (recommended):** Extend `AdminSectionTabs` / hub definition with optional `group?: "primary" | "tools"` and render two labeled rows for Radio only. +- **B:** Nested “Tools” dropdown tab — less discoverable; avoid unless row A overflows badly. + +**Acceptance:** Radio remains fully linked; primary ops are visible without horizontal scroll on a typical laptop width (~1280px). + +### 1.5 Distinct Access vs Moderation icons + +- **Access & security** sidebar: keep `Ban` (or `Shield`) — already distinct from Users. +- **Moderation** sidebar: change from `Shield` to something like `Gavel` or `ShieldAlert` so it does not match Access. + +Hub definition icons for Access vs Moderation should also differ if both appear in chrome. + +**Acceptance:** Sidebar icons for Access and Moderation are not the same glyph. + +--- + +## Phase 2 — Admin i18n (queued) + +- Move hub `title` / `subtitle` / tab `label` to `labelKey` + `pages.admin.hubs.*` (and tab keys). +- Translate high-traffic pages: Users, Events, Logs, Settings, Moderation. +- i18n theme switcher aria/title strings for `variant="admin"`. +- Do not block Phase 1 on this; Phase 1 may leave English hub strings as today. + +## Phase 3 — Design system (queued) + +- Standardize list pages on `--admin-*` tokens (`admin-card`, shared empty state, table chrome). +- Optional shared `AdminListToolbar` for actions formerly next to removed `h1`s. +- Gradual migration; no big-bang rewrite of catalog/user detail. + +--- + +## Risks & mitigations + +| Risk | Mitigation | +|------|------------| +| Removing `h1` hurts accessibility | Hub shell already exposes one `h1`; detail pages keep entity `h1`. Spot-check with one screen reader pass on Users + Events. | +| Tab active-state regressions | Add/adjust `match` arrays; manually verify Directory vs Multi-accounts, Logs vs Chat. | +| Radio two-row tabs feel heavy | Only Radio uses groups; other hubs stay single row. | +| Mobile loses theme/lang | Keep switchers in sidebar drawer; optional `lg:hidden` topbar pair. | + +## Out of scope leftovers + +- Calendar under Shop hub (IA smell) — defer unless requested. +- Legacy user route folder split (`show/[id]` vs `[id]`) — defer. +- Avatar `/imaging` proxy — separate track. + +## Success criteria (Phase 1) + +1. No double hub+page title on representative pages: Articles, Users directory, Events list, Logs index, Radio overview. +2. Orphan routes listed above reachable from tabs. +3. Desktop: single theme/language control location. +4. Radio primary tabs visible without scrolling on 1280px width. +5. Moderation and Access icons differ. + +--- + +## Approval + +- Phase 1 approach approved in conversation (2026-07-17). +- Implementation proceeds via a Phase-1 plan under `docs/superpowers/plans/`.