<!--
ROBOTS ON PAYROLL / THE VAULT
What this is: a complete real example of the DESIGN-KIT.md the heist prompt produces, for a playful-brutalist habit tracker.
How to use it: download this file and give it to your AI (Claude, ChatGPT,
Cursor, Lovable chat) as a reference. Say: "Use this as my playbook for
what a finished DESIGN-KIT.md should look like."
Latest version + full guide: https://robotsonpayroll.com/resources/design-heist-kit
-->

# DESIGN-KIT.md

Extracted from: screenshot of a fictional playful-brutalist tool site ("the loud sticker-shop look").
Target product: a habit tracker for freelancers. Stack: Next.js + Tailwind.
This file is a constraint set for an AI coding agent. Follow it for all UI work.

## 0. Design DNA

Playful brutalism: flat colors, hard black borders, hard offset shadows, zero gradients, zero blur. The first-2-seconds feeling is "a well-organized zine": loud but disciplined. Three load-bearing decisions create it: (1) every surface is outlined in 2px solid ink, so depth comes from borders and offsets, never softness; (2) one screaming accent (yellow) used on under 10% of the screen, so it always reads as a highlight, not wallpaper; (3) a chunky grotesque headline face set tight against a plain readable body face, so the loudness lives in headings only.

## 1. Color Tokens

| Token | Hex | Role | Usage rule |
|---|---|---|---|
| `--color-surface` | `#FAF7F0` | Page background | The only page background. Warm off-white, never pure white. |
| `--color-surface-raised` | `#FFFFFF` | Cards, inputs, modals | Anything outlined with a border sits on this. |
| `--color-ink` | `#111111` | Text, borders, icons | Near-black, never `#000`. All borders use this token. |
| `--color-ink-muted` | `#5C5852` (est.) | Secondary text, captions | Body-secondary only. Never on borders or icons. |
| `--color-accent` | `#FFD23F` | Primary buttons, highlights, active states | Max 10% of any viewport. One accent block per section. |
| `--color-accent-ink` | `#111111` | Text on accent | Always ink on accent, never white. |
| `--color-pop-pink` | `#FF6BAA` (est.) | Badges, decorative shapes | Decoration and tags only, never interactive elements. |
| `--color-pop-blue` | `#4D9DE0` (est.) | Links, info badges | Links and info states. |
| `--color-danger` | `#E4572E` | Destructive actions, errors | Buttons and error text only. |
| `--color-success` | `#3BB273` (est.) | Success states | Confirmation text and check icons. |
| `--color-border` | `#111111` | All borders | Same as ink. Borders are never gray in this system. |

Contrast logic: ink on surface is roughly 16:1; muted text roughly 7:1; accent-ink on accent roughly 12:1. Nothing interactive drops below 4.5:1.
Accent budget: yellow on primary CTAs, active nav item, and at most one highlight block per section. If two yellow elements would be visible at once, demote one to a bordered white card.

## 2. Type Scale

- Display/headings: chunky geometric grotesque, near-black weight. Open-license candidates: Archivo Black, Space Grotesk (700), Anybody (800).
- Body: plain humanist sans. Candidates: Inter, Public Sans.
- Mono (numbers, streak counters): candidates: Space Mono, JetBrains Mono.

| Step | Size | Weight | Line-height | Letter-spacing | Usage |
|---|---|---|---|---|---|
| display-xl | 64px (est.) | 800 | 1.0 | -0.02em | Hero only, one per page |
| h1 | 40px | 800 | 1.1 | -0.01em | Page titles |
| h2 | 28px | 800 | 1.15 | 0 | Section titles |
| h3 | 20px | 700 | 1.3 | 0 | Card titles |
| body | 16px | 400 | 1.6 | 0 | Paragraphs |
| small | 14px | 500 | 1.5 | 0 | Meta, form hints |
| caption | 12px | 700 | 1.4 | +0.08em | ALL-CAPS labels, badges |

Scale ratio: roughly 1.4 between display steps, roughly 1.25 below h2 (est.).
Case rules: all-caps only at caption size with +0.08em tracking (badges, eyebrow labels, button text optional). Headings are sentence case.
Body max line length: 65ch.

## 3. Spacing Scale

Base unit: 4px. Steps in use: 4, 8, 12, 16, 24, 32, 48, 64, 96.

- Section vertical padding: 96px desktop, 48px mobile.
- Heading to body gap: 16px. Eyebrow to heading: 8px.
- Card internal padding: 24px (compact cards 16px).
- Grid gutter: 24px. Card grid gap: 24px.
- Button padding: 12px 24px.

Density verdict: medium-dense inside components, airy between sections. Whitespace is concentrated BETWEEN sections; inside a card things sit close and confident.

## 4. Shape Language: Borders, Radii, Shadows

- Radius scale: 0px on structural blocks (sections, tables), 8px on cards and inputs, 999px on badges/pills only. Buttons: 8px.
- Borders: 2px solid `--color-ink` on every card, button, input, and badge. 3px on the hero CTA (est.). Borders are the depth system; gray hairlines do not exist here.
- Shadows: hard offset only, no blur ever. Recipe: `box-shadow: 4px 4px 0 var(--color-ink)`. Hover recipe: `6px 6px 0` with a -2px translate. Small elements (badges): `2px 2px 0`.
- Signature moves: hard-shadow offset on interactive elements, 2px solid underlines on links (no text-decoration-color tricks), section dividers are 2px full-width ink rules.

## 5. Component Inventory

### Button, primary
- Anatomy: accent background, accent-ink text, 2px ink border, 8px radius, 12px 24px padding, 700 weight, hard shadow 4px.
- States: default as above; hover: translate(-2px,-2px) + shadow 6px 6px 0; active: translate(2px,2px) + shadow 0 0 0 (pressed flat); focus: 2px offset outline in `--color-pop-blue` (derived); disabled: surface background, ink-muted text, shadow removed (derived).
- Rule: one primary button per view section.

### Button, secondary
- Anatomy: surface-raised background, ink text, 2px ink border, same padding, hard shadow 4px.
- States: same physics as primary; hover lifts, active presses flat (derived where not visible).
- Rule: any action that is not THE action.

### Input / textarea
- Anatomy: surface-raised, 2px ink border, 8px radius, 12px 16px padding, body 16px, placeholder in ink-muted.
- States: focus: border stays ink, add `4px 4px 0 var(--color-accent)` shadow (derived from system logic); error: border and hint in `--color-danger`; disabled: surface background, muted text (derived).
- Rule: labels above inputs, 700 weight, 14px. Never floating labels.

### Card
- Anatomy: surface-raised, 2px ink border, 8px radius, 24px padding, optional 4px hard shadow.
- States: static cards have no shadow; clickable cards get the shadow plus the button hover physics (derived).
- Rule: shadow means clickable. Never shadow a static card.

### Nav bar
- Anatomy: surface background, 2px ink bottom border, 64px height, logo left, links right at 16px/700, 24px gaps.
- States: active link gets an accent background pill (8px radius, 4px 12px padding); hover gets a 2px underline (derived).
- Rule: max 5 nav items; overflow goes into a bordered dropdown.

### Badge / tag
- Anatomy: pop color background, ink text, 2px ink border, 999px radius, 4px 12px padding, caption style (12px caps).
- States: non-interactive by default; interactive badges get 2px 2px 0 shadow (derived).
- Rule: max 3 badge colors per view.

### Footer
- Anatomy: ink background, surface text, 2px accent top border, 64px vertical padding, link columns at small size.
- Rule: the only inverted (dark) surface on the page.

## 6. Motion Rules

Motion is INFERRED from the genre (screenshot is static). Defaults:
- Micro-interactions (hover lift, press): 120ms, `cubic-bezier(0.2, 0, 0, 1)`.
- Layout/entrance: 250ms max, transform + opacity only, 8px travel distance.
- Animate only `transform` and `opacity`. Never animate colors, borders, width, height, or shadows except the press/lift pair.
- No parallax, no scroll-jacking, no autoplaying loops. The physicality is snap, not float.
- `prefers-reduced-motion: reduce` disables all transforms; opacity fades stay under 150ms.

## 7. Voice of the Visuals

- Adjectives: loud, honest, handmade, confident, playful, cheap-in-a-good-way, precise.
- Copy style: sentence case, terse, first person allowed ("Track it. Done."). Button labels are verbs, 1-3 words. Playful microcopy allowed in empty states only.
- Iconography: 2px stroke outline icons, square corners, ink colored. No filled icons, no duotone.
- Imagery: flat illustration or plain product screenshots inside 2px ink borders. Never stock photos, never 3D renders, never glassmorphism.

## 8. Do / Don't

DO:
1. Outline every raised element with 2px solid `--color-ink`.
2. Use hard offset shadows (`4px 4px 0`) only on interactive elements.
3. Keep accent yellow under 10% of the viewport.
4. Use the press-flat active state on everything clickable.
5. Set headings in the display face at 700+ weight, sentence case.
6. Use the mono face for all numbers that update (counters, streaks, prices).
7. Put whitespace between sections (96px), not inside components.
8. Use 2px ink rules as section dividers.

DON'T:
1. Don't use gradients, blur, or glassmorphism anywhere.
2. Don't use soft shadows (`rgba` blur shadows are banned).
3. Don't use gray borders; borders are ink or they don't exist.
4. Don't use pure white page backgrounds or pure black text.
5. Don't center body text; only hero headings may center.
6. Don't introduce new colors; derive from the 11 tokens.
7. Don't round corners past 8px except pills.
8. Don't use thin font weights (under 400) anywhere.
9. Don't animate anything longer than 250ms.

## 9. Do Not Lift (Legal/Brand Flags)

- Source site's logo and wordmark: replace with our own wordmark set in Archivo Black.
- Source mascot illustration (hand-drawn character): do not reproduce; if we want a mascot, commission an original in a flat 2px-outline style.
- The custom proprietary display typeface: substitute Archivo Black or Space Grotesk 700 (open license).
- The source tagline and any headline copy: write our own.
- The specific hero illustration composition: reuse the STRUCTURE (bordered image right, headline left), not the artwork.

## 10. Agent Bootstrap

```css
:root {
  --color-surface: #FAF7F0;
  --color-surface-raised: #FFFFFF;
  --color-ink: #111111;
  --color-ink-muted: #5C5852;
  --color-accent: #FFD23F;
  --color-accent-ink: #111111;
  --color-pop-pink: #FF6BAA;
  --color-pop-blue: #4D9DE0;
  --color-danger: #E4572E;
  --color-success: #3BB273;
  --color-border: #111111;

  --radius-sm: 8px;
  --radius-pill: 999px;

  --border-std: 2px solid var(--color-ink);
  --shadow-hard: 4px 4px 0 var(--color-ink);
  --shadow-hard-lg: 6px 6px 0 var(--color-ink);
  --shadow-hard-sm: 2px 2px 0 var(--color-ink);

  --space-1: 4px;  --space-2: 8px;  --space-3: 12px; --space-4: 16px;
  --space-6: 24px; --space-8: 32px; --space-12: 48px; --space-16: 64px; --space-24: 96px;

  --ease-snap: cubic-bezier(0.2, 0, 0, 1);
  --dur-micro: 120ms;
  --dur-layout: 250ms;
}
```

Standing instruction for the agent:
"Follow DESIGN-KIT.md for all UI work. When a value is not covered, derive it from the nearest token; never invent new colors, fonts, radii, or shadows."