blackrim/cobalt Design Tokens¶
Canonical reference. Every value here is the single source of truth for the
blackrim/cobaltdesign system. The MkDocs stylesheet (docs/stylesheets/extra.css) and the Tailwind preset (packages/design-tokens/tailwind.preset.js) both derive from this document. When a token changes, update this file first.
The blackrim/cobalt system is applied across three surfaces:
- Docs site (
blackrim-vox.dev) — MkDocs Material; seedocs/stylesheets/extra.css - Marketing site — future; consumes
@blackrim-vox/design-tokensTailwind preset - Commercial / enterprise admin console — future; same preset
Brand¶
--brand-primary¶
The primary interactive color. Buttons, links, focus rings, active nav items.
| Mode | Value | Swatch |
|---|---|---|
| Light | #2563EB |
|
| Dark | #60A5FA |
--brand-primary-hover¶
Hover/active state of the primary color. Pressed buttons, hovered links.
| Mode | Value | Swatch |
|---|---|---|
| Light | #1D4ED8 |
|
| Dark | #3B82F6 |
--brand-accent¶
Amber accent. Callouts, highlights, the "beta" badge, attention-grabbing UI elements.
| Mode | Value | Swatch |
|---|---|---|
| Light | #F59E0B |
|
| Dark | #FBBF24 |
--brand-deep¶
The blackrim. Dark chrome, sidebars, hero backgrounds. Both modes.
| Mode | Value | Swatch |
|---|---|---|
| Light + Dark | #0A0A14 |
Neutrals (Slate Scale)¶
--surface¶
Page background. Pure white in light mode; blackrim-deep in dark mode.
| Mode | Value | Swatch |
|---|---|---|
| Light | #FFFFFF |
|
| Dark | #0A0A14 |
--surface-muted¶
Subtle background for code blocks, sidebars, inset regions.
| Mode | Value | Swatch |
|---|---|---|
| Light | #F8FAFC |
|
| Dark | #111827 |
--surface-elevated¶
Cards, popovers, dialogs — slightly lifted from the base surface.
| Mode | Value | Swatch |
|---|---|---|
| Light | #FFFFFF |
|
| Dark | #1F2937 |
--border¶
Dividers, input outlines, table rules.
| Mode | Value | Swatch |
|---|---|---|
| Light | #E2E8F0 |
|
| Dark | #374151 |
--text¶
Primary body text. High-contrast in both modes.
| Mode | Value | Swatch |
|---|---|---|
| Light | #0F172A |
|
| Dark | #F8FAFC |
--text-muted¶
Secondary text, captions, metadata.
| Mode | Value | Swatch |
|---|---|---|
| Light | #475569 |
|
| Dark | #CBD5E1 |
--text-subtle¶
Placeholder text, disabled states, decorative labels. Same in both modes.
| Mode | Value | Swatch |
|---|---|---|
| Light + Dark | #94A3B8 |
Semantic¶
--success¶
Confirmations, passing tests, healthy status indicators.
| Mode | Value | Swatch |
|---|---|---|
| Light | #10B981 |
|
| Dark | #34D399 |
--warning¶
Deprecation notices, partial support, caution states.
| Mode | Value | Swatch |
|---|---|---|
| Light | #F59E0B |
|
| Dark | #FBBF24 |
--error¶
Failures, errors, destructive actions, broken states.
| Mode | Value | Swatch |
|---|---|---|
| Light | #EF4444 |
|
| Dark | #F87171 |
--info¶
Informational callouts, tips, neutral notifications.
| Mode | Value | Swatch |
|---|---|---|
| Light | #0EA5E9 |
|
| Dark | #38BDF8 |
--roadmap¶
Planned / roadmap items, the ✅🔬🛣️ feature matrix. Purple signals "coming" without confusion with status colors.
| Mode | Value | Swatch |
|---|---|---|
| Light | #A855F7 |
|
| Dark | #C084FC |
Typography¶
| Role | Family | Weights | Notes |
|---|---|---|---|
| Display | Inter | 700 / 800 | letter-spacing: -0.02em on h1 |
| Body | Inter | 400 / 500 | System fallback: system-ui, sans-serif |
| Mono | JetBrains Mono | 400 / 700 | Code blocks, inline code, CLI examples |
Both fonts are loaded from Google Fonts. The @import lives in docs/stylesheets/extra.css.
Spacing¶
Base unit: 4px (Tailwind defaults). All spacing scales in multiples of 4.
| Token | Value | Usage |
|---|---|---|
xs |
4px | Icon padding, tight inline gaps |
sm |
8px | Component internal padding |
md |
16px | Card padding, section gaps |
lg |
24px | Section separators |
xl |
32px | Page-level breathing room |
2xl |
48px | Hero, marketing section spacing |
Radii¶
--r-sm: 6px /* Inputs, small buttons, badges */
--r-md: 10px /* Cards, panels, modals */
--r-lg: 16px /* Hero cards, large surfaces */
Shadows¶
Subtle only. No dramatic drop-shadows — depth is implied by --surface-elevated background.
--shadow-card: 0 1px 3px rgba(0,0,0,.04), 0 1px 2px rgba(0,0,0,.06)
Use sparingly: cards, popovers, and dropdowns only.
Why these choices¶
The cobalt+amber B2B trust pair: cobalt (--brand-primary) reads as reliable and technical — the default register for developer tooling, compliance tooling, and enterprise dashboards. Amber (--brand-accent) injects warmth and signals attention without the alarm connotations of red or orange. Together they communicate "this is serious infrastructure that won't embarrass you in a procurement review."
--brand-deep is #0A0A14, not #000000. Pure black is harsh and creates halo artifacts on OLED displays. The near-black with a blue undertone aligns brand-deep with the cobalt family and prevents the "void" effect that pure black surfaces produce in dark mode.
Slate over zinc: the slate scale has a cooler, bluer undertone than zinc. For a product built around audio, voice, and language — which live in a cooler perceptual register — slate surfaces read as calm and precise. Zinc reads slightly warmer and more "app-like"; slate reads more "infrastructure."
Three surface variants (--surface, --surface-muted, --surface-elevated) give the UI enough layering to express hierarchy — hero behind nav behind card behind popover — without resorting to heavy shadows or stark borders.
--roadmap purple complements the existing ✅🔬🛣️ feature matrix: green for shipping (success), amber for alpha (warning), purple for roadmap. Purple is visually distinct from all three status colors (success/warning/error) and has no negative connotation, making it the natural "planned" signal.