Docs
v2.0

Cave Language

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 Peripheral Vision · Second monitor ready Density · 3 modes, 1 keystroke
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

Loading & Empty States

Spinner
Deploying...
Icon Spinner
Skeleton

No services yet

Add your first service to get started

or
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
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
Cave Language v2.0
View Concepts