@stylecrib/cli 0.3.1 → 0.3.3

package/themes/schema.ts

@@ -0,0 +1,235 @@
+// Shared schema for every design direction in this library.
+// The CLI consumes this shape to emit `tailwind.config.ts` and `src/index.css`.
+// Hand-authoring is fine; runtime validation happens at codegen time.
+
+export type BrandTrait = {
+  brand: string;     // "NYT", "Tesla", "Aman"
+  trait: string;     // "typography", "blackout", "cream paper"
+};
+
+export type HSL = `${number} ${number}% ${number}%`;
+
+export type ColorToken = {
+  hsl: HSL;          // raw triple, no hsl() wrapper — feeds opacity modifier syntax
+  from: string;      // verbatim provenance: "Masters green, restrained" — survives in generated css as a comment
+};
+
+export type FontStack = {
+  family: string;          // primary face the project loads — "EB Garamond", "Manrope"
+  fallback: string[];      // system fallbacks in order
+  from: string;            // brand provenance: "NYT serif feel", "Linear's sans"
+  googleFont?: string;     // url-safe Google Fonts name; null if self-hosted or system-only
+  weights?: number[];      // weights to load (default: [400, 600])
+};
+
+export type MotionTier = "reveal" | "loop" | "ambient";
+
+export type Direction = {
+  // identity
+  name:
+    | "editorial"
+    | "soft-modern"
+    | "dense-utility"
+    | "brutalist"
+    | "cinematic-dark"
+    | "mid-century"
+    | "maximalist"
+    | "outdoor-adventure"
+    | "hyperminimal-mono"
+    | "newsletter"
+    | "y2k-chrome"
+    | "glassmorphic-modern"
+    | "signal-dark"
+    | "couture-luxury"
+    | "stadium-sport"
+    | "performance-engineered"
+    | "saturday-morning"
+    | "enterprise-tech"
+    | "creator-social"
+    | "kaiju-reveal"
+    | "runway-fashion"
+    | "streetwear-hype"
+    | "architectural"
+    | "kinetic-data"
+    | "indie-art-game"
+    | "corporate-grid"
+    | "enterprise-cloud"
+    | "business-tiles"
+    | "acrylic-soft"
+    | "cloud-friendly"
+    | "team-kanban"
+    | "government-civic"
+    | "banking-gravity"
+    | "pharma-clinical"
+    // ──────── Batch 2026-06: 30 new directions across under-covered categories ────────
+    | "fintech-trust"
+    | "fintech-card"
+    | "crypto-onchain"
+    | "web3-restraint"
+    | "education-warm"
+    | "education-formal"
+    | "healthcare-bright"
+    | "telehealth-modern"
+    | "wellness-spa"
+    | "music-streaming"
+    | "music-vinyl"
+    | "podcast-warm"
+    | "realestate-luxury"
+    | "realestate-marketplace"
+    | "marketplace-vintage"
+    | "marketplace-modern"
+    | "gaming-streamer"
+    | "gaming-esports"
+    | "devtool-cli"
+    | "devtool-docs"
+    | "nonprofit-warm"
+    | "agency-portfolio"
+    | "agency-creative"
+    | "studio-photographer"
+    | "studio-architect"
+    | "restaurant-modern"
+    | "hotel-boutique"
+    | "wellness-active"
+    | "food-blog"
+    | "ai-startup"
+    // ──────── Batch 2026-06 (B): 40 new directions, push library past 100 ────────
+    | "travel-luxury"
+    | "vacation-rental"
+    | "airline-modern"
+    | "tourism-board"
+    | "yoga-studio"
+    | "gym-chain"
+    | "sports-league"
+    | "cycling-brand"
+    | "linkedin-pro"
+    | "dating-friendly"
+    | "forum-classic"
+    | "community-niche"
+    | "newspaper-classic"
+    | "magazine-glossy"
+    | "news-tabloid"
+    | "news-tech"
+    | "law-firm"
+    | "lawtech-modern"
+    | "insurance-modern"
+    | "insurance-legacy"
+    | "automotive-luxury"
+    | "automotive-ev"
+    | "motorcycle-brand"
+    | "classic-car"
+    | "beauty-clean"
+    | "beauty-luxury"
+    | "furniture-modern"
+    | "home-decor"
+    | "pet-food"
+    | "baby-modern"
+    | "toys-modern"
+    | "vet-modern"
+    | "solar-residential"
+    | "ev-charging"
+    | "farm-direct"
+    | "logistics-modern"
+    | "museum"
+    | "bookstore-indie"
+    | "publisher-indie"
+    | "nonprofit-arts"
+    | "spotter-bright";
+  ethos: string;                  // one-line brand·trait synthesis
+  references: BrandTrait[];       // 4-6 brands max
+  feel: string;                   // 2-3 sentence prose description
+
+  // typography
+  fonts: {
+    display: FontStack;
+    body: FontStack;
+    mono: FontStack;
+  };
+  typography: {
+    headingTracking: string;      // e.g. "-0.01em"
+    bodyTracking: string;         // e.g. "0" or "0.17em" for cinematic
+    fontFeatureSettings?: string; // e.g. `"ss01", "cv11"` for Manrope
+    h1ScaleClamp: string;         // e.g. "clamp(2.5rem, 6vw, 4.5rem)"
+    bodyBaseSize: string;         // e.g. "1rem", "0.9375rem"
+    bodyLineHeight: string;       // e.g. "1.6"
+  };
+
+  // colors — every token traces to a brand·trait
+  colors: {
+    background: ColorToken;
+    foreground: ColorToken;
+    card: ColorToken;
+    popover: ColorToken;
+    primary: ColorToken;
+    primaryForeground: ColorToken;
+    secondary: ColorToken;
+    secondaryForeground: ColorToken;
+    muted: ColorToken;
+    mutedForeground: ColorToken;
+    accent: ColorToken;
+    accentForeground: ColorToken;
+    border: ColorToken;
+    input: ColorToken;
+    ring: ColorToken;
+    destructive: ColorToken;
+    destructiveForeground: ColorToken;
+    // brand tokens (named, not numbered) — any additional colors the direction calls for
+    brand?: Record<string, ColorToken>;
+  };
+
+  // spacing — base unit + the canonical scale
+  spacing: {
+    base: number;                 // px, almost always 4
+    scale: number[];              // tailwind scale steps actually allowed in this direction
+    containerMax: string;         // "max-w-6xl", "max-w-2xl" for editorial prose-first
+    containerPadding: string;     // "px-4 lg:px-8"
+    sectionPadding: {
+      hero: string;               // "pt-20 pb-12 lg:pt-28 lg:pb-16"
+      default: string;            // "py-16 lg:py-24"
+      tight: string;              // "py-12"
+    };
+  };
+
+  // radius — single source for the rounding language
+  radius: {
+    base: string;                 // "0.4rem" (sharp), "0.75rem" (rounded), "0" (editorial)
+    pillsAllowed: boolean;        // false for editorial/dense-utility; true for soft-modern
+  };
+
+  // shadow language — utilities defined in index.css, named by intent
+  shadows: {
+    style: "minimal" | "soft" | "glow" | "none";
+    utilities: Record<string, string>; // e.g. { "glow-gold": "0 0 0 1px ..., 0 30px 80px ..." }
+  };
+
+  // motion — the project library
+  motion: {
+    easing: string;               // "cubic-bezier(0.22, 1, 0.36, 1)" — universal across directions
+    durations: Record<MotionTier, number>;  // ms
+    keyframes: Record<string, {   // every keyframe the direction ships
+      css: string;                // the @keyframes block body
+      defaultDuration: number;    // ms
+      iteration: "once" | "infinite";
+      purpose: string;            // why this keyframe exists
+    }>;
+    respectsReducedMotion: true;  // hard-coded; non-negotiable
+  };
+
+  // density — informs spacing scale, line-height, component patterns
+  density: "low" | "medium" | "high";
+
+  // component patterns — declarative rules the Director and QA agents enforce
+  patterns: {
+    button: string;               // e.g. "ghost only; no solid-fill on brand-mark colors"
+    card: string;                 // e.g. "hairline border, no fill differentiation from background"
+    input: string;                // e.g. "border-bottom only, no full box"
+    cta: string;                  // e.g. "text link with gold-gradient utility; never a filled rect"
+  };
+
+  // selection + scrollbar + focus — small details that signal "built"
+  details: {
+    selectionBg: string;          // "hsl(var(--gold) / 0.3)"
+    selectionFg: string;          // "hsl(var(--foreground))"
+    focusRing: string;            // "2px solid hsl(var(--ring))"
+    scrollbarStyle: "thin" | "auto" | "none";
+  };
+};

package/themes/signal-dark/BUILD_BRIEF.md

@@ -0,0 +1,168 @@
+# Signal-Dark — Build Brief
+
+> This file is the CONTRACT the theme ships with. It IS the source of truth
+> the `brief-enforcer` subagent reads at commit time and the payload the
+> `Copy for Claude Code` button on the theme detail page hands out.
+>
+> The contract has three sections:
+>   1. MANDATORY BUILD DIRECTIVE — the `You MUST` list.
+>   2. SLOP-BLOCKLIST — the `You MUST NOT` list.
+>   3. CHROME INVENTORY — the allow-list of ornaments this theme may use.
+>
+> Any UI change that touches this theme's section source (or applies this
+> theme to a project) must pass the enforcer against this file.
+
+---
+
+## MANDATORY BUILD DIRECTIVE — you MUST
+
+1. **Hold the warm-black canvas at `#0F0D0C`** (30° warm-bias). Never pure
+   black. On light canvas: cotton-paper `#F7F4F0` (30° warm bias). Never
+   pure white. Both canvases share the register; only tokens invert.
+2. **Use ONE signal color on the page** (the palette variant). No second
+   color for "variety." Status signals use mono labels with a signal-hued
+   dot, not green / orange / blue chips.
+3. **Set the hero display at `clamp(3.5rem, 10vw, 9rem)`** with tight
+   tracking (-0.04em). Type is the primary design element.
+4. **Radius 12px on cards.** Pills allowed only on model-card meta chips +
+   status badges.
+5. **Reserve prominent mono (JetBrains Mono) for CODE-shaped things:**
+   terminal specimens, model IDs, semver tags, CLI output, at-handles.
+   NEVER for decorative eyebrow labels.
+6. **Real Pexels photos for the marketing hero + product surfaces.** No
+   SVG stand-ins for photo-worthy subjects.
+
+---
+
+## SLOP-BLOCKLIST — you MUST NOT
+
+Each is a hard fail. If the section source contains any of these, the
+enforcer verdict is BLOCK.
+
+- **Mono-caps decorative eyebrows** (`SECTION · X`, `WHAT WE X`). CSS
+  fingerprint: `textTransform: uppercase` + `letterSpacing ≥ 0.18em` at
+  `fontSize < 20px`. Not on this theme's chrome inventory, so banned.
+- **Dot-separated decorative metadata rows** (`ISSUE 04 · CHAPTER 03`,
+  `EST. 2019`, `12 MIN READ`). Content-level `·` (`handle · role`,
+  terminal output like `stylecrib qa --ci · 12s · passed`) is fine.
+- **`№` / no. / vol. ornaments.**
+- **`▸ TAG` labels.**
+- **`TRUSTED BY` / `AS SEEN IN` / `COMPOSED BY TEAMS AT`** wordmark strips
+  — content-slop under any name.
+- **Ticker bars, auto-advancing hero sliders (< 6s mutation), cycling
+  headline words** (`we [design][build][ship]`), `AUTO 4s` helpers.
+- **Warm-radial glow gradients as image FALLBACKS.**
+- **Roman-numeral copyright** (`MMXXVI. ALL RIGHTS RESERVED.`).
+- **3-pillar identical feature-card grids as the marketing spine.**
+- **Vague trust copy:** hand-crafted, thoughtfully-made, considered,
+  for-teams-that-care, made-with-love.
+- **Attribution of influence in visible copy** — Tesla, Hugging Face,
+  Apple, Vercel, Cybertruck are STUDIED, never NAMED in slug, copy, or UI.
+
+---
+
+## CHROME INVENTORY — the allow-list
+
+Every ornament this theme may use. Anything visible in the section source
+that is NOT on this list falls under the SLOP-BLOCKLIST above.
+
+- **Full-bleed warm-black hero band** with subtle radial warm+cool mesh
+  backdrop (opacity ~0.4, drifts on `gradient-shift 32s` ambient loop; NOT
+  a purple/pink slop gradient — warm amber + cool blue only, matching
+  `--glow-warm` and `--glow-cool`).
+- **Oversized display h1** in Inter 700 at `clamp(3.5rem, 10vw, 9rem)`,
+  tracking -0.04em, one line-break maximum.
+- **ONE primary CTA per page:** filled signal button, radius 12px,
+  `glow-signal` outer halo on hover only.
+- **ONE ghost secondary next to the primary:** bordered, foreground
+  color, radius 12px, no glow.
+- **Model-card panel:** rounded-xl (12px), 1px border, subtle raised card
+  bg, meta row at top in mono (icon dot + slug + status pill),
+  display-font title, softInk body copy, no shadow beyond hairline border.
+- **Terminal specimen:** rounded-xl (12px) card with a top window bar
+  (err-red · warn-amber · signal dots) + mono CLI title. Body is
+  pre-formatted JetBrains Mono at 13px, signal-yellow prompt glyph (`$ `),
+  softInk body text, mutedInk system text.
+- **Status pill** (mono, rounded-full, px-2.5 py-1 text-[11px]): dot
+  prefix in signal for active, mutedInk otherwise. No colored fills.
+- **Full-bleed marketing hero photograph**, 21:9 or 16:9, warm-shadow
+  cool-highlight grade, hero display text OVERLAID (never a caption card).
+- **Table-style live metrics grid:** label / value / status dot in mono,
+  tabular figures, one row per metric.
+- **3-tier pricing card row**, ONE primary CTA on the middle recommended
+  tier (signal-filled), other tiers use ghost secondary.
+- **Footer:** minimal — brand name, one-line studio note, three columns of
+  links max, small copyright line (regular Arabic numerals, no MMXXVI,
+  no dot-metadata).
+
+---
+
+## SIGNATURE MOVES — verbs, not adjectives
+
+The theme's actual moves you MUST land, not adjectives to gesture at.
+
+- **Fill the hero band with a warm-black canvas + oversized display type**
+  breaking the baseline; hold the mesh-gradient backdrop under it at 0.4
+  opacity, drifting via `gradient-shift 32s` so the horizon never sits
+  still.
+- **Place ONE signal-yellow button per page**, at the point of conversion.
+  Its `glow-signal` halo appears ONLY on hover — never as a static bloom
+  (that's Stripe-Linear-Vercel AI-default slop).
+- **Show a terminal specimen with `$` in signal + real CLI output** — the
+  developer-tool signature. The prompt IS the visual accent, not
+  decorative chrome.
+- **Model-card grid:** put the meta row at the TOP in mono (like a HF
+  model card would show `provider/name · v0.14 · task`); display-font
+  title comes SECOND, body copy underneath. Never invert that order.
+- **Marketing hero:** full-bleed photograph, big-quiet display text laid
+  OVER the photo (not in a caption card next to it). Warm shadows + cool
+  highlights color grade so the yellow signal never competes with the
+  image.
+- **Use tabular figures for all metric numbers** so they align in columns.
+  Non-tabular metric numerals break the register.
+
+---
+
+## COLOR TOKENS (measured)
+
+**Dark canvas**
+- `bg`: `#0F0D0C`   `card`: `#1A1614`   `border`: `#2A231F`
+- `ink`: `#F7F4F0`  `softInk`: `#E4DFD8`  `mutedInk`: `#9F958A`
+
+**Light canvas**
+- `bg`: `#F7F4F0`   `card`: `#FFFFFF`   `border`: `#DED6CB`
+- `ink`: `#0F0D0C`  `softInk`: `#2A231F`  `mutedInk`: `#6C6259`
+
+**Signal** (default `hazard`)
+- Dark canvas: `#FFDF29`   Light canvas: `#B58900`
+
+---
+
+## TYPOGRAPHY
+
+- **Display:** Inter (SF Pro Display approximation), 500 / 600 / 700 / 800.
+  Hero h1 at `clamp(3.5rem, 10vw, 9rem)`, tracking -0.04em (loosens to
+  -0.005em at body).
+- **Body:** Inter, 17px, line-height 1.55, tracking -0.005em.
+- **Mono:** JetBrains Mono — for code / terminal / metric values /
+  @handles ONLY.
+
+---
+
+## SECTION SKELETON (top → bottom)
+
+1. Sticky palette + canvas picker strip (meta-UI, not theme composition).
+2. Masthead nav — brand + 4 nav items + one signal CTA.
+3. Hero — mesh-gradient backdrop, oversized display, one signal CTA +
+   ghost secondary, one paragraph of body copy.
+4. Product surface photograph — full-bleed 21:9, warm-shadow grade, no
+   caption card.
+5. Terminal specimen — rounded-xl card with `$` prompt, real CLI output.
+6. Model-card feature grid (2×2 or 4×1) — mono meta at top, display
+   title, body, status pill.
+7. Marketing hero — full-bleed photograph with oversized display overlay
+   + one signal CTA.
+8. Live metrics table — 4 rows, tabular figures, status dots.
+9. Pricing — 3 tiers, ONE signal CTA on the recommended tier.
+10. Footer — brand + one-line note + three link columns + small
+    copyright.

package/themes/signal-dark/THEME.md

@@ -0,0 +1,107 @@
+# Design Direction — Signal-Dark
+
+## Ethos
+Tesla blackout · Hugging Face yellow signal · Apple display type · Cybertruck engineered restraint · Vercel typographic discipline
+
+## Feel
+Warm-black backdrop with one bright yellow signal color and oversized display type. Hugging-Face-style model-card grids carry technical content; Tesla-style hero moments carry marketing. Reads as a premium developer tool — serious, friendly, expensive without being noisy. The opposite of generic AI-startup purple.
+
+## Reference brands
+- **Tesla** → warm-black blackout marketing surfaces. Photography is the lead; UI gets out of the way.
+- **Hugging Face** → yellow signal accent (#FFD21E) and model-card chrome. Code prominence; technical-but-friendly voice.
+- **Apple** → oversized SF Pro display type at 80-140px, generous tracking refinement, hero whitespace.
+- **Cybertruck** → engineered angular restraint, raw materiality. Hairline borders that *suggest* without enforcing.
+- **Vercel** → developer-tool typographic discipline. Body type that's neutral; mono type that's prominent.
+
+## Tokens
+HSL triples in `src/index.css`. The warm bias on dark surfaces (`30°` hue) is deliberate — it keeps photography from looking dead. Tesla cinematic uses cool 220° blue-black; signal-dark uses warm 30°. Same pitch-black at first glance, different feeling underneath.
+
+Brand tokens: `signal` (= primary), `signal-glow`, `ice` (Vercel cyan, used sparingly for info states), `carbon` (Cybertruck steel for contrast panels), `platinum` (warm silver for sub-headings), `glow-warm` + `glow-cool` (radial-gradient stops for hero backdrops).
+
+The yellow `signal` is the **only allowed accent color** on a page. No second color for "variety." If you need a status signal (success/warning/info), use mono labels with the signal-yellow dot prefix, not green/orange/blue chips. The single-color rule is what makes the yellow read as *the signal*.
+
+## Typography
+- **Display:** Inter (Apple SF Pro Display approximation). Weights 500/600/700/800. h1-h4. Hero h1 uses `clamp(3.5rem, 10vw, 9rem)` — Apple/Vercel hero scale. Tracking `-0.04em` (very tight at display sizes; loosens to `-0.005em` at body).
+- **Body:** Inter, 17px, line-height 1.55. Negative tracking `-0.005em`.
+- **Mono:** JetBrains Mono. **Prominent.** Used for eyebrow labels (small-caps mono), code, model IDs, CLI output, status meta. Hugging-Face-style code-first surfaces.
+
+Font features: `"cv11", "ss01", "ss03", "tnum"` — Inter stylistic sets + tabular figures. Numbers use `font-mono` or `.tabular`.
+
+## Spacing
+- **Container:** `max-w-7xl px-6 lg:px-12` (1280px wide — Apple/Tesla claim the screen).
+- **Section padding tiers:**
+  - Hero: `pt-24 pb-32 lg:pt-32 lg:pb-48` — oversized
+  - Default: `py-20 lg:py-32`
+  - Tight: `py-12 lg:py-20`
+- **Allowed scale:** 4 6 8 12 16 20 24 32 40 48 64 80 96 128.
+
+## Color
+No hex anywhere. All color via tokens. Opacity via `/N` modifier on a token. **Pure black is forbidden** (`--background` is `30 8% 5%`, never `0 0% 0%`). **Pure white is forbidden** (`--foreground` is `30 15% 96%`, never `0 0% 100%`). The warm bias is structural; abandoning it makes everything look like every other dark-mode site.
+
+## Radius
+`--radius: 0.75rem` (12px). Apple-iOS card radius — rounded but not pillowy. **Pills are allowed** (`pillsAllowed: true`) for status badges, tags, model-card meta chips. Pure right angles read as a Vercel-dashboard surface (off-direction); pure pills read as a chip toggle (also off-direction).
+
+## Shadows
+Style is **"glow"**. Signature utility: `.glow-signal` (yellow halo + soft drop) on primary CTAs and active states. Cards use `.glow-card` (border + subtle drop + ambient backdrop shadow). The glow is the depth language — drop-shadows alone read as 2018 SaaS.
+
+Three utilities:
+- `.glow-signal` — yellow halo for the one primary action per page
+- `.glow-card` — default card lift with border + subtle dark drop
+- `.glow-subtle` — minimal hairline + small drop for secondary surfaces
+
+## Motion
+- **Easing:** `cubic-bezier(0.22, 1, 0.36, 1)`
+- **Duration tiers:** reveal (700ms), loop (3s), ambient (32s)
+- **Keyframes:**
+  - `fade-rise` — standard content reveal
+  - `glow-pulse` — primary CTA breathes slowly (3s loop on the main action)
+  - `gradient-shift` — hero backdrop drifts slowly (32s ambient, no visible loop point)
+  - `terminal-type` — staggered slide-in for terminal-demo lines
+
+`prefers-reduced-motion` honored throughout. Transform-only animations on loops; never animate `top/left/width/height`.
+
+## Component patterns
+- **Buttons:** primary = solid yellow signal (`bg-signal text-primary-foreground rounded-xl font-medium`), `glow-signal` shadow on hover. Secondary = ghost (border + foreground). Tertiary = mono text-link with signal underline. **One primary per page.**
+- **Cards:** `rounded-xl border bg-card`, `glow-card` shadow. Padding `p-6 lg:p-8`. Title in display font; meta in mono. Hover lifts with `translate-y-[-2px]` and the glow strengthens. **Model-card-style** — HF influence: meta lives at the top in mono, content lives below.
+- **Inputs:** rounded-lg box, border, `bg-secondary`. Focus ring `2px solid signal at 60% opacity`. Label above; helper below in `mutedForeground`.
+- **CTAs:** primary action is *the* yellow button — always. There is ONE primary CTA per page maximum. Secondary actions are ghost buttons or text-links. Marketing-heavy "free trial / sign up" double-CTAs are forbidden — pick one.
+
+## Component families
+**Model-card** (`*Card`, `*ModelCard`): rounded-xl, border, bg-card, glow-card; meta row in mono at top (icon + slug + version pill); display-font title; mono description; hover lifts. **Status pill** (`*Pill`, `*Badge`): rounded-full, text-xs, px-2 py-0.5, mono, signal-yellow dot prefix for active/success; never colored fills. **Hero block** (`*Hero`): full-bleed gradient backdrop, oversized h1, mono eyebrow, single yellow CTA + ghost secondary.
+
+## Recommended rich media
+
+Signal-dark is **photography-rich** in the Tesla / Apple-marketing tradition, but **screenshot-rich** in the Hugging Face / Vercel developer-tool tradition. The mix is the direction.
+
+**Hero media:** widescreen photography (21:9 or 16:9), color-graded toward warm shadows + cool highlights (Tesla-cinematic), or product photography on warm-black seamless. **CSS mesh-gradient backdrops** are also permitted as the hero — radial gradients of `--glow-warm` and `--glow-cool` over `--background`, animated subtly via `gradient-shift`. The gradient backdrop is the cheapest hero option that still reads premium.
+
+**Code / terminal demo:** the signature signal-dark element. Show the product running — CLI output, code snippets, model-card examples — in a styled `<pre>` with terminal chrome (window dots, title bar). HF leans into this hard; signal-dark should too. Use **JetBrains Mono**, signal-yellow for the prompt and accents, off-white body, dimmed muted-foreground for system text.
+
+**AI tool recommendations:**
+- **Midjourney / Flux** with prompts like *"Tesla marketing site photography, warm shadows, cool highlights, 21:9 cinematic, slight film grain, anamorphic lens flare suppressed"* for hero photography
+- **Sora / Runway / Veo** for hero video loops (cinematic atmosphere, slow motion, max 8 MB)
+- **Spline** for hero 3D — premium product objects, glass/chrome surfaces with warm rim lighting
+- **mesh-gradient.com** for the CSS-only gradient backdrop (no AI needed)
+- **Carbon (carbon.now.sh)** or **Ray.so** for static code-snippet images in warm-black theme
+
+**Aspect ratios:** 21:9 or 16:9 for hero photography; 4:3 or 1:1 for product shots; gradient backdrops are full-bleed (no aspect constraint).
+
+**Performance:** hero photo ≤200 KB AVIF at 1920w; hero video ≤6 MB H.265 with poster fallback; mesh-gradient is ~0 KB CSS. LCP target <2s on 4G.
+
+**Avoid:** pure black photography backgrounds (kills the warm bias), saturated chrome 3D (that's Y2K), gradient backdrops in the wrong hue (no purple, no pink — warm amber + cool blue only), generic stock photography with watermarks, autoplay video with sound, photography that competes with the yellow signal (no yellow-dominant images — the signal must remain the unique yellow on the page).
+
+**Accessibility:** WCAG AA for text on warm-black requires foreground at ≥`30 15% 88%` minimum (we use `30 15% 96%`, well above). Yellow signal on warm-black passes AA at large size; for small body text on yellow, the foreground must be the near-black `--primary-foreground`, never off-white.
+
+## Component families (when projects add them)
+Document each family here as it emerges. Initial expected families: `*Card` (model-card pattern), `*Pill` (status/tag), `*Hero` (full-bleed gradient + oversized type).
+
+## Details
+- **Selection:** `hsl(var(--signal) / 0.3)` background, foreground text.
+- **Focus ring:** `2px solid hsl(var(--signal) / 0.6)` — visible and on-brand.
+- **Scrollbar:** thin, warm-toned.
+
+## Exceptions
+None yet. When an intentional violation lands (e.g. a Tesla cinematic-dark *blue* hue used for a single hero moment), add it here with the reason.
+
+## Revisions
+- Initial direction, generated at install time. Authored as the 13th canonical direction to dogfood the synthesis Tesla + Hugging Face + Apple — and to provide a premium-developer-tool aesthetic the original twelve didn't cover.