Bulwark/DESIGN.md

DESIGN.md

Design system reference for Bulwark, a Security Operations Center (SOC) dashboard.

Aesthetic Profile: Auditor Professional

A high-density, dark-mode-only interface inspired by GitHub Settings, Vercel Dashboard, and Linear. No shadows, gradients, or decorative elements. Focus on borders, grid lines, and clear visual hierarchy.

Color Palette

Base

Monochromatic zinc scale. All surfaces use dark palette directly (no dark: variants).

Role	Token	Usage
Background	zinc-950	Body, sidebar, header, status bar
Surface	zinc-900	Cards, panels, active nav items
Border	zinc-800	All dividers, card borders, table lines
Muted text	zinc-500	Labels, secondary text, inactive nav
Body text	zinc-300	Standard content text
Emphasis	zinc-100	Headings, active items, primary text

Semantic Accents

Color is strictly reserved for severity and status indicators. Never use for decoration.

Severity	Color	Badge Label	Usage
Critical	red-500	CRT	Border, bg, text at 10%/20%
High	orange-500	HI	Border, bg, text at 10%/20%
Medium	yellow-500	MED	Border, bg, text at 10%/20%
Low	green-500	LOW	Border, bg, text at 10%/20%
Info	zinc-500	INF	Border, bg, text at 10%/20%

Status Colors

Status	Color	Usage
Connected	green-500	Status bar dot + text
Processing	sky-500	Scan badge with spinner
Completed	green-500	Scan badge
Failed	red-500	Scan badge
Cancelled	zinc-500	Scan badge with line-through

Typography

Role	Font	Weight	Size
UI text	Inter	400-600	text-sm
Technical data	JetBrains Mono	400-500	text-xs
Micro labels	JetBrains Mono	500	text-xxs
Headings	Inter	600-700	text-lg+

Custom size text-xxs = 0.625rem / 0.875rem defined via @theme in app.css.

Fonts loaded via Google Fonts <link> in root.html.heex.

Density

• Row padding: py-1.5 (table cells), py-2 (nav items)
• Card padding: p-5
• Max border radius: rounded-md
• Borders: border-zinc-800 (1px solid)
• No shadows anywhere

Layout

App Shell

• Sidebar: 52px collapsed / 180px expanded (desktop). Full-width overlay on mobile. Controlled by data-expanded attribute + CSS, decoupled from LiveView DOM patching.
• Header: 48px (h-12). Breadcrumbs left, system integrity pulse right.
• Main: flex-1 overflow-y-auto. Dot-grid background pattern (radial-gradient).
• Status Bar: 28px (h-7). Connection status, sync timer, pipeline health, uptime counter.

Navigation

Section	Icon	Path
Dashboard	hero-chart-bar-square	/
Scans	hero-arrow-up-tray	/scans
Vulnerabilities	hero-shield-exclamation	/vulnerabilities
Findings	hero-magnifying-glass-circle	/findings
Assets	hero-server-stack	/assets

Active state: bg-zinc-900 text-zinc-100. Inactive: text-zinc-500 hover:text-zinc-300 hover:bg-zinc-900/50.

Components

Stat Card

Dark card with colored left accent border matching the metric's severity/status color. Mono label, large numeric value, optional trend indicator.

Data Table (.data-table)

Sticky header with backdrop-blur-sm. Mono uppercase column headers at text-xxs. Dividing lines via divide-y divide-zinc-900. Link style: underline decoration-zinc-700 hover:decoration-zinc-500.

Badges

Severity: 3-letter mono labels with colored border/bg at low opacity. Scan status: similar pattern with semantic colors. Finding status: short labels (Open, Ack, Fixed, FP) in zinc tones.

Pagination (.pagination)

Compact mono-spaced page numbers. Active page: bg-zinc-800 text-zinc-100 border border-zinc-700. Disabled: text-zinc-700.

Animations

• Integrity pulse: 2s ease-in-out infinite on system status dot
• Sidebar transition: width 0.15s ease
• Processing spinner: animate-spin on hero-arrow-path icon

Scrollbar

Custom webkit scrollbar: 6px width, zinc-950 track, zinc-800 thumb, zinc-700 hover.

Accessibility

• WCAG 2.2 AA compliance
• aria-current="page" on active nav item
• aria-label on icon-only buttons
• aria-live="polite" on flash container
• Keyboard navigable sidebar and triage actions
• Focus-visible outlines on interactive elements