27192dd69f
Frontend redesign in progress: updated styles, layout, and components across all pages to align with new design system. Includes Jira API compliance specs, property tests, and load test script.
200 lines
12 KiB
Markdown
200 lines
12 KiB
Markdown
# 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
|