WIP: Dashboard redesign — design system overhaul and component updates
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.
This commit is contained in:
root
199
.kiro/specs/dashboard-redesign/design.md
Normal file
199
.kiro/specs/dashboard-redesign/design.md
Normal file
@@ -0,0 +1,199 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user