🎨 Design Playbook

TrueBalance × TrueCredits Hackathon · June 11–12, 2026 · all teams · deploy playbook

Your app works but renders flat and black-on-white. You don't need a rebuild — you need a 30-minute paint job: one token block (§1) → 6 moves (§2) → avoid 8 slop tells (§3) → 60-second check (§4).

Feed it to your Claude session — that's the whole workflow:
Read https://hackathon.afinit.dev/playbooks/design.md and apply a TrueBalance design touch to my app — tokens + the 6 moves, nothing more.

Machine-readable original: /playbooks/design.md · This is a stylist, not an architect — don't restructure, just paint.

1 · One can of paint — TrueBalance tokens

Paste this :root block once (a global CSS file, or a <style> in your <head>). Then reference the variables everywhere — never hard-code a hex again.

orange orange-press orange-soft bg surface border text text-sub error success info warning 
:root {
  /* brand — the ONE accent. use sparingly. */
  --tb-orange:        #FA823B;  /* primary action / selected / progress */
  --tb-orange-press:  #E36C25;  /* pressed */
  --tb-orange-soft:   #FEF2EB;  /* secondary action surface */

  /* surface + ink */
  --tb-bg:        #FFFFFF;  /* page background */
  --tb-surface:   #F5F5F5;  /* cards, tertiary fills */
  --tb-border:    #DCDDDF;  /* dividers, borders */
  --tb-text:      #131E29;  /* primary text */
  --tb-text-sub:  #7E868D;  /* secondary text, captions, placeholder */

  /* status (only when you mean it) */
  --tb-error:   #FF2E34;
  --tb-success: #1DB66B;
  --tb-info:    #1879FF;  /* also focus ring */
  --tb-warning: #EB9D00;

  /* spacing rhythm — pick from this scale, don't free-hand */
  --sp-xs: 8px;  --sp-sm: 10px;  --sp-md: 16px;  --sp-lg: 20px;  --sp-xl: 24px;  --sp-2xl: 32px;

  /* corner + lift */
  --r-sm: 6px;  --r-md: 10px;  --r-lg: 12px;  --r-pill: 9999px;
  --shadow-1: 0 0 2px 0 rgba(0,0,0,.12);   /* subtle */
  --shadow-3: 0 0 8px 0 rgba(0,0,0,.12);   /* card */
  --shadow-4: 0 8px 8px 0 rgba(0,0,0,.12); /* raised / sticky */

  /* type — 3 tiers is enough */
  --font: 'Roboto', -apple-system, 'SF Pro Text', system-ui, sans-serif;
  /* head: 26px/700 · subhead: 18px/700 · body: 16px/400 · caption: 12px/400 */
}

Design System — your source of truth, not a vibe:

2 · Six paint moves

Apply in order, ~5 minutes each. Stop when it looks calm and intentional.

  1. Background & ink — kill the raw black-on-white. background: var(--tb-bg); color: var(--tb-text); and wrap content in a centered container (max-width: 720–960px; margin-inline: auto; padding: var(--sp-lg)).
  2. One accent, one place — --tb-orange goes on the primary action only (the main button/CTA). Everything else stays neutral. One orange per screen beats ten.
  3. Spacing rhythm — replace ad-hoc margins with the --sp-* scale. Default gap = --sp-md (16px). Consistency reads as "designed."
  4. Corners & lift — buttons/cards get border-radius: var(--r-sm) and box-shadow: var(--shadow-3). Things sit on the page instead of bleeding into it.
  5. Type hierarchy — 3 tiers, no more: head (26px/700) → body (16px/400) → caption (12px/400, --tb-text-sub). Don't make everything the same size.
  6. State paint — give empty / loading / error their own look: greyed placeholder (--tb-text-sub), a spinner, error in --tb-error. A screen that handles emptiness looks finished. (Static app? Paint the data you have — status pills, an .empty style.)

Forms (most hackathon apps are forms): inputs get border: 1px solid var(--tb-border); border-radius: var(--r-sm); padding: var(--sp-sm), label in caption type, and a --tb-info focus ring (outline: 2px solid var(--tb-info) on :focus).

3 · AI-slop tells to avoid ❌

If your app shows any of these, it reads as "machine-generated." Cut them.

4 · 60-second check ✅

Four out of four = shipped. That's the touch.