---
name: mercury-design
description: "This skill should be used when the user explicitly says 'Mercury style', 'Mercury design', '/mercury-design', or directly asks to use/apply the Mercury design system. NEVER trigger automatically for generic UI or design tasks."
version: 1.0.0
allowed-tools: [Read, Write, Edit, Glob, Grep]
---

# Mercury Design Language

Editorial fintech. Banking-grade data density softened by serif restraint.

## 1. Philosophy

Mercury looks like a magazine that happens to be a bank. The tension at the core is between **dense product data** (multi-account dashboards, transaction tables, wire-transfer forms, treasury reporting) and **editorial calm** (Tiempos serif headlines, near-white canvases, copy that says "banking as it should be" instead of "next-gen financial platform"). The design lineage runs through Klim Type Foundry's typographic confidence, Swiss editorial layout, and the small movement of fintechs that refused to default to cold tech blue.

The primary tension: **precision + restraint.** Every number is exact, every color is muted. The brand earns trust by looking unhurried.

Designers who do Mercury well feel like editors, not decorators.

## 2. Design Principles

1. **Serif for voice, sans for work.** Tiempos-style serif carries the brand's emotional moments (hero headlines, section leads, editorial pull quotes). A neutral grotesque (Arcadia / Inter Tight) runs the actual product UI. Never swap these roles. A serif product table reads as pretentious; a sans marketing hero reads as generic SaaS.

2. **One accent, used sparingly.** Indigo `#5266EB` is the only chromatic color. It appears on primary CTAs, focused inputs, and active links. Never on decorative elements. Never two chromatic colors on the same screen. The neutral canvas makes each accent arrival feel intentional.

3. **Near-white, not white.** Canvas is `#FBFCFD` — cool, faint navy bias. Surface lifts to `#F4F5F9`. Text is `#272735`, not `#000`. Pure black and pure white are both banned; they feel engineered for contrast, not for reading.

4. **Geometry skips 24px.** Radii go 4 → 8 → 12 → 16 → 32 → 40. There is no 20, no 24, no pill (999). The gap from 16 to 32 is where Mercury's geometric identity lives — small components are crisp (≤ 16), marketing showcases are generously rounded (32 / 40).

5. **Cards breathe.** Card padding is generous (24–32px), card density is low (4–5 items per card max, not 12). Dense data lives in tables, not cards. If you find yourself stuffing a card, split it into two.

6. **Borders before shadows.** Depth comes from 1px borders at `#ededf3` (light) or `#28253b` (dark) first, shadows second. When a shadow is needed, it's a whisper — `0 1px 2px rgba(39,39,53,0.04)`, not a glow. No accent-colored glows ever.

7. **Data is mono, money is not.** Account numbers, routing numbers, API keys, code blocks → IBM Plex Mono. Dollar amounts, counts, percentages → the regular sans. This is the opposite of most dev tools and is load-bearing Mercury: money is editorial, metadata is technical.

## 3. Craft Rules

### Visual hierarchy layers

| Layer | Treatment | Examples |
|-------|-----------|----------|
| **Canvas** | `var(--background)`, near-white | Page backdrop, section backgrounds |
| **Surface 1** | `var(--surface1)`, one step up | Standard cards, sidebar |
| **Surface 2** | `var(--surface2)`, two steps up | Nested panels, modal interiors |
| **Surface 3** | `var(--surface3)` = `brand.50` | Accent-tinted callouts, highlighted rows |
| **Accent** | `var(--accent)` at `#5266EB` | Primary CTAs, focus rings, active links ONLY |

### Type budget per screen

Max **one display serif** + **one body sans** + **one mono** = three families. Never mix two serifs. Headlines (display, h1, h2) are always serif. Product UI (h3, body, body_sm, caption, label) is always sans. The mono appears for identifiers, never for body copy.

### Spacing semantics

| Token | Use |
|-------|-----|
| `--space-2xs` (4px) | Icon-text gap, inline tag padding |
| `--space-xs` (8px) | Internal control padding, tight list gap |
| `--space-sm` (12px) | Form field internal gap, small card padding |
| `--space-md` (16px) | Default gap, standard card internal padding |
| `--space-lg` (24px) | Card padding, section internal spacing |
| `--space-xl` (32px) | Between major sections |
| `--space-2xl` (48px) | Page-level section separation |
| `--space-3xl` (64px) | Hero vertical rhythm, big feature blocks |
| `--space-4xl` (96px) | Marketing page section gap |

### Color strategy

One accent. Two semantic (success green `#188554`, error red `#D03275`). Five neutrals (`50 / 100 / 200 / 300 / 500 / 900`). Nothing else. If you feel you need a sixth color, you need better hierarchy.

### Composition

Marketing pages alternate **text-left / visual-right** feature blocks. Product pages use a left sidebar (accounts / nav) + main content + optional right rail (context, activity). Modals are always centered, never slide-over. Tables are bordered (1px `--border`), rows alternate subtly via `surface2` at 50% opacity, not zebra stripes.

### Squint test

Squint at a Mercury screen from across the room. What you should see:
- One warm haze of near-white
- One navy mass of text
- One indigo dot (the CTA)
- A shape — the card / table / device frame

If you see two or three indigo dots, you've over-used the accent. If you see no warm haze (pure white), the palette is wrong. If you see multiple bright colors, you're on a different brand.

## 4. Anti-Patterns

1. **No pure black (`#000`) or pure white (`#FFF`).** Text is `#272735`. Background is `#FBFCFD`. These specific hexes matter — substituting `#111` or `#F8F8F8` shifts the brand's temperature.

2. **No pill buttons or pill cards (`border-radius: 999px`).** Mercury's radii top out at 40px. Pills read as consumer-app / social / playful — the opposite of Mercury's editorial calm.

3. **No accent-colored shadows or glows.** Indigo lives on solid backgrounds and borders, never as a soft glow behind a CTA. Shadows are always near-black at < 10% alpha.

4. **No two chromatic colors on one screen.** One accent at a time. If you need to show success, use green alone; the primary CTA in that section can stay neutral.

5. **No gradients on text.** Headlines are solid `text1`. Gradient text is a consumer-AI trope that would vandalize Mercury's editorial voice.

6. **No serif for body or UI.** Serif is reserved for display, h1, h2 — the emotional tier. Serif at 14px looks like a legal document.

7. **No stock photography in hero composition.** Mercury's hero is always a product window (dashboard screenshot, account overview) on a mesh background. Lifestyle stock photos are explicitly off-brand.

8. **No radius of 24px.** The scale skips from 16 → 32 on purpose. A 24px radius card reads as "almost Mercury but slightly off."

9. **No mono for dollar amounts.** `$42,310.00` stays in the sans. Mono is for account numbers, routing numbers, API keys, code — the identifier tier, not the value tier.

10. **No toast notifications as the primary feedback pattern.** Inline confirmation in the form itself is preferred. Toasts break the editorial calm.

11. **No skeleton loaders longer than 300ms.** Either the data loads or it doesn't. Animated placeholders that linger feel more anxious than a brief spinner.

12. **No decorative illustrations.** Mercury earns its character from typography and restraint, not from icon-stack compositions or cartoon spot illustrations. When an illustration slot exists, use a product screenshot or a geometric abstract shape — never characters, never hand-drawn scenes.

## 5. Workflow

When applying Mercury design to a new surface:

1. **Start from `--background` (`#FBFCFD`).** Do not use pure white anywhere.
2. **Set text in `#272735` / Inter Tight 16px / 1.55 line-height** as the baseline body. Every deviation must have a reason.
3. **Use Source Serif 4 for the screen's one emotional tier** — usually the page title or section lead. Everything else is sans.
4. **Place ONE primary CTA per visible viewport.** Accent `#5266EB`, white text, 8px radius, 10px/20px padding, 500 weight. All other actions are secondary (outline) or ghost.
5. **Build cards at 12px radius with 24px padding, 1px `--border`, optional `shadow-sm`.** Marketing showcase cards scale up to 32–40px radius.
6. **Wire money in sans, wire identifiers in mono.** `$42,310.00` → sans. `routing 021000021` → IBM Plex Mono.
7. **Check the squint test before shipping.** One warm canvas, one navy mass, one indigo dot, one shape. If more, remove.

## 6. Cross-references

- **Token reference:** `references/tokens.md` — every color, type, spacing, radius, shadow value with usage.
- **Component reference:** `references/components.md` — buttons, cards, inputs, tables, navigation, overlays, states.
- **Platform mapping:** `references/platform-mapping.md` — CSS custom properties, Tailwind extend, SwiftUI extensions.
- **Visual preview:** `preview.html` — Bento grid dashboard rendered in the language.
- **Component library:** `component-library.html` — every component with spec tables.
- **Landing page:** `landing-page.html` — full marketing narrative in Mercury voice.
- **App screen:** `app-screen.html` — product dashboard inside a browser frame.