training/skills/hallmark/references/themes/cobalt.md

Theme — Cobalt

Modern-minimal, dev-tool register. The page for an API, an SDK, a CLI, a docs home, a developer platform — the GitBook / Firecrawl / Vercel school, executed in cool cobalt-on-light, not orange. A calm cool-white ground, ruler-drawn hairlines, exactly ONE electric cobalt signal accent, and code as the hero. It reads like good infrastructure: calm, precise, fast.

Loaded eagerly by SKILL.md Step 3 whenever the catalog pick is cobalt. The OKLCH palette + font stack live in site/css/tokens.css under [data-theme="cobalt"]. Canonical build: site/examples/cobalt-01/ (an API product landing with a request/response hero).

Why not orange. GitBook and Firecrawl both converged on orange-as-signal — but that lane is now crowded, and Hallmark's warm slots are already taken (Lumen brass, Bloom terracotta, Coral coral). Cobalt keeps their discipline (cool ground + one signal + code-as-hero + hairlines) and aims the signal at the open electric-blue lane instead. The blue is the differentiator, not a copy.

Axes (diversification)

• Paper band — cool light (L 98.5%, hue ~250, very low chroma). An engineered near-white — distinct from Coral's warm grey and from the genre's dark grounds.
• Display style — grotesk-sans (Space Grotesk 500/600 — slightly mechanical, tight tracking). Distinct from Geist (Coral) and from every serif/rounded option.
• Accent hue — electric cobalt (oklch(58% 0.20 256)). High-chroma true blue — reads "API-live," sits clear of Midnight/Lumen's dusky indigos (~250/268). Used as a signal, never a flood.

Reference register

GitBook · Firecrawl · Vercel / Geist · Linear · Mintlify · Stripe docs · Resend · Clerk · Railway · Supabase.

The aesthetic: the developer-product landing and docs home — a cool engineered canvas, one signal accent, code/terminal/API as the focal element, hairline structure, a ⌘K-flavoured nav. Never name any of these in the output.

Patron-saint reference (internal): Vercel's blueprint-and-mono restraint + Firecrawl's live request-result credibility move, recoloured cobalt. When in doubt, ask "does this read like an instrument panel, or like a marketing template?" Keep the former.

Required dependencies

1. Fonts — Space Grotesk (display, 500/600), Inter (body, 400/500), JetBrains Mono (code + small UPPERCASE labels). All-sans; no serif anywhere. Google Fonts:

   <link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet" />
   

2. A small reveal script — one IntersectionObserver adding .is-in (fade + ~10px rise, ease-out ~600ms). Plus a one-shot "type-in" of a single line in the hero code demo, then static.
3. A working ⌘K command palette — a small JS overlay that opens on click and ⌘K / Ctrl+K (Esc or backdrop closes; Arrow↑/↓ select; type-to-filter), role="dialog" / aria-modal, focus-managed, reduced-motion safe. The ⌘K in the nav actually works — Cobalt's signature interactive move.

The signature moves

1. Cool engineered paper, never #fff — oklch(98.5% 0.004 250). Ink is cool charcoal oklch(24% 0.02 258), never #000. Body text sits a notch lighter (oklch(34% 0.018 257)).

2. Hairlines do the work — 1px --color-rule borders define every surface. No boxed cards, no drop-shadows beyond a single barely-there 0 1px 2px lift on the code card. Depth comes from borders, not blur.

3. One cobalt signal, used sparingly (< 5% of any viewport) — the eyebrow tick, a link's hover underline, the one primary button, focus rings, the 200 OK chip, the active nav item. Everything else is ink-on-cool-white.

4. Code is the hero — a dark graphite card (oklch(22% 0.016 260)) with a window bar (3 dots + a filename), syntax tokens (cobalt for methods/keys, light for strings, muted for punctuation), and a status chip. One line types in once, then static. Either a live API request/response (POST + JSON 200 OK) or a terminal (install + a clean PASS run). Title + lede sit LEFT; the demo sits RIGHT — asymmetric, never centred.

5. Bordered nav + a working ⌘K palette — a flush full-width bar, single hairline bottom border, light blur on scroll. Wordmark + 2–3 text links left; a bordered ⌘K affordance + one solid cobalt button right. The ⌘K opens a real command palette (mono search + command rows; click or ⌘K/Ctrl+K; Esc to close) — the page behaves like a dev tool, not just looks like one. Not a floating pill (softer, and Coral's vocabulary).

6. Tight technical radii — 6px on buttons/inputs, 10px on code cards. Not Coral's soft pills, not 0px brutalism — "drawn with a ruler."

7. Mono labels — eyebrows, meta, status, kbd hints in JetBrains Mono, UPPERCASE, 0.06em tracking. The machine-readout voice against the Space Grotesk display.

8. One dark graphite band per page — a single full-bleed dark section (a quickstart, a how-it-works, a watch-mode demo) on oklch(~20% 0.016 260) with light cool text and the cobalt accent popping. It gives the page a light → dark → light rhythm and a showcase moment. The page's one dark beat — Cobalt is a light theme with a dark band, never a dark theme.

Motion

Composed and sparse. The one hero type-in (plays once). Section reveals fade + rise. Hover: cobalt underline-grow on nav/links; a 1px border-colour shift to cobalt on the code card / focusable surfaces. No bounce, no parallax, no autoplay. Everything gates behind prefers-reduced-motion: no-preference; reduced-motion ships static + fully visible.

Anti-patterns

• No orange accent — the crowded GitBook/Firecrawl lane and a collision with Lumen/Bloom/Coral. Cobalt is blue.
• No warm paper — warm grey is Coral's. Cobalt is cool (hue ~250–258).
• No pure #fff / #000. Cool near-white paper, cool charcoal ink.
• No pill / gradient CTAs. One solid cobalt button at 6px radius + understated typographic links. Name the destination.
• No centred-everything hero (gate 6) — left-biased, title-left / demo-right.
• No three-equal-icon-tile feature grid (gate 3) — vary it (one wide code example + narrower points; asymmetric benchmark figures).
• No glassmorphism, no gradient text (gates), no aurora/mesh blob, and no background texture/pattern at all — cool paper + hairlines carry the page; its one dark beat is the graphite band (signature 8), not a background.

Macrostructure affinity

Cobalt loves these.

• SaaS / API Product — hero + quick-start code + feature rows + pricing/CTA (canonical — cobalt-01)
• Dev-tool / CLI — terminal hero + install + benchmark figures + docs CTA
• Docs home — a calm index with a search-first nav
• Workbench — the technical, tool-first shape
• Marquee — when the hero is one confident code demo

Macrostructure rejection

Cobalt refuses these.

• Letter — too intimate; Cobalt is a product, not a note
• Manifesto — too loud; Cobalt is calm infrastructure
• Photographic / image-led — Cobalt leads with code, not imagery
• Long Document — prose-led; route warm-editorial instead

Voice fixtures

Declarative, technical, specific. Name the X concretely. No hype adjectives.

• "Turn any website into clean Markdown for LLMs."
• "One API. Every page."
• "From idea to production in an afternoon."
• "Type-safe by default. Fast by design."
• "Built to ship — 200 OK in under 200 ms."

Never any of: seamless, robust, cutting-edge, leverage, synergy, revolutionary, unlock, supercharge. Never "click here." Name the endpoint, the command, the number.

How Cobalt differs from neighbouring themes

vs	difference
Coral (modern-minimal sibling)	Coral is warm-grey paper + warm coral accent + Geist + soft pills + a quiet title/lede hero. Cobalt is cool-white + electric blue + Space Grotesk/JetBrains Mono + tight bordered controls + a live code hero. Same genre, opposite temperature — the rotation walks between them.
Midnight (atmospheric)	Both live near hue 250–258, but Midnight is a dark canvas (atmospheric, numbered display, typewriter reveals). Cobalt is a light engineered canvas (modern-minimal, code hero). Light vs dark settles it instantly.
Lumen (atmospheric)	Lumen is a dark (or cool-bone) apparatus page with Instrument Serif + an emit/refract focal artefact. Cobalt is light, all-sans, and its focal element is a literal code/API card, not a built light-instrument.
Aurora (atmospheric)	Aurora is dark cyan blooms + Sentient serif body. Cobalt is light, hairline-structured, cobalt-on-white — no blooms, no serif.

Test brief expectations

Cobalt should be a candidate when the brief mentions:

• API · SDK · CLI · dev tool · developer platform · docs · documentation · infrastructure · backend · database · observability · webhooks · type-safe · open-source tool · ship · deploy · developer experience · B2B developer
• Product categories: API · developer tool · dev platform · docs site · infra · SaaS-for-engineers
• Emotional tone: precise · engineered · fast · technical · instrument-panel · calm-confident · cool

Briefs that are warm / consumer / editorial / image-led route elsewhere (Coral for warm SaaS, the editorial themes for content). When the brief is for developers and wants to show the code, it's Cobalt.

Build hint

The first lines of CSS establish Cobalt's anchor moves:

html, body { overflow-x: clip; }
body { background: var(--color-paper); color: var(--color-ink-2);
       font-family: var(--font-body); font-weight: 400; }

/* Reveal — the whole motion engine */
.reveal { opacity: 0; transform: translateY(10px);
          transition: opacity .6s cubic-bezier(0.16,1,0.3,1),
                      transform .6s cubic-bezier(0.16,1,0.3,1); }
.reveal.is-in { opacity: 1; transform: none; }

/* The code hero — dark graphite card, hairline-framed */
.code-card { background: var(--color-graphite); border: 1px solid var(--color-rule-2);
             border-radius: 10px; box-shadow: 0 1px 2px oklch(24% 0.02 258 / 0.05);
             font-family: var(--font-mono); }
.code-card .tok-key, .status--ok { color: var(--color-accent); }   /* the one signal */
.status--ok { font: 500 0.75rem/1 var(--font-mono); letter-spacing: .06em; }

/* Bordered nav + the one cobalt button (6px, never a pill) */
.nav { border-bottom: 1px solid var(--color-rule); backdrop-filter: blur(8px); }
.btn--primary { background: var(--color-accent); color: var(--color-accent-ink);
                border-radius: 6px; }

@media (prefers-reduced-motion: reduce) {
  .reveal { opacity: 1; transform: none; transition: none; }
}

Plus the Space Grotesk + Inter + JetBrains Mono link and the small reveal/type-in script. The canonical build to mirror is site/examples/cobalt-01/.