v2.0

Cave Design

A severity-driven design language for infrastructure engineers who manage at scale. Design for the 3AM page that wakes you up.

Attention-Driven · 10:1 visual weight Temporal · Duration at a glance Keyboard-Native · ≤2 keystrokes
Foundation

Color System

Cave Palette

#080b10

950 · Overlay

#0d1117

900 · Page bg

#111820

850 · Input bg

#161b22

800 · Card bg

#1c2128

750 · Hover

#21262d

700 · Borders

#30363d

600 · Heavy

Text Colors

Primary — text-white

Body — cave-100 #c9d1d9

Secondary — cave-300 #8b949e

Tertiary — cave-400 #6e7681

Labels / disabled — cave-500 #484f58

Link — text-indigo-400

Severity Colors
Critical 5 signals: pulse + glow + sweep + border + tint
#ff4757
High Slow pulse + subtle glow
#ff6b35
Medium Static dot + tinted background
#ffa801
Healthy Small static dot, neutral bg — recedes
#2ed573
Muted / Unknown Deeply muted, fades away
#484f58
Transitional States
Deploying
Scaling
Migrating
Draining
Service Types & Providers
Web Database Cache Worker GPU
Fly.io RunPod Self-hosted
Foundation

Typography

Round text = label (Outfit). Square text = data (JetBrains Mono).

Page Title text-2xl font-bold tracking-tight
Section Header text-lg font-semibold
Card Title text-sm font-medium
Body text — the quick brown fox text-sm cave-100
Secondary text — metadata text-xs cave-300
Section Label 10px uppercase tracking-widest cave-500
fly.io/api:v2.4.0 font-mono cave-200 (tech values)
4m 22s · uptime 14d 10px font-mono cave-400 (temporal)
Foundation

Spacing & Radius

Spacing Scale
4px
gap-1
8px
gap-2 / p-2
12px
p-3 (card)
16px
p-4 / px-4
24px
p-6 / space-y-6
32px
mb-8 (page header)
Border Radius
rounded 4px — badges, compact inputs
rounded-lg 8px — buttons, inputs, icons
rounded-xl 12px — cards, modals, toasts
rounded-full 50% — status dots
Severity

Attention Hierarchy

A healthy card and a critical card must never look similar. 10:1 visual weight ratio.

Healthy — Recedes
api-gateway web
3/3 · 99.9% · 12ms p95
Critical — Demands Attention
ml-inference critical
0/2 down · 4m 22s
5-Signal System (Critical Only)
1. Saturated color + 8% tinted bg 2. Red border at 25% opacity 3. Glow shadow (glow-critical) 4. Pulsing dot at 1.2s (pulse-critical) 5. Gradient sweep (attention-sweep)
Severity

Density Modes

Toggle with D 1, D 2, D 3. All modes maintain severity hierarchy.

Compact D 1 · Max services per screen
api-gateway 3
postgres-primary 1
ml-inference 0/2
redis-cache 2
Default D 2 · Name + count + type + duration
api-gateway 3/3 · web
ml-inference 0/2 · down 4m
redis-cache 2/2 · cache
Relaxed D 3 · Full metadata + icon + provider
api-gateway 3/3 healthy · web · Fly.io
ml-inference 0/2 · down for 4m 22s
Severity

Temporal Patterns

"How long has this been broken?" — answered at a glance, always inline.

DurationFormatColorPsychology
< 10 min 4m 22s Severity color Active — act now
10m – 6h 2h 14m High orange Extended — escalate?
6h – 7d 3d 6h Medium amber Chronic — accepted?
Stable uptime 14d Healthy green Stable — go back to sleep
Duration Appears Inline
Card: 0/2 down · 4m 22s
Status bar: uptime 14d 6h
Palette result: critical · 0/2 · 4m 22s
Toast: ml-inference is down 4m 22s
Severity

Glanceable Patterns

Assess fleet health in under one second. Designed for second-monitor peripheral vision.

System Health Bar

Lives at the top of every page. Green bar = go back to sleep. Any red = wake up.

1 Critical
1 Degraded
8 Healthy
10 services · 24 instances
Fleet Grid

Each square = one service. Red pulsing square pulls your eyes without direct focus.

Components

Buttons & Actions

Every action ≤2 keystrokes away. Buttons show their shortcuts.

Design Rule On pages showing service status, buttons should recede. The loudest elements should be severity indicators, not action buttons. Reserve primary (indigo) for focused contexts like modals and detail panels.
Actions with Keyboard Shortcuts
Secondary ← default for layout
Primary — modals/panels
Ghost / Text
View logs →
Icon Buttons
Destructive
Components

Inputs

Standard Input
Select
Compact Input
Port
CPU
Memory
Error State

Service name is required

Key-Value (Environment Variables) + Add
Components

Badges & Tags

Type Badges
web critical deploying v2.4.0
Version & Status
v2.0 stable beta
Keyboard Hints
⌘ K esc ↵ ⌘ D ← on primary buttons
Components

Checkboxes & Selection

Selection Items
Toggles
Components

Accordion — Multi-Step Wizard

Used in deploy flows. CSS-animated, with step indicators and various input types.

Image Source
Select Deploy Target
Instance Configuration
Content Patterns Inside Accordion
Tag Selection
latest
Or custom:
Config Grid
Environment Variables + add
Multiline Input
Action Footer
Step Indicators
Completed
Active
3
Pending
Components

Service Cards — Full Spectrum

Sparklines, temporal context, severity-driven visual weight, transitional states

api-gateway web
3/3 · 99.9% · 12ms p95
redis-cache cache
1/2 degraded · 8m
ml-inference critical
0/2 down · 4m 22s
auth-service
deploying
v2.3.1 → v2.4.0
background-worker scaling
scaling 6 → 10 · auto
+4
legacy-cron custom
no data · last seen 2h ago
Sparkline Specification
Bar: 3px wide Gap: 1px Height: 24px Min bar: 2px Points: 8–12 Healthy cards: opacity-30 → hover opacity-60
Stable
Crash trajectory
Degraded
Components

Status Indicators

Status Dots (By Severity)
Healthy — size="sm" static
Medium — size="sm" static
High — size="md" pulse
Critical — size="md" auto-pulse
Deploying — pulse
Unknown — size="sm" static
Instance Dots & Status Bars
3/3 running
1/2 healthy
+4 8/8 running
Components

Sparklines

Inline trend visualizations. Answer "is it getting worse?" at a glance.

Property Value
Bar width 3px (w-[3px])
Bar gap 1px (gap-px)
Container height 24px (h-6)
Bar radius 1px (rounded-sm)
Min bar height 2px (min-h-[2px])
Data points 8–12 recommended
Stable Trend
bg-[#2ed573]/60
Crash Trajectory
Color shifts with severity
Context Bar Color
Healthy trend bg-[#2ed573]/60
Medium/degrading bg-[#ffa801]
High bg-[#ff6b35]
Critical/down bg-[#ff4757]
Selected card bg-indigo-400/50
Components

Loading & Empty States

Spinner
Deploying...
Icon Spinner
Skeleton

No services yet

Add your first service to get started

or
Components

Empty States

Friendly guidance when there's no data to show.

No services yet

Add your first service to get started

or Create your first service
Components

Modals

Primary buttons reserved for focused contexts like modals where the user has committed their attention.

Add Service
esc
Modal Widths
max-w-sm — 384px max-w-md — 448px (default) max-w-lg — 512px max-w-2xl — 672px
Components

Actionable Toasts

One click from "something's wrong" to "I'm fixing it." Actions embedded inline.

ml-inference is down 4m 22s

0/2 instances responding. Last healthy: 14:32:18 UTC

redis-cache memory at 91%

Projected to hit limit in ~45 min

api-gateway deployed

v2.3.1 → v2.4.0 · 3/3 healthy · 18s

Deployment started

api-gateway is being deployed to us-east-1

Components

Alert Banners

Full-width, top of page. Critical banner appears above the health bar.

2 services down · ml-inference, gpu-worker
4m ago
High memory · postgres-primary at 87%
12m ago
All systems operational · 10 services healthy
Components

Command Palette

⌘K to access any service, action, or navigation in ≤2 keystrokes.

esc
Services
api-gateway
3/3 ↵ to select
ml-inference-api
0/2 · 4m
Actions
Deploy api-gateway
⌘D
View logs for api-gateway
L
Navigation
Dashboard
G D
Settings
G S
↑↓ navigate ↵ select esc close
Global Shortcuts
⌘K Open palette / Focus search ? Show shortcuts
Components

Service Detail Panel

Slide-in panel with temporal context, quick actions with keyboard shortcuts, and activity timeline.

api-gateway web · fly.io · us-east-1
esc
Healthy · 3/3
for 4d 12h
12ms p95 latency
99.97% uptime 30d
842 req/s
Recent Activity
2m
Health check passed (instance 3)
1h
Deployed v2.4.0 (was v2.3.1)
3d
Scaled from 2 → 3 instances
Configuration Edit
Image fly.io/api:v2.4.0
Port 8080/tcp
Resources 1 vCPU · 256 MB
Environment + Add
DATABASE_URL ••••••
REDIS_URL ••••••
API_KEY ••••••
Panel Keyboard Shortcuts
D Deploy R Restart L Logs C Configure esc Close panel
Activity Timeline Dot Colors
Health check
Deployment
Scaling
Incident
Warning
Patterns

Layout Patterns

Standard page structures and responsive grid patterns.

Page Structure
Workspace
Critical alert banner (conditional)
Health bar
Page Title
+ Add
Two-Column Layout (List + Detail)
api-gateway
postgres (selected)
ml-inference
Detail Panel w-[384px] shrink-0
Dashboard Grid
Service card
Service card
Critical
Service card
Degraded
Service card

grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-3

Grouped Lists
api-gateway
auth-service
frontend
ml-inference 0/2
Patterns

Interactive States

Consistent hover, focus, selected, and disabled states.

Transitions
transition-colors Color changes (buttons, links)
transition-all duration-300 ease-out Slide/fade (panel open/close)
transition-all duration-200 ease-out Quick state changes
transition-opacity Sparkline reveal
Hover States
bg-[#21262d] → hover:bg-[#30363d] Buttons
hover:bg-[#161b22]/60 Cards
text-indigo-400 → hover:text-indigo-300 Links
opacity-0 group-hover:opacity-100 Icon buttons, delete actions
opacity-30 group-hover:opacity-60 Sparklines on healthy cards
Selected States
Selected Card
bg-indigo-500/10 border-indigo-500/30 ring-1 ring-indigo-500/20
Focus States

Double-ring pattern for visibility on all background shades:

focus:border-indigo-500/50 focus:ring-1 focus:ring-indigo-500/20
Disabled States
disabled:bg-[#21262d] disabled:cursor-not-allowed disabled:text-[#484f58]
Patterns

Animation Patterns

Motion for severity, attention, and state changes.

Severity Pulse
Critical (1.2s)
High (2s)
Deploying (Tailwind pulse) 
@keyframes severity-pulse {
  0%, 100% { opacity: 1; }
  50% { opacity: 0.4; }
}
.pulse-critical { animation: severity-pulse 1.2s ease-in-out infinite; }
.pulse-high { animation: severity-pulse 2s ease-in-out infinite; }
Glow Effects
glow-critical
glow-high 
.glow-critical { box-shadow: 0 0 12px -2px rgba(255, 71, 87, 0.3); }
.glow-high { box-shadow: 0 0 12px -2px rgba(255, 107, 53, 0.2); }
Attention Sweep (Critical Cards)
Critical card with sweep animation 
@keyframes attention-sweep {
  0% { transform: translateX(-100%); }
  100% { transform: translateX(200%); }
}
.attention-sweep::after {
  content: '';
  position: absolute;
  inset: 0;
  background: linear-gradient(90deg, transparent, rgba(255,71,87,0.15), transparent);
  animation: attention-sweep 3s ease-in-out infinite;
}
Tailwind Utilities
animate-spin Loading spinners
animate-pulse Transitional states (deploying, scaling)
Reference

Border Radius

Consistent radii. Cards = rounded-xl. Buttons/inputs = rounded-lg. No mixing.

Element Class Value
Cards, panels, modals rounded-xl 12px
Buttons rounded-lg 8px
Inputs rounded-lg 8px
Compact inputs rounded 4px
Badges, tags rounded 4px
Status dots rounded-full 50%
Icon containers rounded-lg 8px
Fleet grid squares rounded-lg 8px
Toasts rounded-xl 12px
Reference

Icons — Heroicons v2.2.0

x-mark
plus
pencil
trash
check
error
info
warning
settings
search
deploy
refresh
server
database
globe
cpu
cube
bolt
clock
chart
eye
signal
key
lock
Reference

Keyboard Shortcuts

Every major action ≤2 keystrokes. Shown on buttons so engineers learn passively.

Action Shortcut Context
Command palette
⌘ K
Global
Close
esc
Global
Search
/
Global
Density modes
D 1 D 2 D 3
Global
Deploy
⌘ D
Service
Restart
⌘ R
Service
Navigate list
↑ ↓ or J K
List / Palette
Reference

Z-Index Scale

Layering hierarchy for overlapping elements.

Layer Value Usage
Command palette z-50 ⌘K overlay
Modal overlay z-50 Modals, dialogs
Toast container z-50 Flash messages, alerts
Dropdown z-40 Menus, popovers
Sticky header z-30 Navigation
Default z-auto Normal flow
Reference

Best Practices

Guidelines for maintaining consistency across Cave UI.

Do
Use severity colors to communicate urgency
Include temporal context (4m 22s) inline on all status changes
Use sparklines to show trends at a glance
Make healthy services visually recede
Show keyboard shortcuts on buttons
Use actionable toasts with likely next action
Use font-mono for all technical values
Use flex-shrink-0 on icons and status dots
Add min-w-0 to flex children that should truncate
Use named classes (glow-critical, pulse-critical)
Don't
Treat all services with equal visual weight
Hide duration behind a detail view
Use only color to communicate status
Create new gray shades outside cave palette
Use primary buttons on status pages
Use modals when slide-in panels work
Require mouse for common actions
Skip hover states on interactive elements
Mix rounded-lg and rounded-xl on cards
Use inline shadow-[...] when named glow exists
Reference

Sound UX

Crisp, high-frequency audio feedback for precision and accuracy. Sounds use Web Audio API with square wave oscillators in the 8-14kHz range.

Philosophy

• Crisp & Precise — High-frequency sounds (8-14kHz) convey precision and accuracy

• Symmetrical — Appear sounds sweep up, disappear sounds sweep down

• Immediate — Click sounds trigger on mousedown (touch), not click (release)

• Non-intrusive — Sounds skip initial page render to avoid startling users

Action Sound Frequency Duration
Click (mousedown) Crisp Tick 12kHz 6ms
Scroll Crisp Tick 12kHz 6ms
Tab close Single Tick 8kHz 8ms (40ms delay)
Notification appear Crisp Rise 8kHz → 14kHz 25ms
Notification manual close Single Tick 8kHz 8ms (40ms delay)
Notification auto-dismiss Crisp Fall 14kHz → 8kHz 25ms
Delete Exhale Filtered noise + A2 150ms
Do
Use symmetrical rise/fall for appear/disappear
Trigger click sounds on mousedown for immediacy
Skip sounds during initial page render
Keep volumes low (0.04 gain)
Use exponential ramps for natural decay
Don't
Play sounds on page load
Use low frequencies for UI feedback
Double-trigger sounds on same action
Use long duration sounds for clicks