{
  "contract": "shapeable.site-design-system",
  "version": "1.1.0",
  "site": "waterfall.sh",
  "repository": "repo://waterfall.sh",
  "status": "owner-approved",
  "approval": {
    "state": "approved",
    "ownerReviewRequired": true,
    "approvedAt": "2026-11-04T22:00:00.000Z",
    "evidence": "contracts/waterfall-sh-owner-feedback-20261104.md"
  },
  "generatedAt": "2026-11-04T22:00:00.000Z",
  "identityBrief": "repo://waterfall.sh/ribbon.css, repo://waterfall.sh/ribbon-pages.css, repo://waterfall.sh/index.html, repo://waterfall.sh/PERFECT.md, and contracts/waterfall-sh-owner-feedback-20261104.md (no standalone identity brief file exists; this pack was extracted from the accepted, shipped CSS).",
  "ownerPreferences": {
    "ledger": "preferences/owner-preferences.json",
    "site": "waterfall.sh",
    "latestFeedbackId": "waterfall-ribbon-home-accepted"
  },
  "intent": "Make waterfall.sh feel as considered as Stripe while staying its own: a light page, one luminous cascade ribbon that reads as falling water, and the real local board shown large, so a developer sees the product and the price in one pass.",
  "northStar": "A developer understands in one pass that waterfall.sh is a local board that sends each prompt to the cheapest model that can do it, sees the product itself, and can buy the $30 founding license or download in one click.",
  "personality": {
    "traits": [
      "luminous",
      "calm",
      "confident",
      "precise",
      "honest",
      "generous with space"
    ],
    "signature": "A single cascade ribbon (a conic gradient of #5ec6ff, #2f6bff, #6b5cff, #12c2b3, and #a7f3ff with fine diagonal white striations, clipped to a polygon and masked to fade into white) falling behind a light-weight Inter Tight headline, with the dark local board overlapping it and bleeding off the right edge. The ribbon returns once in the navy closing band.",
    "mustPreserve": [
      "The light white page with ink #0a2540 type.",
      "One cascade ribbon in the hero and its return in the closing band, nowhere else.",
      "Light-weight (300) display headlines with negative tracking.",
      "The product shown large: the dark board still overlaps the ribbon and bleeds off the right edge on desktop.",
      "Pill-shaped actions, 22px tiles, and soft layered shadows for depth.",
      "Sentence-case labels; honest status, the unsigned-installer note, and labelled example figures."
    ],
    "mustNotBecome": [
      "Dark generic SaaS. Adam rejected the earlier dark v3 system on 2026-11-04 ('i still dont like the waterfall design system').",
      "Hand-drawn mockups that skip the Shapeable pipeline (previews A, B, and C were rejected on 2026-11-04).",
      "Stripe trade dress: no Stripe gradient shape, wave, logo, product imagery, or copy. Learn principles only.",
      "Tracked micro-caps eyebrows over every section (the measured top generated-look tell).",
      "Uniform grids of three identical cards.",
      "Fabricated savings or results presented as measured."
    ]
  },
  "foundations": {
    "color": {
      "strategy": "Light only. White and a pale tint carry the page; ink type sits on them. Blue is for links and the one highlighted phrase. The ribbon stops appear only inside the ribbon art layer. Good green is reserved for savings figures and success. The dark board keeps its own sub-palette as an illustration and never leaks into page chrome.",
      "tokens": [
        {
          "name": "ink",
          "role": "primary text and dark surfaces",
          "light": "#0a2540",
          "dark": "unspecified: light-only identity",
          "usage": "Headlines, body emphasis, the dark pill, code blocks, and the navy closing band."
        },
        {
          "name": "mute",
          "role": "secondary text",
          "light": "#425466",
          "dark": "unspecified: light-only identity",
          "usage": "Ledes, section subtitles, and tile copy."
        },
        {
          "name": "soft",
          "role": "tertiary text",
          "light": "#5f6f84",
          "dark": "unspecified: light-only identity",
          "usage": "Fine print, captions, and meta. Minimum 12px."
        },
        {
          "name": "line",
          "role": "hairline",
          "light": "#e3e8ee",
          "dark": "unspecified: light-only identity",
          "usage": "Card outlines (as 1px box-shadow), band borders, and dividers."
        },
        {
          "name": "tint",
          "role": "pale surface",
          "light": "#f6f9fc",
          "dark": "unspecified: light-only identity",
          "usage": "The full-bleed cascade band, bento tiles, install cards, and inner-page cards."
        },
        {
          "name": "white",
          "role": "page canvas",
          "light": "#ffffff",
          "dark": "unspecified: light-only identity",
          "usage": "Body background on every route."
        },
        {
          "name": "blue",
          "role": "accent on white",
          "light": "#0a6fd6",
          "dark": "unspecified: light-only identity",
          "usage": "Home links, the highlighted headline phrase, focus rings, and the hard-step outline."
        },
        {
          "name": "accent-inner",
          "role": "accent on light tints",
          "light": "#0859ad",
          "dark": "unspecified: light-only identity",
          "usage": "Inner-page accent (leaderboard, workshop, docs) so blue text stays AA on #e6f0fb and #eaf3fd tints."
        },
        {
          "name": "good",
          "role": "savings and success",
          "light": "#08744e",
          "dark": "unspecified: light-only identity",
          "usage": "Savings figures, per-step costs, and the works-today status dot only."
        },
        {
          "name": "warn",
          "role": "caution",
          "light": "#9a5b00",
          "dark": "unspecified: light-only identity",
          "usage": "Pilot or caution states on inner pages."
        },
        {
          "name": "ribbon-cyan",
          "role": "ribbon stop",
          "light": "#5ec6ff",
          "dark": "unspecified: light-only identity",
          "usage": "Cascade ribbon gradient stop and the cascade line in the routing band."
        },
        {
          "name": "ribbon-blue",
          "role": "ribbon stop",
          "light": "#2f6bff",
          "dark": "unspecified: light-only identity",
          "usage": "Cascade ribbon gradient stop and step markers."
        },
        {
          "name": "ribbon-violet",
          "role": "ribbon stop",
          "light": "#6b5cff",
          "dark": "unspecified: light-only identity",
          "usage": "Cascade ribbon gradient stop."
        },
        {
          "name": "ribbon-teal",
          "role": "ribbon stop",
          "light": "#12c2b3",
          "dark": "unspecified: light-only identity",
          "usage": "Cascade ribbon gradient stop."
        },
        {
          "name": "ribbon-mist",
          "role": "ribbon stop",
          "light": "#a7f3ff",
          "dark": "unspecified: light-only identity",
          "usage": "Cascade ribbon highlight stop."
        },
        {
          "name": "board-bg",
          "role": "board canvas",
          "light": "#0b1220",
          "dark": "unspecified: light-only identity",
          "usage": "Illustration-only sub-palette for the dark local board still. Board chat area."
        },
        {
          "name": "board-rail",
          "role": "board rail",
          "light": "#08101c",
          "dark": "unspecified: light-only identity",
          "usage": "Illustration-only sub-palette for the dark local board still. Board sidebar, title bar, and side panel."
        },
        {
          "name": "board-card",
          "role": "board card",
          "light": "#0f1830",
          "dark": "unspecified: light-only identity",
          "usage": "Illustration-only sub-palette for the dark local board still. Board message cards and the active project row."
        },
        {
          "name": "board-accent",
          "role": "board accent",
          "light": "#5ec6ff",
          "dark": "unspecified: light-only identity",
          "usage": "Illustration-only sub-palette for the dark local board still. Hard-route badge and sparkline."
        },
        {
          "name": "board-good",
          "role": "board success",
          "light": "#3dd68c",
          "dark": "unspecified: light-only identity",
          "usage": "Illustration-only sub-palette for the dark local board still. Cheap-route badge, live dots, and the saved metric."
        }
      ]
    },
    "typography": {
      "strategy": "Inter Tight, self-hosted as one variable woff2 (weights 300 to 600, SIL Open Font License), carries everything except code, which uses system mono. Display type is large and light (300) with negative tracking; body is 17px. Labels are sentence case, never tracked uppercase. Nothing renders below 12px.",
      "families": [
        {
          "role": "interface and display",
          "family": "Inter Tight",
          "fallback": "-apple-system, \"Segoe UI\", system-ui, sans-serif",
          "usage": "Headlines, body, navigation, pills, labels. Served from /fonts/inter-tight-latin.woff2 and preloaded."
        },
        {
          "role": "code and figures",
          "family": "system mono",
          "fallback": "ui-monospace, \"SF Mono\", \"Cascadia Code\", Menlo, Consolas, monospace",
          "usage": "Code blocks, the prompt line, per-step costs, and board figures."
        }
      ],
      "scale": [
        {
          "name": "h1",
          "size": "72px desktop, 48px tablet (900px and below), 40px phone (480px and below)",
          "lineHeight": "1.02",
          "weight": 300,
          "tracking": "-0.035em",
          "usage": "The single hero headline, with one highlighted phrase in blue."
        },
        {
          "name": "close-h2",
          "size": "56px desktop, 34px mobile",
          "lineHeight": "1.04",
          "weight": 300,
          "tracking": "-0.035em",
          "usage": "The closing band headline on navy."
        },
        {
          "name": "h2",
          "size": "48px desktop, 34px mobile",
          "lineHeight": "1.06",
          "weight": 300,
          "tracking": "-0.03em",
          "usage": "Section and cascade band headlines."
        },
        {
          "name": "tile-title",
          "size": "24px to 28px",
          "lineHeight": "1.2",
          "weight": 400,
          "tracking": "-0.02em to -0.025em",
          "usage": "Bento tiles and ranking link cards."
        },
        {
          "name": "lede",
          "size": "21px desktop, 18px mobile",
          "lineHeight": "1.5",
          "weight": 400,
          "tracking": "0",
          "usage": "The one hero sentence; section subtitles use 19px."
        },
        {
          "name": "body",
          "size": "17px",
          "lineHeight": "1.6",
          "weight": 400,
          "tracking": "0",
          "usage": "Reading text and lists."
        },
        {
          "name": "small",
          "size": "13px to 15px (12px minimum)",
          "lineHeight": "1.5",
          "weight": 400,
          "tracking": "0",
          "usage": "Captions, notes, fine print, and sentence-case labels at 15px weight 500."
        }
      ]
    },
    "spacing": {
      "baseUnitPx": 4,
      "density": "Generous. Sections are separated by 128px on desktop and 88px on mobile; the hero opens with 112px (64px mobile). One idea per section. Density is allowed only inside the board still and data tables.",
      "scalePx": [
        8,
        12,
        16,
        24,
        32,
        48,
        56,
        72,
        88,
        112,
        128
      ]
    },
    "shape": {
      "radiusPx": [
        999,
        22,
        18,
        14,
        12
      ],
      "border": "Hairlines are drawn as 1px box-shadow in #e3e8ee (or ink at low alpha) rather than CSS borders, except the cascade band's top and bottom rules.",
      "elevation": "Soft layered shadows are part of the identity: for example 0 30px 60px -20px #0a254040 on the floating savings card and 0 50px 100px -20px #0a254066 on the board. Steps and tabs use 0 1px 2px #0a25400d plus a soft 0 8px 24px -12px lift. Never hairline-only flatness.",
      "signatureShape": "Pills (999px) for every action, 22px tiles and cards, 18px for the floating savings card, 14px for the board and routing steps, 12px for code blocks and tab rows."
    },
    "layout": {
      "strategy": "Max content width 1200px with a 32px gutter (20px under 480px). The hero is a 660px text column with the ribbon behind the right side; the stage below lets the board run off the right edge. The cascade is a full-bleed tint band with copy left and the routing picture right. Promises are a bento: one wide tile plus two stacked tiles, never three identical cards. At most one sentence-case label per section, and no tracked caps.",
      "maxContentWidthPx": 1200,
      "columns": 12,
      "gutterPx": 32,
      "breakpointsPx": [
        480,
        900,
        960
      ]
    },
    "motion": {
      "principle": "Motion only confirms hover and focus: background and box-shadow transitions on pills and link cards. Nothing animates on load or on scroll.",
      "durationsMs": [
        0,
        300
      ],
      "easing": "cubic-bezier(.22, 1, .36, 1)",
      "reducedMotion": "Under prefers-reduced-motion: reduce, all transitions are off and every state renders complete."
    },
    "focus": {
      "ring": "3px solid #0a6fd6",
      "offset": "3px",
      "rule": "Every link, pill, and summary shows a visible focus-visible ring with a 6px radius; the skip link becomes visible on focus."
    },
    "imagery": {
      "direction": "One art layer and one product. The cascade ribbon is pure CSS (conic gradient, polygon clip-path, linear mask, repeating diagonal striations). The product is a stageshow-style still of the real local board (rail, tabs, chat with routed badges, savings side panel), aria-hidden with data-shapeable-illustration and captioned 'Illustrative board. Example numbers, not measured savings.' The Drop is the logo: one disc sliced once with the right half dropped (two exact arcs), chosen by Adam through the logo-design skill. Master in blue #0a6fd6 on white; white on ink or blue; on a blue #0a6fd6 tile as the app icon and favicon. Files: /brand/waterfall-mark.svg, /brand/waterfall-mark-white.svg, /brand/waterfall-mark-app-icon.svg, /favicon.ico. Never stretch, rotate, outline, add a gradient, or place it on the ribbon.",
      "allowed": [
        "The cascade ribbon in the hero and once in the closing band.",
        "Code-built stills of the real board and the routing flow, with labelled example figures.",
        "The floating savings card overlapping the board.",
        "The Drop mark in blue, white, or on a blue tile, at any size from 16px up."
      ],
      "forbidden": [
        "Third-party logos or Stripe imagery as decoration.",
        "Stock photos or AI-generated people.",
        "More than one ribbon per view, or ribbon colors outside the ribbon.",
        "Unlabelled figures that could read as measured savings."
      ]
    }
  },
  "patterns": [
    {
      "name": "hero",
      "intent": "Product, promise, and price in one pass.",
      "rules": [
        "One h1 at weight 300 with one blue phrase.",
        "One 21px sentence.",
        "Dark pill 'Buy the founding license · $30' and light pill 'Download for Windows'.",
        "One fine-print line: one-time, own keys, no markup, unsigned installer."
      ],
      "states": [
        "default",
        "hover",
        "focus-visible",
        "stacked-mobile"
      ]
    },
    {
      "name": "board-stage",
      "intent": "Show the real product large, with depth.",
      "rules": [
        "The board (1040px) overlaps the ribbon and bleeds off the right edge on desktop.",
        "A white savings card floats in front at the left.",
        "On mobile the board becomes one column (rail and side panel hidden) and the card is hidden.",
        "Always captioned as illustrative with example numbers."
      ],
      "states": [
        "desktop-bleed",
        "mobile-column"
      ]
    },
    {
      "name": "cascade-band",
      "intent": "Explain routing as a picture, not a paragraph.",
      "rules": [
        "Full-bleed tint band with top and bottom hairlines.",
        "A dark prompt line, three white routing steps on a cyan-to-teal line, the hard step outlined in blue.",
        "Per-step costs in good green mono, then an all-Claude comparison.",
        "A note that costs are examples and real prices come from OpenRouter at run time."
      ],
      "states": [
        "default",
        "compact-mobile"
      ]
    },
    {
      "name": "bento",
      "intent": "Three promises in three shapes.",
      "rules": [
        "One wide tile with live project rows plus two stacked tiles.",
        "One tile carries the large blue 0% markup figure.",
        "Never three identical cards."
      ],
      "states": [
        "desktop-bento",
        "stacked-mobile"
      ]
    },
    {
      "name": "close-band",
      "intent": "End on the offer with the ribbon's return.",
      "rules": [
        "Navy band, ribbon masked in from the right.",
        "56px weight 300 headline, three checked inclusions, white Buy pill and a contact pill."
      ],
      "states": [
        "default",
        "focus-visible"
      ]
    },
    {
      "name": "inner-pages",
      "intent": "Every page reads as the same product.",
      "rules": [
        "Same Ribbon nav and footer on every page, current page marked with aria-current.",
        "A soft radial wash replaces the ribbon on inner pages.",
        "Legacy dark tokens are remapped to the light palette in ribbon-pages.css; former uppercase labels are sentence case."
      ],
      "states": [
        "default",
        "current-page"
      ]
    }
  ],
  "content": {
    "voice": "A calm, precise developer explaining a tool to another developer: plain verbs, short sentences, real numbers, and the limits stated up front.",
    "rules": [
      "Lead with what it does in one sentence.",
      "State the price once in the hero, once in the close, and compactly in the nav.",
      "Label every example figure as an example.",
      "Keep honest status: works today, being wired up, pending.",
      "Use sentence case for every label."
    ],
    "bannedPatterns": [
      "Hype words such as revolutionary, magic, or 10x.",
      "Em dashes.",
      "Tracked all-caps eyebrows.",
      "Claims of measured savings without evidence."
    ]
  },
  "responsiveRules": [
    {
      "name": "mobile-sequence",
      "rule": "At 390px: headline, sentence, stacked full-width pills, fine print, then the one-column board, with no horizontal page overflow.",
      "acceptance": "Site audit reports zero horizontal overflow and zero offscreen page text at 390 x 844."
    },
    {
      "name": "ribbon-mobile",
      "rule": "Under 900px the ribbon spans the viewport width at 45% opacity behind the hero and never sits behind the Buy pill.",
      "acceptance": "Rendered 390px frame shows the nav and pills fully legible over the ribbon."
    },
    {
      "name": "bands-full-bleed",
      "rule": "The cascade band and close band run edge to edge while their content stays on the 1200px grid.",
      "acceptance": "No horizontal overflow at 1440 or 390."
    }
  ],
  "accessibility": [
    {
      "name": "contrast",
      "rule": "All text meets WCAG 2.2 AA; blue on tints uses #0859ad, savings green is #08744e.",
      "acceptance": "axe-core reports zero color-contrast violations at both viewports on every route."
    },
    {
      "name": "targets",
      "rule": "Every link, pill, nav item, and footer link has at least a 44 by 44px hit area.",
      "acceptance": "Shapeable touch-target checks report zero shortfalls."
    },
    {
      "name": "illustrations",
      "rule": "The ribbon, board still, savings card, and tab rows are aria-hidden; decorative regions carry data-shapeable-illustration.",
      "acceptance": "No illustrative text appears in the accessibility tree; captions carry the meaning."
    },
    {
      "name": "reduced-motion",
      "rule": "Transitions are off under prefers-reduced-motion.",
      "acceptance": "Shapeable reduced-motion check reports no active transitions."
    }
  ],
  "influences": [
    {
      "id": "stripe",
      "title": "Stripe",
      "author": "Stripe design team",
      "url": "https://stripe.com/",
      "principle": "A light page, very light display type, one luminous art layer, and dense product proof shown with depth.",
      "take": "Light-weight headlines, a single gradient art layer, product shown large with layered shadows. Adam's primary gold reference.",
      "doNotCopy": "Do not copy Stripe's gradient shape, wave, colors as a set, logos, product imagery, layouts, or copy."
    },
    {
      "id": "framer",
      "title": "Framer",
      "author": "Framer",
      "url": "https://www.framer.com/",
      "principle": "The product canvas is the hero and runs large.",
      "take": "Let the board be big and real rather than a small boxed still.",
      "doNotCopy": "Do not copy Framer's glow treatment, typography, or assets."
    },
    {
      "id": "family",
      "title": "Family",
      "author": "Benji Taylor and the Family team",
      "url": "https://family.co/",
      "principle": "Warmth and friendliness in a trust-critical product, with zero tracked caps.",
      "take": "Friendly sentence-case copy and generous rounding.",
      "doNotCopy": "Do not copy Family's characters, illustrations, or brand."
    },
    {
      "id": "cursor",
      "title": "Cursor",
      "author": "Anysphere",
      "url": "https://cursor.com/",
      "principle": "Show the actual app window framed by an art layer.",
      "take": "The board still framed by the ribbon art layer.",
      "doNotCopy": "Do not copy Cursor's paintings, app chrome, or typography."
    },
    {
      "id": "stageshow",
      "title": "stageshow",
      "author": "Benji Taylor",
      "url": "https://github.com/benjitaylor/skills",
      "principle": "Product stills with a word budget, cropped off the edge, never boxed with even margins.",
      "take": "The board's few real strings, the right-edge bleed, and the illustrative caption.",
      "doNotCopy": "Do not ship the stageshow kit's brand marks or components as page UI."
    }
  ],
  "governance": {
    "owner": "Adam Pang (waterfall.sh owner)",
    "sourceOfTruth": "This design-system.json, extracted from repo://waterfall.sh/ribbon.css and ribbon-pages.css. The Claude guide is rendered from this file deterministically. Runtime tokens live in body.ribbon in those stylesheets and must match.",
    "versioning": "Semantic versioning. Patch clarifies evidence, minor adds compatible rules or tokens, major changes identity. 1.0.0 is the first version of the Ribbon identity and replaces the rejected dark v3 pack (0.1.0).",
    "adoption": "Owner-approved. Adam previewed the Ribbon home on localhost and answered 'accept' on 2026-11-04, after choosing direction A from three pipeline-built directions (gold references Stripe, Framer, Family, Cursor). The inner-page rollout (leaderboard, workshop, starter packs, about, contact, privacy, thanks, design) follows the accepted home and carries its tokens; it needs the owner's review before production.",
    "deviations": "The board still keeps a dark illustration-only sub-palette. Inner pages use #0859ad instead of #0a6fd6 so blue stays AA on light tints. Record any further deviation with rationale, page, owner, and expiry in the next version.",
    "lastAuditId": "site-audit-20261104191533",
    "reviewCadence": "Re-audit the full site after any material visual, interaction, or route change; persist every owner direction or rejection to the ledger before the next revision."
  },
  "agentInstructions": {
    "readFirst": [
      "Read this design-system.json and repo://waterfall.sh/ribbon.css before changing any page.",
      "Read contracts/waterfall-sh-owner-feedback-20261104.md for the owner's rejections and choices.",
      "Read shapeable.art reference/premium-pipeline-20261104.md for the build and review pipeline."
    ],
    "decisionRules": [
      "Keep the page light; never return to the rejected dark system.",
      "Use only the tokens above; no one-off colors or sizes.",
      "One cascade ribbon in the hero and one in the close, nowhere else.",
      "Show the product large; never a boxed window with even margins.",
      "Use sentence-case labels; never tracked uppercase eyebrows.",
      "Prefer bento layouts; never three identical cards.",
      "Label every example figure."
    ],
    "forbidden": [
      "Stripe trade dress or any third-party logos as decoration.",
      "Dark generic SaaS styling.",
      "Hand-drawn mockups that skip the Shapeable pipeline.",
      "Inline style attributes (the site CSP forbids them)."
    ],
    "reviewChecklist": [
      "Shapeable audit:sitewide reports 100/100 with full route coverage.",
      "The taste tells report zero tracked micro-caps and zero uniform card grids.",
      "A fresh-eye reviewer compares frames against the Stripe gold reference and names the one difference."
    ]
  },
  "runnableEvidence": [
    {
      "command": "npm run audit:sitewide -- --url http://127.0.0.1:4100 --allow-loopback true --public-url https://waterfall.sh --output artifacts/audits/waterfall-sh-ribbon-20261104-pass4",
      "expected": "100/100, 100% profile coverage, 8 of 8 eligible routes, zero findings (site-audit-20261104190810). The accepted Ribbon home.",
      "scope": "Local preview of branch shapeable-ribbon-20261104; run from shapeable.art."
    },
    {
      "command": "npm run audit:sitewide -- --url http://127.0.0.1:4100 --allow-loopback true --public-url https://waterfall.sh --include /design --output artifacts/audits/waterfall-sh-ribbon-rollout-20261104-pass4",
      "expected": "100/100, 100% profile coverage, 8 of 8 eligible routes (site-audit-20261104191533). Ribbon carried to every page.",
      "scope": "Local preview of the inner-page rollout; run from shapeable.art."
    }
  ],
  "exports": {
    "machinePath": ".shapeable/design-system.json",
    "claudePath": ".shapeable/CLAUDE_DESIGN_SYSTEM.md",
    "claudeImport": "@.shapeable/CLAUDE_DESIGN_SYSTEM.md"
  }
}
