@stylecrib/cli 0.3.1 → 0.3.3

package/themes/signal-dark/tokens.ts

@@ -0,0 +1,181 @@
+import type { Direction } from "../schema";
+
+export const signalDark: Direction = {
+  name: "signal-dark",
+  ethos:
+    "Tesla blackout · Hugging Face yellow signal · Apple display type · Cybertruck engineered restraint",
+  references: [
+    { brand: "Tesla", trait: "warm-black blackout marketing surfaces" },
+    { brand: "Hugging Face", trait: "yellow signal accent + model-card chrome" },
+    { brand: "Apple", trait: "oversized SF Pro display type, generous whitespace" },
+    { brand: "Cybertruck", trait: "engineered angular restraint, raw materiality" },
+    { brand: "Vercel", trait: "developer-tool 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.",
+
+  fonts: {
+    display: {
+      family: "Inter",
+      fallback: ["-apple-system", "BlinkMacSystemFont", "Segoe UI", "system-ui", "sans-serif"],
+      from: "Apple SF Pro Display feel via Inter — closest open-source approximation, used at 80-140px hero sizes",
+      googleFont: "Inter",
+      weights: [400, 500, 600, 700, 800],
+    },
+    body: {
+      family: "Inter",
+      fallback: ["-apple-system", "BlinkMacSystemFont", "system-ui", "sans-serif"],
+      from: "Apple SF Pro Text feel — clean at 14-18px body sizes",
+      googleFont: "Inter",
+      weights: [400, 500, 600],
+    },
+    mono: {
+      family: "JetBrains Mono",
+      fallback: ["Berkeley Mono", "ui-monospace", "SFMono-Regular", "Consolas", "monospace"],
+      from: "Hugging-Face-style code prominence — model IDs, tokens, CLI output, eyebrow labels",
+      googleFont: "JetBrains+Mono",
+      weights: [400, 500, 600],
+    },
+  },
+
+  typography: {
+    headingTracking: "-0.04em", // Apple-tight at display sizes; tighter than editorial -0.015em
+    bodyTracking: "-0.005em",   // very subtle negative tracking — Apple body convention
+    fontFeatureSettings: '"cv11", "ss01", "ss03", "tnum"',
+    h1ScaleClamp: "clamp(3.5rem, 10vw, 9rem)", // ALERT-LEVEL oversized — Apple/Vercel hero scale
+    bodyBaseSize: "1.0625rem", // 17px — Apple body default
+    bodyLineHeight: "1.55",
+  },
+
+  colors: {
+    // Surfaces — warm-black, Tesla blackout with slight warm bias (30°) so
+    // photography reads alive, not corpse-blue
+    background: { hsl: "30 8% 5%", from: "Tesla blackout — warm-bias near-black" },
+    foreground: { hsl: "30 15% 96%", from: "warm off-white, never pure white — Apple-tinted" },
+    card: { hsl: "30 6% 8%", from: "card surface, 3% lighter than bg" },
+    popover: { hsl: "30 6% 11%", from: "popover/menu surface, 6% lighter than bg" },
+
+    // Primary — Hugging Face yellow signal
+    primary: { hsl: "48 100% 56%", from: "Hugging Face yellow #FFD21E — the ONE signal color" },
+    primaryForeground: { hsl: "30 8% 5%", from: "near-black on yellow for max contrast" },
+
+    // Secondary surfaces — monochromatic steps
+    secondary: { hsl: "30 6% 14%", from: "secondary surface, Cybertruck engineered restraint" },
+    secondaryForeground: { hsl: "30 15% 96%", from: "off-white on dark gray" },
+    muted: { hsl: "30 6% 14%", from: "same as secondary; differentiation by usage" },
+    mutedForeground: { hsl: "30 8% 65%", from: "warm gray — captions, meta, eyebrows" },
+    accent: { hsl: "30 6% 18%", from: "hover surface, one tier lighter than secondary" },
+    accentForeground: { hsl: "30 15% 96%", from: "off-white on hover" },
+
+    // Borders — Cybertruck hairline, visible but quiet
+    border: { hsl: "30 6% 18%", from: "Cybertruck hairline — same as accent, structural" },
+    input: { hsl: "30 6% 18%", from: "same as border" },
+    ring: { hsl: "48 100% 56%", from: "primary yellow — focus rings everywhere" },
+
+    // Destructive — warm red, not pure (matches warm palette)
+    destructive: { hsl: "8 80% 56%", from: "warm Tesla brake-light red" },
+    destructiveForeground: { hsl: "30 15% 96%", from: "off-white on warm red" },
+
+    brand: {
+      signal: { hsl: "48 100% 56%", from: "alias for primary — the yellow signal color" },
+      "signal-glow": { hsl: "48 100% 65%", from: "brighter yellow for hover/glow states" },
+      ice: { hsl: "200 85% 65%", from: "Vercel-cyan tertiary accent, used sparingly for info" },
+      carbon: { hsl: "0 0% 12%", from: "Cybertruck steel — pure-neutral panel for contrast moments" },
+      platinum: { hsl: "30 8% 88%", from: "warm silver — sub-headings, premium meta text" },
+      "glow-warm": { hsl: "40 85% 60%", from: "amber glow stop for backdrop gradients" },
+      "glow-cool": { hsl: "200 75% 55%", from: "cool blue glow stop for backdrop gradients" },
+    },
+  },
+
+  spacing: {
+    base: 4,
+    scale: [4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96, 128],
+    containerMax: "max-w-7xl", // wider than editorial — Apple/Tesla claim the screen
+    containerPadding: "px-6 lg:px-12",
+    sectionPadding: {
+      hero: "pt-24 pb-32 lg:pt-32 lg:pb-48", // oversized hero — Apple convention
+      default: "py-20 lg:py-32",
+      tight: "py-12 lg:py-20",
+    },
+  },
+
+  radius: {
+    base: "0.75rem", // 12px — Apple iOS card; rounded but not pillowy
+    pillsAllowed: true, // status pills, tags, badges — HF model-card convention
+  },
+
+  shadows: {
+    style: "glow", // signature: yellow glow on hover for primary surfaces
+    utilities: {
+      "glow-signal":
+        "0 0 0 1px hsl(var(--signal) / 0.4), 0 8px 32px hsl(var(--signal) / 0.25), 0 16px 64px hsl(var(--signal) / 0.15)",
+      "glow-card":
+        "0 0 0 1px hsl(var(--border)), 0 4px 16px hsl(0 0% 0% / 0.4), 0 16px 48px hsl(0 0% 0% / 0.2)",
+      "glow-subtle":
+        "0 0 0 1px hsl(var(--border)), 0 2px 8px hsl(0 0% 0% / 0.3)",
+    },
+  },
+
+  motion: {
+    easing: "cubic-bezier(0.22, 1, 0.36, 1)",
+    durations: { reveal: 700, loop: 3000, ambient: 32000 },
+    keyframes: {
+      "fade-rise": {
+        css:
+          "from { opacity: 0; transform: translateY(20px); }\n" +
+          "to { opacity: 1; transform: translateY(0); }",
+        defaultDuration: 700,
+        iteration: "once",
+        purpose: "standard reveal — content enters with subtle rise",
+      },
+      "glow-pulse": {
+        css:
+          "0%, 100% { box-shadow: 0 0 0 1px hsl(var(--signal) / 0.4), 0 8px 32px hsl(var(--signal) / 0.25); }\n" +
+          "50% { box-shadow: 0 0 0 1px hsl(var(--signal) / 0.6), 0 12px 48px hsl(var(--signal) / 0.4); }",
+        defaultDuration: 3000,
+        iteration: "infinite",
+        purpose: "primary CTA breathing — slow yellow pulse on the main action",
+      },
+      "gradient-shift": {
+        css:
+          "0%, 100% { background-position: 0% 50%; }\n" +
+          "50% { background-position: 100% 50%; }",
+        defaultDuration: 32000,
+        iteration: "infinite",
+        purpose: "hero backdrop — slow gradient drift, set-and-forget ambient",
+      },
+      "terminal-type": {
+        css:
+          "from { opacity: 0; transform: translateX(-8px); }\n" +
+          "to { opacity: 1; transform: translateX(0); }",
+        defaultDuration: 400,
+        iteration: "once",
+        purpose: "terminal demo — each line types in with a small slide",
+      },
+    },
+    respectsReducedMotion: true,
+  },
+
+  density: "medium",
+
+  patterns: {
+    button:
+      "Primary = solid yellow signal (bg-signal, foreground=near-black, rounded-xl, font-medium, glow-signal shadow on hover). Secondary = ghost with border + foreground. Tertiary = mono text-link with signal underline.",
+    card:
+      "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 glow strengthens.",
+    input:
+      "rounded-lg box, border, bg-secondary. Focus ring = 2px solid signal at 60% opacity. Label above; helper below in mutedForeground.",
+    cta:
+      "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.",
+  },
+
+  details: {
+    selectionBg: "hsl(var(--signal) / 0.3)",
+    selectionFg: "hsl(var(--foreground))",
+    focusRing: "2px solid hsl(var(--signal) / 0.6)",
+    scrollbarStyle: "thin",
+  },
+};

package/themes/soft-modern/THEME.md

@@ -0,0 +1,91 @@
+# Design Direction — Soft-Modern
+
+## Ethos
+Linear's geometric calm · Notion warmth · Stripe homepage gradients · Vercel's quiet polish · Plain's friendly chrome
+
+## Feel
+Approachable and considered. Rounded corners, soft layered shadows, friendly geometric sans, muted accent palette with one signal color. Subtle motion that confirms interaction without demanding attention. Reads productive, not flashy.
+
+## Reference brands
+- **Linear** → geometric calm. Quiet UI that disappears into the work.
+- **Notion** → approachable warmth. Friendly without being childish.
+- **Stripe** → soft gradient backdrops. Marketing surfaces, not docs.
+- **Vercel** → quiet polish. Hairline borders, minimal shadow.
+- **Plain (plain.com)** → friendly type, rounded chrome.
+
+## Tokens
+HSL triples in `src/index.css`. Brand tokens: `--violet-soft`, `--violet-deep`, `--teal`, `--amber`. Primary is **violet** (Linear-style 262° hue). Surface stack is monochromatic (220° hue across background/secondary/muted/accent) — depth from border + shadow, never from hue shift.
+
+The brand tokens (`teal`, `amber`) are the **secondary accents** — used sparingly, never as primary CTA color. They exist for status indicators, highlight badges, and one-off marketing moments.
+
+## Typography
+- **Display:** Plus Jakarta Sans (Notion/Plain — friendly geometric, slightly humanist). h1–h4, weights 500/600/700.
+- **Body:** Inter (Linear/Vercel sans — clean at small sizes). Base 16px, line-height 1.6. Tracking `0`.
+- **Mono:** JetBrains Mono. Code blocks, metrics, tabular numerics.
+
+Headings track `-0.02em` (sans-serif headings benefit from tight tracking). Numbers always use `font-variant-numeric: tabular-nums`. Inter stylistic sets `"cv11", "ss01", "ss03"` for single-story a/g.
+
+## Spacing
+- **Container:** `max-w-6xl px-4 lg:px-8`.
+- **Section padding tiers:**
+  - Hero: `pt-24 pb-16 lg:pt-32 lg:pb-24`
+  - Default: `py-16 lg:py-24`
+  - Tight: `py-12 lg:py-16`
+- **Allowed scale values:** 4 6 8 10 12 16 20 24 32 40 48 64 80.
+
+## Color
+No hex anywhere. All color via tokens. Opacity via `/N` modifier. Pure white is allowed for cards (`--card`); pure black is not — `--foreground` is `224 38% 10%` (deep slate).
+
+## Radius
+`--radius: 0.75rem` (12px). **Rounded is the signature.** Pills are allowed for status chips and tags (`pillsAllowed: true`). Hard right angles read "bare HTML" in this language — keep things rounded.
+
+## Shadows
+Three soft-layered utilities:
+- `.shadow-soft` — default card lift
+- `.shadow-soft-lg` — hover lift, larger spread
+- `.shadow-soft-inset` — top-edge highlight for raised surfaces
+
+Shadows use 220° gray at 4-8% opacity — never pure black, never high opacity. The soft-modern shadow is *almost not there*.
+
+## Motion
+Three keyframes:
+- `fade-rise` (600ms) — standard content entrance
+- `scale-in` (200ms) — modals, popovers, tooltips
+- `shimmer` (1600ms loop) — loading skeletons
+
+Easing: `cubic-bezier(0.22, 1, 0.36, 1)`. Reveal duration `600ms` — fast enough to feel responsive. `prefers-reduced-motion` honored.
+
+## Component patterns
+- **Buttons:** solid-fill primary (`bg-primary`, `text-primary-foreground`, `rounded-xl`, `shadow-soft`). Secondary is ghost (border + foreground text). Tertiary is link. Hover lifts subtly (scale 1.01 + `shadow-soft-lg`).
+- **Cards:** `rounded-xl`, border, `bg-card`, `shadow-soft`. Padding `p-6 lg:p-8`. Title in display font. Hover lifts to `shadow-soft-lg`.
+- **Inputs:** full rounded-lg box, border, `bg-background`. Focus ring `2px solid var(--ring) / 0.5`. Label above; helper text below in `mutedForeground`.
+- **CTAs:** primary button is default. Secondary CTAs use ghost button or text-link with primary color.
+
+## Recommended rich media
+Soft-modern's lead media is the **gradient backdrop** itself — Stripe-homepage-style soft mesh gradients (violet → teal → amber, low saturation, smooth blends). Product imagery is studio-clean on white seamless, slightly elevated with a soft shadow. Hero illustrations lean toward isometric or abstract geometric — Linear/Notion/Plain visual language. Photography is sparingly used; the gradient is doing the visual work.
+
+**AI tool recommendations:** for mesh gradients, **mesh-gradient.com** or **csshero.org/mesh** for declarative CSS (no AI needed, often the right answer); **Midjourney / Flux** with prompts like *"soft mesh gradient, violet to teal to amber, smooth blend, 4K, abstract background"*; **Spline** for interactive 3D shapes (gradient orbs, soft geometry) when a hero needs depth; **Recraft** for isometric product illustrations and Notion-style figurative drawings; **Linear's screenshot library aesthetic** as a prompting target ("Linear app screenshot, geometric calm, single accent color").
+
+**Aspect ratios:** gradient backdrops are full-bleed (no aspect constraint); product shots 4:3 or 1:1; isometric illustrations 16:9 hero or 4:3 supporting. Avoid 21:9 cinematic widescreen — that's cinematic-dark territory.
+
+**Video:** subtle hero video accents are on-brand — UI screen-recordings with soft transitions (Linear-style demo), short product loops (4-8s, autoplay muted, no narration). ≤6 MB, H.265. Background gradient continues to play even when video pauses.
+
+**Performance:** mesh gradient as CSS is ~0 KB. AVIF product shots ≤120 KB at 1200w. Video kept short and tightly compressed. LCP target under 1.5s on 4G.
+
+**Avoid:** photorealistic AI hero images (too much depth — fights the soft palette), film-grain textures (cinematic-dark), dark moody photography, chrome 3D renders (Y2K), heavy decorative pattern (maximalist), pure black backgrounds.
+
+**Accessibility:** gradient backgrounds at low contrast can fail WCAG AA — always verify text-on-gradient contrast; consider placing copy on a card surface inside the gradient rather than directly on the backdrop.
+
+## Component families
+None at install time. As `*Card`, `*Tile`, `*Badge` families emerge in the project, the Director lists them here with their shared pattern.
+
+## Details
+- **Selection:** `hsl(var(--primary) / 0.18)` background, foreground text.
+- **Focus ring:** `2px solid hsl(var(--ring) / 0.5)` — visible, not loud.
+- **Scrollbar:** thin.
+
+## Exceptions
+None yet.
+
+## Revisions
+- Initial direction, generated at install time.

package/themes/soft-modern/tokens.ts

@@ -0,0 +1,166 @@
+import type { Direction } from "../schema";
+
+export const softModern: Direction = {
+  name: "soft-modern",
+  ethos: "Linear's softer cousin · Notion warmth · Stripe homepage gradients · Vercel's quiet polish",
+  references: [
+    { brand: "Linear", trait: "geometric calm" },
+    { brand: "Notion", trait: "approachable warmth" },
+    { brand: "Stripe", trait: "soft gradient backdrops" },
+    { brand: "Vercel", trait: "quiet polish on the marketing site" },
+    { brand: "Plain (plain.com)", trait: "friendly type, rounded chrome" },
+  ],
+  feel:
+    "Approachable and considered. Rounded corners, soft layered shadows, " +
+    "friendly geometric sans, muted accent palette with one signal color. " +
+    "Subtle motion that confirms interaction without demanding attention. " +
+    "Reads productive, not flashy.",
+
+  fonts: {
+    display: {
+      family: "Plus Jakarta Sans",
+      fallback: ["Inter", "system-ui", "-apple-system", "sans-serif"],
+      from: "Notion/Plain — friendly geometric, slightly humanist",
+      googleFont: "Plus+Jakarta+Sans",
+      weights: [500, 600, 700],
+    },
+    body: {
+      family: "Inter",
+      fallback: ["system-ui", "-apple-system", "BlinkMacSystemFont", "sans-serif"],
+      from: "Linear/Vercel sans — clean, neutral, readable at small sizes",
+      googleFont: "Inter",
+      weights: [400, 500, 600],
+    },
+    mono: {
+      family: "JetBrains Mono",
+      fallback: ["ui-monospace", "SFMono-Regular", "monospace"],
+      from: "code blocks, metrics — tabular numerics",
+      googleFont: "JetBrains+Mono",
+      weights: [400, 500],
+    },
+  },
+
+  typography: {
+    headingTracking: "-0.02em",      // friendly sans-serif headings benefit from tight tracking
+    bodyTracking: "0",
+    fontFeatureSettings: '"cv11", "ss01", "ss03"',  // Inter stylistic sets — single-story a/g
+    h1ScaleClamp: "clamp(2.25rem, 5vw, 3.75rem)",
+    bodyBaseSize: "1rem",
+    bodyLineHeight: "1.6",
+  },
+
+  colors: {
+    background: { hsl: "220 20% 99%", from: "near-white, faint blue bias — Linear surface" },
+    foreground: { hsl: "224 38% 10%", from: "deep slate, never pure black — Notion ink" },
+    card: { hsl: "0 0% 100%", from: "pure white card — lifts off the background subtly" },
+    popover: { hsl: "0 0% 100%", from: "same as card" },
+    primary: { hsl: "262 70% 58%", from: "violet — Linear's accent" },
+    primaryForeground: { hsl: "0 0% 100%", from: "white on violet" },
+    secondary: { hsl: "220 16% 96%", from: "soft cool gray — Vercel quiet surface" },
+    secondaryForeground: { hsl: "224 38% 14%", from: "slate ink on cool gray" },
+    muted: { hsl: "220 16% 96%", from: "same as secondary" },
+    mutedForeground: { hsl: "220 12% 46%", from: "slate gray — captions and meta" },
+    accent: { hsl: "220 16% 94%", from: "hover surface — one tier deeper than secondary" },
+    accentForeground: { hsl: "224 38% 14%", from: "slate ink" },
+    border: { hsl: "220 14% 90%", from: "soft border — visible, not assertive" },
+    input: { hsl: "220 14% 90%", from: "same as border" },
+    ring: { hsl: "262 70% 58%", from: "primary, used for focus only" },
+    destructive: { hsl: "354 80% 56%", from: "warm red — not the harsh enterprise red" },
+    destructiveForeground: { hsl: "0 0% 100%", from: "white on warm red" },
+    brand: {
+      "violet-soft": { hsl: "262 60% 96%", from: "primary tinted bg — pills, highlights" },
+      "violet-deep": { hsl: "262 75% 42%", from: "primary hover, intensified" },
+      teal: { hsl: "172 60% 42%", from: "second accent — Stripe/Linear teal, used sparingly" },
+      amber: { hsl: "38 90% 60%", from: "warmth/highlight accent — Notion-like" },
+    },
+  },
+
+  spacing: {
+    base: 4,
+    scale: [4, 6, 8, 10, 12, 16, 20, 24, 32, 40, 48, 64, 80],
+    containerMax: "max-w-6xl",
+    containerPadding: "px-4 lg:px-8",
+    sectionPadding: {
+      hero: "pt-24 pb-16 lg:pt-32 lg:pb-24",
+      default: "py-16 lg:py-24",
+      tight: "py-12 lg:py-16",
+    },
+  },
+
+  radius: {
+    base: "0.75rem",                  // 12px — the soft-modern signature
+    pillsAllowed: true,               // pills are part of this language (status chips, tags)
+  },
+
+  shadows: {
+    style: "soft",
+    utilities: {
+      "shadow-soft":
+        "0 1px 2px hsl(220 14% 50% / 0.04), 0 4px 12px hsl(220 14% 50% / 0.06)",
+      "shadow-soft-lg":
+        "0 2px 4px hsl(220 14% 50% / 0.04), 0 12px 32px hsl(220 14% 50% / 0.08)",
+      "shadow-soft-inset":
+        "inset 0 1px 0 hsl(0 0% 100% / 0.6)",
+    },
+  },
+
+  motion: {
+    easing: "cubic-bezier(0.22, 1, 0.36, 1)",
+    durations: {
+      reveal: 600,                    // faster than editorial — UI feels responsive
+      loop: 2400,
+      ambient: 24000,
+    },
+    keyframes: {
+      "fade-rise": {
+        css:
+          "from { opacity: 0; transform: translateY(12px); }\n" +
+          "to { opacity: 1; transform: translateY(0); }",
+        defaultDuration: 600,
+        iteration: "once",
+        purpose: "standard content entrance — short rise, faster than editorial",
+      },
+      "scale-in": {
+        css:
+          "from { opacity: 0; transform: scale(0.96); }\n" +
+          "to { opacity: 1; transform: scale(1); }",
+        defaultDuration: 200,
+        iteration: "once",
+        purpose: "modals, popovers, tooltips — confirms interaction",
+      },
+      "shimmer": {
+        css:
+          "0% { background-position: -200% 0; }\n" +
+          "100% { background-position: 200% 0; }",
+        defaultDuration: 1600,
+        iteration: "infinite",
+        purpose: "loading skeletons — gradient sweep",
+      },
+    },
+    respectsReducedMotion: true,
+  },
+
+  density: "medium",
+
+  patterns: {
+    button:
+      "Solid-fill primary (primary bg, primary-foreground text, rounded-xl, shadow-soft). " +
+      "Secondary is ghost (border, foreground text). Tertiary is link. " +
+      "Hover: subtle scale (1.01) + shadow-soft-lg.",
+    card:
+      "Rounded-xl, border, bg-card, shadow-soft. Internal padding p-6 lg:p-8. " +
+      "Title in display font; body in sans. Hover lifts to shadow-soft-lg.",
+    input:
+      "Full rounded-lg box, border, bg-background. Focus = ring (2px primary at 40% opacity). " +
+      "Label above, helper text below in muted-foreground.",
+    cta:
+      "Primary button is the default. Secondary CTAs use ghost button or text-link with primary color.",
+  },
+
+  details: {
+    selectionBg: "hsl(var(--primary) / 0.18)",
+    selectionFg: "hsl(var(--foreground))",
+    focusRing: "2px solid hsl(var(--ring) / 0.5)",
+    scrollbarStyle: "thin",
+  },
+};

package/themes/solar-residential/THEME.md

@@ -0,0 +1,92 @@
+# Design Direction — Solar-Residential
+
+## Ethos
+Sunrun homeowner-friendly chrome · Tesla Solar minimal white · SunPower trust-blue restraint · Sunnova warm signal-green · ADT Solar suburban-safe rounding
+
+## Feel
+Clean white residential-installer page. One signal-green accent does all the savings and CTA work. Numbers are big and tabular — kWh, dollar-per-month, panel count. Rounded corners read suburban-safe, not enterprise-sharp. The page reads as a confident neighborhood quote, never a sales pitch.
+
+## Reference brands
+- **Sunrun** → homeowner-friendly CTA stack. The page is a quote, the quote is a button.
+- **Tesla Solar** → near-zero-chrome white canvas. One accent moment per screen.
+- **SunPower** → trust-blue restraint and savings-calculator gravity. Numbers are the hero.
+- **Sunnova** → warm signal-green for go/install/active states. Green means yes.
+- **ADT Solar** → rounded suburban-safe card chrome. The corners reassure the homeowner.
+
+## Tokens
+All tokens live in `src/index.css` as HSL triples. Every token's `from:` comment names its brand origin.
+
+Surface stack is **pure white background** → `--card` (a single degree above) → `--secondary` (cool-gray inset panels). Depth comes from soft shadows on the savings card, hairline borders elsewhere. Pure black is forbidden; `--foreground` is a deep cool slate.
+
+Brand tokens: `--signal-green`, `--signal-green-deep`, `--signal-green-soft`, `--trust-blue`, `--sun-amber`, `--panel-slate`. The `--sun-amber` is decorative-only — it appears on the sunshine glyph and never on a CTA. `--trust-blue` is reserved for warranty and certification badges.
+
+## Typography
+- **Display:** Inter heavy (Tesla Solar / Sunrun marketing display). h1–h4. Tracking `-0.02em`.
+- **Body:** Inter regular/medium (SunPower body). Body base **15px** with **line-height 1.55** — readable for older homeowners by design.
+- **Mono:** JetBrains Mono. Dollar amounts, kWh, panel count, zip-code input — tabular-nums on by default.
+
+H1 uses `clamp(2.25rem, 5vw, 3.75rem)`. Restrained — the dollar numbers carry the page, not the heading. Font features: `"tnum", "ss01"`.
+
+## Spacing
+- **Container:** `max-w-6xl px-4 lg:px-8` — wide enough for a three-panel installer-process timeline.
+- **Section padding tiers:**
+  - Hero: `pt-20 pb-12 lg:pt-28 lg:pb-20`
+  - Default: `py-14 lg:py-20`
+  - Tight: `py-10 lg:py-14`
+- **Allowed scale values:** 4 6 8 10 12 16 20 24 32 40 48 64 80.
+
+## Color
+No hex anywhere in component files. All color via tokens.
+
+Signal green is the only saturated CTA accent. Trust blue and sun amber are decorative-semantic. The savings-row highlight (`bg-signal-green-soft`) is the only acceptable green-on-white surface tint. Status pills (`Quote`, `Permit`, `Install`, `Inspect`, `Activate`) use the signal-green-soft + signal-green-deep pair — never solid fills.
+
+## Radius
+`--radius: 0.625rem` (10px). Suburban-safe rounding — softer than enterprise dashboards, sharper than soft-modern. Pills allowed (`pillsAllowed: true`) for process-step badges and zip-code chips.
+
+## Shadows
+**Soft, three utilities:** `.shadow-quote` (savings-calculator card lift), `.shadow-card` (general panel lift), `.shadow-panel-glow` (the single green-ringed glow on the panel-render hero or the active quote card). No glows on body cards. No colored shadows except panel-glow on hero.
+
+## Motion
+Three keyframes: `fade-rise` (400ms — savings card and quote-block entrance), `counter-up` (600ms — estimated-savings dollar number rolls in once the zip is entered), `sun-rays` (18s slow ambient rotation behind the panel-render hero only). The counter-up is the one performative moment — it confirms the homeowner that their input did something.
+
+Easing: `cubic-bezier(0.22, 1, 0.36, 1)`. `prefers-reduced-motion` is honored — `sun-rays` halts, `counter-up` resolves immediately to its final state.
+
+## Density
+Medium. The page makes room for the dollar number to be 48px and tabular. Process-timeline steps get generous side-padding. Customer-story rows are airy — three homeowners across, photo-name-quote, not a packed grid.
+
+## Component patterns
+- **Buttons:** solid signal-green primary (rounded-lg, shadow-card) for the single commit — `Get my quote`, `Schedule install`. Secondary is ghost. Tertiary is text-link green. Hover deepens fill to `--signal-green-deep`; no scale, no shadow growth.
+- **Cards:** rounded-lg, 1px `--border`, `bg-card`, `shadow-card`. Padding `p-5 lg:p-6`. The savings-calculator card is the one exception — it wears `shadow-panel-glow` for emphasis.
+- **Inputs:** full rounded-lg box, 1px `--input` border, `bg-card`. Zip-code input is mono 18px center-aligned. Focus = 2px signal-green ring at 45% opacity.
+- **CTA:** primary signal-green for the quote commit. Process timeline pills are soft-green badges. Customer-story name carries a thin trust-blue underline only.
+
+## Recommended rich media
+Solar-Residential leans on **photorealistic 3D roof-panel renders** and **real homeowner photography** — suburban houses in golden-hour light, panels visible, family-on-driveway energy. Avoid stock photography of suit-and-tie engineers or generic green-energy abstractions.
+
+**Iconography:** 24px grid, 1.5px stroke, rounded line caps. Sun, house, panel, plug, leaf, dollar — drawn in a single hand. The literal sun glyph may use `--sun-amber` as a fill.
+
+**AI tool recommendations:** **Midjourney / Flux** for *"photorealistic suburban single-family home with rooftop solar panels, golden hour, family standing in driveway, wide-angle, soft natural light, no logos"* and *"photorealistic 3D render of monocrystalline solar panel, isolated on white, three-quarter angle, soft studio lighting"*. Avoid the default Midjourney "green energy" abstract gradients — they look stock.
+
+**Aspect ratios:** 16:10 for the hero roof shot. 4:3 for the savings-calculator screenshot. 1:1 for homeowner-story portraits. Never 16:9 — that's video and reads consumer-broadcast.
+
+**Video:** rare, optional. If used, a 15-second silent install timelapse (truck, panels rising, family thumbs-up). Poster frame mandatory. ≤6MB H.265. Never autoplay with sound.
+
+**Performance:** roof-render hero ships as AVIF at 1800w ≤140KB. Customer portraits at 600w ≤40KB each. LCP target 2s.
+
+**Avoid:** generic green-leaf gradient backgrounds, world-globe imagery, suit-and-tie sales reps, polar-bear-on-ice climate visuals, neon-glow solar-cell renders, before/after slider gimmicks. The page sells a roof job, not a global mission.
+
+**Accessibility:** every dollar figure has an accompanying spelled-out aria-label (`$184 saved per month`). Process-step pills include the step number and label, never icon-only. Signal-green meets 4.5:1 against white at button text size.
+
+## Component families
+None at install time. Family conventions emerge as the project grows.
+
+## Details
+- **Selection:** `hsl(var(--primary) / 0.20)` background, foreground text.
+- **Focus ring:** `2px solid hsl(var(--ring) / 0.45)`. Signal-green, soft.
+- **Scrollbar:** thin.
+
+## Exceptions
+None yet.
+
+## Revisions
+- Initial direction, generated at install time.