{ "layer": "principles", "title": "Identity rules — what is and isn't a Supercard", "spec": "supercard", "version": "3.2.0", "era": "atlas", "spec_revision": "05290259e680", "summary": "The 12 foundational principles (10 V3.0 + 2 V3.1). PRINCIPLES is the identity-audit reference; anything that violates these is by definition not a Supercard. The load-bearing one is #1, screenshot autonomy.", "source": "10-GOVERNANCE/PRINCIPLES-supercard-v3.md", "provenance": [ { "file": "10-GOVERNANCE/PRINCIPLES-supercard-v3.md", "updated": "2026-05-16", "version": "3.2.0", "sha256": "d5e3fde9bfbfc6a7612b479af8793dd0cddccaaa06c1fd607e879de686d2cd48" } ], "data": { "count": 12, "principles": [ { "n": 1, "title": "Screenshot autonomy", "qualifier": "non-negotiable", "statement": "Every visible region of a Supercard must convey one complete idea on its own. A stranger seeing only a cropped screenshot — no scroll context, no surrounding sections — should still understand a single, coherent thought, and be able to trace it back to the system via the corner glyph.", "why_it_matters": "This is the load-bearing principle. It's what made V1 work and what V2 lost. Supercards live in the wild — shared, screenshotted, dropped into Slack, pinned on Pinterest — and a card that requires its full scroll to make sense is a card that breaks the moment it leaves the canvas.", "how_to_apply": "Run the screenshot test on every section, including the header. First sentence must stand without prior context. No pronoun-first openers (\"It works because...\") that depend on what came before." }, { "n": 2, "title": "Single emphasis per block", "qualifier": "Lorch 1995", "statement": "Each block has exactly **one** emphasized phrase — one bold span, one focal stat, one highlighted callout. Two emphases compete; three is noise.", "why_it_matters": "Cognitive load research (Lorch 1995, Sanchez & Wiley 2006) shows that emphasis effects collapse when more than one item per visual region competes for primacy. The reader's eye doesn't know where to land, so it lands nowhere — and the block reads as a wall.", "how_to_apply": "Before publishing any block, ask: \"If a reader takes away one phrase from this block, which is it?\" Bold that phrase. Strip everything else back to body weight." }, { "n": 3, "title": "Format-as-grammar, not length", "qualifier": null, "statement": "A Supercard is defined by its grammar (the 7-beat narrative spine, the block library, the screenshot test) — not by how long it is. Mini, Standard, and XL are presentation variants of the same grammar, not separate formats.", "why_it_matters": "Length-as-identity is how V2 drifted: \"Standard\" started meaning \"long\" rather than \"complete,\" and Mini stopped existing because it felt like \"less Supercard.\" Same grammar, different density — Standard remains canonical.", "how_to_apply": "Author the content first as a 7-beat structure. Then choose a length variant based on topic depth, not desired ceremony. Don't pad a Mini to fill a Standard; don't compress an XL to fit a Standard." }, { "n": 4, "title": "Sparing use of cards", "qualifier": "chrome is noise", "statement": "Cards (rounded, lofted, padded surfaces) are the most expensive visual primitive in the system. Reserve them for the hero and at most two other elevated moments. Everything else is flat.", "why_it_matters": "When every block sits in a card shell, the chrome becomes the design — and the reader stops being able to distinguish the *anchor* moments from ordinary text. The hard cap is **1–3 lofted elements per Supercard** (hero + ≤2 others).", "how_to_apply": "Default every block to flat. Justify each lofted element by what it anchors. If you can't articulate why a block deserves elevation, leave it flat." }, { "n": 5, "title": "Strict grayscale", "qualifier": "no color, ever", "statement": "Supercards use black, white, and a six-step gray ramp (0%, 6%, 12%, 30%, 60%, 100%). No accent colors. No category colors. No data colors.", "why_it_matters": "Color introduces hue management cost (which red? which orange? does it match across cards?). Grayscale forces emphasis to come from weight, position, and size — the underlying typography decisions. The result is editorial timelessness instead of web-app fashion.", "how_to_apply": "All emphasis lives in font weight (300 → 700) and gray opacity. Charts use solid black for the focal series and gray-30/gray-60 for context series. Never use color to \"highlight\" — use weight or position." }, { "n": 6, "title": "SF Pro Rounded as the canonical typeface", "qualifier": null, "statement": "SF Pro Rounded for body and display, SF Mono for code and equations. The CSS keyword `ui-rounded` resolves to it on Apple platforms, with a documented fallback chain.", "why_it_matters": "The rounded variant of SF Pro carries warmth that pure SF Pro doesn't — it reads as cognitive-prosthesis (a thinking aid) rather than corporate (a deliverable). That tonal difference is the entire reason a Supercard feels different from a slide deck.", "how_to_apply": "Always declare the full font stack (`ui-rounded, \"SF Pro Rounded\", \"SF Pro\", -apple-system, BlinkMacSystemFont, system-ui, ...`). Inline the font on the container, not via a Tailwind class." }, { "n": 7, "title": "Authoring friction is a feature", "qualifier": null, "statement": "Writing a Supercard should feel like writing — i.e., it should be slow, considered, and require synthesis. The format actively resists templates that let you skip thinking.", "why_it_matters": "A card that's easy to author tends to be easy to skim past. The friction (filling out a Metadata table, running the screenshot test, choosing the right block per beat) forces the author to actually have a position. Cards written in 5 minutes look like cards written in 5 minutes.", "how_to_apply": "Don't shortcut the redundancy filter. Don't skip beats because \"this topic doesn't need them.\" If a block writes itself in seconds, suspect it." }, { "n": 8, "title": "Content frozen at authored version", "qualifier": null, "statement": "A Supercard authored under V3.0 stays valid under V3.0 forever. Spec updates don't retroactively reformat old cards. The renderer maintains versioned rule libraries; new blocks added in V3.1+ are unknown to V3.0 cards and skipped, not auto-migrated. (Formalized in ADR-0003.)", "why_it_matters": "Auto-migration corrupts the archive — Notion's block format auto-migrates and you can never reconstruct what you wrote in 2019. Frozen-at-authored preserves the genealogy as a true historical record. V3.0's design choices become consequential because we can't quietly fix them later.", "how_to_apply": "Every Supercard's frontmatter declares `frozen_at_version: 3.X.Y`. Forward migration is allowed only voluntarily — re-author a card under a newer version, with a migration note in the new card's history." }, { "n": 9, "title": "The redundancy filter", "qualifier": null, "statement": "Before any block ships, ask: *what unique element does this add that's not already in any other block on this Supercard?* If the answer is \"nothing\" or \"restates the thesis,\" cut the block.", "why_it_matters": "Redundancy is the silent killer of synthesis. Each block competes for attention; a block that re-says what an adjacent block already said dilutes both. The filter forces every block to earn its scroll.", "how_to_apply": "Run on every block at draft completion. Pull-quotes that paraphrase body fail. Definitions for context-obvious terms fail. Padding sections that \"balance the structure\" fail. When in doubt, cut — a card that's tighter is always more authoritative." }, { "n": 10, "title": "Genealogy-as-asset", "qualifier": null, "statement": "The history of how a Supercard came to be — the ADRs, the stewards' log, the rejected ideas, the version it was authored under, the cards that superseded it — is part of the artifact, not metadata. The system optimizes for legibility of its own evolution.", "why_it_matters": "Most knowledge systems optimize for the current state and treat history as overhead. Supercards treat history as a load-bearing feature: a future reader (or future-Derick) can reconstruct *why* a card looks the way it does, which is the only way to evolve the system without repeating V2's drift.", "how_to_apply": "Every card declares `version` and `frozen_at_version`. Every card optionally declares `supersedes` and `related`. ADRs document why decisions were made. The stewards' log captures the *noticing* — patterns observed, temptations resisted. Treat the archive as the asset, not as cleanup to do later." }, { "n": 11, "title": "Cognitive prosthesis, made operational", "qualifier": "V3.1+", "statement": "The ADHD framing in principle 1 isn't a vibe; it must translate into four MUST rules every V3.1+ card honours: (a) every block is scannable in under 4 seconds, (b) every beat is re-enterable from any of its blocks, (c) every cropped screenshot carries beat identity via the micro-folio, (d) every prose block frontloads its thesis in a bolded lead-clause.", "why_it_matters": "V3.0 stated the goal (cognitive prosthesis) but enforced it only at the principle level — single emphasis, redundancy filter, screenshot autonomy. That left room for long `standard-text` walls, undifferentiated multi-block beats in XL, and cards that scan beautifully on the hero and collapse two beats later. The operational rules close that gap without breaking the existing constraints.", "how_to_apply": "The single-emphasis rule (principle 2) is unchanged. The bolded lead-clause **is** the block's one emphasis — no second bold runs in the same block. Long prose splits at the 75-word ceiling. Re-entry comes from the top-and-bottom micro-folio (`BEAT 3 · MECHANISM · 4 / 7`) on every card. See `GRAMMAR` § G-7 / G-8 and `RENDERING` § R-9 / R-10 for the rendering contract." }, { "n": 12, "title": "First-pass extraction test", "qualifier": "V3.1+", "statement": "A reader who scans ONLY the bolded clauses of a card, top to bottom, must be able to reconstruct the card's thesis in one sentence. If the bold-only read fails, the card fails review.", "why_it_matters": "This is the discipline check on principle 11(d). It forces every bolded clause to do real work and exposes lead-clauses that hedge, restate, or filler their way through a block. Pernice's eye-tracking work (NN/g 2017, 2019) shows scanners enter at the leftmost 1–3 words of each line; that's exactly what this test optimizes for.", "how_to_apply": "Run alongside the screenshot test (below), not after. Read only the bolded spans, top to bottom — title, hero takeaway, every lead-clause, every focal stat, every key-takeaway. They should compose a coherent thesis. If they don't, the lead-clauses aren't earning their bold.\n\n---" } ] }, "see_also": [ "grammar", "tokens" ], "doc_markdown": "# PRINCIPLES — Supercard\n\n| key | value |\n|---|---|\n| id | PRINCIPLES-supercard-v3 |\n| type | governance |\n| era | atlas |\n| version | 3.2.0 |\n| owner | derick |\n| updated | 2026-05-16 |\n\nThe 10 foundational principles of the Supercard format. PRINCIPLES says *what we're doing*; GRAMMAR says *how to assemble it*. When in doubt, this doc is the identity anchor — anything that violates these is by definition not a Supercard.\n\n---\n\n## 1. Screenshot autonomy (non-negotiable)\n\nEvery visible region of a Supercard must convey one complete idea on its own. A stranger seeing only a cropped screenshot — no scroll context, no surrounding sections — should still understand a single, coherent thought, and be able to trace it back to the system via the corner glyph.\n\n**Why it matters.** This is the load-bearing principle. It's what made V1 work and what V2 lost. Supercards live in the wild — shared, screenshotted, dropped into Slack, pinned on Pinterest — and a card that requires its full scroll to make sense is a card that breaks the moment it leaves the canvas.\n\n**How to apply.** Run the screenshot test on every section, including the header. First sentence must stand without prior context. No pronoun-first openers (\"It works because...\") that depend on what came before.\n\n## 2. Single emphasis per block (Lorch 1995)\n\nEach block has exactly **one** emphasized phrase — one bold span, one focal stat, one highlighted callout. Two emphases compete; three is noise.\n\n**Why it matters.** Cognitive load research (Lorch 1995, Sanchez & Wiley 2006) shows that emphasis effects collapse when more than one item per visual region competes for primacy. The reader's eye doesn't know where to land, so it lands nowhere — and the block reads as a wall.\n\n**How to apply.** Before publishing any block, ask: \"If a reader takes away one phrase from this block, which is it?\" Bold that phrase. Strip everything else back to body weight.\n\n## 3. Format-as-grammar, not length\n\nA Supercard is defined by its grammar (the 7-beat narrative spine, the block library, the screenshot test) — not by how long it is. Mini, Standard, and XL are presentation variants of the same grammar, not separate formats.\n\n**Why it matters.** Length-as-identity is how V2 drifted: \"Standard\" started meaning \"long\" rather than \"complete,\" and Mini stopped existing because it felt like \"less Supercard.\" Same grammar, different density — Standard remains canonical.\n\n**How to apply.** Author the content first as a 7-beat structure. Then choose a length variant based on topic depth, not desired ceremony. Don't pad a Mini to fill a Standard; don't compress an XL to fit a Standard.\n\n## 4. Sparing use of cards (chrome is noise)\n\nCards (rounded, lofted, padded surfaces) are the most expensive visual primitive in the system. Reserve them for the hero and at most two other elevated moments. Everything else is flat.\n\n**Why it matters.** When every block sits in a card shell, the chrome becomes the design — and the reader stops being able to distinguish the *anchor* moments from ordinary text. The hard cap is **1–3 lofted elements per Supercard** (hero + ≤2 others).\n\n**How to apply.** Default every block to flat. Justify each lofted element by what it anchors. If you can't articulate why a block deserves elevation, leave it flat.\n\n## 5. Strict grayscale (no color, ever)\n\nSupercards use black, white, and a six-step gray ramp (0%, 6%, 12%, 30%, 60%, 100%). No accent colors. No category colors. No data colors.\n\n**Why it matters.** Color introduces hue management cost (which red? which orange? does it match across cards?). Grayscale forces emphasis to come from weight, position, and size — the underlying typography decisions. The result is editorial timelessness instead of web-app fashion.\n\n**How to apply.** All emphasis lives in font weight (300 → 700) and gray opacity. Charts use solid black for the focal series and gray-30/gray-60 for context series. Never use color to \"highlight\" — use weight or position.\n\n## 6. SF Pro Rounded as the canonical typeface\n\nSF Pro Rounded for body and display, SF Mono for code and equations. The CSS keyword `ui-rounded` resolves to it on Apple platforms, with a documented fallback chain.\n\n**Why it matters.** The rounded variant of SF Pro carries warmth that pure SF Pro doesn't — it reads as cognitive-prosthesis (a thinking aid) rather than corporate (a deliverable). That tonal difference is the entire reason a Supercard feels different from a slide deck.\n\n**How to apply.** Always declare the full font stack (`ui-rounded, \"SF Pro Rounded\", \"SF Pro\", -apple-system, BlinkMacSystemFont, system-ui, ...`). Inline the font on the container, not via a Tailwind class.\n\n## 7. Authoring friction is a feature\n\nWriting a Supercard should feel like writing — i.e., it should be slow, considered, and require synthesis. The format actively resists templates that let you skip thinking.\n\n**Why it matters.** A card that's easy to author tends to be easy to skim past. The friction (filling out a Metadata table, running the screenshot test, choosing the right block per beat) forces the author to actually have a position. Cards written in 5 minutes look like cards written in 5 minutes.\n\n**How to apply.** Don't shortcut the redundancy filter. Don't skip beats because \"this topic doesn't need them.\" If a block writes itself in seconds, suspect it.\n\n## 8. Content frozen at authored version\n\nA Supercard authored under V3.0 stays valid under V3.0 forever. Spec updates don't retroactively reformat old cards. The renderer maintains versioned rule libraries; new blocks added in V3.1+ are unknown to V3.0 cards and skipped, not auto-migrated. (Formalized in ADR-0003.)\n\n**Why it matters.** Auto-migration corrupts the archive — Notion's block format auto-migrates and you can never reconstruct what you wrote in 2019. Frozen-at-authored preserves the genealogy as a true historical record. V3.0's design choices become consequential because we can't quietly fix them later.\n\n**How to apply.** Every Supercard's frontmatter declares `frozen_at_version: 3.X.Y`. Forward migration is allowed only voluntarily — re-author a card under a newer version, with a migration note in the new card's history.\n\n## 9. The redundancy filter\n\nBefore any block ships, ask: *what unique element does this add that's not already in any other block on this Supercard?* If the answer is \"nothing\" or \"restates the thesis,\" cut the block.\n\n**Why it matters.** Redundancy is the silent killer of synthesis. Each block competes for attention; a block that re-says what an adjacent block already said dilutes both. The filter forces every block to earn its scroll.\n\n**How to apply.** Run on every block at draft completion. Pull-quotes that paraphrase body fail. Definitions for context-obvious terms fail. Padding sections that \"balance the structure\" fail. When in doubt, cut — a card that's tighter is always more authoritative.\n\n## 10. Genealogy-as-asset\n\nThe history of how a Supercard came to be — the ADRs, the stewards' log, the rejected ideas, the version it was authored under, the cards that superseded it — is part of the artifact, not metadata. The system optimizes for legibility of its own evolution.\n\n**Why it matters.** Most knowledge systems optimize for the current state and treat history as overhead. Supercards treat history as a load-bearing feature: a future reader (or future-Derick) can reconstruct *why* a card looks the way it does, which is the only way to evolve the system without repeating V2's drift.\n\n**How to apply.** Every card declares `version` and `frozen_at_version`. Every card optionally declares `supersedes` and `related`. ADRs document why decisions were made. The stewards' log captures the *noticing* — patterns observed, temptations resisted. Treat the archive as the asset, not as cleanup to do later.\n\n## 11. Cognitive prosthesis, made operational (V3.1+)\n\nThe ADHD framing in principle 1 isn't a vibe; it must translate into four MUST rules every V3.1+ card honours: (a) every block is scannable in under 4 seconds, (b) every beat is re-enterable from any of its blocks, (c) every cropped screenshot carries beat identity via the micro-folio, (d) every prose block frontloads its thesis in a bolded lead-clause.\n\n**Why it matters.** V3.0 stated the goal (cognitive prosthesis) but enforced it only at the principle level — single emphasis, redundancy filter, screenshot autonomy. That left room for long `standard-text` walls, undifferentiated multi-block beats in XL, and cards that scan beautifully on the hero and collapse two beats later. The operational rules close that gap without breaking the existing constraints.\n\n**How to apply.** The single-emphasis rule (principle 2) is unchanged. The bolded lead-clause **is** the block's one emphasis — no second bold runs in the same block. Long prose splits at the 75-word ceiling. Re-entry comes from the top-and-bottom micro-folio (`BEAT 3 · MECHANISM · 4 / 7`) on every card. See `GRAMMAR` § G-7 / G-8 and `RENDERING` § R-9 / R-10 for the rendering contract.\n\n## 12. First-pass extraction test (V3.1+)\n\nA reader who scans ONLY the bolded clauses of a card, top to bottom, must be able to reconstruct the card's thesis in one sentence. If the bold-only read fails, the card fails review.\n\n**Why it matters.** This is the discipline check on principle 11(d). It forces every bolded clause to do real work and exposes lead-clauses that hedge, restate, or filler their way through a block. Pernice's eye-tracking work (NN/g 2017, 2019) shows scanners enter at the leftmost 1–3 words of each line; that's exactly what this test optimizes for.\n\n**How to apply.** Run alongside the screenshot test (below), not after. Read only the bolded spans, top to bottom — title, hero takeaway, every lead-clause, every focal stat, every key-takeaway. They should compose a coherent thesis. If they don't, the lead-clauses aren't earning their bold.\n\n---\n\n## What these principles aren't\n\n- **They're not a checklist.** A card can pass every individual check and still feel wrong. The principles work together; violating one usually surfaces in another.\n- **They're not aesthetic preferences.** Every principle has a load-bearing reason — most grounded in cognition research, design system precedent, or specific incidents (V2 drift, archive corruption).\n- **They're not exhaustive.** GRAMMAR, LENGTHS, and RENDERING formalize the *how*. PRINCIPLES is the *what we're doing and why* — when those three docs disagree with this one, this one wins.\n\n## The screenshot test (the principle of principles)\n\nIf you can only remember one rule from this doc, remember this: **every visible region must convey one complete idea, traceable back to the system via the corner glyph.** Everything else flows from that.\n\n## The ADHD scan-ability gate (V3.1+)\n\nRuns alongside the screenshot test on every V3.1+ card before publication. Ten questions, binary Y/N. Any \"no\" blocks the render.\n\n1. Does every `standard-text` block open with a bolded 2–6-word lead-clause?\n2. Does no block contain more than one bolded run?\n3. Does reading only the bold clauses top-to-bottom yield the card's thesis?\n4. Does no `standard-text` block exceed 75 words or 4 sentences?\n5. Does the anchor-to-content ratio per beat sit between 1:2 and 1:4?\n6. Does no beat contain more than 4 consecutive content blocks without an asterism or anchor break?\n7. Does every beat of ≥ 5 blocks contain at least one centered asterism (⁂)?\n8. Are top-edge and bottom-edge beat micro-folios present and tabular-aligned?\n9. Is every `stat-callout` accompanied by a verbal-anchor sentence, and every `table` of ≥ 4 rows closed by a bolded takeaway row?\n10. Does body text render at 17pt SF Pro Rounded, 26pt leading, +0.5pt tracking, left-aligned ragged-right, with no italic-for-emphasis runs?\n\nV3.0 cards are exempt — they're frozen at their authored version per ADR-0003. The gate applies only to cards with `frozen_at_version: 3.1.0` or higher.\n", "see_also_urls": [ "https://berafoot.com/spec/grammar.json", "https://berafoot.com/spec/tokens.json" ], "mirror_urls": [ { "name": "berafoot", "url": "https://berafoot.com/spec/principles.json" }, { "name": "vercel", "url": "https://supercard-seven.vercel.app/spec/principles.json" } ] }