cve-dashboard/docs/design-system-redesign/README.md

STEAM Security Design System

A design system for the STEAM Security Dashboard — a self-hosted vulnerability management workbench used by the NTS-AEO-STEAM and NTS-AEO-ACCESS-ENG business units. This repo captures the visual language, content patterns, tokens, and UI kit needed to extend or rebuild the product without drifting from its established look.

What the product is

The STEAM Security Dashboard centralises:

• CVE tracking — searchable, filterable, vendor-aware CVE list with NVD auto-fill, document attachment, and group-based ownership
• Ivanti / RiskSense host findings — live remediation queue with FP / Archer / CARD workflows, inline editing, per-finding notes, and a personal "Ivanti Queue" staging list
• AEO compliance posture — weekly xlsx upload with drift detection, diff preview, per-team metric health cards, device-level violation tracking, and timestamped notes
• Archer EXC tickets — risk-acceptance ticket tracking linked to CVE / vendor pairs
• Knowledge base — internal document library (PDF, Markdown, Office, etc.) for runbooks, advisories, and policies
• Admin panel — user / group management, audit log, system info — all gated behind an Admin group

Four user groups (Admin, Standard_User, Leadership, Read_Only) define every permission boundary, and every state-changing action is audit-logged.

The 6 pages

1. Home / Dashboard — CVE list, filters, calendar widget for due dates
2. Reporting — Ivanti host findings, charts, queue, export
3. Compliance — AEO posture, metric health cards, device drill-in
4. Knowledge Base — document library
5. Exports — bulk export tools (group-gated)
6. Admin Panel — user management, audit log, system info (Admin only)

Sources

• Codebase: https://vulcan.apophisnetworking.net/jramos/cve-dashboard (Gitea, master branch). Auth required; raw file fetch is gated. The repo's own README.md (fetched via the source viewer) is the most accurate functional spec we had access to and is the basis for this system.
• Existing design ref: DESIGN_SYSTEM.md (290 lines, in-repo) — referenced in the audit but not directly accessible from the host.
• Component audit provided in the project brief: 29 components, 5 primitives, 14 composites, 5 pages, 1 context provider.
• Stack: React 19, lucide-react, recharts, react-markdown + rehype-sanitize, mermaid, xlsx. Backend Express 5 / SQLite3.

Index — what's in this folder

Path	What it is
README.md	This file — context, content + visual foundations, iconography
SKILL.md	Agent Skill manifest for Claude Code compatibility
colors_and_type.css	Source-of-truth tokens — color, type, spacing, radii, elevation
fonts/	Font references (Outfit + JetBrains Mono via Google Fonts CDN)
assets/	Logo mark, brand SVGs, severity icons
preview/	Design System tab cards — registered as assets
ui_kits/cve-dashboard/	High-fidelity recreation of the dashboard, focused on Knowledge Base

---

CONTENT FUNDAMENTALS

The product is a tactical operations console for security engineers. Copy is dense, terse, and assumes a reader who already knows what a CVE, EXC ticket, FP workflow, and BU filter are. There is no marketing voice, no onboarding nudges, and no exclamation marks.

Voice & tone

• Operational, not editorial. Buttons say "Sync", "Confirm Upload", "Reconcile Config", "Add to Queue". Never "Let's get started" or "You're all set".
• Imperative for actions, declarative for state. "Save", "Delete", "Hide Selected" — never "Saving your changes…" with three dots and a heart.
• No emoji. Status is communicated through colour-coded badges and short text labels.
• Title Case for navigation and headers, Sentence case for body and inline labels. Tabs and buttons: User Management, Audit Log, System Info. Helper text: Filter tickets by CVE ID, vendor, or status.

Person & address

• Second-person sparingly — only when the system is talking about the user's data: "your login", "your filtered view", "your queue". Never "Welcome back, {name}".
• First-person plural never. No "We've updated" or "Let us know".
• Errors are direct, no apology. "SESSION_SECRET environment variable must be set." "Login rate limited — wait 15 minutes." Never "Oops! Something went wrong."

Casing

• CVE IDs: uppercase with hyphen — CVE-2024-12345. Validated against /^CVE-\d{4}-\d{4,}$/.
• EXC numbers: uppercase — EXC-12345. Validated /^EXC-\d+$/.
• Severity labels: Title Case — Critical, High, Medium, Low. Status labels: Open, Addressed, In Progress, Resolved.
• Workflow state badges: SHOUT CASE for SLA states only — OVERDUE, AT_RISK, WITHIN_SLA. Everything else is Title Case.
• Group names: snake_case in code (Standard_User), Title Case in UI (Standard User).

Density and units

• Numerical metrics are bare integers ("12 findings", "47 devices"). Percentages always carry the % sign with no space.
• Dates are explicit, no relative time except "Last sync: 4h ago" patterns.
• Column headers are short — Host, IP Address, DNS, BU, SLA — never Host Name (Editable).

Specific copy conventions seen in product

• "— empty —" as a filter option for empty cells
• "Hidden (N)" pattern for counted UI states
• "+N" badge for overflow (e.g., 2 CVEs shown, "+5" badge)
• "↻" revert glyph next to overridden cells, with a small amber dot ● for the overridden state
• Tooltips appear after a 300ms delay and are session-cached
• "View in Reporting →" inline link pattern with a literal arrow

What NOT to write

• No motivational copy ("Great work!", "You're crushing it")
• No question-mark headlines ("Need help?")
• No marketing CTAs ("Upgrade now", "Try premium")
• No mascot or persona — the system is the system

---

VISUAL FOUNDATIONS

The dashboard reads as a dark tactical intelligence console — slate / graphite backgrounds, sky-blue as the primary accent and ambient glow, severity colours used like signal flags, animated pulse-glow status dots, and information density prioritised over breathing room. The aesthetic is closer to a SOC / NOC mission display than to a flat enterprise SaaS.

Colour vibe

• Dark slate base. #0F172A (deep slate) for the page, #1E293B for surfaces, #334155 for elevated surfaces and borders. Almost black, never pure black. The cool tone is consistent — no warm shadows.
• Sky blue is the brand accent — #38BDF8 is the primary action / link / focused state colour. It appears in buttons, active nav items, link text, and the "create" badge in the audit log.
• Severity is a fixed semantic system — the colours below MUST mean what they mean and nothing else.
  • Critical → Red #EF4444
  • High → Amber #F59E0B
  • Medium → Sky #38BDF8
  • Low → Emerald #10B981
• Neutral text scale — #F1F5F9 (primary fg), #CBD5E1 (secondary), #94A3B8 (muted), #64748B (placeholder / disabled). Never pure white.
• Group badges — Admin red, Standard_User accent blue, Leadership amber, Read_Only muted grey. The same severity language reappears here for status urgency.

Typography

• Outfit for all UI (headers, body, buttons, navigation). Geometric sans, friendly but precise; weights 400 / 500 / 600 / 700.
• JetBrains Mono for data — CVE IDs, IP addresses, hostnames, EXC numbers, finding IDs, code blocks. Anything you'd grep for.
• Scale is compact. Page titles 24–28px / 600 weight; section headers 16–18px / 600; body 14px / 400; data table cells 13px / 400 mono. Line-height stays tight (1.4) to preserve density.

Spacing

• 4 / 8 / 12 / 16 / 24 / 32 / 48 — a roughly 4px grid. Cards have 16–20px internal padding; rows in dense tables have 8–10px vertical padding; modals have 24px internal padding.
• Section gaps are 24–32px. Between siblings, 12–16px is the dominant rhythm.

Backgrounds

• No imagery. No hero photographs, illustrations, or marketing visuals. The page is solid #0F172A.
• Subtle sky-blue grid is allowed. A 20×20px grid at rgba(14,165,233,0.025) (.grid-bg utility) sits behind hero / empty regions. It is barely visible and never dominates.
• Surfaces use diagonal gradients, not flat fills — linear-gradient(135deg, rgba(30,41,59,0.95), rgba(51,65,85,0.9)) is the canonical card surface.

Cards and surfaces (intel-card)

• Background: diagonal gradient 135deg, rgba(30,41,59,0.95) 0%, rgba(51,65,85,0.9) 50%, rgba(30,41,59,0.95) 100%
• Border: 1.5px solid rgba(14,165,233,0.30) — sky-blue at low alpha, not slate grey
• Radius: 8px (default) / 12px (modals) / 4px (chips)
• Internal padding: 16–20px
• Resting shadow: 0 4px 12px rgba(0,0,0,0.4) + 0 2px 6px rgba(0,0,0,0.3) + inset 0 1px 0 rgba(14,165,233,0.10) (sky highlight on top edge)
• Hover: border opacity climbs to 0.50, the card lifts translateY(-2px), and gains a 0 0 30px rgba(14,165,233,0.10) ambient glow. A ::after shimmer sweeps left→right on entry.
• Stat cards add a 2px linear-gradient(90deg, transparent, #0EA5E9, transparent) rail on the top edge.

Borders

• Sky-blue at low alpha is the dominant border treatment — rgba(14,165,233,0.15) for subtle dividers, 0.25 for default, 0.40 for strong / hover. Pure slate #334155 borders appear only on tables and inputs at rest.
• Focus state: 2px sky-blue ring 0 0 0 2px rgba(14,165,233,0.15) plus the border swaps to solid #0EA5E9.
• Severity-tinted left borders are NOT a pattern — colour is carried by badges, dots, and glow.

Animation

• Pulse-glow on status dots is canonical. Every severity / SLA badge has an 8px circle that pulses box-shadow: 0 0 5px → 15px currentColor on a 2s ease-in-out loop (@keyframes pulse-glow).
• Card hover lift is 300ms cubic-bezier(0.4,0,0.2,1) with a ::after shimmer sweep — linear-gradient(90deg, transparent, rgba(14,165,233,0.08), transparent) translating from left:-100% to 100% over 500ms.
• Buttons have a circular ripple ::before that scales from 0×0 to 300×300 on hover (500ms).
• Modal entry: 200ms fade + slight translate. Slide-out panels: 240ms ease-out from the right.
• Tooltips have a deliberate 300ms hover delay before appearing.
• A .scan-line utility (3s loop) is available for hero / loading affordances — used sparingly.

Hover states

• Cards lift -2px, border opacity climbs from 0.30 → 0.50, and a sky-blue ambient glow 0 0 30px rgba(14,165,233,0.10) appears.
• Buttons brighten their gradient fill from 0.15/0.10 to 0.25/0.20 alpha, gain a 0 0 20px brand-color glow, and lift -1px.
• Text links lighten from #38BDF8 to #7DD3FC and the bottom border brightens to match.
• Table rows get a rgba(0,217,255,0.06) wash plus 0 2px 8px rgba(0,217,255,0.10) sub-shadow.
• The audit notes a current anti-pattern: hover states implemented via onMouseEnter / onMouseLeave JS handlers. The design system standard is CSS :hover pseudo-classes — JS hover is a defect to migrate away from.

Press / active states

• Button: shifts to #0EA5E9 (slightly darker than hover), no shrink, no shadow change. Press is a colour signal, not a physics signal.
• Rows / interactive cards: #475569 background on :active.

Transparency & blur

• Modal backdrops: rgba(10, 14, 39, 0.97) with backdrop-filter: blur(12px). The blur is heavy and the backdrop is near-opaque — modals fully obscure the background.
• Tooltips: gradient linear-gradient(135deg, #334155, #475569) with a sky-blue border and 0 4px 12px + 0 0 16px rgba(14,165,233,0.15) glow.
• Inputs: translucent rgba(30,41,59,0.6) background with inset 0 2px 4px rgba(0,0,0,0.2) for a subtle recessed feel.

Inner / outer shadows

• Both are used. Cards combine outer drop + inner sky-blue highlight: 0 4px 12px rgba(0,0,0,0.4), inset 0 1px 0 rgba(14,165,233,0.10).
• Inputs are recessed — inset 0 2px 4px rgba(0,0,0,0.2) plus a 0 1px 0 rgba(255,255,255,0.03) top sheen.
• Document items (within KB / vendor lists) use a stronger inset inset 0 2px 4px rgba(0,0,0,0.3) to read as nested / pressed-in.
• Modals lift on 0 20px 60px rgba(0,0,0,0.6) + 0 10px 30px rgba(14,165,233,0.10) — heavier than most enterprise products, but the brand glow is the signature.

Layout rules

• Full-width fluid above 1024px — the dashboard fills the viewport, with content max-width capping at ~1600px on very wide displays.
• Top app bar is fixed — height 56px, contains brand mark, page nav, and UserMenu. Sits above all content with z-index: 50.
• Side nav drawer (NavDrawer) slides from the left on icon click; it does not push content (overlay model).
• Slide-out panels (Atlas, Compliance Detail) come from the right, ~480px wide on desktop, full-width on narrow viewports.
• Modals are centered, max-width 640px (small) or 960px (wizard / upload), with the standard backdrop.

Severity language

This is the most important visual rule in the product. Severity badges use the status-badge pattern:

• 2px solid border at 0.6 alpha
• Diagonal gradient fill at 0.20 / 0.15 alpha
• Lighter text for legibility — #FCA5A5 (critical), #FCD34D (high), #7DD3FC (medium), #6EE7B7 (low) — not the raw severity colour
• Text-shadow 0 0 8px brand-color at 0.4 alpha
• 8px filled circle dot with a pulsing box-shadow: 0 0 12px / 0 0 6px glow on a 2s loop
• 0 4px 8px rgba(0,0,0,0.4) outer shadow
• Always JetBrains Mono, uppercase, 0.5px letter-spacing

Secondary references can use simpler tinted pills (rgba(brand,0.12) background + brand text, no border, no glow). Single coloured dots ● next to numeric scores are also valid. The colour-to-severity mapping is fixed across every component.

Headings — the brand glow

Page titles and section headers are JetBrains Mono, uppercase, sky-blue #38BDF8, with text-shadow: 0 0 16px rgba(14,165,233,0.30), 0 0 32px rgba(14,165,233,0.15). This is the most identifiable single signal in the product — every page header reads as a glowing terminal title. Outfit is reserved for body, helper, and table cell text. The Knowledge Base markdown viewer continues this language: h1 sky-blue, h2 emerald, h3 amber — a deliberate severity-coloured hierarchy.

---

ICONOGRAPHY

The product uses lucide-react as its sole icon system. Lucide is a 1.5px-stroke, geometric, open-source icon set — clean, restrained, and perfectly aligned with the dark tactical aesthetic.

Rules

• All icons are line / stroke style — never filled glyphs (with one exception: the calendar's red due-date dot is a filled circle, but it's a status indicator, not an icon).
• Stroke width: 1.5–2px (lucide default). 1.5px on small icons (≤16px), 2px on larger icons.
• Sizes: 14px (inline with text), 16px (default UI), 20px (nav items, prominent buttons), 24px (page-header icons).
• Colour: inherits currentColor — text-foreground for default, #38BDF8 for active / accent, severity colours when used as a status indicator.
• No emoji anywhere. Status, severity, and category use icons + colour; never 🔴 or ⚠️.
• No unicode-as-icon shortcuts beyond ● (status dot), ↻ (revert / cycle), ↱ (redirect), ⊙ (filter handle), → (inline link), +N (count badge). These are part of the typography, not stand-ins for missing icons.

Brand mark

The product has no published logo file in the repo (the audit references AtlasIcon as a custom SVG brand icon — Atlas appears to be the action-plan integration, not the dashboard's own brand). For this design system the brand mark is a typographic stack: STEAM in Outfit 700 with a sky-blue underline accent and a small shield glyph (lucide Shield) to the left. See assets/logo.svg and assets/atlas-shield.svg.

Substitutions flagged

• Atlas action-plan brand icon is recreated as a generic shield (lucide Shield) tinted sky-blue. If you have the real AtlasIcon SVG, please attach it — the in-product version is custom and not available from the repo URL.
• Fonts (Outfit, JetBrains Mono) load from Google Fonts CDN. If you need offline font files, attach the woff2s and we'll bundle them into fonts/.

Icons used per page (from README)

• Home: Calendar (CalendarWidget), Search, Filter, Plus, Upload, Edit, Trash, X (close)
• Reporting: RefreshCw (Sync), Eye / EyeOff (row visibility), Check, Filter (⊙ in column header), Columns, Download (Export), MoreHorizontal
• Compliance: Upload, AlertTriangle (drift breaking), AlertCircle (drift silent-miss), Info, ChevronRight, FileText
• Knowledge Base: FileText, FilePlus, Folder, Download, Eye
• Admin: Users, ScrollText (audit log), Activity (system info), Shield (admin badge)
• Universal: ChevronDown, ChevronUp, Check, X, Loader, ExternalLink

When picking an icon, prefer the lucide-react name from this list before introducing a new one.

---

UI Kits

Kit	Path	What it covers
cve-dashboard	ui_kits/cve-dashboard/	App shell (top bar, nav drawer, user menu), Knowledge Base page + viewer, primitives (Button, Badge, Pill, Input, Select, Modal shell, SlideOutPanel, DataTable, GroupBadge, SeverityBadge, EmptyState, LoadingState)

The Knowledge Base page is the focused recreation. Other surfaces (Reporting, Compliance, Admin) are intentionally not built out — the primitives + shell are sufficient to compose them.

---

How to use this system

1. Tokens first. Import colors_and_type.css into the root of any HTML file. All colour, type, radius, shadow, and spacing decisions should pull from these CSS custom properties.
2. Pick a primitive before inventing. Severity badges, group badges, status pills, table row, modal shell, slide-out panel — they all live in ui_kits/cve-dashboard/.
3. Match the density. When in doubt, tighter is more on-brand than airier.
4. Lucide for icons. Use the lucide-react CDN or copy individual SVGs from the lucide site. Do not draw your own.
5. No emoji, no gradients, no illustration, no marketing copy. The product is a console.