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

Requirements Document

Introduction

This document captures the requirements for a 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. All existing behavior, routes, state management, and API calls are preserved — only presentational JSX, inline styles, and CSS change.

Glossary

• Dashboard: The STEAM Security Dashboard frontend React application served from frontend/src/
• Design_Token_File: The source-of-truth CSS custom properties file at docs/design-system-redesign/colors_and_type.css defining color, typography, spacing, radii, elevation, and motion tokens
• App_CSS: The global stylesheet at frontend/src/App.css containing CSS variables, utility classes, component classes, and animations
• UI_Kit: A self-contained reference implementation in docs/design-system-redesign/ui_kits/<name>/ consisting of a primitives file (component vocabulary) and a page assembly file (target rendering)
• Token: A CSS custom property (e.g., --intel-accent, --sp-4, --r-lg) that encodes a design decision for color, spacing, radius, elevation, or motion
• App_Shell: The persistent chrome surrounding page content — top bar, navigation drawer, user menu, and brand mark
• Page_Component: A top-level view rendered by the Dashboard — Home (App.js), Reporting, Compliance, Knowledge Base, Exports, or Admin Panel
• Severity_Badge: A styled inline element displaying CVE severity level (Critical, High, Medium, Low) with a pulse-glow dot, gradient fill, and tinted border
• Card_Surface: A styled container using the diagonal gradient background, sky-blue border, and layered shadow treatment defined in the design system
• Inline_Style_Object: A JavaScript object constant defined in a component file and passed to the style prop of a React element
• Google_Fonts_CDN: The external font service at fonts.googleapis.com used to load Outfit and JetBrains Mono typefaces

Requirements

Requirement 1: Port Design Tokens to App.css

User Story: As a developer, I want the new design tokens ported into App.css, so that all components can reference a single source of truth for colors, typography, spacing, radii, elevation, and motion values.

Acceptance Criteria

1. WHEN the Dashboard loads, THE App_CSS SHALL define all CSS custom properties present in the Design_Token_File within the :root block, including surface colors, foreground colors, border tokens, brand accent tokens, semantic severity tokens, severity text tokens, severity fill tokens, group badge tokens, font families, type scale, line heights, font weights, letter spacing, spacing scale, radii, elevation shadows, severity glows, heading glow, motion easings, motion durations, and layout tokens
2. WHEN the Dashboard loads, THE App_CSS SHALL preserve all existing CSS custom properties that are not superseded by the Design_Token_File tokens
3. WHEN the Dashboard loads, THE App_CSS SHALL include the alias tokens defined in the Design_Token_File (e.g., --bg-page, --bg-surface, --fg-1, --fg-2, --border-1, --accent, --sev-critical) so that components can use either the canonical or alias form
4. WHEN the Dashboard loads, THE App_CSS SHALL define the --font-ui and --font-mono custom properties matching the Design_Token_File values ('Outfit', system-ui, -apple-system, sans-serif and 'JetBrains Mono', ui-monospace, 'SF Mono', Menlo, monospace)
5. WHEN the Dashboard loads, THE App_CSS SHALL define the spacing scale tokens (--sp-1 through --sp-12) matching the 4px grid from the Design_Token_File
6. WHEN the Dashboard loads, THE App_CSS SHALL define the radii tokens (--r-xs through --r-pill) matching the Design_Token_File
7. WHEN the Dashboard loads, THE App_CSS SHALL define the elevation tokens (--shadow-rest, --shadow-card, --shadow-card-hover, --shadow-popover, --shadow-modal, --shadow-focus) matching the Design_Token_File
8. WHEN the Dashboard loads, THE App_CSS SHALL define the motion tokens (--ease-out, --ease-in-out, --dur-fast, --dur-med, --dur-slow) matching the Design_Token_File
9. WHEN the Dashboard loads, THE App_CSS SHALL define the layout tokens (--topbar-h, --drawer-w, --panel-w, --content-max, --z-topbar, --z-drawer, --z-modal, --z-tooltip) matching the Design_Token_File

Requirement 2: Load Fonts via Google Fonts CDN

User Story: As a user, I want the Dashboard to load Outfit and JetBrains Mono from Google Fonts CDN, so that typography renders consistently with the design system specification.

Acceptance Criteria

1. WHEN the Dashboard loads, THE Dashboard SHALL import Outfit (weights 300, 400, 500, 600, 700, 800) and JetBrains Mono (weights 400, 500, 600, 700) from Google_Fonts_CDN
2. WHEN the Dashboard loads, THE App_CSS SHALL set the default font-family on the universal selector (*) to var(--font-ui) referencing the Outfit font stack
3. WHEN the Dashboard loads, THE Dashboard SHALL apply font-display: swap to prevent invisible text during font loading

Requirement 3: Update Global CSS Classes and Animations

User Story: As a developer, I want the global CSS classes in App.css updated to match the new design token values, so that components using class-based styling reflect the redesigned visual language.

Acceptance Criteria

1. WHEN a component applies the intel-card class, THE App_CSS SHALL render the card with the diagonal gradient background, 1.5px sky-blue border at 0.30 alpha, 8px border-radius, and the --shadow-card elevation token
2. WHEN a user hovers over an element with the intel-card class, THE App_CSS SHALL increase the border opacity to 0.50, apply translateY(-2px), apply the --shadow-card-hover elevation, and sweep a sky-blue shimmer from left to right over 500ms
3. WHEN a component applies the status-badge class, THE App_CSS SHALL render the badge with JetBrains Mono font, 0.75rem size, 700 weight, uppercase text, 0.5px letter spacing, 6px border-radius, 2px solid border, and an 8px pulse-glow dot using the pulse-glow keyframe animation at 2s interval
4. WHEN a component applies the intel-button class, THE App_CSS SHALL render the button with JetBrains Mono font, 600 weight, uppercase text, 0.5px letter spacing, 6px border-radius, and the circular ripple hover effect expanding to 300px
5. WHEN a component applies the intel-input class, THE App_CSS SHALL render the input with var(--bg-input) background, var(--border-subtle) border, 6px border-radius, and on focus apply var(--border-focus) border color with var(--shadow-focus) ring
6. WHEN a component applies the stat-card class, THE App_CSS SHALL render the card with the diagonal gradient, 8px border-radius, a 2px top-edge gradient rail (linear-gradient(90deg, transparent, #0EA5E9, transparent)), and the --shadow-card elevation
7. WHEN a component applies the modal-overlay class, THE App_CSS SHALL render the overlay with var(--bg-overlay) background and backdrop-filter: blur(12px)
8. THE App_CSS SHALL define the pulse-glow, spin, fade-in, and scan keyframe animations matching the Design_Token_File definitions
9. THE App_CSS SHALL define the semantic type utility classes (t-display, t-h1, t-h2, t-h3, t-body, t-sm, t-meta, t-label, t-mono, t-mono-sm, t-code) matching the Design_Token_File definitions
10. THE App_CSS SHALL define the *:focus-visible rule applying var(--border-focus) border color and var(--shadow-focus) box-shadow with no outline

Requirement 4: Redesign the App Shell

User Story: As a user, I want the top bar, navigation drawer, and user menu to match the new design system, so that the persistent application chrome is visually consistent with the redesigned pages.

Acceptance Criteria

1. WHEN the Dashboard loads, THE App_Shell SHALL render a top bar with var(--topbar-h) height (64px), var(--bg-surface) background, var(--border-subtle) bottom border, and var(--z-topbar) z-index
2. WHEN the Dashboard loads, THE App_Shell SHALL render the brand mark as a typographic stack with "STEAM" in Outfit 700 weight at 15px and "SECURITY" in Outfit 500 weight at 9px with 0.18em letter spacing, accompanied by a sky-blue Shield icon
3. WHEN the Dashboard loads, THE App_Shell SHALL render navigation tabs in the top bar for Home, Reporting, Compliance, Knowledge Base, and Exports using Outfit font at 13px with 500 weight (600 weight when active)
4. WHEN a user selects a navigation tab, THE App_Shell SHALL highlight the active tab with var(--accent) text color and var(--accent-soft) background
5. WHEN a user clicks the menu icon, THE App_Shell SHALL open a navigation drawer from the left with var(--drawer-w) width (240px), var(--bg-surface) background, var(--border-subtle) right border, and var(--z-drawer) z-index
6. WHEN the navigation drawer is open, THE App_Shell SHALL render a semi-transparent overlay behind the drawer with var(--bg-overlay) background and backdrop-filter: blur(4px)
7. WHEN the Dashboard loads, THE App_Shell SHALL render the user menu button with a circular avatar showing the user's initials in var(--accent) color on var(--accent-soft) background, the user's name, and a chevron indicator
8. WHEN a user clicks the user menu button, THE App_Shell SHALL display a dropdown with var(--bg-surface) background, var(--border-subtle) border, var(--shadow-popover) elevation, and var(--z-drawer) z-index, showing the user's name, email, group badge, and menu items

Requirement 5: Redesign the Home Page (App.js)

User Story: As a user, I want the Home page to match the new design system, so that the CVE list, stat cards, filters, calendar widget, and right-rail panels reflect the refined visual language.

Acceptance Criteria

1. WHEN the Home page loads, THE Dashboard SHALL render stat cards at the top of the page using the Card_Surface treatment with a 2px top-edge gradient rail, color-coded borders (sky for neutral, amber for attention, red for critical), and the --shadow-card elevation with severity-tinted glow
2. WHEN the Home page loads, THE Dashboard SHALL render the page title in JetBrains Mono, 24px, 700 weight, sky-blue color, uppercase, with 0.1em letter spacing and the heading glow text-shadow
3. WHEN the Home page loads, THE Dashboard SHALL render CVE row cards using the Card_Surface treatment with 1.5px sky-blue border at 0.12 alpha, 8px border-radius, and a chevron toggle that rotates from -90deg (collapsed) to 0deg (expanded)
4. WHEN a user expands a CVE row, THE Dashboard SHALL display the full description, severity badge with pulse-glow dot, vendor count, document count, and status labels, with vendor entry sub-cards using the nested Card_Surface gradient
5. WHEN the Home page loads, THE Dashboard SHALL render the Quick Lookup section as a Card_Surface with sky-blue identity, containing search input with icon, filter controls, and result banners using tone-coded backgrounds (success green, warning amber, error red)
6. WHEN the Home page loads, THE Dashboard SHALL render the calendar widget with JetBrains Mono font, sky-blue highlight for the current day, severity-colored dots for marked dates, and navigation buttons with sky-blue borders
7. WHEN the Home page loads, THE Dashboard SHALL render right-rail panels (Open Tickets, Archer, Ivanti) as Card_Surface containers with left-rail color accents (amber for tickets, purple for Archer, teal for Ivanti), BigStat centered counts, and scrollable MiniTicket lists
8. WHEN the Home page loads, THE Dashboard SHALL render filter controls using the redesigned input and select styles with var(--bg-input) background, sky-blue focus borders, and JetBrains Mono font for data fields

Requirement 6: Redesign the Reporting Page

User Story: As a user, I want the Reporting page to match the new design system, so that the findings table, charts, filters, and toolbar reflect the refined visual language.

Acceptance Criteria

1. WHEN the Reporting page loads, THE Dashboard SHALL render the page header with "REPORTING" in JetBrains Mono, 24px, 700 weight, green (#10B981) color, uppercase, with 0.1em letter spacing and green glow text-shadow
2. WHEN the Reporting page loads, THE Dashboard SHALL render the Sync button as a green tinted-fill primary variant and secondary action buttons (Atlas, Export, Queue, Column manager) as sky-blue outlined or tinted-fill variants
3. WHEN the Reporting page loads, THE Dashboard SHALL render the findings table panel as a Card_Surface with sky-blue border at 0.12 alpha, containing a toolbar with mono uppercase labels, filter chips in amber, and pill tabs for Ivanti/Atlas views
4. WHEN the Reporting page loads, THE Dashboard SHALL render table rows with var(--border-subtle) bottom borders, severity dots with 7px diameter and colored glow, SLA pills with pill-radius and tinted backgrounds, and workflow badges with 4px radius and tinted borders
5. WHEN a user hovers over a table row, THE Dashboard SHALL apply a rgba(0,217,255,0.06) background wash and 0 2px 8px rgba(0,217,255,0.10) sub-shadow
6. WHEN the Reporting page loads, THE Dashboard SHALL render chart panels as Card_Surface containers with sky-blue borders, mono uppercase title labels, and donut charts using the severity color palette
7. WHEN an error occurs during sync, THE Dashboard SHALL display a status banner with red-tinted background, red border, AlertCircle icon, and mono font error message

Requirement 7: Redesign the Compliance Page

User Story: As a user, I want the Compliance page to match the new design system, so that the metric health cards, device table, charts, and team tabs reflect the teal-accented visual language.

Acceptance Criteria

1. WHEN the Compliance page loads, THE Dashboard SHALL render the page header with "AEO COMPLIANCE" in JetBrains Mono, 24px, 700 weight, teal (#14B8A6) color, uppercase, with 0.1em letter spacing and teal glow text-shadow
2. WHEN the Compliance page loads, THE Dashboard SHALL render team tabs (STEAM, ACCESS-ENG) with teal-tinted active state, mono uppercase labels, and 6px border-radius
3. WHEN the Compliance page loads, THE Dashboard SHALL render metric health cards as clickable Card_Surface containers with status-colored borders (green for meeting target, amber for within 15%, red for below 15%), variant pills showing compliance percentages, and a status ribbon at the bottom
4. WHEN a user clicks a metric health card, THE Dashboard SHALL highlight the active card with a status-colored background fill at 0.15 alpha and a solid status-colored border
5. WHEN the Compliance page loads, THE Dashboard SHALL render the device table with teal-tinted borders at 0.15 alpha, mono uppercase column headers, hostname/IP in JetBrains Mono, category-colored metric badges, escalating seen-count badges (slate for 1, amber for 2–3, red for 4+), and a teal-accented search input
6. WHEN a user hovers over a device row, THE Dashboard SHALL apply a subtle white-alpha background wash and highlight the selected row with a 2px teal left border
7. WHEN the Compliance page loads, THE Dashboard SHALL render chart cards with teal-tinted borders, mono uppercase titles, and the standard Card_Surface gradient background
8. WHEN an admin triggers a rollback, THE Dashboard SHALL display a centered modal with red-tinted border, red mono uppercase title, dark recessed file label, and danger-styled confirm button

Requirement 8: Redesign the Knowledge Base Page

User Story: As a user, I want the Knowledge Base page to match the new design system, so that the document library, viewer, and search interface reflect the refined visual language.

Acceptance Criteria

1. WHEN the Knowledge Base page loads, THE Dashboard SHALL render the page header following the same mono uppercase glow pattern used by other pages, with sky-blue or green identity color
2. WHEN the Knowledge Base page loads, THE Dashboard SHALL render document list items using the recessed Card_Surface treatment with inset 0 2px 4px rgba(0,0,0,0.3) shadow, sky-blue borders at 0.20 alpha, and hover state increasing border opacity to 0.35
3. WHEN the Knowledge Base page loads, THE Dashboard SHALL render the document viewer with markdown content styled according to the App_CSS .markdown-content rules — h1 in sky-blue, h2 in emerald, h3 in amber, code blocks with dark recessed background, and blockquotes with sky-blue left border
4. WHEN the Knowledge Base page loads, THE Dashboard SHALL render action buttons (upload, create, view) using the redesigned button variants with mono uppercase labels and tinted-fill backgrounds

Requirement 9: Redesign Shared Components

User Story: As a developer, I want the shared components (LoginForm, CalendarWidget, UserManagement, AuditLog, NvdSyncModal, KnowledgeBaseModal, KnowledgeBaseViewer) to match the new design system, so that every surface in the application is visually consistent.

Acceptance Criteria

1. WHEN the LoginForm renders, THE Dashboard SHALL style the login form using Card_Surface treatment, redesigned input fields with var(--bg-input) background and sky-blue focus rings, and the primary button variant
2. WHEN a modal opens, THE Dashboard SHALL render the modal overlay with var(--bg-overlay) background and backdrop-filter: blur(12px), and the modal card with var(--shadow-modal) elevation and 12px border-radius
3. WHEN the UserManagement component renders, THE Dashboard SHALL style group badges using the token-based group colors (--group-admin red, --group-standard sky-blue, --group-leadership amber, --group-readonly grey) with pill-radius and tinted backgrounds
4. WHEN the AuditLog component renders, THE Dashboard SHALL style log entries using the data-row treatment with var(--border-subtle) bottom borders, mono font for timestamps and action types, and hover state with sky-blue background wash
5. WHEN the NvdSyncModal renders, THE Dashboard SHALL style the modal content using Card_Surface treatment with the standard modal elevation and redesigned button variants
6. WHEN the CalendarWidget renders, THE Dashboard SHALL style the calendar with JetBrains Mono font, sky-blue current-day highlight with 1px border, severity-colored date markers, and navigation buttons with sky-blue borders

Requirement 10: Redesign the Exports Page

User Story: As a user, I want the Exports page to match the new design system, so that the export tools interface is visually consistent with the rest of the application.

Acceptance Criteria

1. WHEN the Exports page loads, THE Dashboard SHALL render the page header following the mono uppercase glow pattern with appropriate identity color
2. WHEN the Exports page loads, THE Dashboard SHALL render export action cards using the Card_Surface treatment with sky-blue borders and the redesigned button variants for export triggers

Requirement 11: Preserve Existing Behavior

User Story: As a user, I want all existing functionality to continue working after the redesign, so that the visual update does not break any workflows.

Acceptance Criteria

1. THE Dashboard SHALL preserve all existing page navigation routes and state management logic without modification
2. THE Dashboard SHALL preserve all existing API calls, request parameters, response handling, and error handling without modification
3. THE Dashboard SHALL preserve all existing user interactions — click handlers, form submissions, modal open/close, expand/collapse, drag-and-drop, inline editing — without modification
4. THE Dashboard SHALL preserve all existing role-based access control checks and conditional rendering logic without modification
5. THE Dashboard SHALL preserve all existing data display logic — filtering, sorting, searching, pagination — without modification

Requirement 12: No New Dependencies

User Story: As a developer, I want the redesign to use only existing dependencies, so that the bundle size and dependency surface area remain unchanged.

Acceptance Criteria

1. THE Dashboard SHALL use only React, lucide-react, recharts, react-markdown, rehype-sanitize, mermaid, and xlsx as frontend dependencies — no new libraries shall be added
2. THE Dashboard SHALL load Outfit and JetBrains Mono fonts exclusively from Google_Fonts_CDN — no bundled font files shall be added

Requirement 13: Incremental Migration Approach

User Story: As a developer, I want the redesign applied incrementally (tokens first, then page-by-page), so that changes can be verified in isolation and big-bang breakage is avoided.

Acceptance Criteria

1. WHEN the token migration is complete, THE App_CSS SHALL be fully functional with both old and new token names available, so that components can be migrated one at a time without breaking unmigrated components
2. WHEN a Page_Component is migrated, THE Dashboard SHALL render the migrated page using the new design tokens and styles while unmigrated pages continue to render correctly using the existing styles

Requirement 14: Severity Color Mapping Preservation

User Story: As a user, I want severity colors to remain semantically fixed, so that Critical is always red, High is always amber, Medium is always sky-blue, and Low is always emerald across every component.

Acceptance Criteria

1. THE Dashboard SHALL render Critical severity indicators using #EF4444 (border/dot), rgba(239,68,68,0.20) (fill), and #FCA5A5 (text) across all Severity_Badge instances, status badges, chart segments, and inline severity references
2. THE Dashboard SHALL render High severity indicators using #F59E0B (border/dot), rgba(245,158,11,0.20) (fill), and #FCD34D (text) across all severity-displaying components
3. THE Dashboard SHALL render Medium severity indicators using #0EA5E9 (border/dot), rgba(14,165,233,0.20) (fill), and #7DD3FC (text) across all severity-displaying components
4. THE Dashboard SHALL render Low severity indicators using #10B981 (border/dot), rgba(16,185,129,0.20) (fill), and #6EE7B7 (text) across all severity-displaying components

Requirement 15: Brand Mark and Asset Integration

User Story: As a user, I want the new STEAM brand mark and severity icons available in the application, so that the visual identity is complete.

Acceptance Criteria

1. WHEN the Dashboard loads, THE App_Shell SHALL display the STEAM brand mark as a typographic stack with a Shield icon, matching the assets/logo.svg reference — not the previous AtlasIcon custom SVG
2. WHEN the Dashboard renders severity icons, THE Dashboard SHALL use the severity icon SVGs from docs/design-system-redesign/assets/ or equivalent inline SVG representations matching the design system specification

Requirement 16: Scrollbar and Focus Styling

User Story: As a user, I want scrollbars and focus indicators to match the new design system, so that these browser-level affordances are visually integrated.

Acceptance Criteria

1. THE App_CSS SHALL style webkit scrollbars with 8px width, var(--intel-dark) track background, and rgba(14,165,233,0.3) thumb with 4px border-radius, increasing to rgba(14,165,233,0.5) on hover
2. THE App_CSS SHALL apply focus-visible styling with var(--border-focus) border color and var(--shadow-focus) box-shadow to all focusable elements, with no outline