# LMV Design System - How To Use This **Luckiest Man Ventures · v1.0 · 2026-06-17** This is the kit. Drop it into any chat (Claude, Claude Code, etc.) or hand it to a teammate, and you can build anything on-brand. It has two faces: the **human reference** (the live HTML files you can look at) and the **machine layer** (`lmv-tokens.css` + `lmv-tokens.json`) an LLM reads to build correctly. --- ## The 10-second brief (paste this when starting a build) > Build using the Luckiest Man Ventures design system. Load `lmv-tokens.css` and follow `lmv-tokens.json`. Use only those tokens - never hardcode a hex, duration, or easing. Put a surface class (`.on-cream` / `.on-navy` / `.on-rust` / `.on-sand` / `.on-dark`) on every section and card so colors pair correctly. Warm editorial meets restrained neo-brutalism - not generic SaaS. Section rhythm cream → navy → cream → rust → cream, never two darks adjacent. PILL BAN (no radius > 8px on non-circular elements). `--white` is `#fffaf0`, never `#ffffff`. Caveat font for personality accents only. One to three personality moments per page. Every animation resolves to a static state under reduced-motion. --- ## What's in the kit | File | What it is | |------|-----------| | `lmv-tokens.css` | The single source of truth. Colors, warm softs, gradients, the **surface contract** (`.on-*` classes), type, spacing, radius, shadows, motion tokens. Copy into any project. | | `lmv-tokens.json` | Machine-readable mirror of everything + the rules. This is what an LLM parses to build on-brand. | | `USE-THIS.md` | This file. | **Live reference files** (look at these to see the system in action - in `~/ai-projects/`): - `lmv-living-brand-guide.html` - the whole brand on one page (colors, type, cards, personality, gradients). - `lmv-surface-contract.html` - every surface with its exact on-top colors. - `lmv-animation-playbook.html` - the 4 motion tiers, live. - `lmv-tier3-scroll-scene.html` - the scroll-driven scene (both scrub + autoplay). - `lmv-polaroid.html` - the Polaroid component, pixel-matched. --- ## The core idea: the surface contract The #1 bug in every design system is color-on-color: you change a surface color and the text/border/button on top stays wrong. This kit kills that permanently. For each background surface there is ONE class that sets every on-top color: `.on-cream`, `.on-navy`, `.on-rust`, `.on-sand`, `.on-dark`. Inside, every element uses contract variables - `var(--hd)` heading, `var(--bd)` body, `var(--mu)` muted, `var(--ki)` kicker/accent, `var(--br)` border, `var(--lk)` link, `var(--bbg)`/`var(--btx)` button - **never a hardcoded color**. ```html

KICKER

Heading

Body copy.

A link
``` Switch `.on-navy` → `.on-cream` and everything re-pairs correctly. White-on-white is impossible. --- ## The hard rules (non-negotiable) - `--white` = `#fffaf0`. Never `#ffffff`. - **Pill ban.** No radius > 8px on non-circular elements. Only a real circular icon button or status dot is round. - **Card contrast.** Dark cards on cream; light/paper cards on navy or rust. Never a white card on cream. Never same-tone-on-same-tone. - **Section rhythm.** cream → navy → cream → rust → cream. Two darks never adjacent. - **Caveat** = personality accents only (captions, margin notes, attributions). Never headlines, body, UI, nav. - **Gradients** = surfaces only (heroes, section bands, large fills). Never on buttons/tags/small UI. - **No em dashes** in visible copy. - **Reduced motion** collapses every animation to its final state (handled in the token file). - **Product casing:** lightbreak, greetform (lowercase); Luckiest Man Ventures, Skip School (title); LMV (caps); WilcoGuide (camel). --- ## Typography Fraunces (display/headlines/big numbers) · Source Serif 4 (body) · Inter (UI/buttons) · JetBrains Mono (metadata/datelines/kickers) · Caveat (accents only). Push headline contrast - Fraunces big, with one italic rust word for emphasis. ## Animation - the four tiers - **T1 Ambient** (cursor): hover lift, dot-pulse, shimmer, link underline. Polish you don't notice. - **T2 Reveal** (scroll): content arrives - staggered deal-in, count-up, bar-fill, rule-draw. Fire-once on view. - **T3 Scroll scene** (scroll position): a scene unfolds as you scroll (newsletter assembling). Scrub or pin+autoplay. - **T4 Showpiece** (plays on its own): a product-demo animation that depicts what the product does. Compose only from the 5 durations + 5 easings in the tokens. Mechanical feel for structure; spring/overshoot reserved for 1–2 personality moments per page. ## Personality layer One to three moments per page, never more. Neo-brutalist offset shadow (upright, 1/view), Polaroid (warm frame, top-center tape, Caveat caption), tape strip, animated buttons (shimmer/snake, solid fills), announcement banner. Intentional imperfection, not sloppiness. --- ## How to ADD to the system later (this is built to grow) The system is token-driven and modular, so adding is *append*, not *rewire*: - **New color:** add it to `lmv-tokens.css` and `lmv-tokens.json`. If it can be a surface, add a matching `.on-yourcolor` class defining the on-top set (copy an existing one and adjust). Done - every component picks it up. - **New card style:** build it as a standalone block using contract variables + tokens. Drop it in the card library. Nothing else changes. (Cards are pure optionality - have as many as you want.) - **New hero / pricing / section:** same - it's a menu option, not a load-bearing wall. Add it alongside the others. - **New animation:** build it from the existing durations + easings, assign it a tier, include a reduced-motion fallback. Add it to the playbook. - **New whole aesthetic** (a different "world" like a newspaper skin): that's a project, not a tweak - but the tokens, surface contract, and motion infrastructure carry over. Rule of thumb: if you're adding an *option*, it's easy and safe. If you're changing a *foundational rule* (e.g. lifting the pill ban) or inventing a new *aesthetic*, do it deliberately because it ripples. --- ## Still to come (roadmap) - **Card library** - the full menu of card options (in progress). - **Recolor engine** - drop in one brand color, auto-derive all five surface sets contrast-safe. The surface contract is the foundation for this. - **Brand brain** - LLM-readable voice + facts so the system generates on-brand content, not just style. - **Install scaffold + MCP** - one-command "start a new LMV project," and MCP access so a company brain can build on-brand on demand.