@stylecrib/cli 0.3.1 → 0.3.3

package/themes/raw-concrete/theme.yml

@@ -0,0 +1,88 @@
+# Base 06 Raw Concrete — the first flagship theme authored under the v2 arc.
+#
+# Per SURVIVOR_MAPPING.md, Family A (Art & Design Movements) has zero
+# survivor precedent. Raw Concrete is chosen as theme #1 specifically
+# because its signature move is "unstyled honesty" — default link colors,
+# visible borders, exposed structure. That's hard to slop up: the failure
+# mode is over-styling, not under-styling. Good forcing function for a
+# harness whose gates are looking for slop patterns.
+#
+# See site/design-system/BESPOKE_THEME_SYSTEM.md #06 for the source
+# entry. This file expands that one line into the full YAML schema.
+
+name: Raw Concrete
+concept: Web brutalism — system defaults weaponized, honest structure, monospace throughout.
+influence: Web brutalism (brutalistwebsites.com era). Kate Moross print, Vitalik's blog, the original Craigslist, arxiv.org paper listings.
+
+# v2 metadata — for anchor-compare + regression-scan scoping.
+family: A
+base_number: 6
+
+# Where the theme renders live. anchor-compare fetches this URL and
+# passes the rendered screenshot to Director for grading. Anchor-compare
+# is skipped for Family A + G in MVP (no survivor precedent) but the URL
+# is here so the site-integration path is stable across families.
+render_url: http://localhost:5173/themes/raw-concrete
+
+surface: web
+
+typography:
+  display: Berkeley Mono (paid) or JetBrains Mono (free) — 500 weight for headings, no display face beyond this
+  body: same as display — Berkeley Mono or JetBrains Mono, 400 weight, 15px
+  mono: same as display and body — the whole theme is monospace, one family, three weights
+  scale: 1.2 (minor third — deliberately shallow contrast; body and heading feel close)
+
+palette:
+  bg: "#FFFFFF"
+  surface: "#FFFFFF"
+  ink: "#000000"
+  accent: "#0000EE"      # default browser link blue — used as-is, not "our brand blue"
+  secondary: "#C0C0C0"   # default table border gray
+  visited: "#551A8B"     # default visited link purple — used as-is
+
+density: dense
+
+motion: none — no transitions, no scroll reveals, no hover animations. The absence IS the register.
+
+signature: |
+  Every link is `#0000EE`. Every visited link is `#551A8B`. Every border is a
+  `1px solid #C0C0C0` hairline. No border-radius anywhere — every corner is
+  90°. No box-shadow ever. Tables render as tables (visible cell borders).
+  Buttons look like `<button>` elements pre-CSS. Underlines on links stay.
+  The composition is unmistakably "the browser did this, not a designer."
+
+imagery: |
+  Photographs render at native aspect ratio with a 1px black border and no
+  cropping. No filters, no gradients, no vignettes. Illustrations are ASCII
+  or single-color line drawings. No 3D, no rendered shapes, no icons beyond
+  what unicode provides.
+
+best_for:
+  - Personal blogs (Vitalik-register)
+  - Academic paper listings (arxiv-register)
+  - Indie developer portfolios that want to feel earned
+  - Manifestos and long-form essays
+  - Art projects that trade on refusal-of-polish
+  - Craigslist-shaped marketplaces
+
+avoid:
+  - "Border-radius greater than 0px anywhere on the page"
+  - "Any box-shadow — hover, focus, or decorative"
+  - "CSS transitions or animations of any kind"
+  - "Prettified link colors — links must render as browser-default #0000EE"
+  - "Sans-serif or serif faces — monospace only, one family throughout"
+  - "Rounded buttons or pill-shaped controls"
+  - "Gradient backgrounds or gradient text"
+  - "Icon fonts or SVG icons — unicode symbols only (▲ ▼ · × → ←)"
+  - "Padding standardization — deliberately inconsistent, exposed structure"
+  - "Hover states other than the browser default underline / link-color-change"
+
+banned_defaults:
+  # Global blocklist (inherited from BESPOKE_THEME_SYSTEM.md's global slop-blocklist)
+  - "claude-cream (#F4F1EA + serif + #D97757)"
+  - "void+acid (near-black bg + single bright acid-green or vermilion accent)"
+  - "broadsheet-on-noneditorial (hairline rules + zero border-radius + newspaper columns on non-editorial content)"
+  - "tech-bro purple gradient (purple→blue gradient hero + centered headline + double CTA + emoji icons)"
+  - "uniform-everything (identical padding + one weight of one sans doing every job + rounded-2xl + shadow-md cards)"
+  # Base-specific: Raw Concrete has its OWN slop failure mode
+  - "brutalism-as-decoration (visible borders + monospace applied as decoration to an otherwise polished SaaS layout — Raw Concrete must refuse polish structurally, not aesthetically)"

package/themes/raw-concrete/tokens.ts

@@ -0,0 +1,27 @@
+// Generated from theme.yml. Do not edit by hand — edit theme.yml + re-materialize.
+
+export const tokens = {
+  slug: "raw-concrete",
+  family: "A",
+  base: "06",
+  palette: {
+    "bg": "#FFFFFF",
+    "surface": "#FFFFFF",
+    "ink": "#000000",
+    "accent": "#0000EE",
+    "secondary": "#C0C0C0",
+    "visited": "#551A8B"
+  },
+  typography: {
+    "display": "Berkeley Mono (paid) or JetBrains Mono (free) — 500 weight for headings, no display face beyond this",
+    "body": "same as display — Berkeley Mono or JetBrains Mono, 400 weight, 15px",
+    "mono": "same as display and body — the whole theme is monospace, one family, three weights",
+    "scale": "1.2 (minor third — deliberately shallow contrast; body and heading feel close)"
+  },
+  surface: "web",
+  density: "dense",
+  motion: "none — no transitions, no scroll reveals, no hover animations. The absence IS the register.",
+  signature: "Every link is `#0000EE`. Every visited link is `#551A8B`. Every border is a\n`1px solid #C0C0C0` hairline. No border-radius anywhere — every corner is\n90°. No box-shadow ever. Tables render as tables (visible cell borders).\nButtons look like `<button>` elements pre-CSS. Underlines on links stay.\nThe composition is unmistakably \"the browser did this, not a designer.\"\n",
+} as const;
+
+export type Tokens = typeof tokens;

package/themes/realestate-luxury/THEME.md

@@ -0,0 +1,94 @@
+# Design Direction — Realestate-Luxury
+
+## Ethos
+Sotheby's cream listing-book · Compass deep navy · Modern House serif · The Agency cinematic listings · 1stDibs editorial luxury
+
+## Feel
+An eight-figure listing book delivered through the browser. Deep cream backgrounds carry full-bleed property cinematography, high-contrast serif headlines name the address as if it were a chapter title, and a single deep navy accent does all the interaction work. Burgundy is the second luxury accent — focus rings, selection, the occasional vertical rule on a spec table. Reads as a bound real estate catalog, not as a marketplace search experience.
+
+## Reference brands
+- **Sotheby's Realty** → cream paper + Cormorant-feel serif + listing-as-portrait photography. The headline IS the address; the photograph IS the listing.
+- **Compass** → deep navy mark + clean sans + structured global search. Navy is the canonical action color; nothing else competes.
+- **Modern House (London)** → cream + serif + architectural full-bleed photography. The page is a quiet frame for the property.
+- **The Agency** → deep cream + restrained nav + cinematic listing reels. Motion is slow ken-burns over stills, never UI animation for its own sake.
+- **1stDibs Estate** → warm cream + editorial serif + provenance copy. Long-form descriptive prose is welcome — the listing has a story.
+
+## 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 brand it traces to.
+
+Surface stack is **deep cream** (background) → **lifted cream** (card) → **deeper cream** (secondary/muted/accent). Depth comes from hairline borders on a warm hairline color, never from drop shadows or fill differentiation. Pure white is forbidden — `--paper`/`--cream` replace it; pure black is forbidden — `--navy-ink` replaces it.
+
+Brand tokens: `--cream`, `--cream-deep`, `--navy`, `--navy-ink`, `--burgundy`, `--brass`. Primary is deep navy. Burgundy is reserved for focus, selection, and the occasional editorial rule. Brass is reserved for hardware-feeling accents — spec-table rules, divider dots — never as a button face.
+
+## Typography
+- **Display:** Cormorant Garamond (Sotheby's listing-book serif feel). h1–h4. Tracking `-0.012em` — Garalde display wants near-zero, just shy of it.
+- **Body:** Inter (Compass clean sans). Body base **17px** with **line-height 1.65** — catalog-comfortable, never marketplace-dense.
+- **Mono:** JetBrains Mono. Price, lot size, sqft, MLS number, dateline. Always `font-variant-numeric: tabular-nums` so prices align column-wise.
+
+H1 uses `clamp(2.75rem, 7vw, 6rem)` — the address-as-title scale. Font features: `"liga"`, `"dlig"`, `"tnum"`, `"ss01"` — discretionary ligatures on the display serif, tabular numerics on body and mono.
+
+## Spacing
+- **Container:** `max-w-7xl px-6 lg:px-12` — wide enough for full-bleed photography and 21:9 hero stills, with generous outer gutters.
+- **Section padding tiers:**
+  - Hero: `pt-24 pb-20 lg:pt-32 lg:pb-28`
+  - Default: `py-20 lg:py-32`
+  - Tight: `py-12 lg:py-20`
+- **Allowed scale values:** 4 8 12 16 20 24 32 40 48 64 96 128. No arbitrary spacing. Density tier is **low** — catalog breathing, never marketplace density.
+
+## Color
+No hex in component files. All color via tokens. Opacity via `/N` modifier. White and pure black are forbidden — `--cream` and `--navy-ink` replace them. The palette is intentionally small: cream, navy, burgundy, brass, and the cream-family neutrals. If a designer needs a new color, the answer is almost always a wider use of one of the six brand tokens, not a new one.
+
+## Radius
+`--radius: 0`. **Sharp corners only.** Pills are disallowed (`pillsAllowed: false`) — they read marketplace. Every listing card, every input, every button has catalog-page corners.
+
+## Shadows
+**Minimal.** Two utilities:
+- `.hairline-bottom` — `inset 0 -1px 0 hsl(var(--border))`, the divider rule between listing sections.
+- `.shadow-listing` — `0 1px 2px hsl(var(--navy-ink) / 0.04), 0 8px 24px hsl(var(--navy-ink) / 0.06)`, used only on listing-card hover.
+
+No glows. No colored shadows. The cream paper absorbs depth gracefully through hairlines and full-bleed photography.
+
+## Motion
+Three keyframes:
+- `fade-rise` — 1000ms opacity + 20px translate, the standard entrance. Slow on purpose: catalog pacing.
+- `ken-burns` — 32000ms infinite scale + translate on hero stills, the architectural camera push.
+- `underline-sweep` — 600ms scaleX 0→1 from left origin, the text-link hover.
+
+Easing: `cubic-bezier(0.22, 1, 0.36, 1)`. `prefers-reduced-motion` is honored — wrapped in a media query in every motion utility. **No marquee. No parallax. No UI bounce. No glow pulse.** This direction does not perform.
+
+## Component patterns
+- **Buttons:** Text-link CTAs by default, navy color, underline-sweep on hover. Solid-fill is reserved for the single hero action per page — navy bg, cream text, sharp corners. Secondary actions are hairline-outlined ghost buttons in navy. **No pill shapes. No burgundy buttons** — burgundy is focus-only.
+- **Cards:** Sharp 0 corners, hairline border on `--cream` card surface. Internal padding `p-8 lg:p-12`. Listing cards lead with full-width photography (4:5 portrait or 3:2 landscape), address in Cormorant display, spec line in mono. Hover lifts to `shadow-listing`.
+- **Inputs:** Border-bottom only (1px `--border`) on the cream surface. No full box. Label sits above in mono-uppercase, tracking `0.12em`. Focus shifts border to burgundy.
+- **CTA links:** Text-link with underline-sweep for the catalog body. Solid navy rectangle for the single hero CTA (Request Viewing). **Never a pill, never a gradient, never a glow.**
+
+## Recommended rich media
+Realestate-Luxury is a photography-driven language. The lead asset on any listing is **environmental architectural photography, color-graded toward Architectural Digest warmth** — golden-hour interior light, cool blue-grey exterior shadow, no HDR halos, no overly-corrected verticals. Real estate hero stills should feel like Helene Binet or Iwan Baan, not like MLS phone photography.
+
+Twilight exteriors are the canonical hero treatment — lights on inside, sky still holding cobalt, no people in frame. Interior shots are staged and styled (a single book on the bench, a vase of olive branches, never a family photo). Drone aerials are welcome for estates with land; never use drone footage of suburban subdivisions — it reads marketplace.
+
+**AI tool recommendations:** **Midjourney v6+** with prompts like *"architectural photography, twilight exterior, Iwan Baan style, warm interior light, cobalt sky, medium format, 50mm, no people"* for hero stills; *"interior architectural photography, AD magazine, golden hour, Hasselblad, natural light, styled interior"* for interiors. Avoid Midjourney's default "luxury real estate" prompt — it produces glossy, over-saturated McMansion renders. Explicitly prompt for medium format and architectural authorship.
+
+**Aspect ratios:** 21:9 cinematic for the hero (full-bleed, the cinematic real-estate frame); 4:5 portrait for vertical environmental shots; 3:2 for inline catalog photography. **Never 1:1 square** — that reads Instagram listing, not catalog.
+
+**Video:** A single autoplay-muted hero reel of the property is welcome — slow drone push, slow interior tracking, 18–24 second loop. No music in autoplay. Full property tour videos sit behind a play-button poster image. ≤6 MB per hero loop, H.265 or AV1.
+
+**Performance:** hero image ≤180 KB AVIF at 2400w; inline catalog photography ≤120 KB at 1600w. LCP under 2.2s with hero image — if it slips, optimize the image; do not strip the photography.
+
+**Avoid:** MLS-style 14-photo carousels (marketplace territory), red SOLD overlays (Redfin territory), price-drop badges (marketplace territory), virtual-tour glasses iconography (gimmicky), AI-generated "luxury homes" (the uncanny-valley grass tells), drone footage of cookie-cutter subdivisions.
+
+**Accessibility:** alt-text describes the property as a Sotheby's catalog would — *"Hudson Valley farmhouse with limestone exterior, cedar-shingle roof, and a maple grove descending to the river at golden hour"*. Address + property type alone is not enough.
+
+## Component families
+None at install time. Family conventions emerge as the project grows; the Director appends them here as they're established. First likely families: listing-card, spec-table, agent-attribution, neighborhood-frame.
+
+## Details
+- **Selection:** `hsl(var(--brand-burgundy) / 0.22)` background, foreground text. Burgundy doing its second-accent job.
+- **Focus ring:** `1px solid hsl(var(--ring))` — thin burgundy. Quiet, considered, never a 2px blue web-app ring.
+- **Scrollbar:** thin.
+
+## Exceptions
+None yet. When an intentional one-of-one violation lands, add it here with the reason. The Director's consistency pass lists all exceptions for human review.
+
+## Revisions
+- Initial direction, generated at install time.

package/themes/realestate-luxury/tokens.ts

@@ -0,0 +1,169 @@
+import type { Direction } from "../schema";
+
+export const realestateLuxury: Direction = {
+  name: "realestate-luxury",
+  ethos:
+    "Sotheby's cream listing-book · Compass deep navy · Modern House serif · The Agency cinematic listings · 1stDibs editorial luxury",
+  references: [
+    { brand: "Sotheby's Realty", trait: "cream paper + Cormorant serif + listing-as-portrait photography" },
+    { brand: "Compass", trait: "deep navy mark + clean sans + structured global search" },
+    { brand: "Modern House (London)", trait: "cream + serif + architectural full-bleed photography" },
+    { brand: "The Agency", trait: "deep cream + restrained nav + cinematic listing reels" },
+    { brand: "1stDibs Estate", trait: "warm cream + editorial serif + curated provenance copy" },
+  ],
+  feel:
+    "Eight-figure listing book in browser form. Deep cream backgrounds carry full-bleed property cinematography, " +
+    "high-contrast serif headlines name the address, and a single deep navy or burgundy accent does all the " +
+    "interaction work. Reads as bound real estate catalog, not as marketplace search.",
+
+  fonts: {
+    display: {
+      family: "Cormorant Garamond",
+      fallback: ["Cormorant", "EB Garamond", "Garamond", "Didot", "Georgia", "serif"],
+      from: "Sotheby's listing-book serif — high-contrast Garalde with a 1stDibs catalog feel",
+      googleFont: "Cormorant+Garamond",
+      weights: [400, 500, 600],
+    },
+    body: {
+      family: "Inter",
+      fallback: ["system-ui", "-apple-system", "BlinkMacSystemFont", "Helvetica Neue", "sans-serif"],
+      from: "Compass clean sans — neutral body that lets the serif and photography lead",
+      googleFont: "Inter",
+      weights: [400, 500, 600],
+    },
+    mono: {
+      family: "JetBrains Mono",
+      fallback: ["Berkeley Mono", "ui-monospace", "SFMono-Regular", "Consolas", "monospace"],
+      from: "tabular numerics for price, lot size, sqft — instrument-feel for the spec table",
+      googleFont: "JetBrains+Mono",
+      weights: [400, 500],
+    },
+  },
+
+  typography: {
+    headingTracking: "-0.012em",         // Cormorant tightens slightly — display Garalde wants near-zero, just shy
+    bodyTracking: "0",
+    fontFeatureSettings: '"liga", "dlig", "tnum", "ss01"',
+    h1ScaleClamp: "clamp(2.75rem, 7vw, 6rem)",   // address-as-title scale — the headline IS the listing
+    bodyBaseSize: "1.0625rem",                    // 17px — catalog comfort
+    bodyLineHeight: "1.65",
+  },
+
+  colors: {
+    background: { hsl: "38 32% 94%", from: "Sotheby's deep cream — the listing-book paper, never white" },
+    foreground: { hsl: "215 38% 14%", from: "Compass deep navy-ink — heading + body, never pure black" },
+    card: { hsl: "38 28% 97%", from: "lifted cream — listing card surface, one tone above paper" },
+    popover: { hsl: "38 28% 97%", from: "same family as card — depth via hairline, not fill" },
+    primary: { hsl: "215 48% 22%", from: "Compass deep navy — the canonical action color across the listing book" },
+    primaryForeground: { hsl: "38 32% 94%", from: "cream on deep navy" },
+    secondary: { hsl: "38 22% 88%", from: "deeper cream tier — secondary panels and quiet surfaces" },
+    secondaryForeground: { hsl: "215 38% 14%", from: "navy-ink on deeper cream" },
+    muted: { hsl: "38 18% 86%", from: "muted cream — listing meta strips, dateline backgrounds" },
+    mutedForeground: { hsl: "215 18% 36%", from: "Modern House soft navy — secondary copy on cream" },
+    accent: { hsl: "38 24% 90%", from: "hover cream — one tier under secondary" },
+    accentForeground: { hsl: "215 38% 14%", from: "navy-ink on accent cream" },
+    border: { hsl: "38 18% 78%", from: "warm hairline — visible on cream but never assertive" },
+    input: { hsl: "38 18% 78%", from: "same as border — single hairline language" },
+    ring: { hsl: "350 48% 32%", from: "deep burgundy — the luxury second-accent, used for focus only" },
+    destructive: { hsl: "8 62% 42%", from: "deep terracotta — alert tone that respects the cream palette" },
+    destructiveForeground: { hsl: "38 32% 94%", from: "cream on terracotta" },
+    brand: {
+      cream: { hsl: "38 32% 94%", from: "= background; the listing-book paper itself" },
+      "cream-deep": { hsl: "38 22% 88%", from: "= secondary; the deeper cream for panel surfaces" },
+      navy: { hsl: "215 48% 22%", from: "= primary; Compass deep navy" },
+      "navy-ink": { hsl: "215 38% 14%", from: "= foreground; the deepest navy, used as ink" },
+      burgundy: { hsl: "350 48% 32%", from: "Modern House / Sotheby's deep burgundy — second luxury accent" },
+      brass: { hsl: "38 42% 52%", from: "antique brass — fitting-hardware accent, rule lines on spec tables" },
+    },
+  },
+
+  spacing: {
+    base: 4,
+    scale: [4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 96, 128],
+    containerMax: "max-w-7xl",          // full-bleed listing photography needs the width
+    containerPadding: "px-6 lg:px-12",
+    sectionPadding: {
+      hero: "pt-24 pb-20 lg:pt-32 lg:pb-28",
+      default: "py-20 lg:py-32",
+      tight: "py-12 lg:py-20",
+    },
+  },
+
+  radius: {
+    base: "0",                          // sharp — catalog-page corners, never rounded
+    pillsAllowed: false,                // pills read marketplace, not listing book
+  },
+
+  shadows: {
+    style: "minimal",
+    utilities: {
+      "hairline-bottom":
+        "inset 0 -1px 0 hsl(var(--border))",
+      "shadow-listing":
+        "0 1px 2px hsl(215 38% 14% / 0.04), 0 8px 24px hsl(215 38% 14% / 0.06)",
+    },
+  },
+
+  motion: {
+    easing: "cubic-bezier(0.22, 1, 0.36, 1)",
+    durations: {
+      reveal: 1000,                     // slow on purpose — catalog pacing
+      loop: 2400,
+      ambient: 32000,                   // ken-burns on hero stills
+    },
+    keyframes: {
+      "fade-rise": {
+        css:
+          "from { opacity: 0; transform: translateY(20px); }\n" +
+          "to { opacity: 1; transform: translateY(0); }",
+        defaultDuration: 1000,
+        iteration: "once",
+        purpose: "section entrance — listing reveal, deliberately unhurried",
+      },
+      "ken-burns": {
+        css:
+          "0% { transform: scale(1.04) translate(0, 0); }\n" +
+          "100% { transform: scale(1.12) translate(-1.5%, -1%); }",
+        defaultDuration: 32000,
+        iteration: "infinite",
+        purpose: "hero listing photography drift — architectural camera push",
+      },
+      "underline-sweep": {
+        css:
+          "from { transform: scaleX(0); transform-origin: left; }\n" +
+          "to { transform: scaleX(1); transform-origin: left; }",
+        defaultDuration: 600,
+        iteration: "once",
+        purpose: "text-link hover — underline wipes in left-to-right",
+      },
+    },
+    respectsReducedMotion: true,
+  },
+
+  density: "low",                       // catalog breathing; never marketplace density
+
+  patterns: {
+    button:
+      "Text-link CTAs by default — navy color, underline-sweep on hover. " +
+      "Solid-fill is reserved for the single hero action per page (navy bg, cream text, sharp corners). " +
+      "Secondary actions are hairline-outlined ghost buttons in navy. No pill shapes. " +
+      "Burgundy is focus-ring only, never a button face.",
+    card:
+      "Sharp corners. Hairline border (--border) on a card-cream surface. Internal padding p-8 lg:p-12. " +
+      "Listing cards lead with full-width photography (4:5 portrait or 3:2 landscape), " +
+      "address in Cormorant display, spec line in mono. Hover lifts to shadow-listing.",
+    input:
+      "Border-bottom only (1px --border) on cream. No full box. " +
+      "Label above in mono-uppercase tracking 0.12em. Focus shifts border to burgundy.",
+    cta:
+      "Text-link with underline-sweep for the catalog. Solid navy rectangle for the single hero CTA (Request Viewing). " +
+      "Never a pill, never a gradient, never a glow.",
+  },
+
+  details: {
+    selectionBg: "hsl(var(--brand-burgundy) / 0.22)",
+    selectionFg: "hsl(var(--foreground))",
+    focusRing: "1px solid hsl(var(--ring))",
+    scrollbarStyle: "thin",
+  },
+};

package/themes/realestate-marketplace/THEME.md

@@ -0,0 +1,106 @@
+# Design Direction — Realestate-Marketplace
+
+## Ethos
+Zillow listing-card grid · Redfin signal red · Apartments.com warm orange · Trulia friendly map · Streeteasy dense tabular
+
+## Feel
+Built for browsing two hundred listings on a Saturday. A warm-white canvas carries a friendly geometric sans, dense photo-card grids, and a single signal-color CTA. The map and the list co-exist; filters are first-class chrome, not an afterthought. Reads as a marketplace tool, not as a catalog or a brochure.
+
+## Reference brands
+- **Zillow** → deep blue brand mark + warm white + listing-card grid. Blue carries everything: search, save, primary CTAs, focus ring.
+- **Redfin** → signal red + soft cards + structured filter chrome. Red is a status color (Sold, Off-market, urgent badges) — never a primary CTA.
+- **Apartments.com** → warm orange accent + density + photo-card volume. Orange is the New / Hot listing badge; one accent color among several signals.
+- **Trulia** → sand surface + friendly map UI + neighborhood scoring. The map is a first-class surface, not a modal.
+- **Streeteasy** → NYC-specific dense tabular listings. Density is a feature; tabular numerics are non-negotiable on price columns.
+
+## 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 brand it traces to.
+
+Surface stack is **warm white** (background) → **pure white** (card/popover) → **cool gray** (secondary/muted/accent). Depth comes from soft card shadows and hairline borders. The filter bar uses `shadow-filterbar` — a single hairline + soft drop, the signature marketplace chrome.
+
+Brand tokens: `--blue-zillow`, `--blue-deep`, `--red-redfin`, `--orange-apt`, `--green-saved`, `--sand-warm`, `--map-water`. Primary is `--blue-zillow`. Status colors (red, orange, green) are reserved for status chips and badges — never primary CTAs.
+
+## Typography
+- **Display:** Manrope (Zillow-adjacent geometric sans). h1–h4 and listing-card titles. Tracking `-0.02em` — confident, slightly tight.
+- **Body:** Inter (Redfin/Streeteasy clean sans). Body base **15px** with **line-height 1.5** — marketplace density.
+- **Mono:** JetBrains Mono. Price, sqft, bed/bath count, lot size, MLS, last-updated date. Tabular numerics always on.
+
+H1 uses `clamp(2rem, 4.5vw, 3.25rem)` — restrained on purpose. The H1 is rarely the show on a marketplace page; the listings are. Font features: `"cv11"`, `"ss01"`, `"tnum"` — tabular numerics enabled site-wide so prices align in the result grid without per-component overrides.
+
+## Spacing
+- **Container:** `max-w-screen-2xl px-4 lg:px-6` — marketplace lives full-width for the map/list split. Gutters are tighter than catalog directions because content is the point.
+- **Section padding tiers:**
+  - Hero: `pt-12 pb-10 lg:pt-16 lg:pb-12` (modest — the search bar is the hero, not a marketing slab)
+  - Default: `py-10 lg:py-16`
+  - Tight: `py-6 lg:py-10`
+- **Allowed scale values:** 4 6 8 10 12 16 20 24 28 32 40 48 64 80. High-density scale with many small steps — marketplace UI needs the granularity.
+
+## Color
+No hex in component files. All color via tokens. Opacity via `/N` modifier. The marketplace palette intentionally carries multiple signal colors — red, orange, green, blue — but each has a strict role:
+
+- **Blue** = primary action, focus, brand. The catch-all.
+- **Red** = status only (Sold, Off-market, Removed, urgent alerts). Never a CTA.
+- **Orange** = badge accent (New, Hot, Open House). Never body chrome.
+- **Green** = confirmation only (Saved, Favorited, Verified). Never a CTA.
+
+Pure white is allowed (it's the card surface — marketplace cards must lift off the canvas). Pure black is forbidden — `--foreground` is a deep blue-ink.
+
+## Radius
+`--radius: 0.5rem` (8px). Softer than utility/dense, sharper than soft-modern. Pills are allowed (`pillsAllowed: true`) — filter chips, status badges, and category pills are part of the language. Pill shape encodes data (it's a filter / badge / chip), not chrome.
+
+## Shadows
+**Soft.** Four utilities:
+- `.shadow-card` — base listing-card lift: `0 1px 2px hsl(var(--navy-ink) / 0.05), 0 2px 6px hsl(var(--navy-ink) / 0.04)`.
+- `.shadow-card-hover` — listing-card hover lift.
+- `.shadow-mappin` — `0 2px 4px hsl(var(--navy-ink) / 0.18), 0 0 0 2px hsl(0 0% 100%)`, the white halo + drop shadow that defines a map pin.
+- `.shadow-filterbar` — `0 1px 0 hsl(var(--border)), 0 2px 8px hsl(var(--navy-ink) / 0.04)`, the sticky filter bar separation.
+
+No glows. No colored shadows.
+
+## Motion
+Four keyframes:
+- `fade-rise` — 240ms, the standard listing/result entrance. Marketplace must feel responsive; 1000ms is unacceptable here.
+- `card-lift` — 180ms hover lift on listing cards. Confirms targetability on a dense grid.
+- `pin-drop` — 320ms map-pin reveal with a slight overshoot. Feedback when a result lands on the map.
+- `skeleton-shimmer` — 1600ms infinite gradient sweep on loading skeletons. Listings stream in; the skeleton tells the user to keep scrolling.
+
+Easing: `cubic-bezier(0.22, 1, 0.36, 1)`. `prefers-reduced-motion` is honored. **No ambient ken-burns — this is a tool, not a film.**
+
+## Component patterns
+- **Buttons:** Solid-fill primary in `--primary` (Zillow blue), white text, 0.5rem radius, `shadow-card`. Secondary is white ghost with `--border` outline. Tertiary is text-link in primary. Pills are allowed for filter chips and status badges (Sold/New/Open House) — pill shape is data semantics, not chrome.
+- **Cards:** Listing card: rounded-lg, bg-card (pure white), `shadow-card`, no border. Photo-first (4:3 landscape, full-bleed at top). Below: price in display 700 weight, address in body, mono spec line (`3 bd · 2 ba · 1,840 sqft`). Hover applies `card-lift`. Filter and panel cards use a hairline border with no shadow.
+- **Inputs:** Full rounded-lg box with 1px `--input` border, bg-card. Focus = 2px ring in primary at 40% opacity. Search input gets a leading magnifier icon. Label sits small above; helper text below in muted-foreground.
+- **CTA links:** Solid-fill primary button is the canonical CTA. Save (heart) and Tour (calendar) buttons sit as filled-icon or icon+label variants. Sold / Off-market badges use destructive red — **never as a CTA, always as a status pill**.
+
+## Recommended rich media
+Realestate-Marketplace is photography-volume-driven, not photography-prestige-driven. Listings carry 8–24 photos each, optimized for grid thumbnails and a full-screen lightbox. The first photo is the canonical hero — usually a 4:3 exterior or wide living-room shot. **Photography quality matches the listing's price tier** — a $300k starter home with iPhone photos sits comfortably in this direction; a $3M home pushes toward Realestate-Luxury territory.
+
+Map screenshots and floor plans are first-class media. Floor plans render best at 4:3 landscape with the listing's price overlaid as a chip in the top-right. Map pin tiles use `--map-water` as the basemap water; pins use primary blue with the white halo from `shadow-mappin`.
+
+Neighborhood images sit in a separate tier — `--sand-warm` panels with a 16:9 photo, a walk-score block, and three nearby category icons (coffee, transit, schools).
+
+**AI tool recommendations:** Marketplace listing photography is rarely AI-generated — real photos win on trust. For **neighborhood imagery and category illustrations**, **Midjourney v6+** with prompts like *"editorial neighborhood photography, warm afternoon light, residential street, no people, 35mm, natural color"* works for filler. For floor plans and icons, **Recraft** with *"isometric floor plan, line drawing, restrained color, no shadows"* and a small icon set in **Lucide** (already a common marketplace standard).
+
+**Aspect ratios:** 4:3 landscape for listing photography (the marketplace standard, tessellates cleanly in a grid); 16:9 for neighborhood hero photography; 1:1 for thumbnails and avatars. **Avoid 21:9 cinematic** — that reads luxury catalog, off-feel here.
+
+**Video:** Listing tour videos sit behind a play-button poster image in the photo gallery. Autoplay is forbidden — the user is scanning 200 results. ≤4 MB per tour video, H.265 or AV1, 30s typical length.
+
+**Performance:** listing thumbnail ≤30 KB AVIF at 800w; lightbox image ≤120 KB AVIF at 2000w. Critical: the grid must lazy-load below the fold. LCP under 1.8s with the search bar + first row of cards rendered.
+
+**Avoid:** twilight cinematic real-estate hero stills (luxury territory), serif typography on listing cards (luxury territory), parallax map effects (gimmicky and bad on mobile), animated price-drop badges (cheap), AI-generated listing photos (illegal in many jurisdictions and a trust failure regardless).
+
+**Accessibility:** alt-text on listing photos must include property type + photo subject — *"Two-story craftsman home, front exterior with attached garage"* not *"Image: 123 Oak St"*. Map pins must have a text alternative (price + address); the map is not a substitute for a list.
+
+## Component families
+None at install time. Likely first families: listing-card (grid + lightbox), filter-pill, map-pin, neighborhood-tile, save-button.
+
+## Details
+- **Selection:** `hsl(var(--primary) / 0.18)` background, foreground text — the standard blue selection.
+- **Focus ring:** `2px solid hsl(var(--ring) / 0.5)` — visible, web-app-standard, accessibility-first.
+- **Scrollbar:** thin.
+
+## Exceptions
+None yet. When an intentional one-of-one violation lands, add it here with the reason. The Director's consistency pass lists all exceptions for human review.
+
+## Revisions
+- Initial direction, generated at install time.