@stylecrib/cli 0.0.0-stage → 0.3.2

package/themes/newspaper-classic/tokens.ts

@@ -0,0 +1,159 @@
+import type { Direction } from "../schema";
+
+// Note: "newspaper-classic" is not yet in the Direction["name"] enum.
+// The schema is closed; until it is extended this file casts the name.
+// All other fields fully validate.
+
+export const newspaperClassic: Direction = {
+  name: "newspaper-classic" as Direction["name"],
+  ethos: "NYT Cheltenham · WaPo dignified daily · Le Monde five-column page · Guardian section ribbons · WSJ stipple authority",
+  references: [
+    { brand: "The New York Times", trait: "Cheltenham-style display serif, five-column front-page grid" },
+    { brand: "The Washington Post", trait: "Democracy-Dies-in-Darkness gravitas, breaking-news ticker" },
+    { brand: "Le Monde", trait: "broadsheet column rhythm, dateline as masthead anchor" },
+    { brand: "The Guardian", trait: "section ribbons across the page top, byline grids" },
+    { brand: "The Wall Street Journal", trait: "stippled portrait engravings, business-formal restraint" },
+  ],
+  feel:
+    "Cream newsprint stock with deep ink. Tall stately display serif headlines over a wide five-column page. " +
+    "Section nav reads like the top of a folded broadsheet; bylines and read-times sit in small caps. " +
+    "Restrained red is reserved for the breaking-news ticker and the masthead rule — never for decoration.",
+
+  fonts: {
+    display: {
+      family: "Playfair Display",
+      fallback: ["Cheltenham", "Georgia Pro", "Iowan Old Style", "Georgia", "serif"],
+      from: "Cheltenham-style high-contrast display serif — NYT front-page headline feel",
+      googleFont: "Playfair+Display",
+      weights: [400, 500, 700, 900],
+    },
+    body: {
+      family: "Source Serif Pro",
+      fallback: ["Charter", "Iowan Old Style", "Georgia", "serif"],
+      from: "WaPo/Guardian body serif — long-form readable on newsprint stock",
+      googleFont: "Source+Serif+Pro",
+      weights: [400, 600],
+    },
+    mono: {
+      family: "JetBrains Mono",
+      fallback: ["ui-monospace", "SFMono-Regular", "Consolas", "monospace"],
+      from: "datelines, bylines, read-times — instrument feel for editorial metadata",
+      googleFont: "JetBrains+Mono",
+      weights: [400, 500],
+    },
+  },
+
+  typography: {
+    headingTracking: "-0.018em",        // Playfair sits tighter; broadsheet headlines need it
+    bodyTracking: "0",
+    fontFeatureSettings: '"liga", "onum", "tnum"',
+    h1ScaleClamp: "clamp(2.5rem, 6.5vw, 5.25rem)",
+    bodyBaseSize: "1.0625rem",          // 17px — comfortable for long reading
+    bodyLineHeight: "1.62",
+  },
+
+  colors: {
+    background: { hsl: "40 28% 95%", from: "cream newsprint stock — slightly warmer than editorial paper" },
+    foreground: { hsl: "220 22% 11%", from: "deep newspaper ink, never pure black" },
+    card: { hsl: "40 30% 97%", from: "lighter cream card — sits one tier above the page" },
+    popover: { hsl: "40 30% 97%", from: "same as card; depth from rules, not fill" },
+    primary: { hsl: "0 65% 38%", from: "NYT op-ed red / WaPo breaking red — restrained masthead mark" },
+    primaryForeground: { hsl: "40 28% 95%", from: "cream on red" },
+    secondary: { hsl: "40 20% 90%", from: "deeper cream — quiet panels and inset boxes" },
+    secondaryForeground: { hsl: "220 22% 11%", from: "ink on cream" },
+    muted: { hsl: "40 20% 90%", from: "same as secondary; differentiation by usage" },
+    mutedForeground: { hsl: "220 12% 36%", from: "slate ink — bylines, datelines, read-times" },
+    accent: { hsl: "40 22% 88%", from: "deeper cream still — hover states and section panels" },
+    accentForeground: { hsl: "220 22% 11%", from: "ink on accent cream" },
+    border: { hsl: "220 14% 78%", from: "newsprint rule — visible column divider, not a hairline" },
+    input: { hsl: "220 14% 78%", from: "same as border — full-width input rules" },
+    ring: { hsl: "0 65% 38%", from: "primary, focus only" },
+    destructive: { hsl: "0 72% 45%", from: "alert red, more saturated than primary" },
+    destructiveForeground: { hsl: "40 28% 95%", from: "cream on alert" },
+    brand: {
+      ink: { hsl: "220 22% 11%", from: "deep newspaper ink — also semantic foreground" },
+      newsprint: { hsl: "40 28% 95%", from: "cream stock — also semantic background" },
+      "ink-soft": { hsl: "220 18% 26%", from: "secondary headings, decks, kicker text" },
+      "rule-strong": { hsl: "220 22% 11%", from: "page-top thick rule under masthead" },
+      "ticker-red": { hsl: "0 65% 38%", from: "breaking-news ticker base — = primary, named for intent" },
+      stipple: { hsl: "220 20% 36%", from: "WSJ stipple-portrait midtone, for caption motifs" },
+    },
+  },
+
+  spacing: {
+    base: 4,
+    scale: [4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64, 96],   // newsprint rhythm
+    containerMax: "max-w-6xl",         // wide — five-column grid needs the room
+    containerPadding: "px-6 lg:px-10",
+    sectionPadding: {
+      hero: "pt-16 pb-12 lg:pt-24 lg:pb-20",
+      default: "py-16 lg:py-24",
+      tight: "py-10 lg:py-14",
+    },
+  },
+
+  radius: {
+    base: "0",                          // sharp — newsprint convention
+    pillsAllowed: false,
+  },
+
+  shadows: {
+    style: "minimal",
+    utilities: {
+      "rule-bottom":
+        "0 1px 0 0 hsl(var(--border))",                    // column divider rule
+      "rule-thick":
+        "0 3px 0 0 hsl(var(--foreground))",                // page-top thick rule under masthead
+    },
+  },
+
+  motion: {
+    easing: "cubic-bezier(0.22, 1, 0.36, 1)",
+    durations: {
+      reveal: 800,
+      loop: 30000,                        // ticker speed
+      ambient: 60000,
+    },
+    keyframes: {
+      "fade-rise": {
+        css:
+          "from { opacity: 0; transform: translateY(16px); }\n" +
+          "to { opacity: 1; transform: translateY(0); }",
+        defaultDuration: 800,
+        iteration: "once",
+        purpose: "section entrance — subtle, never theatrical",
+      },
+      "ticker-scroll": {
+        css:
+          "from { transform: translateX(0); }\n" +
+          "to { transform: translateX(-50%); }",
+        defaultDuration: 30000,
+        iteration: "infinite",
+        purpose: "breaking-news ticker strip — slow horizontal crawl",
+      },
+    },
+    respectsReducedMotion: true,
+  },
+
+  density: "medium",
+
+  patterns: {
+    button:
+      "Text-link CTAs in --ink with underline on hover. The single masthead CTA (Subscribe) may be a solid --ink fill with --newsprint text. " +
+      "Section ribbons use --ticker-red flat fill, no border. No pill buttons — print convention.",
+    card:
+      "Top rule (1px --border) + bottom rule, no side borders. No fill differentiation from page. " +
+      "Title in display serif, kicker in mono uppercase, byline in mono small caps. Padding p-6 lg:p-8.",
+    input:
+      "Border-bottom only (1px --ink-soft). Label sits above in mono small caps. No full box.",
+    cta:
+      "Text-link with --ink color, underline on hover. Subscribe pill is the sole solid fill, --ink bg + --newsprint fg.",
+  },
+
+  details: {
+    selectionBg: "hsl(var(--primary) / 0.2)",
+    selectionFg: "hsl(var(--foreground))",
+    focusRing: "1px solid hsl(var(--ring))",
+    scrollbarStyle: "thin",
+  },
+};

package/themes/nonprofit-arts/THEME.md

@@ -0,0 +1,78 @@
+# Design Direction — Nonprofit-Arts
+
+## Ethos
+NY Phil deep wine + cream · Royal Ballet formal serif · SF Symphony season-calendar gravity · Lincoln Center curtain-up restraint · Carnegie Hall masthead pedigree
+
+## Feel
+An orchestra's printed season-book translated to the web. Deep wine red on warm ivory cream, formal serif display in small caps for performance titles, mono for dates and opus numbers. The page is slightly elevated, slightly hushed — but anchored in functional list-driven content: season calendar, ensemble roster, donor recognition. It must read like a program-book, not a marketing brochure.
+
+## Reference brands
+- **New York Philharmonic** → deep wine red, formal serif, season-calendar driven.
+- **Royal Ballet** → ivory program-book stock, Trajan-feel display, formal capitals.
+- **San Francisco Symphony** → concert-program serif, performance-row layout.
+- **Lincoln Center** → curtain-up restraint, deep red marker, generous whitespace.
+- **Carnegie Hall** → masthead pedigree, donor recognition tiers, formal capitals.
+
+## Tokens
+Surface stack is **program ivory** (background) → **lighter ivory** (card) → **deeper ivory** (secondary/muted/accent). Brand tokens: `--wine`, `--ivory`, `--ink`, `--gold`.
+
+Primary is `--wine`. Used for performance markers, focus ring, the hero CTA fill, and selection wash. `--gold` is reserved exclusively for donor-circle tier markers ("Maestro Circle", "Composer's Circle") — never elsewhere.
+
+## Typography
+- **Display:** Cormorant SC (small caps) — Royal Ballet / Carnegie masthead feel. h1–h4. Tracking `0.04em` — small caps need positive tracking.
+- **Body:** Cormorant Garamond (roman) — same family, lowercase variant for prose. 17px / 1.7.
+- **Mono:** JetBrains Mono. Dates, opus numbers, donor levels.
+
+H1 uses `clamp(2.5rem, 7vw, 5.5rem)`. Performance titles use display SC at body+2 — they read like marquee titles.
+
+## Spacing
+- **Container:** `max-w-6xl px-6 lg:px-12` — wider than editorial, accommodates the 5-column season grid.
+- **Sections:** hero `pt-28 pb-16 lg:pt-44 lg:pb-28`; default `py-20 lg:py-32`; tight `py-12 lg:py-20`.
+- **Scale:** 4 6 8 12 16 20 24 32 40 48 64 80 96 128 160.
+
+## Color
+No hex. Tokens only. Wine appears as fill only on the single 'Subscribe to the season' / 'Buy tickets' CTA. Everywhere else it's a hover state, hairline accent, or selection wash. Gold appears only on donor tier names — `font-variant: small-caps`.
+
+## Radius
+`--radius: 0`. Program books are sharp-cornered. Pills disallowed.
+
+## Shadows
+**Soft (one).** Three utilities: `.hairline-bottom`, `.program-rule`, and `.curtain-wash` (24px diffused wine glow under the hero only — the curtain-up feeling). No drop shadows on cards.
+
+## Motion
+Two keyframes: `fade-rise` (1200ms, ceremonial) and `wine-wash` (one-shot ambient under hero, opacity 0 → 0.06 over 2400ms). `prefers-reduced-motion` honored — `wine-wash` disables to a static state.
+
+## Component patterns
+- **Buttons:** text-link CTAs with wine-on-hover. 'Buy tickets' / 'Subscribe to the season' is the single solid-fill — wine bg + ivory text + small-caps label.
+- **Cards:** hairline rules, ivory-tier shift. Padding `p-8 lg:p-12`. Title in display SC; date + venue in mono; conductor / composer in body serif italic.
+- **Inputs:** border-bottom only (1px wine-ink). Label above in display SC.
+- **CTA links:** wine-ink → wine on hover. Never a chip, never a gradient.
+
+## Recommended rich media
+Performance photography — only. Stage lighting, low-light orchestral pit shots, conductor portraits in profile, ensemble shots taken from the back of the hall. Color-graded to a warm tungsten cast (the actual color of stage light). Never event-PR photography, never crowd shots at galas, never "behind the scenes" lifestyle. Headshots are formal — concert-program style, often in performance attire.
+
+**AI tool recommendations:** **Midjourney / Flux** with *"orchestra performance, warm tungsten stage lighting, deep shadows, photographed from the back of the hall"* or *"formal portrait, conductor, concert attire, soft window light"*. Avoid AI's tendency toward dramatic uplighting — concert lighting is warm and overhead, not theatrical.
+
+**Aspect ratios:** 16:9 widescreen (concert hall convention), 3:4 portrait (conductor headshot), 21:9 ultra-wide (proscenium / stage-from-the-balcony hero shot only).
+
+**Captions** in display SC small caps. Format: *"GUSTAVO DUDAMEL · MAHLER NO. 2 · GEFFEN HALL"*.
+
+**Avoid:** gala-night PR photos, crowd shots, "behind the scenes" rehearsal candids that read marketing, gradients, glassmorphic, decorative SVG.
+
+**Accessibility:** alt-text describes the performance — *"Orchestra performing under warm stage lights, conductor in profile, brass section visible."*
+
+## Component families
+- `Performance` family — list row with date + composer + conductor + venue.
+- `EnsembleMember` family — portrait + name + instrument + section.
+- `DonorTier` family — named circle (Maestro / Composer's / Conductor's) + tier amount + donor list.
+
+## Details
+- **Selection:** `hsl(var(--primary) / 0.22)` — wine wash.
+- **Focus ring:** `1px solid hsl(var(--ring))`.
+- **Scrollbar:** thin.
+
+## Exceptions
+None yet.
+
+## Revisions
+- Initial direction.

package/themes/nonprofit-arts/tokens.ts

@@ -0,0 +1,157 @@
+import type { Direction } from "../schema";
+
+export const nonprofitArts: Direction = {
+  name: "nonprofit-arts" as Direction["name"],
+  ethos:
+    "NY Phil deep wine + cream · Royal Ballet formal serif · SF Symphony season-calendar gravity · Lincoln Center curtain-up restraint · Carnegie Hall masthead pedigree",
+  references: [
+    { brand: "New York Philharmonic", trait: "deep wine red, formal serif, season-calendar driven" },
+    { brand: "Royal Ballet", trait: "ivory program-book stock, Trajan-feel display, formal capitals" },
+    { brand: "San Francisco Symphony", trait: "concert-program serif, performance-row layout" },
+    { brand: "Lincoln Center", trait: "curtain-up restraint, deep red marker, generous whitespace" },
+    { brand: "Carnegie Hall", trait: "masthead pedigree, donor recognition tiers, formal capitals" },
+  ],
+  feel:
+    "An orchestra's printed season-book made into a website. Deep wine red on warm ivory cream, formal " +
+    "serif display in small caps for performance titles, mono for dates and conductors. The page is " +
+    "atmospheric — slightly elevated, slightly hushed — but anchored in functional list-driven content " +
+    "(season calendar, ensemble, donor recognition).",
+
+  fonts: {
+    display: {
+      family: "Cormorant SC",
+      fallback: ["Cormorant Garamond", "Trajan Pro", "EB Garamond", "Georgia", "serif"],
+      from: "Royal Ballet / Carnegie Hall masthead-capitals feel — small-caps display serif",
+      googleFont: "Cormorant+SC",
+      weights: [400, 500, 600, 700],
+    },
+    body: {
+      family: "Cormorant Garamond",
+      fallback: ["EB Garamond", "Iowan Old Style", "Georgia", "serif"],
+      from: "concert-program body serif — Cormorant's roman, slightly tighter than display",
+      googleFont: "Cormorant+Garamond",
+      weights: [400, 500, 600],
+    },
+    mono: {
+      family: "JetBrains Mono",
+      fallback: ["ui-monospace", "SFMono-Regular", "Consolas", "monospace"],
+      from: "performance dates, opus numbers, donor levels — concert-program tabular feel",
+      googleFont: "JetBrains+Mono",
+      weights: [400, 500],
+    },
+  },
+
+  typography: {
+    headingTracking: "0.04em",
+    bodyTracking: "0",
+    fontFeatureSettings: '"tnum", "calt", "smcp"',
+    h1ScaleClamp: "clamp(2.5rem, 7vw, 5.5rem)",
+    bodyBaseSize: "1.0625rem",
+    bodyLineHeight: "1.7",
+  },
+
+  colors: {
+    background: { hsl: "38 32% 93%", from: "ivory program-book stock — Royal Ballet / Carnegie program" },
+    foreground: { hsl: "0 35% 12%", from: "deep wine-ink, almost black with a red undertone — concert ink" },
+    card: { hsl: "38 35% 96%", from: "lighter ivory — performance-row surface" },
+    popover: { hsl: "38 35% 96%", from: "matches card" },
+    primary: { hsl: "350 65% 28%", from: "deep wine red — NY Phil / Lincoln Center curtain-up red" },
+    primaryForeground: { hsl: "38 32% 93%", from: "ivory on wine" },
+    secondary: { hsl: "38 26% 88%", from: "deeper ivory — section divider, masthead row" },
+    secondaryForeground: { hsl: "0 35% 12%", from: "wine-ink on deeper ivory" },
+    muted: { hsl: "38 26% 88%", from: "same as secondary" },
+    mutedForeground: { hsl: "0 12% 38%", from: "concert-program gray — dates, opus numbers" },
+    accent: { hsl: "38 22% 84%", from: "hover surface" },
+    accentForeground: { hsl: "0 35% 12%", from: "wine-ink on hover" },
+    border: { hsl: "0 10% 78%", from: "program-page hairline rule, slightly warm" },
+    input: { hsl: "0 10% 78%", from: "same as border" },
+    ring: { hsl: "350 65% 28%", from: "wine red — focus" },
+    destructive: { hsl: "8 65% 38%", from: "sold-out / cancelled indicator, brighter than wine" },
+    destructiveForeground: { hsl: "38 32% 93%", from: "ivory on destructive" },
+    brand: {
+      wine: { hsl: "350 65% 28%", from: "the curtain-up wine red — also semantic primary" },
+      ivory: { hsl: "38 32% 93%", from: "program-book ivory — also semantic background" },
+      ink: { hsl: "0 35% 12%", from: "wine-ink black — also semantic foreground" },
+      gold: { hsl: "42 55% 50%", from: "donor-circle gold, used only on donor-tier markers" },
+    },
+  },
+
+  spacing: {
+    base: 4,
+    scale: [4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96, 128, 160],
+    containerMax: "max-w-6xl",
+    containerPadding: "px-6 lg:px-12",
+    sectionPadding: {
+      hero: "pt-28 pb-16 lg:pt-44 lg:pb-28",
+      default: "py-20 lg:py-32",
+      tight: "py-12 lg:py-20",
+    },
+  },
+
+  radius: {
+    base: "0",
+    pillsAllowed: false,
+  },
+
+  shadows: {
+    style: "soft",
+    utilities: {
+      "hairline-bottom":
+        "0 1px 0 0 hsl(var(--border))",
+      "program-rule":
+        "0 1px 0 0 hsl(var(--border)), inset 0 1px 0 0 hsl(var(--border))",
+      "curtain-wash":
+        "0 24px 60px hsl(var(--primary) / 0.12)",
+    },
+  },
+
+  motion: {
+    easing: "cubic-bezier(0.22, 1, 0.36, 1)",
+    durations: {
+      reveal: 1200,
+      loop: 3000,
+      ambient: 24000,
+    },
+    keyframes: {
+      "fade-rise": {
+        css:
+          "from { opacity: 0; transform: translateY(24px); }\n" +
+          "to { opacity: 1; transform: translateY(0); }",
+        defaultDuration: 1200,
+        iteration: "once",
+        purpose: "curtain-up entrance — slow, ceremonial",
+      },
+      "wine-wash": {
+        css:
+          "0% { opacity: 0; }\n" +
+          "100% { opacity: 0.06; }",
+        defaultDuration: 2400,
+        iteration: "once",
+        purpose: "hero ambient — wine-red ambient wash behind season hero",
+      },
+    },
+    respectsReducedMotion: true,
+  },
+
+  density: "low",
+
+  patterns: {
+    button:
+      "Text-link CTAs with wine on hover; 'Buy tickets' is the single solid-fill — wine bg + ivory text. " +
+      "Small-caps label inside the button. Pills disallowed.",
+    card:
+      "Hairline rules top + bottom, ivory-tier shift from background. Padding p-8 lg:p-12. " +
+      "Title in display SC (small caps); date + venue in mono; conductor/composer in body serif italic.",
+    input:
+      "Border-bottom only (1px wine-ink). Label above in display SC small caps.",
+    cta:
+      "Text-link with wine-ink, hover transitions to wine. The hero 'Subscribe to the season' is the single solid-fill exception.",
+  },
+
+  details: {
+    selectionBg: "hsl(var(--primary) / 0.22)",
+    selectionFg: "hsl(var(--foreground))",
+    focusRing: "1px solid hsl(var(--ring))",
+    scrollbarStyle: "thin",
+  },
+};

package/themes/nonprofit-warm/THEME.md

@@ -0,0 +1,105 @@
+# Design Direction — Nonprofit-Warm
+
+## Ethos
+charity:water yellow signal · Wikimedia serif restraint · Doctors Without Borders warm-red urgency · 350.org activist serif · GiveDirectly tabular trust
+
+## Feel
+Warm cream paper, serif headlines that read like a printed annual report, and photographic storytelling that puts the people first. One restrained give-button signal — warm-yellow on cream — earns attention without ever feeling slick. The whole surface telegraphs trust: emotionally honest, structurally clear, with the financials and the field reports both visible in the same calm hierarchy.
+
+## Reference brands
+- **charity:water** → yellow signal + warm cream + documentary photography. The canonical "I trust where my $30 went" surface.
+- **Wikimedia Foundation** → cream + serif + restrained chrome. Mission over marketing; the year-end appeal that doesn't feel like an ad.
+- **Doctors Without Borders (MSF)** → warm cream + warm-red signal + field photography. Urgency without aggression.
+- **350.org** → deep cream + activist serif + grassroots warmth. Movement aesthetic, not agency aesthetic.
+- **GiveDirectly** → cream + structured + nonprofit-tabular impact data. The receipt is part of the design.
+
+## Tokens
+All tokens live in `src/index.css` as HSL triples. Every token's `from:` comment names its brand origin. Do not introduce numbered or generic tokens — if a new color is needed, name a purpose (give-CTA, impact-verified, field-photo-caption) and the brand it traces to.
+
+Surface stack is **warm cream paper** (background) → **warm-card** (one tier brighter, never pure white) → **warm paper deeper** (secondary, muted). The warmth is in the cream — HSL hue stays in the 30–44 amber band across all neutrals. Cool grays here would feel corporate and break the empathy.
+
+Brand tokens: `--paper`, `--ink`, `--ink-soft`, `--give-yellow` (charity:water signal), `--field-red` (MSF urgency), `--trust-green` (GiveDirectly verified-data). **The give-yellow is the one anchor accent** — it appears on the primary Donate CTA, in the active-state of the give-form, and nowhere else. Adding a second accent dilutes the call to action.
+
+## Typography
+- **Display:** Source Serif 4. Annual-report headline weight without academic stiffness. h1–h4. Tracking `-0.012em`.
+- **Body:** Source Sans 3 (humanist sans). Base **17px** with line-height **1.7** — slightly larger than default for trust and accessibility. Field stories read slow.
+- **Mono:** JetBrains Mono. Impact data tables, financial statements, beneficiary counts, last-updated stamps. **Numbers in nonprofit work are not decoration — they are the receipt.** Tabular figures are mandatory.
+
+H1 uses `clamp(2.25rem, 5.5vw, 4rem)` — emotional but not theatrical. The serif carries the gravity; oversizing reads as marketing.
+
+## Spacing
+- **Container:** `max-w-5xl px-5 lg:px-10` — 1024px. Wider than editorial (the field photos need room) but narrower than a dashboard.
+- **Section padding tiers:**
+  - Hero: `pt-20 pb-16 lg:pt-28 lg:pb-24`
+  - Default: `py-16 lg:py-24`
+  - Tight: `py-10 lg:py-14`
+- **Allowed scale values:** 4 6 8 12 16 20 24 32 40 48 64 80 96 128. Low-to-medium density — story breathing.
+
+## Color
+No hex anywhere in component files. All color via tokens. Opacity via `/N` modifier. Pure white and pure black are forbidden — `--paper` (warm cream) and `--ink` (warm-deep ink) replace them. The cream is non-negotiable: a cool-gray background here breaks the trust the surface is built to communicate.
+
+**Accessibility-critical pairing:** `--give-yellow` carries `--ink` text, never paper text. The yellow is bright enough that white-on-yellow fails WCAG by a wide margin — and the dark text on bright yellow is part of the charity:water visual signature anyway.
+
+## Radius
+`--radius: 0.25rem` (4px). Gently softened ledger-rect — annual-report convention. **Pills are disallowed** (`pillsAllowed: false`) — pills read web-app or DTC-marketing, both of which are wrong tones for mission-led work. Status and labels use rectangles or text rules.
+
+## Shadows
+**Minimal style.** Three utilities ship:
+- `.hairline-bottom` — 1px `--border` ledger line. Magazine column divider. Used between story sections and table rows.
+- `.card-paper` — very light 1px + 4px stack. For impact-stat cards and floating panels.
+- `.give-glow` — 1px `--give-yellow` ring + soft halo. **Reserved for the single Donate CTA per page** — never another use.
+
+No drop shadows on story cards. No glow on heroes (the photography carries it).
+
+## Motion
+Nonprofit motion is **slow, intentional, and earned**. Five keyframes, all reverent of the content:
+
+- `fade-rise` — 1000ms once. Section entrance; gentle 20px rise. Story-paced, never theatrical.
+- `count-up` — 1800ms once (opacity reveal; pair with a JS counter for the number itself). For impact stats: *242,000 people served*, *1,847 wells dug*. The number arriving is part of the message.
+- `progress-fill` — 1600ms once. Campaign progress bars (fundraising goal, vaccination percentage). Width animates from 0 to `var(--progress)`. **Honest, never gamified** — no overshoot bounce, no celebration confetti.
+- `give-pulse` — 2800ms infinite. The Donate CTA breathes. **One per page, ever.** Never on a secondary action.
+- (no marquee, no parallax, no autoplay video carousel — these all break the trust tone.)
+
+Easing: `cubic-bezier(0.22, 1, 0.36, 1)`. `prefers-reduced-motion` is honored — pulse freezes mid-state, progress bars resolve instantly to final width, count-up resolves to final number without animation.
+
+## Component patterns
+- **Buttons:** ghost-default (1px `--border`, foreground text, hover `bg-secondary`). **Primary "Donate" / "Give" = solid `--give-yellow` fill with `--ink` text.** Secondary urgency action ("Take action," "Sign the petition") = solid `--field-red` with paper text, used sparingly. Tertiary = inline text link, foreground color, **underline always visible** (accessibility-first, not hover-only). Rectangles with 4px radius; never pills, never gradient fills.
+- **Cards:** soft `0.25rem` corners, hairline `--border`, `bg-card`. **Story-card** variant: full-bleed photo top, prose body `p-6 lg:p-8`, byline in mono. **Impact-stat card**: oversized serif number, body sans label below, optional `--trust-green` check glyph. **Financial-card**: tabular-mono columns for revenue / programs / overhead — the transparency receipt.
+- **Inputs:** full box, 1px `--border`, `bg-card`, `0.25rem` radius. **Donation-amount input** has `$` prefix in `--muted-foreground`; preset amount buttons ($10 / $25 / $50 / $100 / Other) sit below as a row of ghost buttons. Focus = 2px `--ring` with 2px offset — accessibility-first.
+- **CTAs:** the Give/Donate CTA is the **single visual anchor per page** — solid yellow rectangle with ink text, optional `.give-pulse` loop, optional `.give-glow` shadow. Secondary CTAs ("Read the report," "Volunteer," "Subscribe") are ghost buttons or text links. **Never two yellow buttons on the same screen.**
+- **Quotes (testimony / field voice):** large serif, italic, foreground color, no quotation-mark glyph (the type carries it). Attribution below in mono `text-sm`, `--muted-foreground` — *"— Amina, community health worker, Kakuma"*.
+- **Tables (impact / financials):** tabular-mono numbers. Row separator 1px `--border`. Header row in body sans, `--muted-foreground`, uppercase, `tracking-wide`. **Total / subtotal rows** get `font-medium` and a 2px `--border` top.
+
+## Recommended rich media
+Nonprofit-Warm is **photography-led**. The portraits and field shots ARE the story; the design is the frame.
+
+1. **Documentary portraiture** — single-subject, environmental, eye-contact, color-graded for warm cream tones (matches the paper). Kodak Portra 400 grading is the canonical reference. Always shot with consent, always with the subject's name and location in the caption.
+2. **Field photography** — context shots: a clinic, a classroom, a well being dug, a clean-water tap running. Documentary, not staged. **Never a smiling subject with a thumbs-up holding the donor's product** — this is the failure mode (and the cliché).
+3. **Hand-drawn maps and diagrams** — for "where the work happens" sections. Watercolor-style or letterpress-style, warm-palette. Built in Procreate or commissioned from illustrators; never AI.
+4. **Impact-receipt visualizations** — simple horizontal bar charts in `--trust-green` + `--ink`, mono labels, no 3D, no animation beyond `progress-fill`. The aesthetic is annual-report, not dashboard-SaaS.
+
+**AI tool recommendations:** **Midjourney / Flux** for photography ONLY with strict prompts — *"documentary portrait, Sebastião Salgado lighting, 50mm, Kodak Portra 400, environmental subject"* — and **always disclose AI use** in the caption if the imagery is generative; AI photos of nonexistent beneficiaries is a trust-breaking failure mode. Prefer commissioned real photography or licensed editorial stock (Magnum, VII Photo, Panos Pictures). **Recraft** acceptable for the hand-drawn maps.
+
+**Aspect ratios:** 3:2 landscape (photographic standard) or 4:5 portrait for environmental subjects. Hero images can be 21:9 letterbox-cinematic IF the photo earns it (a horizon, a landscape, a queue of people). Never 1:1 (Instagram aesthetic — wrong tone for the work).
+
+**Video:** allowed for testimony and field documentary. Always with a poster image, never autoplay, always captioned. 30–90 seconds. ≤8 MB AV1. **Never a music-bed-over-stock-footage donor-marketing video** — that reads as agency work and tanks trust.
+
+**Performance:** hero image ≤180 KB AVIF at 1600w; inline figures ≤100 KB. Mobile-first — nonprofit audiences include people on 3G in donor and field markets both. LCP under 2.5s with the hero photo loaded. If it slips, the photo is too large, not the framework.
+
+**Avoid:** stock photography of "diverse hands joined together," logo soup of media mentions, white-saviorism imagery (subject as object, donor-perspective framing), gradient meshes, glassmorphic donation widgets, animated GIF "thank you" overlays, confetti or fireworks on form-submit, fake urgency countdowns, the word "disrupt."
+
+**Accessibility:** alt text is mandatory and **describes the photograph as if for a blind donor** — *"A woman in a yellow headwrap fills a jerrycan at a hand-pumped well. Three children wait behind her in late afternoon light."* The image's caption (visible to all readers) credits the photographer and names the subject(s) with consent. **Captions are non-negotiable on photographs of people.**
+
+## Component families
+None at install time. Expected first families as the project grows: `story-card`, `impact-stat`, `donation-form`, `financial-table`, `testimony-quote`, `progress-bar`, `field-gallery`.
+
+## Details
+- **Selection:** `hsl(var(--give-yellow) / 0.4)` background, foreground text — the signal yellow highlights the reader's attention.
+- **Focus ring:** `2px solid hsl(var(--ring))` with offset — accessibility-first, **never thin**. Nonprofit audiences include older donors and keyboard users; the ring earns its visibility.
+- **Scrollbar:** `auto` (OS default). The chrome is the OS's; we don't redecorate. Quiet trust signal — we didn't even bother to skin the scrollbar, because we spent the design budget on the story.
+
+## Exceptions
+None yet. When an intentional one-of-one violation lands, add it here with the reason — and the reason must trace back to the mission, not to a design preference.
+
+## Revisions
+- Initial direction, generated at install time.