cve-dashboard/.kiro/specs/dashboard-redesign/design.md

Design Document: Dashboard Redesign

Overview

This design covers the comprehensive visual redesign of the STEAM Security Dashboard frontend. The redesign applies a refined design system extracted to docs/design-system-redesign/ — evolving the existing dark tactical console aesthetic with an expanded token system, updated typography, refined card surfaces, enhanced severity badges, new layout tokens, proper font loading, a new brand mark, and refined animations.

The redesign is purely presentational. All existing behavior, routes, state management, and API calls are preserved. Only JSX style props, inline style objects, CSS custom properties, CSS classes, and the HTML font-loading link change.

Design Decisions

1. Token-first migration: All new design tokens are added to App.css :root alongside existing tokens. Old token names are preserved so unmigrated components continue to render correctly. This enables incremental page-by-page migration without big-bang breakage.

2. No new dependencies: The redesign uses only existing libraries (React, lucide-react, recharts). Fonts load from Google Fonts CDN via a <link> tag in index.html. The existing Tailwind CDN script in index.html remains untouched — it is used by some components and removing it is out of scope.

3. Dual styling strategy: The app uses both inline style objects (JS constants in component files) and CSS classes from App.css. Both are updated. The UI kit reference files in docs/design-system-redesign/ui_kits/ use inline styles with var(--token) references — the same pattern the production code already uses.

4. Severity colors are immutable: Critical (#EF4444), High (#F59E0B), Medium (#0EA5E9), Low (#10B981) — these mappings never change across any component.

---

Architecture

The redesign does not alter the application architecture. The frontend remains a React 19 SPA (Create React App) with page-level navigation managed in App.js, auth via React Context, and fetch() API calls with cookie-based auth.

Migration Flow

graph TD
    A[Phase 1: Token Migration] --> B[Phase 2: Font Loading]
    B --> C[Phase 3: Global CSS Classes]
    C --> D[Phase 4: App Shell]
    D --> E[Phase 5: Home Page]
    E --> F[Phase 6: Reporting Page]
    F --> G[Phase 7: Compliance Page]
    G --> H[Phase 8: Knowledge Base Page]
    H --> I[Phase 9: Exports Page]
    I --> J[Phase 10: Shared Components]

Each phase is independently verifiable. After Phase 1–3, all existing components render correctly with both old and new token names available. Phases 4–10 migrate individual pages and components one at a time.

---

Components and Interfaces

Files Modified (no new files created)

File	Change Type	Description
frontend/src/App.css	Token + class update	Port all design tokens from colors_and_type.css, update global CSS classes, add semantic type utilities, update animations
frontend/public/index.html	Font link update	Add Outfit weight 800 to existing Google Fonts link (weight 300 already missing), ensure display=swap
frontend/src/App.js	Inline style update	Update STYLES object, stat cards, CVE rows, Quick Lookup, calendar, right-rail panels, top bar, brand mark
frontend/src/components/NavDrawer.js	Inline style update	Update drawer chrome, nav items, backdrop overlay to use design tokens
frontend/src/components/UserMenu.js	Inline style update	Update dropdown, avatar, menu items to use design tokens
frontend/src/components/pages/ReportingPage.js	Inline style update	Update page header, table, charts, buttons, filter chips, status banners
frontend/src/components/pages/CompliancePage.js	Inline style update	Update teal-accented page header, metric cards, device table, team tabs
frontend/src/components/pages/ComplianceUploadModal.js	Inline style update	Update modal overlay, card, buttons
frontend/src/components/pages/ComplianceDetailPanel.js	Inline style update	Update panel chrome, data rows
frontend/src/components/pages/ComplianceChartsPanel.js	Inline style update	Update chart card wrappers, teal borders
frontend/src/components/pages/KnowledgeBasePage.js	Inline style update	Update document list, viewer, action buttons
frontend/src/components/pages/ExportsPage.js	Inline style update	Update page header, export cards, buttons
frontend/src/components/LoginForm.js	Inline style update	Update form card, inputs, button
frontend/src/components/CalendarWidget.js	Inline style update	Update calendar grid, day cells, navigation buttons
frontend/src/components/UserManagement.js	Inline style update	Update group badges, table rows, buttons
frontend/src/components/AuditLog.js	Inline style update	Update log entry rows, timestamps, action badges
frontend/src/components/NvdSyncModal.js	Inline style update	Update modal chrome, buttons
frontend/src/components/KnowledgeBaseModal.js	Inline style update	Update modal chrome, form inputs
frontend/src/components/KnowledgeBaseViewer.js	Inline style update	Update viewer chrome, markdown content area

Token Migration Strategy

The App.css :root block is updated to include all tokens from docs/design-system-redesign/colors_and_type.css. The strategy:

1. Additive merge: New tokens are added. Existing tokens that match (e.g., --intel-darkest, --intel-accent) keep their current values (which already match the design system). No existing token is removed.

2. Alias tokens added: Friendly aliases like --bg-page, --bg-surface, --fg-1, --fg-2, --accent, --sev-critical are added so components can use either canonical or alias form.

3. New token categories added:

   • Surface aliases (--bg-page, --bg-surface, --bg-elevated, --bg-hover, --bg-input, --bg-overlay)
   • Foreground aliases (--fg-1, --fg-2, --fg-muted, --fg-disabled)
   • Border tokens (--border-subtle, --border-default, --border-strong, --border-focus)
   • Brand accent variants (--intel-accent-bright, --intel-accent-soft, --accent, --accent-bright, --accent-soft, --accent-wash)
   • Severity fill tokens (--sev-critical-bg, --sev-high-bg, --sev-medium-bg, --sev-low-bg)
   • Severity text tokens (--sev-critical-text, --sev-high-text, --sev-medium-text, --sev-low-text)
   • Group badge tokens (--group-admin, --group-standard, --group-leadership, --group-readonly)
   • Font family tokens (--font-ui, --font-mono)
   • Type scale tokens (--fs-display through --fs-tiny)
   • Line height, font weight, letter spacing tokens
   • Spacing scale (--sp-1 through --sp-12)
   • Radii (--r-xs through --r-pill)
   • Elevation shadows (--shadow-rest through --shadow-focus)
   • Severity glows (--glow-danger, --glow-warning, --glow-info, --glow-success)
   • Heading glow (--glow-heading)
   • Motion tokens (--ease-out, --ease-in-out, --dur-fast, --dur-med, --dur-slow)
   • Layout tokens (--topbar-h, --drawer-w, --panel-w, --content-max, z-index tokens)

Per-Component Style Mapping

Each component uses a mix of inline style objects and CSS classes. The migration pattern for each:

Inline style objects (e.g., STYLES.statCard in App.js, hardcoded style props in NavDrawer.js):

• Replace hardcoded hex colors with var(--token) references where the token exists
• Update gradient backgrounds to match the Card_Surface treatment from the design system
• Update border values to use the new border tokens
• Update font-family references from 'monospace' or 'JetBrains Mono', monospace to var(--font-mono)
• Update font-family references from 'Outfit', system-ui, sans-serif to var(--font-ui)

CSS classes (e.g., .intel-card, .status-badge, .intel-button in App.css):

• Update to reference new tokens where applicable
• Add new classes (.stat-card top-edge gradient rail, semantic type utilities)
• Update animation keyframes to match design system definitions

App Shell Redesign

The app shell (top bar + nav drawer + user menu) is updated to match AppShell.jsx reference:

• Top bar: 64px height (--topbar-h), var(--bg-surface) background, var(--border-subtle) bottom border, var(--z-topbar) z-index
• Brand mark: Typographic stack — "STEAM" in Outfit 700 at 15px, "SECURITY" in Outfit 500 at 9px with 0.18em letter spacing, Shield icon in var(--accent) color
• Nav tabs: Outfit 13px, 500 weight (600 active), active state uses var(--accent) text + var(--accent-soft) background
• Nav drawer: 240px width (--drawer-w), var(--bg-surface) background, var(--border-subtle) right border, overlay with var(--bg-overlay) + backdrop-filter: blur(4px)
• User menu: Circular avatar with initials in var(--accent) on var(--accent-soft) background, dropdown with var(--shadow-popover) elevation

Page Identity Colors

Each page has a distinct identity color for its header glow:

Page	Identity Color	Header Text
Home	Sky blue (#0EA5E9)	"CVE INTEL"
Reporting	Green (#10B981)	"REPORTING"
Compliance	Teal (#14B8A6)	"AEO COMPLIANCE"
Knowledge Base	Sky blue or green	Page title
Exports	Sky blue	Page title

All page headers follow the same pattern: JetBrains Mono, 24px, 700 weight, uppercase, 0.1em letter spacing, color-matched text-shadow glow.

---

Data Models

No data model changes. This redesign is purely presentational — no database schema, API contract, or state shape changes.

---

Error Handling

No error handling changes. All existing error states, error messages, loading spinners, and fallback UI are preserved. Only their visual styling is updated:

• Error banners use red-tinted backgrounds (rgba(239,68,68,0.08)), red borders, AlertCircle icon, and mono font
• Loading spinners use the existing spin animation with var(--accent) color
• Empty states use the existing pattern with updated token references

---

Testing Strategy

Why Property-Based Testing Does Not Apply

This feature is a pure UI visual redesign. It changes CSS custom properties, inline style objects, CSS class definitions, and font loading. There are:

• No pure functions with input/output behavior to test
• No data transformations, parsers, or serializers
• No business logic changes
• No state management changes
• No API contract changes

Property-based testing requires universal properties that hold across a wide input space. A visual redesign has no meaningful "for all inputs X, property P(X) holds" statements. The correctness of a visual redesign is verified by visual inspection and snapshot comparison, not by generating random inputs.

Recommended Testing Approach

Manual visual verification (primary):

• Compare each page against the UI kit reference files in docs/design-system-redesign/ui_kits/
• Verify token values in browser DevTools (inspect computed styles)
• Check all severity badge colors match the fixed mapping
• Verify font loading (Outfit + JetBrains Mono) in Network tab
• Test hover states, focus rings, transitions, and animations
• Verify scrollbar styling in WebKit browsers

Snapshot testing (optional, for regression):

• Capture rendered HTML snapshots of key components before and after migration
• Use React Testing Library's render() + inline snapshot assertions
• Focus on structural correctness (correct CSS classes applied, correct inline style values)

Build verification:

• npm run build in frontend/ must succeed with zero errors
• No new console warnings related to styling
• No new ESLint warnings

Cross-browser check:

• Verify backdrop-filter: blur() works in target browsers
• Verify font-display: swap prevents FOIT (flash of invisible text)
• Verify webkit scrollbar styling renders correctly

Incremental verification checklist (one per migration phase):

1. After token migration: all existing pages render correctly, no broken styles
2. After font loading: Outfit and JetBrains Mono load, font-display: swap active
3. After global CSS update: .intel-card, .status-badge, .intel-button, .intel-input render correctly
4. After app shell: top bar height, brand mark, nav tabs, drawer, user menu match reference
5. After each page: compare against corresponding UI kit assembly file