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

```mermaid
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