[frontend][design] Production-grade redesign — Figma design system + implementation

[gapilongo]

Problem

The current frontend (frontend/src/, React 18 + Vite + Tailwind + zustand + reactflow) is test-design quality, not production. It exists to prove the backend works end-to-end and to surface audit signals during development — not as the UI an operator would actually want to use on a live engagement.

Specific gaps:

• No design system — colors, spacing, typography are ad-hoc per component
• No brand identity (logo, color scheme, visual voice)
• No dark mode (security tooling convention — operators live in dark themes)
• No mobile / tablet responsive design — desktop-only
• AuditPanel is a JSON dump, not a designed operator surface
• Chat UI doesn't handle technical content well (code blocks, citation tags, verifier rejection banners all render as raw markdown)
• No loading / empty / error states designed — currently bare spinners
• Accessibility is untested (no keyboard navigation audit, no screen-reader pass, contrast ratios uncalibrated)
• No marketing surface — repo lands cold without a screenshot of "this is what it looks like"

This needs a proper design pass with a Figma source of truth, then incremental implementation. The work is bigger than a single PR; it should be phased so contributors can ship one phase at a time.

Scope

A production-grade frontend redesign covering:

1. Visual identity — logo, color palette, type system, brand voice
2. Design system — design tokens (color, spacing, typography, elevation, motion), component primitives (button, input, badge, card, dialog, dropdown, table, code block, banner)
3. Application views — chat (operator main surface), AuditPanel (per-turn substrate / verifier signals), case list, engagement scope manager, settings
4. Cross-cutting: dark mode (default), responsive (mobile / tablet / desktop), accessibility (WCAG 2.1 AA minimum)
5. Marketing surface — a single landing-page-style screenshot for the repo's GitHub social preview + README hero image

Deliverables

Phase 1 — Design audit + research (week 1)

• Screenshot the current frontend (http://localhost:5173 after cd frontend && npm run dev) — capture every view + state for the design audit
• Competitor / inspiration scan: capture screens from at least 3 reference UIs operators respect (suggestions: Caido, Burp Suite Pro, Tines, Datadog Cloud SIEM, Tenable, SpecterOps BloodHound CE Enterprise UI, Hex Notebooks)
• Write a short design-direction doc (1-2 pages) outlining: brand attributes (e.g. "credible / quiet / dense — not flashy"), 2-3 reference influences with rationale, dark-mode-first commitment

Deliverable: a docs/design/audit.md + docs/design/inspiration/ screenshot folder

Phase 2 — Figma design system (week 2-3)

A Figma file (linked from the design doc) containing:

• Tokens page: color palette (light + dark), type scale (suggested: Inter or IBM Plex Sans + JetBrains Mono for code), spacing scale (4px base), elevation (shadows), motion (easing curves, durations)
• Components page: button (variants: primary, secondary, ghost, destructive), input, textarea, select, badge (with all 4 knowability classes + verifier severity variants), card, dialog, dropdown menu, table, code block, banner (info / warn / error), avatar, tooltip, command palette
• Each component documented with states: default, hover, focus, active, disabled, loading, error; both light + dark
• Accessibility annotations: contrast ratios noted per token pair, focus-ring spec, keyboard interaction notes

Deliverable: Figma file link in the issue description + exported design tokens as JSON (for the implementation phase)

Phase 3 — Application views (week 3-4)

High-fidelity Figma mockups for:

• Chat view (operator's primary surface): message list with substrate signals inline (badge for knowability class, chip for playbook fire, chip for catalog hits, citation tags rendered as links), code blocks with copy button, citation hover-cards, verifier rejection banners as designed components (not raw ⚠ markdown), ⚠ Answer truncated UX with explicit "Continue from where it stopped" button
• AuditPanel redesign (currently a JSON dump): structured sections (Routing • Substrate • Generation • Verification • Scope) with collapsible details, finding rows with severity + rule ID + matched excerpt
• Case list: case cards with title, last activity, engagement scope summary
• Engagement scope manager: asset table (in-scope / out-of-scope / unknown), edit / add asset, view the JSON file, validate against an active conversation
• Settings: model profile selector, env var visibility, current backend health
• Empty / error / loading states for each view
• Mobile / tablet variants for chat + audit

Deliverable: Figma file expanded with view mockups, exported high-resolution PNGs for review attached to this issue

Phase 4 — Implementation: tokens + Tailwind config (week 4-5)

• Migrate Figma tokens to frontend/tailwind.config.ts (color palette, spacing, typography, dark variants)
• Pick component approach:
  • Option A: adopt shadcn/ui (Radix + Tailwind, copy-paste components into the repo) — strongly preferred for accessibility + maintainability
  • Option B: hand-build using Radix primitives directly
• Set up dark mode (Tailwind's class strategy + next-themes-like toggle)
• Define semantic color tokens (--color-knowability-fact, --color-verifier-hard-fail, etc.) so component code doesn't reference raw palette values

Deliverable: tokens + theme infra merged; existing components still work (no visual regression yet)

Phase 5 — Implementation: component library (week 5-6)

• Build each design-system component matching the Figma spec
• Storybook or Ladle setup (optional but recommended) so components can be developed + reviewed in isolation
• Each component has: TypeScript types, accessibility props passthrough, dark-mode support, all designed states

Deliverable: frontend/src/components/ui/ directory with the full primitive library; can be PR'd one component at a time

Phase 6 — Implementation: view migration (week 6-8)

Migrate each application view to the new design, one PR per view:

• Chat view + message rendering (the biggest one — coordinate with issue #6: AuditPanel verifier findings and issue #5: knowability badge so they integrate with the redesign rather than fight it)
• AuditPanel redesign
• Case list
• Engagement scope manager
• Settings

Each PR includes before/after screenshots + a checklist confirming the design matches Figma.

Phase 7 — Accessibility audit + fixes (week 8)

• Run axe DevTools or Lighthouse accessibility on every view
• Keyboard navigation pass: tab order, focus management, escape-key dismissal of overlays, focus return after dialog close
• Screen reader pass: VoiceOver (macOS) or NVDA (Windows) on the main flows
• Reduced-motion: respect prefers-reduced-motion
• Color blindness: verify with Stark or similar — semantic colors must not be the sole signal

Deliverable: accessibility audit report in docs/design/accessibility.md, all WCAG 2.1 AA violations fixed

Phase 8 — Marketing surface (week 8)

• Export one polished hero screenshot of the redesigned chat view (dark mode, real operator content like the Linux privesc example from the README) for the repo's GitHub social preview image
• Update README with screenshots in the "What it does" section
• Optional: a simple landing-page hero (frontend/dist/index.html redirect to docs) — out of scope for v1

Constraints

• No frontend framework swap — stay on React 18 + Vite. The work is design + components, not architecture.
• Approved new dependencies: shadcn/ui (Radix), next-themes or equivalent theme manager, optionally Storybook/Ladle for component dev. Anything else: discuss in the issue thread first.
• Backend unchanged — this issue is frontend-only. If a redesign needs new audit data, file a separate [backend] ticket and link it.
• Accessibility is not optional — WCAG 2.1 AA is the floor, not the ceiling. Color contrast, keyboard nav, screen-reader labels are PR-merge gates.
• Dark mode is the default, not an afterthought — operators expect it. Light mode is the alternate.
• No marketing language anywhere in the UI — "AI-powered" / "transform your workflow" copy is rejected on sight. Match the README's operator-grade voice.
• Respect the operator's time — every pixel exists for a reason. No decorative animations, no gratuitous gradients, no "fun" microinteractions.

Pointers

• Current frontend: frontend/src/
• Current chat component: frontend/src/components/chat/
• Current AuditPanel: frontend/src/components/chat/AuditPanel.tsx
• Project tech stack: React 18, Vite 5, Tailwind 3, zustand, react-query, lucide-react, react-markdown, reactflow
• Related (consider merging into the redesign): #5 (knowability badge), #6 (verifier findings UI), #7 (loading phase indicator)
• README context for design voice: README.md — operator-grade, evidence-driven, no marketing

How to take this on

This is a multi-PR effort. Coordinate in this thread before starting:

1. Comment with which phase you want to own (1, 2, 3, etc.) — multiple contributors can take adjacent phases
2. For Phase 1-3 (design), share the Figma file URL (community / public-view link) in this issue so the maintainer + other contributors can review iteratively
3. For Phase 4-7 (implementation), open one PR per phase or per view — small PRs > one mega-PR
4. Reference this issue (Refs #N) in every PR so the dependency graph is visible
5. The maintainer reviews + approves each phase before the next phase starts (so we don't get a Figma file + half-implemented code that don't match)

Difficulty

L (multi-week) — this is a real design + implementation cycle. Estimate: ~4-8 weeks of part-time work depending on phase ownership distribution. Not for first-time contributors; recommended for someone who has shipped a design system before.

Anti-goals

To save time and prevent scope creep, these are explicitly out of scope for this redesign:

• New product features (engagement-management, case sharing, multi-user, RBAC) — different tickets
• Backend / API changes — different tickets
• Marketing website — different repo if it happens
• "AI assistant" personality / branding — this is a tool, not a character
• Animation-heavy / 3D / WebGL chrome — operator UX, not portfolio piece