@stylecrib/cli 0.3.1 → 0.3.3

package/themes/music-streaming/THEME.md

@@ -0,0 +1,101 @@
+# Design Direction — Music-Streaming
+
+## Ethos
+Spotify black canvas · Apple Music album-art hero · Tidal Hi-Fi audiophile blue · Bandcamp Daily editorial weight · SoundCloud waveform energy
+
+## Feel
+Near-black canvas that disappears behind oversized album art. Brand-green signal mark, geometric sans body, condensed numerals for runtimes and bitrates. Reads like lean-back playback — the artwork is the page, the chrome is a thin shell that gets out of the way. The page is the album cover, not the player UI.
+
+## Reference brands
+- **Spotify** → black canvas with green signal mark and Circular sans. The single-color play-button is the most-recognized affordance in the category.
+- **Apple Music** → deep dark with SF Pro and album art as the hero element. The cover is the design.
+- **Tidal Hi-Fi** → deep blue-black with audiophile blue accent and dense type. Hi-Res badges as tertiary chrome.
+- **Bandcamp Daily** → editorial weight inside a dark player chrome. Long reads sit beside playable embeds.
+- **SoundCloud** → waveform iconography and orange signal accent. The waveform is the timeline.
+
+## 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 **canvas-black** (background, HSL `0 0% 7%` — Spotify #121212 equivalent) → **card** at `0 0% 11%` (one stop above) → **popover** at `0 0% 14%` (two stops above). Depth comes from elevation, never from hue shift between tiers.
+
+Brand tokens: `--signal-green` (the canonical play color), `--audiophile-blue` (Tidal Hi-Res accent), `--waveform-orange` (SoundCloud secondary), `--vinyl-cream` (Bandcamp editorial pop-in), `--canvas-black`, `--now-playing` (alias of signal-green). Primary is `--signal-green` — never use it for non-playback actions.
+
+## Typography
+- **Display:** Manrope (Spotify Circular substitute). Headings and album-title scale. Tracking `-0.02em` — tight, "Now Playing" feel.
+- **Body:** Inter (Apple Music SF Pro substitute). Body base **15px** with **line-height 1.55** — denser than editorial, sized to Spotify track-row scale.
+- **Mono:** JetBrains Mono. Runtimes, bitrates, BPM, sample rates — tabular numerics with `tnum` on.
+
+H1 uses `clamp(2.5rem, 7vw, 5.5rem)`. Display headings often paired with adjacent oversized album-art at 1:1 aspect. Font features: `"ss01"`, `"ss02"`, `"tnum"`, `"cv11"`.
+
+## Spacing
+- **Container:** `max-w-7xl px-4 lg:px-8` — wide; album-art grids and playlist tables need it.
+- **Section padding tiers:**
+  - Hero: `pt-16 pb-12 lg:pt-24 lg:pb-16` (the album-art is full-bleed; section padding stays modest)
+  - Default: `py-12 lg:py-20`
+  - Tight: `py-8 lg:py-12`
+- **Allowed scale values:** 4 8 12 16 20 24 32 40 48 64 80 96 128. No arbitrary spacing.
+
+## Color
+No hex anywhere in component files. All color via tokens. Opacity via `/N` modifier on token. Pure black is forbidden — `--canvas-black` (`0 0% 7%`) replaces it; the slight lift off pure black is the entire reason the page feels warm rather than OLED-cold.
+
+**Signal-green is reserved for playback affordances only.** Never use it for "Subscribe", "Sign up", or non-play CTAs — that ruins the play-button signal across the page. For non-playback hero actions, use foreground-color text-links or App Store badges.
+
+## Radius
+`--radius: 0.5rem`. Soft-square — Spotify card and Apple Music tile corner radius. Pills are allowed (`pillsAllowed: true`) for genre chips, filter tags, and the hero play button which is a full circle for icon buttons or a `rounded-full` pill for labeled play CTAs.
+
+## Shadows
+**Glow style.** Three utilities:
+- `.art-lift` — soft black drop behind album-art tiles, lifts cover on hover
+- `.now-playing-glow` — signal-green ring + soft glow on the active playback card (single instance per page)
+- `.row-hover` — ghost inner stroke on track-row hover, 1px white at 6% opacity
+
+No saturated colored shadows beyond the signal-green now-playing-glow.
+
+## Motion
+Five keyframes, all serve playback:
+- `art-fade` (400ms) — album-art tile reveal as covers load; gentle scale-up from 0.98, no flash
+- `equalizer` (1200ms infinite) — now-playing bar pulse, the canonical "this track is playing" indicator
+- `play-pulse` (1800ms infinite) — primary play-button heartbeat ring on hero CTA, single instance per page
+- `art-drift` (24000ms infinite) — blurred album-art backdrop drift behind hero, ambient
+- `waveform-shimmer` (2400ms infinite) — SoundCloud-style waveform fill animation, used on the active scrubber bar only
+
+Easing: `cubic-bezier(0.22, 1, 0.36, 1)`. `prefers-reduced-motion` is honored — every motion utility wrapped in a media query.
+
+## Component patterns
+- **Buttons:** primary play is a SOLID round signal-green circle with canvas-black play glyph — the iconic Spotify mark. Secondary controls (shuffle, repeat, queue) are ghost icon buttons in `--muted-foreground` that brighten to `--foreground` on hover. Text-link CTAs use foreground with underline-on-hover. **Never use green for non-playback actions.**
+- **Cards:** album-art tile is the canonical card — a square cover image with title and artist text below, lifted by `.art-lift` on hover. Section cards use `bg-card`, 0.5rem radius, `p-4 lg:p-5`. No fill differentiation between cards on the same surface tier.
+- **Inputs:** search is a `rounded-full` pill with `bg-input` and leading magnifier icon, no border. Focus shows 2px signal-green ring. Filter chips below are pills (`bg-secondary`, foreground text).
+- **CTA links:** hero CTA is a solid signal-green pill with canvas-black label, optionally wrapped in `play-pulse`. Inline "Listen now" links are foreground-color underline-on-hover. App Store / Play Store badges for cross-platform.
+
+## Recommended rich media
+Music-streaming leans on **album artwork** as the primary visual asset — covers, not stock photography, not gradient illustration. The artwork is the design; everything else is chrome.
+
+Lead media is **square album cover at 1:1 aspect, minimum 600×600 source** displayed at any size from a 64×64 row thumbnail to a full-bleed 1200×1200 hero. Behind the hero, a heavily blurred and saturated copy of the same album art often sits as a backdrop with `art-drift` animation — the Spotify "Now Playing" backdrop pattern. Never use generic music stock photos (headphones on a desk, vinyl in soft focus); those signal "this site doesn't have real catalog content".
+
+**AI tool recommendations:** for placeholder album art when real catalog isn't available, **Midjourney** with prompts like *"square album cover artwork, [genre] aesthetic, minimal typographic mark, full bleed, 1:1"* — explicitly include "no text overlay" when you want clean covers. **Flux** for waveform overlays and abstract sound-art visualizations. Never generate "musicians performing" AI imagery — uncanny hands and instruments are a tell.
+
+**Aspect ratios:** 1:1 square for covers (canonical). 16:9 only for video trailers and artist documentaries. 21:9 for full-bleed hero backdrops with blurred art. Never 4:5 (Instagram-portrait, off-feel for player chrome).
+
+**Video:** muted-autoplay loops of waveform animation or abstract album-art motion are appropriate as ambient hero backdrops at ≤2 MB, H.265 or AV1. Always provide poster image. Music videos themselves are user-initiated only — never autoplay with sound.
+
+**Waveform graphics:** SoundCloud-style horizontal waveforms are appropriate for scrubber/timeline UI. Use `.waveform-shimmer` on the played portion in `--signal-green`, unplayed portion in `--muted-foreground` at low opacity.
+
+**Performance:** album-art thumbnails ≤30 KB AVIF at 600w; hero covers ≤120 KB at 1200w. Use blurhash placeholders during load — `art-fade` covers the transition. LCP under 2s with a single hero cover.
+
+**Avoid:** stock musician/instrument photography, decorative SVG ornament, gradient backgrounds (soft-modern territory), glassmorphic player chrome (Apple-Music-style frosted glass is acceptable only as a sticky-bottom mini-player, never as full-page chrome), AI-generated "performing musicians" with uncanny hands or floating instruments.
+
+**Accessibility:** album art always has alt-text in *"[Artist] — [Album]"* format. The `.now-playing-glow` element has `aria-live="polite"` with the current track. Equalizer animation has `aria-hidden="true"` — it's decorative, the now-playing text is the source of truth.
+
+## Component families
+None at install time. Family conventions emerge as the project grows; the Director appends them here as they're established. Expected first families: `TrackRow`, `AlbumTile`, `NowPlayingBar`, `PlaylistHeader`.
+
+## Details
+- **Selection:** `hsl(var(--signal-green) / 0.35)` background, foreground text.
+- **Focus ring:** `2px solid hsl(var(--signal-green))`. Matches primary signal mark.
+- **Scrollbar:** thin. Track-list virtualization expected for long playlists.
+
+## 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/music-streaming/tokens.ts

@@ -0,0 +1,187 @@
+import type { Direction } from "../schema";
+
+export const musicStreaming: Direction = {
+  name: "music-streaming",
+  ethos:
+    "Spotify black canvas · Apple Music album-art hero · Tidal Hi-Fi audiophile blue · Bandcamp Daily editorial weight · SoundCloud waveform energy",
+  references: [
+    { brand: "Spotify", trait: "black canvas with green signal mark and Circular sans" },
+    { brand: "Apple Music", trait: "deep dark with SF Pro and album art as the hero element" },
+    { brand: "Tidal Hi-Fi", trait: "deep blue-black with audiophile blue accent and dense type" },
+    { brand: "Bandcamp Daily", trait: "editorial weight inside a dark player chrome" },
+    { brand: "SoundCloud", trait: "waveform iconography and orange signal accent" },
+  ],
+  feel:
+    "Near-black canvas that disappears behind oversized album art. Brand-green signal mark, " +
+    "geometric sans body, condensed numerals for runtimes and bitrates. Reads like lean-back " +
+    "playback — the artwork is the page, the chrome is a thin shell that gets out of the way.",
+
+  fonts: {
+    display: {
+      family: "Manrope",
+      fallback: ["Inter", "system-ui", "-apple-system", "BlinkMacSystemFont", "sans-serif"],
+      from: "Spotify Circular substitute — geometric humanist sans, set tight at display sizes",
+      googleFont: "Manrope",
+      weights: [500, 700, 800],
+    },
+    body: {
+      family: "Inter",
+      fallback: ["system-ui", "-apple-system", "BlinkMacSystemFont", "Segoe UI", "sans-serif"],
+      from: "Apple Music SF Pro substitute — neutral OS-feel body for track lists and metadata",
+      googleFont: "Inter",
+      weights: [400, 500, 600],
+    },
+    mono: {
+      family: "JetBrains Mono",
+      fallback: ["Berkeley Mono", "ui-monospace", "SFMono-Regular", "Consolas", "monospace"],
+      from: "Tidal Hi-Fi bitrate readouts and runtimes — tabular numerics for player metadata",
+      googleFont: "JetBrains+Mono",
+      weights: [400, 500],
+    },
+  },
+
+  typography: {
+    headingTracking: "-0.02em",          // album-title scale needs tight tracking — Spotify "Now Playing" feel
+    bodyTracking: "0",
+    fontFeatureSettings: '"ss01", "ss02", "tnum", "cv11"',
+    h1ScaleClamp: "clamp(2.5rem, 7vw, 5.5rem)",   // big — album art adjacency
+    bodyBaseSize: "0.9375rem",             // 15px — denser than editorial, Spotify-row scale
+    bodyLineHeight: "1.55",
+  },
+
+  colors: {
+    background: { hsl: "0 0% 7%", from: "Spotify black canvas — #121212 in HSL, a touch warmer than pure black" },
+    foreground: { hsl: "0 0% 98%", from: "Spotify near-white text — high contrast on the black canvas" },
+    card: { hsl: "0 0% 11%", from: "elevated player surface — Spotify card chrome, one stop above canvas" },
+    popover: { hsl: "0 0% 14%", from: "menu and tooltip surface — two stops above canvas" },
+    primary: { hsl: "141 73% 48%", from: "Spotify signal green — the canonical play-button mark" },
+    primaryForeground: { hsl: "0 0% 7%", from: "canvas-black on Spotify green for legibility on the play button" },
+    secondary: { hsl: "0 0% 16%", from: "row-hover surface — Spotify track-list hover chrome" },
+    secondaryForeground: { hsl: "0 0% 98%", from: "near-white on hover chrome" },
+    muted: { hsl: "0 0% 18%", from: "muted surface for inactive controls and divider panels" },
+    mutedForeground: { hsl: "0 0% 64%", from: "Spotify secondary text — metadata gray, runtime and artist subhead" },
+    accent: { hsl: "0 0% 20%", from: "active row chrome — Spotify selected-track background" },
+    accentForeground: { hsl: "0 0% 98%", from: "near-white on active row" },
+    border: { hsl: "0 0% 22%", from: "hairline divider between track rows — barely-there separator" },
+    input: { hsl: "0 0% 16%", from: "search and filter input surface — Spotify search bar chrome" },
+    ring: { hsl: "141 73% 48%", from: "Spotify green focus ring — matches primary signal mark" },
+    destructive: { hsl: "0 72% 51%", from: "remove-from-playlist red, distinct from any orange waveform accent" },
+    destructiveForeground: { hsl: "0 0% 98%", from: "near-white on destructive red" },
+    brand: {
+      "signal-green": { hsl: "141 73% 48%", from: "Spotify play-button green — the canonical playback signal" },
+      "audiophile-blue": { hsl: "210 100% 56%", from: "Tidal Hi-Fi blue — used on quality badges and now-playing accents" },
+      "waveform-orange": { hsl: "18 100% 56%", from: "SoundCloud waveform orange — secondary accent for upload/share affordances" },
+      "vinyl-cream": { hsl: "36 22% 88%", from: "Bandcamp Daily editorial cream — used inside dark cards for long-form blocks" },
+      "canvas-black": { hsl: "0 0% 7%", from: "= background; the Spotify canvas itself, also a semantic token" },
+      "now-playing": { hsl: "141 73% 48%", from: "= signal-green; the active-track indicator color across the player" },
+    },
+  },
+
+  spacing: {
+    base: 4,
+    scale: [4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96, 128],   // medium-dense — track lists need to pack
+    containerMax: "max-w-7xl",         // wide — album-art grids and playlist tables breathe at this width
+    containerPadding: "px-4 lg:px-8",
+    sectionPadding: {
+      hero: "pt-16 pb-12 lg:pt-24 lg:pb-16",    // album-art hero is full-bleed; section padding stays modest
+      default: "py-12 lg:py-20",
+      tight: "py-8 lg:py-12",
+    },
+  },
+
+  radius: {
+    base: "0.5rem",                    // soft-square — Spotify card and Apple Music tile corner
+    pillsAllowed: true,                // tag chips and genre pills are common in playback UIs
+  },
+
+  shadows: {
+    style: "glow",
+    utilities: {
+      "art-lift":
+        "0 16px 40px hsl(0 0% 0% / 0.6), " +
+        "0 4px 12px hsl(0 0% 0% / 0.4)",   // album-art tile lift — soft black drop behind covers
+      "now-playing-glow":
+        "0 0 0 1px hsl(var(--signal-green) / 0.4), " +
+        "0 0 24px hsl(var(--signal-green) / 0.25)",   // green ring on the active playback card
+      "row-hover":
+        "inset 0 0 0 1px hsl(0 0% 100% / 0.06)",   // ghost inner-stroke on track-row hover
+    },
+  },
+
+  motion: {
+    easing: "cubic-bezier(0.22, 1, 0.36, 1)",
+    durations: {
+      reveal: 400,                    // cover fade-in, play-button morph — quick, app-feel
+      loop: 1600,                     // equalizer-bar pulse — Spotify "now playing" indicator
+      ambient: 24000,                 // slow album-art ken-burns behind hero
+    },
+    keyframes: {
+      "art-fade": {
+        css:
+          "from { opacity: 0; transform: scale(0.98); }\n" +
+          "to { opacity: 1; transform: scale(1); }",
+        defaultDuration: 400,
+        iteration: "once",
+        purpose: "album-art tile reveal as covers load — gentle scale-up, no flash",
+      },
+      "equalizer": {
+        css:
+          "0%, 100% { transform: scaleY(0.3); }\n" +
+          "50% { transform: scaleY(1); }",
+        defaultDuration: 1200,
+        iteration: "infinite",
+        purpose: "now-playing equalizer bars — the canonical 'this track is playing' indicator",
+      },
+      "play-pulse": {
+        css:
+          "0%, 100% { box-shadow: 0 0 0 0 hsl(var(--signal-green) / 0.45); }\n" +
+          "50% { box-shadow: 0 0 0 14px hsl(var(--signal-green) / 0); }",
+        defaultDuration: 1800,
+        iteration: "infinite",
+        purpose: "primary play-button heartbeat ring on hero CTA — single instance per page",
+      },
+      "art-drift": {
+        css:
+          "0% { transform: scale(1.1) translate(0, 0); }\n" +
+          "100% { transform: scale(1.2) translate(-1%, -1%); }",
+        defaultDuration: 24000,
+        iteration: "infinite",
+        purpose: "blurred album-art backdrop drift behind hero — ambient, never on cover tiles themselves",
+      },
+      "waveform-shimmer": {
+        css:
+          "0% { background-position: -200% 0; }\n" +
+          "100% { background-position: 200% 0; }",
+        defaultDuration: 2400,
+        iteration: "infinite",
+        purpose: "SoundCloud-style waveform fill animation — used on the active scrubber bar only",
+      },
+    },
+    respectsReducedMotion: true,
+  },
+
+  density: "medium",
+
+  patterns: {
+    button:
+      "Primary play action is a SOLID round signal-green circle with the canvas-black play glyph — the iconic Spotify mark. " +
+      "Secondary controls (shuffle, repeat, queue) are ghost icon buttons in mutedForeground that brighten to foreground on hover. " +
+      "Text-link CTAs use foreground color with underline-on-hover. Never use green for non-playback actions — that color is reserved.",
+    card:
+      "Album-art tile is the canonical card — a square cover image with title and artist text below, lifted by .art-lift shadow on hover. " +
+      "Playlist/section cards use bg-card (one stop above canvas), 0.5rem radius, p-4 lg:p-5. No fill differentiation between cards on the same surface tier — depth comes from shadow lift on hover.",
+    input:
+      "Search uses a pill-shape (rounded-full) bg-input field with a leading icon, no border. " +
+      "Focus state shows a 2px signal-green ring. Filter chips below the search are pills (bg-secondary, foreground text).",
+    cta:
+      "Hero CTA is a solid signal-green pill with canvas-black label, optionally wrapped in play-pulse. " +
+      "Inline 'Listen now' or 'Open in app' links are foreground-color underline-on-hover. App Store / Play Store badges for cross-platform CTAs.",
+  },
+
+  details: {
+    selectionBg: "hsl(var(--signal-green) / 0.35)",
+    selectionFg: "hsl(var(--foreground))",
+    focusRing: "2px solid hsl(var(--signal-green))",
+    scrollbarStyle: "thin",
+  },
+};

package/themes/music-vinyl/THEME.md

@@ -0,0 +1,98 @@
+# Design Direction — Music-Vinyl
+
+## Ethos
+Resident Advisor clean white · Pitchfork deep-editorial serif · Bandcamp deep-cyan community · 4AD label restraint · Aphex Twin archive typewriter
+
+## Feel
+Warm paper canvas, deep-cyan link color, serif display set tight for review headlines. Long-read column with mono captions for catalog numbers and runtimes. Reads like a record-shop zine — vinyl-collector reverence, dense knowledge, no autoplay anywhere. The page is the review, not the player.
+
+## Reference brands
+- **Resident Advisor** → clean white canvas with DM Sans and dense review layout. Event listings as ledger rows.
+- **Pitchfork** → deep editorial pace with Lora serif and restrained nav. The review is the product.
+- **Bandcamp** → deep cyan link color and Lato body. Community-warm, artist-first commerce.
+- **4AD label site** → deep cream paper with serif headlines and minimal chrome. Label as curator.
+- **Aphex Twin archive** → typewriter mono with dense, obscure cataloguing. Catalog number as art.
+
+## 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 **label-cream** (background, HSL `38 28% 94%` — 4AD vinyl-sleeve inner) → **white card** (`0 0% 100%`) → **deeper cream** (secondary/muted/accent). Depth comes from hairline borders and the cream-on-white contrast, never from drop shadows.
+
+Brand tokens: `--bandcamp-cyan` (primary, canonical link color), `--pitchfork-red` (Best New Music accolade only), `--label-cream`, `--vinyl-ink`, `--ra-blue` (Resident Advisor event chrome), `--archive-ochre` (catalog numerals). Primary is `--bandcamp-cyan` — used for all linkable affordances.
+
+## Typography
+- **Display:** Lora (Pitchfork review-headline serif). Contemporary book-serif, sits well at large sizes. Tracking `-0.02em` — fractional tightening at display scale.
+- **Body:** DM Sans (Resident Advisor body). Geometric humanist sans, comfortable for dense review rows. Body base **17px** with **line-height 1.65**.
+- **Mono:** JetBrains Mono. Catalog numbers, runtimes, BPM, pressing notes — the Aphex-Twin-archive typewriter feel.
+
+H1 uses `clamp(2.5rem, 6.5vw, 5.5rem)`. Numbers always use `font-variant-numeric: tabular-nums`. Font features: `"ss01"`, `"calt"`, `"tnum"`.
+
+## Spacing
+- **Container:** `max-w-3xl px-5 lg:px-10` — 768px reading column for long-form reviews. The review is for *reading*; wider columns break flow.
+- **Section padding tiers:**
+  - Hero: `pt-24 pb-16 lg:pt-36 lg:pb-24`
+  - Default: `py-16 lg:py-28`
+  - Tight: `py-10 lg:py-16`
+- **Allowed scale values:** 4 6 8 12 16 20 24 32 40 48 64 96 128. No arbitrary spacing.
+
+## Color
+No hex anywhere in component files. All color via tokens. Opacity via `/N` modifier on token, not via new tokens. Pure white is reserved for `--card` only — the cream canvas is the default page surface. Pure black is forbidden — `--vinyl-ink` (warm brown-black) replaces it.
+
+**Bandcamp cyan is the link color across the entire surface.** It is the only saturated color used at scale. Pitchfork-red is reserved for the "Best New Music" badge analog and review-score accolades — never as a CTA color. Archive-ochre is used on catalog numerals only, never on body text.
+
+## Radius
+`--radius: 0`. **Sharp corners only.** Pills are disallowed (`pillsAllowed: false`) — they read app-chrome, not zine. If a UI element needs softness, achieve it through whitespace and hairline borders, not corner rounding. This mirrors editorial — the print-zine convention.
+
+## Shadows
+**Minimal.** Two utilities:
+- `.hairline-bottom` (1px border-bottom in `--border`) — ledger line between paragraphs and review-meta blocks
+- `.review-rule` (inset top + bottom border, 1px each) — double-rule wrap for review-meta strips (byline, dateline, catalog meta)
+
+No drop shadows. No glows. No depth.
+
+## Motion
+Three keyframes, all slow on purpose:
+- `fade-rise` (1000ms once) — section entrance, no bounce, no flash, mirrors editorial
+- `ink-bleed` (1400ms once) — review-headline reveal; letters resolve like ink settling on paper, used on h1 only
+- `underline-grow` (400ms once) — Bandcamp-style link underline expansion on hover, left-anchored 1px line
+
+Easing: `cubic-bezier(0.22, 1, 0.36, 1)`. `prefers-reduced-motion` is honored — every motion utility wrapped in a media query. **No looping or ambient animation** — the page does not perform.
+
+## Component patterns
+- **Buttons:** primary action is a text link in `--bandcamp-cyan` with `underline-grow` on hover — the canonical Bandcamp affordance. Solid-fill is reserved for the single "Buy / Add to library" hero action per review — `--vinyl-ink` bg + `--label-cream` label, sharp corners, mono uppercase. Tertiary actions are mono uppercase labels with hairline-bottom underline.
+- **Cards:** review card uses `bg-card` (white) on cream page, hairline border on all four sides, sharp corners. Internal padding `p-6 lg:p-10`. Headline in Lora display serif, byline and catalog meta in mono. Album-art thumbnail sits as a square block at 1:1 aspect, no rounding, no shadow.
+- **Inputs:** border-bottom only (1px `--border`), bg transparent. Label sits above in mono uppercase, tracking 0.06em. Focus shifts the underline to 2px `--ring` (cyan). Placeholder italic mutedForeground.
+- **CTA links:** text-link with cyan color and underline-on-hover. Single hero "Buy on Bandcamp" / "Pre-order" button uses vinyl-ink fill + cream label, sharp corners, mono uppercase label. **Never gradient, never glow, never pill.**
+
+## Recommended rich media
+Music-vinyl leans on **square album covers** treated as printed objects on a zine page, and on **artist photography color-graded warm** like a record-store wall.
+
+Lead media is **square album cover at 1:1 aspect, minimum 600×600**, displayed as a sharp-cornered block with hairline border. The cover sits *on* the page like a record on a shelf, not embedded in chrome. Artist photography uses **3:2 landscape**, color-graded to a warm Portra-400 or Cinestill-800T palette — slight golden highlights, deep shadows, never crushed black. Live-show shots are appropriate; in-studio is appropriate; press-headshot-style is not.
+
+**AI tool recommendations:** **Midjourney** with prompts like *"medium-format film photograph, warm tungsten lighting, 35mm, Cinestill 800T grain"* for environmental artist shots; *"square album cover, [genre] aesthetic, hand-drawn typography, risograph print"* for placeholder catalog covers. Avoid Midjourney's default photorealistic shine — explicitly prompt for film grain. **Recraft** for the kind of stippled / line-art illustrations that sit in long-read reviews.
+
+**Aspect ratios:** 1:1 square for album covers and label catalog imagery (canonical). 3:2 landscape for artist photography. 4:5 portrait for vertical artist shots. Never 16:9 (cinematic, off-feel). Never 1:1 for non-album content (Instagram-aesthetic).
+
+**Video:** generally avoided. Vinyl-review readers are reading, not watching. If used, single hero with poster image and play button — never autoplay loop. Bandcamp-style audio embeds are appropriate: a thin player strip with album-art and play button, user-initiated only.
+
+**Catalog numerals:** treat as the second-most-important typographic element after headlines. Always mono, often in `--archive-ochre`, often given their own meta strip with `.review-rule` framing. Aphex Twin archive aesthetic — the catalog number IS the design.
+
+**Performance:** hero album cover ≤120 KB AVIF at 1200w; inline figures ≤80 KB. Long-read pages should LCP under 2s — if it slips, the hero is too large or the review needs a smaller cover-thumbnail variant.
+
+**Avoid:** glossy product-photography album shots with reflections, lifestyle stock (headphones on coffee table), 3D rendered vinyl mockups with motion blur, animated GIFs, gradient backgrounds, glassmorphic anything, AI photos with uncanny hands or instruments, decorative SVG ornament beyond Bandcamp/4AD-style hand marks.
+
+**Accessibility:** long-form alt-text on artist photography — describe environment and subject as if for a blind reader. Album covers use *"[Artist] — [Album], [Year]"* format. Catalog numbers in mono are decorative-meta, not pure decoration — read by screen readers as *"Catalog: XYZ-001"*.
+
+## Component families
+None at install time. Family conventions emerge as the project grows; the Director appends them here as they're established. Expected first families: `ReviewHeader`, `CatalogMeta`, `BuyStrip`, `EventRow`.
+
+## Details
+- **Selection:** `hsl(var(--bandcamp-cyan) / 0.22)` background, foreground text.
+- **Focus ring:** `2px solid hsl(var(--ring))` (cyan). Thin and quiet — matches link underline weight.
+- **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/music-vinyl/tokens.ts

@@ -0,0 +1,167 @@
+import type { Direction } from "../schema";
+
+export const musicVinyl: Direction = {
+  name: "music-vinyl",
+  ethos:
+    "Resident Advisor clean white · Pitchfork deep-editorial serif · Bandcamp deep-cyan community · 4AD label restraint · Aphex Twin archive typewriter",
+  references: [
+    { brand: "Resident Advisor", trait: "clean white canvas with DM Sans and dense review layout" },
+    { brand: "Pitchfork", trait: "deep editorial pace with Lora serif and restrained nav" },
+    { brand: "Bandcamp", trait: "deep cyan link color and Lato body, warm community feel" },
+    { brand: "4AD label site", trait: "deep cream paper with serif headlines and minimal chrome" },
+    { brand: "Aphex Twin archive", trait: "typewriter mono with dense, obscure cataloguing" },
+  ],
+  feel:
+    "Warm paper canvas, deep-cyan link color, serif display set tight for review headlines. " +
+    "Long-read column with mono captions for catalog numbers and runtimes. Reads like a record-shop " +
+    "zine — vinyl-collector reverence, dense knowledge, no autoplay anywhere.",
+
+  fonts: {
+    display: {
+      family: "Lora",
+      fallback: ["Iowan Old Style", "Apple Garamond", "Garamond", "Georgia", "serif"],
+      from: "Pitchfork review-headline serif — contemporary book-serif weight, sits well at large sizes",
+      googleFont: "Lora",
+      weights: [400, 500, 600, 700],
+    },
+    body: {
+      family: "DM Sans",
+      fallback: ["Lato", "Inter", "system-ui", "-apple-system", "sans-serif"],
+      from: "Resident Advisor body — geometric humanist sans, dense review-row-friendly",
+      googleFont: "DM+Sans",
+      weights: [400, 500, 700],
+    },
+    mono: {
+      family: "JetBrains Mono",
+      fallback: ["Courier Prime", "Berkeley Mono", "ui-monospace", "Consolas", "monospace"],
+      from: "Aphex Twin archive typewriter — catalog numbers, runtimes, BPM, pressing notes",
+      googleFont: "JetBrains+Mono",
+      weights: [400, 500],
+    },
+  },
+
+  typography: {
+    headingTracking: "-0.02em",          // Lora at display scale wants a fractional tightening
+    bodyTracking: "0",
+    fontFeatureSettings: '"ss01", "calt", "tnum"',
+    h1ScaleClamp: "clamp(2.5rem, 6.5vw, 5.5rem)",   // review headline scale — Pitchfork lead
+    bodyBaseSize: "1.0625rem",            // 17px — review prose comfort
+    bodyLineHeight: "1.65",
+  },
+
+  colors: {
+    background: { hsl: "38 28% 94%", from: "deep warm cream — 4AD label-site paper stock, vinyl-sleeve inner" },
+    foreground: { hsl: "30 15% 14%", from: "deep brown-ink — never pure black, sits warm against cream" },
+    card: { hsl: "0 0% 100%", from: "review card — pure white on cream, the way a printed review sits on a zine page" },
+    popover: { hsl: "0 0% 100%", from: "same as card; menus use the white plate, hairline border for depth" },
+    primary: { hsl: "192 80% 36%", from: "Bandcamp deep cyan — canonical link color across the community" },
+    primaryForeground: { hsl: "38 28% 94%", from: "cream paper on Bandcamp cyan" },
+    secondary: { hsl: "38 20% 88%", from: "deeper cream, sidebar panels and review meta-blocks" },
+    secondaryForeground: { hsl: "30 15% 14%", from: "brown-ink on deeper cream" },
+    muted: { hsl: "38 18% 90%", from: "muted cream — quote-block and pull-quote backgrounds" },
+    mutedForeground: { hsl: "30 12% 38%", from: "secondary review prose — byline, dateline, catalog meta" },
+    accent: { hsl: "38 22% 86%", from: "hover state for review-row chrome, fractional darken of cream" },
+    accentForeground: { hsl: "30 15% 14%", from: "brown-ink on hover cream" },
+    border: { hsl: "30 12% 78%", from: "Pitchfork hairline rule — column divider, between-section ledger line" },
+    input: { hsl: "30 12% 78%", from: "same as border — inputs share the hairline language" },
+    ring: { hsl: "192 80% 36%", from: "Bandcamp cyan focus ring — matches the link color" },
+    destructive: { hsl: "356 65% 42%", from: "review-pan red — used sparingly for low-score badges and remove actions" },
+    destructiveForeground: { hsl: "38 28% 94%", from: "cream on pan red" },
+    brand: {
+      "bandcamp-cyan": { hsl: "192 80% 36%", from: "= primary; the Bandcamp link color, the canonical signal mark" },
+      "pitchfork-red": { hsl: "0 70% 48%", from: "Pitchfork 'Best New Music' badge red — review-score accolade color" },
+      "label-cream": { hsl: "38 28% 94%", from: "= background; 4AD/indie-label paper stock, also a semantic token" },
+      "vinyl-ink": { hsl: "30 15% 14%", from: "= foreground; brown-black, also semantic for spine type and serial numbers" },
+      "ra-blue": { hsl: "215 75% 32%", from: "Resident Advisor deep navy — used on event-listing chrome and tertiary accents" },
+      "archive-ochre": { hsl: "36 70% 42%", from: "Aphex Twin archive ochre — catalog highlight, used on numerals only" },
+    },
+  },
+
+  spacing: {
+    base: 4,
+    scale: [4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64, 96, 128],   // editorial-leaning but allows denser review rows
+    containerMax: "max-w-3xl",         // 768px reading column for long-form reviews
+    containerPadding: "px-5 lg:px-10",
+    sectionPadding: {
+      hero: "pt-24 pb-16 lg:pt-36 lg:pb-24",
+      default: "py-16 lg:py-28",
+      tight: "py-10 lg:py-16",
+    },
+  },
+
+  radius: {
+    base: "0",                          // sharp corners — print zine convention, mirrors editorial
+    pillsAllowed: false,                // no pills; tags use sharp rect chips or underlined text
+  },
+
+  shadows: {
+    style: "minimal",
+    utilities: {
+      "hairline-bottom":
+        "0 1px 0 0 hsl(var(--border))",   // ledger line — Pitchfork between-paragraph divider
+      "review-rule":
+        "inset 0 -1px 0 0 hsl(var(--border)), inset 0 1px 0 0 hsl(var(--border))",   // double-rule for review-meta strips
+    },
+  },
+
+  motion: {
+    easing: "cubic-bezier(0.22, 1, 0.36, 1)",
+    durations: {
+      reveal: 1000,                    // slow on purpose — pages settle like a printed page being unfolded
+      loop: 4000,
+      ambient: 30000,
+    },
+    keyframes: {
+      "fade-rise": {
+        css:
+          "from { opacity: 0; transform: translateY(20px); }\n" +
+          "to { opacity: 1; transform: translateY(0); }",
+        defaultDuration: 1000,
+        iteration: "once",
+        purpose: "section entrance — slow, no bounce, no flash, mirrors editorial",
+      },
+      "ink-bleed": {
+        css:
+          "from { opacity: 0; filter: blur(2px); }\n" +
+          "to { opacity: 1; filter: blur(0); }",
+        defaultDuration: 1400,
+        iteration: "once",
+        purpose: "review-headline reveal — letters resolve like ink settling on paper, used on h1 only",
+      },
+      "underline-grow": {
+        css:
+          "from { background-size: 0 1px; }\n" +
+          "to { background-size: 100% 1px; }",
+        defaultDuration: 400,
+        iteration: "once",
+        purpose: "Bandcamp-style link underline expansion on hover — left-anchored 1px line",
+      },
+    },
+    respectsReducedMotion: true,
+  },
+
+  density: "medium",
+
+  patterns: {
+    button:
+      "Primary action is a text link in --bandcamp-cyan with an underline-grow on hover — the canonical Bandcamp affordance. " +
+      "Solid-fill is reserved for the single 'Buy / Add to library' hero action per review — vinyl-ink bg + cream label. " +
+      "Tertiary actions are mono uppercase labels with a hairline-bottom underline. Never a colored pill or rounded fill.",
+    card:
+      "Review card uses bg-card (white) on cream page, hairline border on all four sides, sharp corners. " +
+      "Internal padding p-6 lg:p-10. Headline in Lora display serif, byline and catalog meta in mono. " +
+      "Album-art thumbnail sits as a square block at 1:1 aspect, no rounding, no shadow.",
+    input:
+      "Border-bottom only (1px --border), bg transparent. Label sits above in mono uppercase, tracking 0.06em. " +
+      "Focus shifts the underline to 2px --ring (cyan). Placeholder is italic mutedForeground.",
+    cta:
+      "Text-link with cyan color and underline-on-hover. Single hero 'Buy on Bandcamp' / 'Pre-order' button uses vinyl-ink fill + cream label, sharp corners, mono uppercase label. Never gradient, never glow.",
+  },
+
+  details: {
+    selectionBg: "hsl(var(--bandcamp-cyan) / 0.22)",
+    selectionFg: "hsl(var(--foreground))",
+    focusRing: "2px solid hsl(var(--ring))",
+    scrollbarStyle: "thin",
+  },
+};