{
 "id": "3.1",
 "title": "Design principles",
 "department": "Design",
 "department_slug": "design",
 "direction": null,
 "branded": false,
 "status": "draft",
 "owner": "Param",
 "last_verified": "Mon Oct 26",
 "holds": "Quiet, one of each thing, the brand's photos carry colour, the glance rule",
 "urls": {
  "html": "https://handbook.joinsquareup.com/design/design-principles",
  "markdown": "https://handbook.joinsquareup.com/design/design-principles.md",
  "json": "https://handbook.joinsquareup.com/design/design-principles.json"
 },
 "other_directions": [],
 "tldr": {
  "headline": "Ten rules for every screen, and the higher rule wins an argument",
  "points": [
   {
    "icon": "heart",
    "text": "Truth first: every number has a source chip, and unsure ones say To confirm."
   },
   {
    "icon": "eye",
    "text": "The glance rule: a founder gets any card in three seconds, in 25 words at most."
   },
   {
    "icon": "flag",
    "text": "One main button per screen, and one of each thing, from sheets to toasts."
   },
   {
    "icon": "spark",
    "text": "The brand's photos carry the colour; the hero colour stays on the character and main button."
   },
   {
    "icon": "warn",
    "text": "The live build is inconsistent: 309 surfaces today against a planned 22."
   }
  ],
  "stat": {
   "value": "309",
   "label": "Surfaces a person can reach"
  },
  "decide": "Does truth outrank every brand as the top rule, and does dark stay the default?",
  "mood": "waiting"
 },
 "sources": [
  "brand-directions/_shared/product-model.md:3-5, 99-113, 129-142, 162-213, 221-250",
  "brand-directions/_shared/ia.md:147-176",
  "brand-directions/_shared/kit-contract.md:31-37",
  "brand-directions/_shared/no-ai-look.md:1-58",
  "brand-directions/_shared/surface-map.md:9-18",
  "brand-directions/BRIEF.md:9-24, 147-175, 241-276, 499-508",
  "brand-directions/book/content/d1.js:5-75, 121-176",
  "brew origin/main b91e364: public/feed-system.css:1-40, public/index.html:6, public/jam-fit.css:1-2, 30-32",
  "memory: brew-quiet-ui, brew-one-stage, brew-one-version, brew-loader, brew-connect-sheet-design, brew-card-fit-and-counts, feed-for-all-brands, brand-directions-2026-10-25"
 ],
 "open_questions": [
  "Does truth outrank every brand as the top rule, or the other way round? Proposal: keep truth first, since a wrong number on one brand is worse than a missing feature on every brand.",
  "The live product is dark by default. Should the redesign keep dark as the default or follow the device? Proposal: follow the device, with dark as the fallback, because both themes ship for every direction.",
  "The glass tiers and the per brand wash are still in today's tokens. Remove both in the restyle? Proposal: yes, remove the glass tiers in v1 and keep the brand's photos as the only brand colour.",
  "Should the principles page carry a short example screen for each rule? Proposal: yes, one frame from the screen kit per rule, once a direction is picked."
 ],
 "parts": {
  "Answer": "Brew's screens follow ten rules, quiet first, one of each thing, the brand's photos carry the colour and every card lands in one glance, and when two designs disagree the higher rule on this list wins.",
  "Today": "Checked 26 October 2026 against brew origin/main at b91e364 and the brand direction files.\n\nWhat the live product looks like now:\n\n| Fact | Source |\n|---|---|\n| The live look is design system v13: dark by default, light follows the device, one feed column with gutters for stickers and margin notes | [src: brew origin/main public/feed-system.css:1-4] |\n| The feed column token is 530 px wide, though the file header still says 500 | [src: brew origin/main public/feed-system.css:4, 36] |\n| Text is SF Pro Text with Inter as fallback, plus Caveat as a hand font | [src: brew origin/main public/feed-system.css:31-32] |\n| Inter and Caveat load from Google Fonts on every page | [src: brew origin/main public/index.html:6] |\n| Three tiers of glass sit in the tokens: chrome, action and row | [src: brew origin/main public/feed-system.css:16-21] |\n| The only brand colour in the chrome is a per brand wash taken from the brand's pack | [src: brew origin/main public/feed-system.css:26-27] |\n| The build has 309 surfaces a person can reach, 42 routes, 23 sheet styles, 163 button classes, 25 empty state styles, 12 loader kinds and 44 status lists | [src: brand-directions/_shared/surface-map.md:9-18] |\n| Param called the build inconsistent and more complicated than it needs to be, and asked for one consistent product | [src: brand-directions/_shared/product-model.md:3-5] |\n| Quiet page rules already in force: one sentence under each title, no zero tiles, no empty sections, underline tabs, one signal per state, history folded away, about six items then Show all | [src: memory brew-quiet-ui] |\n| The jam stage follows one contract: one name in the header, only the piece on stage, one primary button, Draft, Make, Send | [src: memory brew-one-stage] |\n| Every make leads with one version, then Redo it for another take, never three options | [src: memory brew-one-version] |\n| Every wait uses one loader, the b mark that fills and steams | [src: memory brew-loader] |\n| Connector sheets are solid, never glass, with a pinned header and footer | [src: memory brew-connect-sheet-design] |\n| A card's button must fit what it makes, and count rows follow today's facts | [src: memory brew-card-fit-and-counts] |\n| Labels are sentence case; the 26 October jam fit removed the last uppercase labels | [src: brew origin/main public/jam-fit.css:30-32] |\n| Top rule for every fix: it works for every brand, card, widget and view | [src: memory feed-for-all-brands] |\n\nWhat is already decided for tomorrow:\n\n| Decision | Source |\n|---|---|\n| One product model for all five brand directions; a direction changes only the character, the skin, the character's words and the sound | [src: brand-directions/_shared/product-model.md:3] |\n| One of each thing: one top bar, one tab set, one bottom bar, one sheet, one menu, one toast, one empty state, one error state, four button kinds | [src: brand-directions/_shared/ia.md:147-153] |\n| The brand's own pictures carry the colour; the hero colour is for the character, the main button and focus, never for cards | [src: brand-directions/_shared/ia.md:152] |\n| The glance rule: a founder gets any card in three seconds without reading past the picture | [src: brand-directions/_shared/product-model.md:166-168] |\n| Nothing may look or read like generic AI output | [src: brand-directions/_shared/no-ai-look.md:1-5] |\n| Fonts are the fastest AI giveaway: never Inter, Poppins, DM Sans and the like; each direction owns its type | [src: memory brand-directions-2026-10-25] |\n| Super clean branding: rich and specific, but few faces, a tight scale, generous space, no clutter | [src: memory brand-directions-2026-10-25] |\n| Fun and playful everywhere, never serious or creepy, user first | [src: memory brand-directions-2026-10-25] |",
  "Tomorrow": "The ten principles, in priority order. When two of them pull apart, the one higher on the list wins.\n\n| # | Principle | What it means on a screen | Version | Tag |\n|---|---|---|---|---|\n| 1 | Truth on the screen | Every number has a source chip. Unsure numbers carry To confirm. Invented examples carry the Sample tag. No screen promises posting, scheduling or results before the version that does it | v1 | Stays |\n| 2 | Every brand, every screen | A design works for every brand, every card kind and every view, with real data that is long, short, missing or odd. Never a fix for the one brand in the screenshot | v1 | Stays |\n| 3 | One next step | One main button per screen, in the bottom bar where there is one: Make it on a pick, Hand it off in Make it | v1 | Changes |\n| 4 | The glance rule | A closed card is five things in 25 words at most. If it needs a second look, it is wrong | v1 | Changes |\n| 5 | Quiet | One sentence under a title, no zeros, no empty boxes, details folded, long lists cut at about six | v1 | Stays |\n| 6 | One of each thing | One way into each thing, one sheet, one toast, one empty state, one error state, four buttons, one word per concept | v1 | Changes |\n| 7 | The brand's photos carry the colour | Calm neutral surfaces. The direction's hero colour only on the main button, focus, the character and small accents | v1 | Changes |\n| 8 | Plain words on controls | Buttons, tabs and cards use the plain word in every direction. The character's words live around them | v1 | New |\n| 9 | The character never blocks a control | It lives in named slots, reads app state and can be switched off with nothing breaking | v1 | New |\n| 10 | Made on purpose | No gradients, glass, sparkle icons, default fonts or identical section rhythm. Each direction commits to one idea from its own world | v1 | Changes |\n\nWhat each one replaces:\n\n| # | Today | Tomorrow |\n|---|---|---|\n| 3 | A jam's next step is said in four places; 16 bars and 13 main button styles | One bottom bar, one main button |\n| 4 | A closed card carries about 60 to 90 words before a tap | 25 words at most, about 19 on the sample card |\n| 6 | 309 surfaces, 16 ways into a jam, 10 hand off buttons | 22 screens and sheets, one way into each thing |\n| 7 | Grey surfaces, white main buttons, a brand wash, glass tiers | Neutral surfaces tinted a little toward the direction, one hero colour, solid sheets |\n| 8 | Many words for one thing, such as Redo it, Another take and Make it again | One plain word per concept, from the word set in Content design |\n| 10 | Inter and SF Pro as the only voice, glass tiers, logo stickers | Two Google font families per direction, chosen to avoid the default faces |\n\nLater versions add to the rules and never relax them:\n\n| Version | Addition | Tag |\n|---|---|---|\n| v2 | When the product posts and schedules, every post shows where and when before it goes, and Undo stays reachable until it goes | New |\n| v3 | When the product measures, How it went shows the number, its source and the date range, never a lift we did not measure | New |\n| v4 | When it runs ads within rules, the rules and the limits sit on the same screen as the action, and Need your yes stays the control centre | New |",
  "How we do it": "1. Before drawing anything, find the existing kit part in Components. Build a new part only when no part fits, and add it to the kit, never to one screen.\n2. Write the plain labels first, from the word set. Then add the character's words around them, in the direction's voice.\n3. Draw every state the screen can be in. See States.\n4. Put the screen on real brand data from at least three brands of different kinds, plus the sample candle store with its Sample tag.\n5. Run the Design QA checklist.\n6. When two principles disagree, go down the list above and take the higher one. Write the call in the pull request.\n7. If a design still feels wrong, measure the cause and fix it. Do not offer style options. [src: memory measure-before-style-options]",
  "Numbers": "| Number | Definition | Today | Where it is measured | Status |\n|---|---|---|---|---|\n| Surfaces | Pages, views, sheets, overlays and menus a person can reach | 309 | Surface map, regenerated from the build | Measured |\n| Words on a closed card | Visible words before a tap | about 60 to 90 | Card lint over every served card | Measured by hand, lint Proposed |\n| Main buttons per screen | Buttons in the hero style visible at once | up to several | Screen kit audit at 390 and 1280 wide | Proposed |\n| Sheet styles | Distinct sheet classes | 23 | CSS class audit | Measured |\n| Button classes | Leading classes on buttons | 163 | CSS class audit | Measured |\n| Five second test pass rate | Share of people who can say what the product does after five seconds on Today | none run | Founder sessions | Proposed |",
  "Open": "1. Does truth outrank every brand as the top rule, or the other way round? Proposal: keep truth first, since a wrong number on one brand is worse than a missing feature on every brand.\n2. The live product is dark by default. Should the redesign keep dark as the default or follow the device? Proposal: follow the device, with dark as the fallback, because both themes ship for every direction.\n3. The glass tiers and the per brand wash are still in today's tokens. Remove both in the restyle? Proposal: yes, remove the glass tiers in v1 and keep the brand's photos as the only brand colour.\n4. Should the principles page carry a short example screen for each rule? Proposal: yes, one frame from the screen kit per rule, once a direction is picked."
 }
}