# DESIGN.md. The Craft Layer > A working draft of the file Lovable should ship with every project. > This is the file that lets a model. and a team. stay on-voice when anyone > can generate anything. Open standard, patterned after Google Stitch's draft. --- ## 0. Purpose This document is the source of truth for the visual and editorial system of *The Craft Layer*. It exists for two readers: 1. **A model** generating or modifying any surface in this project. 2. **A human** reviewing whether a generated surface still belongs here. If a generated change violates anything in this file, the change is wrong . no matter how well-formed the code is. --- ## 1. Voice & tone The voice is Eli Horne's: a smart operator, not a marketer. Direct. Pointed. Cuts everything that doesn't earn its place. Editorial in the register of *The Atlantic* or *The New Yorker*, not a product blog, not a LinkedIn post, not a consultant's deck. ### Tone - **Direct.** Lead with the answer or the takeaway. Never wind up. - **Confident, not arrogant.** Opinions stated clearly, not hedged to death. Always room to be wrong. - **Thoughtful, not verbose.** Depth comes from the right word, not more words. - **Slightly opinionated.** The writing has a perspective. It interprets, it doesn't just describe. - **Grounded.** Rooted in how things actually work, not how they're supposed to work in theory. ### Sharp lines over safe ones | Use | Not | |----------------------------------|--------------------------------------------------| | "This matters because..." | "It's worth noting that..." | | "The risk is..." | "One potential consideration is..." | | "The move here is..." | "There are several approaches you could take..." | ### Hard bans - **No em-dashes.** Use a period, a colon, or parentheses. Hyphens are fine in compound words. - **No emojis.** Anywhere. - **No exclamation points** unless rare and earned. - **No filler:** "at the end of the day", "it's important to note", "in today's landscape", "that said". - **No marketingspeak:** "innovative", "seamless", "best-in-class", "unlock value", "leverage" (as a verb), "synergy", "ecosystem", "empower", "scalable" (unless literally true). - **No over-hedging:** "it could be argued", "in some ways", "arguably", "perhaps", "might want to", "consider". - **No unnecessary setup.** Get to the point in the first sentence. ### Banned openers and closers - Openers: "In today's fast-moving landscape...", "Let's dive in", "Great idea!", "Great question!", "As we navigate...", "Thanks for sharing". - Closers: "Hope this helps!", "Let me know if...", "Stay tuned", "Watch this space". ### Vocabulary Plain language over jargon. Technical terms used precisely, never for texture. Never use complexity to signal intelligence. - **Words that fit:** direct, clear, considered, honest, practical, sharp, ship, bet, tension, move. - **Words that don't:** user, stakeholder, delight, leverage, synergy, ecosystem, empower, seamless, innovative. ### What the writing is about At its core: design, product, systems, and the way expertise is changing. The writing asks: *what's actually happening here, and why does it matter?* It connects things. A product decision and an organizational one. A design pattern and a cultural shift. A tool and the behavior it shapes. It doesn't explain what people already know. It gets to the part that's less obvious. ### Structure - Lead with the point, not the context. - Short paragraphs. Two to four sentences. - Bullets when they genuinely aid clarity, not as a default. - Synthesis over exhaustive lists. - Headings in sentence case. --- ## 2. Editorial structure Every long-form surface uses **numbered sections** with a mono eyebrow (`S Section / 0X`) and a serif/sans display heading. Numbered, not ranked . the structure is the point of view. Memos and scans always follow a five-part shape: 1. **Opening thesis**. where the work sits, not what it does. 2. **What's working**. earn the right to critique. 3. **Three tensions**. conflicts, not defects. Each has a *why* and a *move*. 4. **Where craft becomes a weapon**. the bet that creates distance. 5. **What I'd want to learn**. what the outside read can't see. A pull-quote is allowed once per major surface. Set in serif at display size, **non-italic**, followed by a short 28px hairline and an uppercase mono attribution (`.pull-quote-attr`). No left-bar rule. Emphasized prose that isn't a quote uses `.callout-statement` instead, bracketed by horizontal hairlines above and below. --- ## 3. Type | Role | Family | Weight | Tracking | |---------------|--------------------|---------------|-------------| | Display | Inter Tight | 500 | -0.03em | | Heading | Inter Tight | 500 | -0.018em | | Body | Inter Tight | 400 | normal | | Mono / meta | JetBrains Mono | 400 | 0.05em | | Pull-quote | Instrument Serif | 400 | -0.015em | Body line-height is **1.65**. Display line-height is **0.96**. Never set body type below **15px** or above **18px**. --- ## 4. Color OKLCH-anchored. No raw Tailwind color classes (`text-white`, `bg-black`) anywhere in components. semantic tokens only. ``` --background: #fafaf7 /* warm paper, not pure white */ --foreground: #111111 --muted: #f1f1ec --muted-fg: #6b6b66 --accent: #14233e /* deep navy, used sparingly */ --border: #e8e8e2 --destructive: #8b1c1c ``` **Accent rules.** The navy accent is reserved for: live status indicators, the brand mark glyph (>>), and severity dots on findings. Never use it for body links, body buttons, or decorative fills. Body links are ink-on-ink with a single-pixel rule underneath (`.link-ink`). --- ## 5. Layout & space - Wide column max **1240px**. Prose column max **680px**. - Page padding: **24px** mobile, **48px** tablet, **120px** desktop. - Vertical rhythm in multiples of **8px**. Section breaks at **96px** desktop, **64px** mobile. - Borders are **1px** hairlines (`var(--border)`), often with vertical end-ticks (`.tick-rule`) instead of plain horizontal lines. - Radius is **2px** everywhere. Nothing is round. Nothing is pill-shaped unless it is a status chip. --- ## 6. Components | Pattern | When | Class | |--------------------|---------------------------------------------|--------------------------| | Eyebrow | Section labels, metadata fields | `.eyebrow` | | Mono label | Numbers, codes, status | `.label-mono` | | Meta row | Field-report cells (Type / Author / etc.) | `.meta-row .cell` | | Tick rule | Section dividers | `.tick-rule` | | Arrow link | "Read the proof ->" style | `.arrow-link` | | Ink button | Primary action | `.btn-ink` | | Bare input | Hairline-only inputs, no chrome | `.input-bare` | | Pull-quote attr | Short hairline + mono attribution | `.pull-quote-attr` | | Callout statement | Emphasized prose, hairline-bracketed | `.callout-statement` | | Article grid | Prose 720 column + .wide breakout at xl | `.article-grid` + `.wide`| | Card grid family | Hairline grid of cards. Used for Lineage, | `grid gap-px bg-border` | | | Gates, Lenses, Tensions, Patterns, Retire, | `border-y border-border` | | | Live, Commitments. One eyebrow + one | with `-mx-5 md:-mx-6` to | | | display title + one body per card. | align outer column edges.| | Severity / filter | Mono labels with underline-on-active. | (inline) | | Route rail | Sticky right column at xl. Bet badge + | `RouteRail` component | | | "On this page" TOC + back link + ASCII | | | | canvas accent. | | | Scan takeover | Mono progress checklist with rotating | (inline in panel) | | | block-quadrant glyph for the running step. | | | | Used on /scan and /filter for live work. | | No card shadows. No glass. No gradients. No drop shadows of any kind. --- ## 7. Animation - Fades in on first paint, **400ms**, ease-out. Never on subsequent renders. - Hover transitions on opacity and color only, **120ms**. - Never animate layout. Never bounce. Never spring. - Loading states use a hairline pulse, a typed-text cursor, or a rotating block-quadrant glyph (`▘▝▗▖`). Never a chrome spinner. Never a skeleton block. The scanning takeover (on /scan and /filter) renders progress as a mono checklist with state per step (DONE / RUNNING / —), the glyph spinning only for the active step. - The bets carousel and route rails render an ASCII canvas accent. The accent is drawn into a `
` from a density palette and animated via
  `requestAnimationFrame`. Honors `prefers-reduced-motion`. Typographic
  motion, not chrome.

---

## 8. What this site is not

It is not a SaaS landing page. It is not a portfolio. It is not a deck.
It is a strategic artifact written by one person on the flight back from
Stockholm for one conversation. Anything that makes it look like a
template, a marketing site, or a chrome-heavy app surface is wrong.

Specifically, never add:
- Hero sections with stock photography
- Testimonial carousels
- "Trusted by" logo bars
- Pricing tables
- Social proof badges
- Newsletter capture modals
- Light/dark theme toggles

---

## 9. How a model should use this file

When generating or editing any surface in this project, the model should:

1. Read this file before writing the first line.
2. Resolve any conflict in favor of this file, not the prompt.
3. If the prompt requests something this file forbids, say so out loud and
   propose the closest in-system alternative.
4. Treat additions to this file as additions to the contract. never silently
   override.

---

*Open spec. Modeled on the DESIGN.md draft introduced by Google Stitch.
Maintained as the source of truth for this artifact.*