Phase F11: Design System Overhaul + UX Redesign

phase-pal-e-docs-design-overhaul Phase

phase

Project

Goal: Replace the AI-generated aesthetic with a distinctive, professional design system that prioritizes the "what are my latest projects / what changed recently" user story. Kill the AI slop.

Owner: Dev agent (code), Betty Sue (design direction + QA coordination)

Repo: forgejo_admin/pal-e-app

Depends on: F5 (auth), F6 (private notes), F8 (editing), F9 (board CRUD) — all COMPLETED

Context

The current pal-e-app aesthetic was built fast by dev agents and hits every AI slop anti-pattern: cyan-on-dark, pink neon accents on near-black, identical card grids, system fonts, centered everything, no design token system. The color palette (#e94560 accent, #0a0a14 background, #55efc4/#00cec9 type badges) is the textbook AI color palette warned against by the frontend-design guidelines.

The home page shows all 10 projects alphabetically — it doesn't answer the primary user question: "What are my latest projects? What changed? What needs attention?"

Current technical state: Tailwind 4.1, zero CSS custom properties, all colors hardcoded as arbitrary Tailwind values (bg-[#0e0e18]), no font imports, no type scale.

Design Direction

Aesthetic: Editorial / Command Center. Not a generic SaaS dashboard. Not a dark-mode dev tool. A well-typeset intelligence briefing — clean, scannable, information-dense but not cluttered. Every pixel earns its place.

Light mode primary (dark mode secondary) — dark mode is lazy; light mode forces real design decisions
Real typography — distinctive heading font + clean body font. Not Inter, not Roboto, not system defaults.
Warm neutrals — stone/slate/warm grays, not blue-tinted near-black
One accent color — not a rainbow of type badges. Typography-driven hierarchy.
Activity-first home page — "Recently updated," "In progress," "Needs attention" — not alphabetical dumps
Left-aligned, asymmetric layout — break the centered-everything pattern
Progressive disclosure — the home page is a briefing, not a directory

Scope

F11a: Design Token System + Color Palette (COMPLETED — PR #35)

Create CSS custom properties in app.css for all design tokens (colors, spacing, typography, radii)
Replace ALL hardcoded hex values (bg-[#0e0e18]) with token references
Choose a professional color palette — warm neutrals, one strong accent
Support light mode (primary) and dark mode (secondary) via prefers-color-scheme or toggle
Tint neutrals toward brand hue for cohesion
Note type colors: simplify from 16 distinct colors to a restrained system (3-4 hues max with shade variations)

F11b: Typography + Font Loading (COMPLETED — PR #35)

Select and import distinctive fonts: display/heading + body pair
Implement modular type scale with clamp() for fluid sizing
Font loading strategy: font-display: swap, preload critical fonts
Vary weights and sizes to create clear visual hierarchy without relying on color

F11c: Home Page Redesign — "What Are My Latest Projects?" (COMPLETED — PR #37, Issue #36)

Activity-first layout: recently updated notes/projects at top
In-progress board items section — what's actively being worked on across all projects
Project cards with last-updated timestamps and activity indicators
Board summary with progress bars (backlog/in-progress/done ratios)
Kill the alphabetical project dump and full tag wall
Prototype approved in html-playground/6-pal-e-home before port

F11d: Navigation Rethink

Streamline nav: Primary (Home/Activity, Projects, Search) vs Secondary (Notes, Tags, Repos)
Consider sidebar navigation vs top bar
Mobile-responsive hamburger menu
Keyboard shortcuts (existing / for search is good — extend)
Breadcrumb improvements for note navigation
Gamification elements: progress indicators on project links, notification badges

F11e: Search + Discovery UX

URL-driven search (?q= param should work on notes page)
Search results with better context (snippet, project, type, date)
Filter persistence across navigation
Consider semantic search toggle (backend already supports it)

F11f: Private Notes + Auth UX Polish

Lock icon visibility audit — current h-3 w-3 text-gray-600 is too subtle on dark backgrounds
Signin page design — not Auth.js default
Signout confirmation or redirect behavior
Role display in nav (not just username)

F11g: Component Library Polish

Cards: break the identical grid pattern. Vary sizes by importance/type.
Badges: typography-driven, not rainbow colored
Buttons: clear primary/secondary/ghost hierarchy
Tables: readable in light mode
Code blocks: proper syntax highlighting theme
Empty states: teach the interface, not just "nothing here"

Investigation Required

Does the pal-e-docs API support ?sort=updated_at or similar for activity-first queries? — YES, default sort is updated_at DESC, limit/offset params added in PR #181
Can we add updated_at to the notes list response for "recently updated" sorting? — YES, already in NoteSummary schema
What data does the DORA dashboard already expose that could feed gamification?
Playground-first approach: should design experiments happen in html-playground before pal-e-app? — YES, SOP created: sop-frontend-experiment

Acceptance Criteria

Zero hardcoded hex values in component code — all via CSS custom properties
Home page answers "what changed recently?" within 2 seconds of loading
Passes the AI Slop Test: if someone saw it, they wouldn't immediately say "AI made this"
Lock icons visible and tested for private notes
Search works via URL params
Light mode looks professional; dark mode looks intentional (not the default)
Lighthouse accessibility score >= 90

QA Nits (deferred from PR #37)

Negative relativeTime handling for future dates
Implicit boardProgress return type — add explicit TS type
Asymmetric in-progress test assertion

plan-pal-e-docs — parent plan
phase-pal-e-docs-validation-hardening — F10 (predecessor — design audit started there)
phase-pal-e-docs-frontend-auth — F5 (auth foundation)
phase-pal-e-docs-private-notes — F6 (private notes foundation)
convention-frontend-css — CSS custom property rules
sop-frontend-experiment — prototype-first workflow