@stylecrib/cli 0.0.0-stage → 0.3.2

package/themes/community-niche/THEME.md

@@ -0,0 +1,102 @@
+# Design Direction — Community-Niche
+
+## Ethos
+Patreon coral-tier warmth · Discord-server soft purple + role tags · Buy Me a Coffee yellow CTA · Memberful clean tier-display · Geneva community-room friendliness
+
+## Feel
+A creator's home, not a SaaS landing. Soft purple-pink wash with a coral primary that owns every membership CTA. Tier-cards, member spotlights, and a recent-posts feed are the basic units of the page. Warm rounded surfaces, tinted badges per role/tier, and friendly illustrated avatars where corporate headshots would feel too cold.
+
+Where `linkedin-pro` is corporate-blue density and `dating-friendly` is intimate-warm prompt-cards, community-niche is **creator-warm** — purple-pink-coral over lavender, a tip-jar yellow accent, and tiers as the dominant content shape. The page should feel like walking into a small, curated room, not browsing a marketplace.
+
+## Reference brands
+- **Patreon** → coral primary + tier-tinted cards + creator-photo hero. The membership-economy canonical.
+- **Discord (server pages)** → soft purple bg + role-color name tags + community-room shape. The "members in this server" surface.
+- **Buy Me a Coffee** → yellow tip CTA + warm playful chrome. The one-time-support color.
+- **Memberful** → clean tier-display + readable subscription chrome. The well-organized version.
+- **Geneva** → soft pastel rooms + friendly small-group warmth. The "this is a vibe, not a product" energy.
+
+## Tokens
+HSL triples in `src/index.css`. Every token's `from:` comment names its brand origin.
+
+Surface stack: **lavender wash** (`278 40% 97%`, the home surface) → **white card** (`0 0% 100%`) → **deeper lavender tint** (`278 40% 93%`, hover/secondary). Warmth runs through every neutral; pure gray reads enterprise and breaks the creator-home feel.
+
+Primary is **Patreon coral-pink** (`340 80% 55%`) — the membership-join CTA, the tip-jar, the tier-card top-stripe. It carries the entire economic action of the page.
+
+Brand tokens — language, not decoration:
+- `--patreon-coral` (= primary) — membership CTA.
+- `--discord-purple` — secondary identity, server-tag / role-tag color.
+- `--bmc-yellow` — Buy Me a Coffee yellow; the **one-time-tip** action, distinct from recurring membership.
+- `--tier-bronze` / `--tier-silver` / `--tier-gold` — the canonical tier-badge palette. Used as a small accent stripe at the top of a TIER-CARD, never as a card fill.
+- `--geneva-mint` — Geneva pastel mint, for room/group accent badges. Stays small.
+- `--aubergine` (= foreground) — warm-bias deep ink. Pure black forbidden.
+
+## Typography
+- **Display:** Sora — Patreon's geometric-display spirit, friendly modern sans, weights 600/700/800. h1–h4.
+- **Body:** Inter — neutral, dense-friendly at 16px, line-height 1.6 (looser than linkedin-pro because posts are read here, not scanned).
+- **Mono:** JetBrains Mono — member counts, tier-price, post-meta. Small tabular only.
+
+H1 uses `clamp(2.25rem, 5.5vw, 4rem)`. Heading tracking `-0.02em`.
+
+## Spacing
+- **Container:** `max-w-5xl px-5 lg:px-8` — narrower than enterprise; creator pages read better in a smaller column.
+- **Section padding tiers:**
+  - Hero: `pt-20 pb-12 lg:pt-28 lg:pb-20`
+  - Default: `py-16 lg:py-24`
+  - Tight: `py-10 lg:py-14`
+- **Allowed scale values:** 4 6 8 12 16 20 24 32 40 48 64 80.
+
+## Color
+No hex in components. All color via tokens. Opacity via `/N`.
+
+The palette is **lavender-and-coral with a tip-jar yellow**. Resist adding any cool blue or teal — those break the creator-warm envelope. Discord-purple is the only purple accent and stays small (role tags, server pills). The tier-tints (`--tier-bronze` / `--tier-silver` / `--tier-gold`) appear only as small top-stripes on tier-cards, never as full surfaces.
+
+## Radius
+`--radius: 1rem` (16px). Patreon/Memberful card softness. Pills allowed (`pillsAllowed: true`) for tier-badges, role tags, member-count chips. Sharp corners are forbidden — they read enterprise and kill the creator-home warmth.
+
+## Shadows
+Three warm-tinted utilities — drops carry coral, never neutral gray:
+- `.shadow-card-soft` — resting tier/post-card elevation.
+- `.shadow-card-hover` — hover state.
+- `.shadow-tier-glow` — the **recommended tier** state. A 2px coral ring + 32px coral halo. Used on the one tier the creator wants you to pick.
+
+## Motion
+Three keyframes:
+- `fade-rise` (500ms) — post-feed / tier-card entrance. Warm rise.
+- `tip-pulse` (3000ms loop) — gentle scale-breath on the tip-jar / one-time-support CTA. A nudge that doesn't shout.
+- `join-shimmer` (2400ms loop) — coral shimmer sweep across the **featured/recommended tier**. Premium hint without being a marquee.
+
+`prefers-reduced-motion` honored — `tip-pulse` collapses to a static scale, `join-shimmer` to a static coral fill.
+
+## Component patterns
+- **Buttons:** primary = filled coral pill (weight 700, rounded-full) — the Join / Become a member CTA. Alt = Buy-Me-a-Coffee yellow pill for one-time tips. Secondary = bordered pill in foreground. Discord-purple pill = role-tag display only, never a CTA.
+- **Cards:** two shapes —
+  - **TIER-CARD**: rounded-2xl, tier-tinted top-stripe (3–4px in the relevant `--tier-*` color) + white body + benefit-list (checkmarks) + inline Join pill at the bottom. The recommended tier wears `.shadow-tier-glow` and has the `join-shimmer` sweep on its top-stripe.
+  - **POST-CARD**: rounded-xl, creator avatar + title + body excerpt + small `🔒` lock-icon if the post is tier-gated.
+- **Inputs:** full rounded-2xl box. Focus = 2px coral ring at 40% opacity. **Pledge-amount input** is the special one: $ prefix + giant tabular number + tier-suggestion chips below.
+- **CTAs:** coral pill = membership action. Yellow pill = tip action. Tier-cards have an INLINE Join pill at their bottom — never a separate Buy button outside the card.
+
+## Component families
+- `*TierCard` — tinted top-stripe + benefit-list + inline Join pill. The Patreon-style tier display.
+- `*PostFeedItem` — creator avatar + title + excerpt + paywall lock + posted-time.
+- `*MemberSpotlight` — avatar + name + role-tag + member-since date + small quote.
+- `*RolePill` — Discord-purple pill with a small color-dot prefix; one per server role.
+
+## Recommended rich media
+Creator-led, friendly, slightly illustrated. Headshot photography works but illustrated avatars work better — they make the page feel less like a transaction. Patreon's own creator-pages lean on illustrated portraits because they hold up across tier tiers without going corporate.
+
+**AI tools:** Midjourney *"warm illustrated portrait, coral and lavender palette, friendly creator avatar, soft brushwork, illustrated not photoreal"*. For photographic content (post thumbnails), prompt for warm natural light, behind-the-scenes / workspace shots, never glossy studio.
+
+**Aspect ratios:** 1:1 for creator avatars, 4:3 for post thumbnails, 16:9 only for video previews.
+
+**AVOID:** corporate stock photography, glassmorphic surfaces, dark moody photography, marketplace-grid layouts (this is a creator's home, not a store), pricing-card rows (tier-cards are *inline* and contextual, not a comparison grid), generic feature-tile sections.
+
+## Details
+- **Selection:** `hsl(var(--primary) / 0.22)` background, foreground text.
+- **Focus ring:** `2px solid hsl(var(--ring) / 0.5)` — coral, warm-visible.
+- **Scrollbar:** thin.
+
+## Exceptions
+None yet.
+
+## Revisions
+- Initial direction, generated at install time.

package/themes/community-niche/tokens.ts

@@ -0,0 +1,177 @@
+import type { Direction } from "../schema";
+
+// community-niche — Patreon / Discord-server / Substack-Notes creator warmth.
+// Soft purple-pink palette, member-tier driven, post-feed forward.
+// Decoration-first language: rounded cards, tinted badges, warm illustration
+// territory. Reads as a creator's home, not a SaaS product page.
+export const communityNiche: Direction = {
+  name: "community-niche",
+  ethos:
+    "Patreon coral-tier warmth · Discord-server soft purple + role tags · Buy Me a Coffee yellow CTA · Memberful clean tier-display · Geneva community-room friendliness",
+  references: [
+    { brand: "Patreon", trait: "coral primary + tier-tinted cards + creator-photo hero" },
+    { brand: "Discord", trait: "soft purple bg + role-color name tags + community-room shape" },
+    { brand: "Buy Me a Coffee", trait: "yellow tip CTA + warm playful chrome" },
+    { brand: "Memberful", trait: "clean tier-display + readable subscription chrome" },
+    { brand: "Geneva", trait: "soft pastel rooms + friendly small-group warmth" },
+  ],
+  feel:
+    "A creator's home, not a SaaS landing. Soft purple-pink wash with a coral primary that owns the membership CTAs. " +
+    "Tier-cards, member spotlights, and a recent-posts feed are the basic units. " +
+    "Warm rounded surfaces, tinted badges per role/tier, and friendly illustrated avatars where headshots would feel too corporate.",
+
+  fonts: {
+    display: {
+      family: "Sora",
+      fallback: ["Manrope", "Inter", "system-ui", "sans-serif"],
+      from: "Patreon's geometric-display feel — friendly modern sans, weights 600/700",
+      googleFont: "Sora",
+      weights: [400, 600, 700, 800],
+    },
+    body: {
+      family: "Inter",
+      fallback: ["system-ui", "-apple-system", "BlinkMacSystemFont", "sans-serif"],
+      from: "Memberful / Substack body — neutral, dense-friendly at 16px",
+      googleFont: "Inter",
+      weights: [400, 500, 600],
+    },
+    mono: {
+      family: "JetBrains Mono",
+      fallback: ["ui-monospace", "SFMono-Regular", "monospace"],
+      from: "member counts, tier-price, post-meta — small tabular",
+      googleFont: "JetBrains+Mono",
+      weights: [400, 500],
+    },
+  },
+
+  typography: {
+    headingTracking: "-0.02em",
+    bodyTracking: "0",
+    fontFeatureSettings: '"ss01", "cv11"',
+    h1ScaleClamp: "clamp(2.25rem, 5.5vw, 4rem)",
+    bodyBaseSize: "1rem",
+    bodyLineHeight: "1.6",
+  },
+
+  colors: {
+    background: { hsl: "278 40% 97%", from: "soft lavender wash — Discord's pale-purple home surface" },
+    foreground: { hsl: "278 30% 14%", from: "deep aubergine ink — warm-bias near-black with purple lean" },
+    card: { hsl: "0 0% 100%", from: "white member/post card — lifts off the lavender wash" },
+    popover: { hsl: "0 0% 100%", from: "same as card" },
+    primary: { hsl: "340 80% 55%", from: "Patreon coral-pink — the membership CTA, the tip-jar color" },
+    primaryForeground: { hsl: "0 0% 100%", from: "white on coral-pink" },
+    secondary: { hsl: "278 40% 93%", from: "deeper lavender tint — secondary surface, hover" },
+    secondaryForeground: { hsl: "278 30% 18%", from: "aubergine on lavender" },
+    muted: { hsl: "278 30% 92%", from: "quiet lavender-cream — meta panels, post-body backing" },
+    mutedForeground: { hsl: "278 14% 42%", from: "warm gray with purple bias — captions, post-meta" },
+    accent: { hsl: "270 80% 92%", from: "Discord-purple tinted bg — role chip, mention pill" },
+    accentForeground: { hsl: "270 70% 38%", from: "deeper Discord purple on tinted accent" },
+    border: { hsl: "278 20% 88%", from: "soft lavender hairline — visible but warm" },
+    input: { hsl: "278 20% 88%", from: "same as border" },
+    ring: { hsl: "340 80% 55%", from: "primary, focus only" },
+    destructive: { hsl: "0 70% 52%", from: "warm red — unsubscribe, remove member" },
+    destructiveForeground: { hsl: "0 0% 100%", from: "white on alert" },
+    brand: {
+      "patreon-coral": { hsl: "340 80% 55%", from: "= primary; Patreon membership color, the join-tier action" },
+      "discord-purple": { hsl: "262 60% 55%", from: "Discord blurple — secondary identity, server-tag color" },
+      "bmc-yellow": { hsl: "44 96% 58%", from: "Buy Me a Coffee yellow — tip/one-time-support CTA" },
+      "tier-bronze": { hsl: "28 60% 50%", from: "lowest tier tint — bronze member badge" },
+      "tier-silver": { hsl: "210 14% 60%", from: "mid-tier silver" },
+      "tier-gold": { hsl: "44 80% 50%", from: "top-tier gold — VIP badge" },
+      "geneva-mint": { hsl: "168 50% 70%", from: "Geneva pastel mint — room/group accent" },
+      lavender: { hsl: "278 40% 97%", from: "= background; the home surface" },
+      aubergine: { hsl: "278 30% 14%", from: "= foreground; warm-bias deep ink" },
+    },
+  },
+
+  spacing: {
+    base: 4,
+    scale: [4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80],
+    containerMax: "max-w-5xl",
+    containerPadding: "px-5 lg:px-8",
+    sectionPadding: {
+      hero: "pt-20 pb-12 lg:pt-28 lg:pb-20",
+      default: "py-16 lg:py-24",
+      tight: "py-10 lg:py-14",
+    },
+  },
+
+  radius: {
+    base: "1rem",                    // 16px — Patreon/Memberful card softness
+    pillsAllowed: true,              // tier-badges, role tags, member-count chips
+  },
+
+  shadows: {
+    style: "soft",
+    utilities: {
+      "shadow-card-soft":
+        "0 1px 2px hsl(278 30% 30% / 0.04), 0 8px 24px hsl(340 60% 50% / 0.06)",
+      "shadow-card-hover":
+        "0 2px 4px hsl(278 30% 30% / 0.06), 0 16px 36px hsl(340 70% 55% / 0.12)",
+      "shadow-tier-glow":
+        "0 0 0 2px hsl(340 80% 55% / 0.2), 0 12px 32px hsl(340 80% 55% / 0.22)",
+    },
+  },
+
+  motion: {
+    easing: "cubic-bezier(0.22, 1, 0.36, 1)",
+    durations: {
+      reveal: 500,
+      loop: 3000,
+      ambient: 18000,
+    },
+    keyframes: {
+      "fade-rise": {
+        css:
+          "from { opacity: 0; transform: translateY(12px); }\n" +
+          "to { opacity: 1; transform: translateY(0); }",
+        defaultDuration: 500,
+        iteration: "once",
+        purpose: "post-feed / tier-card entrance — warm rise",
+      },
+      "tip-pulse": {
+        css:
+          "0%, 100% { transform: scale(1); }\n" +
+          "50% { transform: scale(1.04); }",
+        defaultDuration: 3000,
+        iteration: "infinite",
+        purpose: "tip-jar / one-time-support CTA — gentle ongoing nudge",
+      },
+      "join-shimmer": {
+        css:
+          "0% { background-position: 200% 0; }\n" +
+          "100% { background-position: -200% 0; }",
+        defaultDuration: 2400,
+        iteration: "infinite",
+        purpose: "featured-tier card — coral shimmer sweep on the recommended tier",
+      },
+    },
+    respectsReducedMotion: true,
+  },
+
+  density: "medium",
+
+  patterns: {
+    button:
+      "Primary = filled coral pill (weight 700, rounded-full). The 'Join' / 'Become a member' CTA. " +
+      "Alt CTA = Buy-Me-a-Coffee yellow pill for one-time tips. " +
+      "Secondary = bordered pill in foreground color. Discord-purple pill = role-tag display only.",
+    card:
+      "Two patterns: TIER-CARD (rounded-2xl, tier-tinted top-stripe + white body + benefit-list + Join pill) and " +
+      "POST-CARD (rounded-xl, creator avatar + title + body excerpt + lock-icon if paywalled). " +
+      "Both wear shadow-card-soft. Featured tier wears shadow-tier-glow.",
+    input:
+      "Full rounded-2xl box, border, bg-card. Focus = 2px coral ring at 40% opacity. " +
+      "Pledge-amount input is the special one: prefix $ + giant tabular number + tier-suggestion chips below.",
+    cta:
+      "Coral pill is the membership action. Yellow pill is the tip action. " +
+      "Tier-display cards have an inline Join pill, never a separate Buy button.",
+  },
+
+  details: {
+    selectionBg: "hsl(var(--primary) / 0.22)",
+    selectionFg: "hsl(var(--foreground))",
+    focusRing: "2px solid hsl(var(--ring) / 0.5)",
+    scrollbarStyle: "thin",
+  },
+};

package/themes/corporate-grid/THEME.md

@@ -0,0 +1,154 @@
+# Design Direction — Corporate-Grid
+
+## Ethos
+IBM Carbon discipline · Plex Sans everywhere · IBM blue signal · documentation-grade information density · 2x grid system
+
+## Feel
+Corporate seriousness in white. Plex Sans + Plex Mono everywhere — display through caption. Sharp corners, no rounding. IBM blue is the SINGLE signal color, used sparingly on primary actions and link text. Reads as 100-year-old technology company; trustworthy, documentation-grade, never trendy.
+
+## Reference brands
+- **IBM Carbon Design System** → the 2x grid, sharp corners, Plex Sans as canonical face. The structural law.
+- **IBM Plex** → the typeface family, prominently used. Display, body, and mono are all Plex — they were designed as a system.
+- **IBM marketing site (ibm.com)** → clean white surface with blue signal restraint. The proof that documentation density and corporate gravity coexist.
+- **Watson + IBM Cloud** → dense documentation product surfaces. The interior register.
+- **IBM Bluemix-era console** → data-grid heavy, instrument-cluster aesthetic. The historical reference.
+
+This direction ships the LIGHT variant. Carbon also ships a parallel dark theme (`gray-100` background, `gray-10` foreground, same IBM blue) — when a dark variant is needed, mirror the gray scale around the same blue signal.
+
+## Tokens
+HSL triples in `src/index.css`. Surface stack is pure white (`--background: 0 0% 100%`) through Carbon's structural gray scale — `gray-10` (`0 0% 96%`, card / muted), `gray-20` (`0 0% 91%`, border / hover), `gray-70` (`0 0% 32%`, secondary text), `gray-100` (`0 0% 9%`, foreground). Depth comes from **hairline borders**, not shadows.
+
+Brand tokens carry explicit Carbon naming: `--ibm-blue` (alias for primary, Carbon interactive-01), `--gray-10`, `--gray-20`, `--gray-70`, `--gray-100`, `--red-60` (Carbon support-error / destructive), `--green-50` (Carbon support-success), `--yellow-30` (Carbon support-warning), `--cyan-40` (Carbon info accent). The single-color rule: IBM blue is the *only* interactive signal. Red is destructive. Green is affirmative status. Yellow is caution. Cyan is info. Nothing is decorative.
+
+## Typography
+- **Display:** IBM Plex Sans, weights 600/700. Headings are heavier body weight — this is a documentation language. H1 uses `clamp(1.75rem, 3.5vw, 2.75rem)`; the doc body is the work, the headline supports it.
+- **Body:** IBM Plex Sans, 14px (`0.875rem`), line-height 1.5, tracking `0`. Weights 400/500.
+- **Mono:** IBM Plex Mono, weights 400/500/600. **Prominent** — API examples, error codes, CLI snippets, request/response bodies, model IDs, version pins, token names. Pair Plex Sans and Plex Mono together; they were designed as a system.
+
+Font features: `"tnum", "zero", "ss01"` — tabular figures + slashed zero for tables and metrics, IBM stylistic set 01.
+
+Google Fonts (already loaded site-wide; reference in tokens): `IBM+Plex+Sans:wght@400;500;600;700` and `IBM+Plex+Mono:wght@400;500;600`.
+
+## Spacing
+- **Container:** `max-w-screen-2xl px-4 lg:px-8` — wide; documentation and console surfaces claim the screen.
+- **Section padding tiers:**
+  - Hero: `pt-16 pb-12 lg:pt-24 lg:pb-16`
+  - Default: `py-12 lg:py-16`
+  - Tight: `py-8 lg:py-10`
+- **Allowed scale:** **2** 4 8 12 16 20 24 32 40 48 64 80 96. Carbon's 2x grid is the structural law — every dimension is a multiple of 8px where possible, with 4px and 2px steps reserved for chrome details and icon-to-label gaps. The base unit is 4px; the rhythm is 8px.
+
+High density. The reference is the IBM Cloud console and Carbon documentation, not a marketing site.
+
+## Color
+No hex anywhere. The background is pure white (`0 0% 100%`) — Carbon canonical. The foreground is `0 0% 9%` (Carbon gray-100, near-black) — not pure black, deliberately. The gray scale is the structural backbone: `gray-10` for layered surfaces, `gray-20` for borders and hover, `gray-70` for secondary text.
+
+Semantic discipline:
+- **IBM blue** (`220 100% 53%`, #0F62FE) — primary, interactive, links, focus ring. The single Carbon signal.
+- **Red-60** (`352 84% 51%`) — destructive and error only. Never decorative.
+- **Green-50** (`140 70% 38%`) — affirmative status only.
+- **Yellow-30** (`44 100% 56%`) — caution and warning states only.
+- **Cyan-40** (`200 100% 50%`) — info chips and meta accents.
+- **Gray-70** (`0 0% 32%`) — captions, doc meta, dim foreground.
+
+## Radius
+`--radius: 0` — **Carbon is explicitly sharp.** No rounding on cards, buttons, inputs, modals, or panels. `pillsAllowed: false` — even status tags are sharp rectangles in canonical Carbon. (Pill-shaped tags are a permitted single exception when a status badge must distinguish itself from data-grid chrome, but defer to the rectangle by default.)
+
+The sharpness is doctrinal. It signals seriousness, engineering precision, and the absence of consumer-product affordances.
+
+## Shadows
+Style is **"minimal"**. Carbon uses layered border accents over shadows. Two utilities:
+- `.shadow-elevation-1` — `inset 0 0 0 1px hsl(var(--border)), 0 1px 2px hsl(0 0% 0% / 0.08)`. Cards, panels, table containers. Border-as-shadow with a one-pixel drop for layered surfaces.
+- `.shadow-elevation-2` — `inset 0 0 0 1px hsl(var(--border)), 0 2px 6px hsl(0 0% 0% / 0.12)`. Modals, popovers, side panels. The next tier — still restrained.
+
+No marketing-style elevation. No drop-shadow stacks. Depth comes from borders.
+
+## Motion
+- **Easing tokens (Carbon-defined):**
+  - `standard`: `cubic-bezier(0.2, 0, 0.38, 0.9)` — the default for in-place transitions.
+  - `entrance`: `cubic-bezier(0, 0, 0.38, 0.9)` — for elements entering the viewport.
+  - `exit`: `cubic-bezier(0.2, 0, 1, 0.9)` — for elements leaving.
+- **Duration tiers (Carbon-defined):**
+  - `fast` (110ms) — popovers, tooltips, micro-interactions, hover state changes.
+  - `moderate` (240ms) — accordion panels, side-nav expansion, documentation reveals.
+  - `slow` (400ms) — page transitions, modal entrance, large surface changes.
+- **Keyframes:**
+  - `fade-in` (110ms, fast) — opacity-only reveal for popovers, tooltips, micro-interactions.
+  - `expand-panel` (240ms, moderate) — accordion expansion for documentation panels and collapsed sections.
+  - `slide-in` (400ms, slow) — page transitions, modal entrance.
+
+**Deliberate.** No bounce, no spring, no parallax, no ambient drift. Carbon motion is engineering motion. `prefers-reduced-motion` honored throughout.
+
+## Component patterns
+- **Buttons:** primary = solid IBM blue, white text, sharp rectangle (no border-radius), 16px padding-x, weight 600 (`bg-primary text-primary-foreground rounded-none font-semibold px-4`). Secondary = ghost with 1px IBM-blue border, IBM-blue text. Tertiary = IBM-blue text-link with underline-on-hover. Sizes: small (`h-8 px-3 text-sm`) and default (`h-10 px-4 text-sm`). Carbon button heights canonically are 32/40/48px.
+- **Cards:** sharp 0px corners (`rounded-none`), 1px gray-20 border, `bg-card`. Padding 16px or 24px. Header row inside the card uses a bottom border. Tables and code samples embed inline. No drop shadows beyond `.shadow-elevation-1`.
+- **Inputs:** compact (`h-10 text-sm`), 1px gray-20 border, `bg-background`, `rounded-none`. Underline-only variant also valid (border-bottom only, `bg-gray-10`). Focus uses 2px IBM-blue ring. Label above; helper below in gray-70. Inline validation in red-60.
+- **CTAs:** primary = IBM-blue button. Secondary = ghost IBM-blue border. Tertiary = IBM-blue text-link with underline-on-hover. One primary CTA per surface. Marketing-style double-CTAs are forbidden — this is corporate documentation, not conversion theater.
+
+## Brand-book customization
+Carbon is the structural chassis. When an enterprise brings its own brand book on top of Carbon, only a thin brand layer is overridden — the gray scale, grid, motion, and density stay constant.
+
+**Tokens an enterprise typically overrides:**
+- `--primary` — the corporate signal color (their blue, red, orange, purple, whatever the brand book calls for).
+- `display` font family — when the corporate face is mandated (e.g. a custom face delivered by the brand team). Body and mono usually stay Plex Sans / Plex Mono because the documentation rhythm depends on them.
+- `--radius` — some IBM business units (and many non-IBM enterprises) use rounded corners; raising `--radius` to `0.25rem` or `0.5rem` is the cleanest brand-aware deviation.
+
+**Tokens that must NOT be overridden:**
+- The gray scale (`--gray-10` through `--gray-100`). It is structural to Carbon's contrast and density math. Overriding it breaks readability targets.
+- The 2x grid (spacing scale, container widths, section padding tiers).
+- The motion tokens (fast / moderate / slow with Carbon's easing curves).
+- The density scale.
+- The focus ring contract (2px solid, brand primary).
+
+**Mapping a brand-book hex to `--primary` in `index.css`:**
+1. Convert the brand-book hex to HSL (any color picker; macOS Digital Color Meter, Chrome DevTools, or `chroma-js`).
+2. Write the triple as `<H> <S>% <L>%` (no `hsl()` wrapper — the opacity-modifier syntax requires raw triples).
+3. Replace `--primary` and `--ring` (they share the brand signal) and `--ibm-blue` if the brand alias should also shift.
+4. Adjust `--primary-foreground` to maintain WCAG AA contrast against the new primary (white on most saturated hues; gray-100 on very light hues).
+
+**Example:** Cloudflare orange (`#F38020`) → `--primary: 24 90% 54%`. Everything else (Plex Sans, sharp corners, gray scale, layout grid, motion tokens, density) stays Carbon.
+
+**Carbon utilities that stay constant** under any brand overlay:
+- 2x grid spacing scale and section padding tiers.
+- Motion duration tokens (fast 110ms / moderate 240ms / slow 400ms) and Carbon easings (`standard`, `entrance`, `exit`).
+- Density scale (button heights 32/40/48, input height 40, body 14px / line-height 1.5).
+- Focus ring contract (2px solid, brand primary, no border-radius).
+- Gray scale (the entire structural neutral system).
+
+The discipline: a brand-customized Carbon surface still *reads* as Carbon. The brand layer is a thin paint job over the structural chassis.
+
+## Component families
+**Doc cards** (`*DocCard`, `*ApiCard`): rounded-none border bg-card; mono slug + version label in the meta row; Plex Sans title; Plex Mono body for code; "Read more" tertiary IBM-blue text-link with underline-on-hover. **Status indicators** (`*StatusIndicator`, `*SeverityBadge`): sharp rectangles by default with semantic bg/fg from Carbon support tokens (green-50 success, red-60 error, yellow-30 warning, cyan-40 info). **Data tables** (`*Table`, `*DataGrid`): tabular figures, mono numeric columns, `border-collapse`, 1px gray-20 row borders, `bg-gray-10` for zebra (5% delta).
+
+## Recommended rich media
+Carbon-corporate is **diagram-heavy and screenshot-heavy**, the opposite of consumer-photography-heavy. The aesthetic is documentation-grade: schematics, console captures, code panels, and a sparing tradition of cut-paper-modernist illustration in the Eames-adjacent IBM lineage.
+
+**Hero media:**
+- **Technical diagrams** in the IBM architecture-diagram tradition — labeled, gridded, two-to-three-color, mono labels. Lines, boxes, and arrows over white. Show the system; don't decorate it.
+- **Product screenshots** of dashboards, consoles, and API surfaces. Present frankly: no shadow, no border, no decorative crop. The screen is the proof.
+- **Cut-paper-modernist illustration** in the Eames / Paul Rand / mid-century IBM tradition. Sparing use. Flat color planes, geometric, never gradient. When in doubt, omit.
+- **NO decorative photography.** No lifestyle staging, no abstract gradients, no stock imagery. Carbon-corporate does not do consumer photography.
+
+**AI tool recommendations:**
+- **Recraft** — technical schematics, labeled architecture diagrams ("IBM Carbon architecture diagram, flat lines, three-color, Plex Mono labels, white background").
+- **Carbon (carbon.now.sh) / Ray.so** — code-snippet images rendered in IBM Plex Mono with a Carbon light theme matching `--background`.
+- **Mermaid / DBML** — declarative diagrams that update with the code (often the better answer than AI).
+- **Excalidraw** — when a hand-drawn-but-precise feel is wanted for explainer diagrams.
+
+**Aspect ratios:** 16:9 for hero diagrams and architecture renders; 4:3 for documentation screenshots; natural aspect for inline charts, CLI output, and code panels. Square (1:1) for product macro photography on neutral seamless when product photography is permitted at all.
+
+**Performance:** SVG diagrams inline (≤8 KB each); screenshots ≤120 KB AVIF at 1.5x device pixel ratio; no autoplay video. LCP target <1.5s — enterprise users run these surfaces on locked-down corporate networks.
+
+**Avoid:** playful illustrations, gradient meshes, consumer-feel photography, lifestyle staging, glassmorphic anything, autoplay video with sound, 3D product renders that look like a Behance reel, purple-or-pink gradients, decorative SVG ornament, lens flare, anything that signals consumer/startup/AI-fad rather than corporate/documentation/Fortune-500.
+
+**Accessibility:** WCAG AA on white background requires foreground at gray-100 (`0 0% 9%`) — easily passes. IBM blue (`220 100% 53%`) on white passes AA at all sizes above 14px regular. Color-coding (green = good, red = bad, yellow = warning) needs a non-color signal (icon, text label) — colorblind engineers exist and they read everything.
+
+## Details
+- **Selection:** `hsl(var(--primary) / 0.2)` background, foreground text — IBM blue at 20% on white.
+- **Focus ring:** `2px solid hsl(var(--ring))` — Carbon canonical focus, 2px solid IBM blue, no rounding.
+- **Scrollbar:** thin, gray-toned.
+
+## Exceptions
+None yet. When an intentional violation lands (e.g. a rounded card to match a business-unit brand book, or a colored hero panel under a Watson-style data-viz piece), add it here with the reason.
+
+## Revisions
+- Initial direction, generated at install time. Authored to provide the canonical IBM Carbon aesthetic — corporate, documentation-grade, sharp, Plex-typeset — as a brand-bookable chassis other enterprises can re-skin.

package/themes/corporate-grid/tokens.ts

@@ -0,0 +1,182 @@
+import type { Direction } from "../schema";
+
+export const corporateGrid: Direction = {
+  name: "corporate-grid",
+  ethos:
+    "IBM Carbon discipline · Plex Sans everywhere · IBM blue signal · documentation-grade information density · 2x grid system",
+  references: [
+    { brand: "IBM Carbon Design System", trait: "2x grid system, sharp corners, Plex Sans canonical" },
+    { brand: "IBM Plex", trait: "the typeface family, prominently used display through caption" },
+    { brand: "IBM marketing site (ibm.com)", trait: "clean white surface, blue signal restraint" },
+    { brand: "Watson + IBM Cloud", trait: "dense documentation product surfaces" },
+    { brand: "IBM Bluemix-era console", trait: "data-grid heavy, instrument-cluster aesthetic" },
+  ],
+  feel:
+    "Corporate seriousness in white. Plex Sans + Plex Mono everywhere — display through caption. " +
+    "Sharp corners, no rounding. IBM blue is the SINGLE signal color, used sparingly on primary " +
+    "actions and link text. Reads as 100-year-old technology company; trustworthy, " +
+    "documentation-grade, never trendy.",
+
+  fonts: {
+    display: {
+      family: "IBM Plex Sans",
+      fallback: ["Inter", "system-ui", "-apple-system", "sans-serif"],
+      from: "IBM Plex Sans — Carbon's canonical display face, weights 600/700 for headings",
+      googleFont: "IBM+Plex+Sans:wght@400;500;600;700",
+      weights: [600, 700],
+    },
+    body: {
+      family: "IBM Plex Sans",
+      fallback: ["Inter", "system-ui", "-apple-system", "sans-serif"],
+      from: "IBM Plex Sans — same face as display, Carbon body rhythm at 400/500",
+      googleFont: "IBM+Plex+Sans:wght@400;500;600;700",
+      weights: [400, 500],
+    },
+    mono: {
+      family: "IBM Plex Mono",
+      fallback: ["JetBrains Mono", "ui-monospace", "SFMono-Regular", "Consolas", "monospace"],
+      from: "IBM Plex Mono — Carbon's canonical mono, API examples, code, CLI snippets",
+      googleFont: "IBM+Plex+Mono:wght@400;500;600",
+      weights: [400, 500, 600],
+    },
+  },
+
+  typography: {
+    headingTracking: "0",
+    bodyTracking: "0",
+    fontFeatureSettings: '"tnum", "zero", "ss01"',
+    h1ScaleClamp: "clamp(1.75rem, 3.5vw, 2.75rem)",
+    bodyBaseSize: "0.875rem",
+    bodyLineHeight: "1.5",
+  },
+
+  colors: {
+    background: { hsl: "0 0% 100%", from: "Carbon white-100 — canonical light theme surface" },
+    foreground: { hsl: "0 0% 9%", from: "Carbon gray-100 text-primary, near-black documentation ink" },
+    card: { hsl: "0 0% 96%", from: "Carbon gray-10 — layered surface one tier above background" },
+    popover: { hsl: "0 0% 100%", from: "Carbon white-100 — popovers float on white with hairline border" },
+
+    primary: { hsl: "220 100% 53%", from: "IBM blue #0F62FE — Carbon's signature interactive blue" },
+    primaryForeground: { hsl: "0 0% 100%", from: "Carbon white-100 on IBM blue for primary actions" },
+
+    secondary: { hsl: "0 0% 91%", from: "Carbon gray-20 — secondary surface, ghost-button background on hover" },
+    secondaryForeground: { hsl: "0 0% 9%", from: "Carbon gray-100 on gray-20" },
+    muted: { hsl: "0 0% 96%", from: "Carbon gray-10 — muted surface, same as card" },
+    mutedForeground: { hsl: "0 0% 32%", from: "Carbon gray-70 — secondary text, captions, doc meta" },
+    accent: { hsl: "0 0% 91%", from: "Carbon gray-20 — hover surface tier" },
+    accentForeground: { hsl: "0 0% 9%", from: "Carbon gray-100 on gray-20 hover" },
+
+    border: { hsl: "0 0% 91%", from: "Carbon gray-20 — structural hairline border, visible at data-grid density" },
+    input: { hsl: "0 0% 91%", from: "Carbon gray-20 — input border, same as structural border" },
+    ring: { hsl: "220 100% 53%", from: "IBM blue #0F62FE — Carbon focus ring color" },
+
+    destructive: { hsl: "352 84% 51%", from: "Carbon red-60 support-error — destructive actions and error states" },
+    destructiveForeground: { hsl: "0 0% 100%", from: "Carbon white-100 on red-60" },
+
+    brand: {
+      "ibm-blue": { hsl: "220 100% 53%", from: "IBM blue #0F62FE — alias for primary, Carbon interactive-01" },
+      "gray-10": { hsl: "0 0% 96%", from: "Carbon gray-10 — layered surface, code-block background" },
+      "gray-20": { hsl: "0 0% 91%", from: "Carbon gray-20 — borders, dividers, ghost-button hover" },
+      "gray-70": { hsl: "0 0% 32%", from: "Carbon gray-70 — secondary text, doc meta, caption" },
+      "gray-100": { hsl: "0 0% 9%", from: "Carbon gray-100 — text-primary, near-black documentation ink" },
+      "red-60": { hsl: "352 84% 51%", from: "Carbon red-60 support-error — destructive and error" },
+      "green-50": { hsl: "140 70% 38%", from: "Carbon green-50 support-success — affirmative status only" },
+      "yellow-30": { hsl: "44 100% 56%", from: "Carbon yellow-30 support-warning — caution states only" },
+      "cyan-40": { hsl: "200 100% 50%", from: "Carbon cyan-40 — info chips and meta accents" },
+    },
+  },
+
+  spacing: {
+    base: 4,
+    scale: [2, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96],
+    containerMax: "max-w-screen-2xl",
+    containerPadding: "px-4 lg:px-8",
+    sectionPadding: {
+      hero: "pt-16 pb-12 lg:pt-24 lg:pb-16",
+      default: "py-12 lg:py-16",
+      tight: "py-8 lg:py-10",
+    },
+  },
+
+  radius: {
+    base: "0",
+    pillsAllowed: false,
+  },
+
+  shadows: {
+    style: "minimal",
+    utilities: {
+      "shadow-elevation-1":
+        "inset 0 0 0 1px hsl(var(--border)), 0 1px 2px hsl(0 0% 0% / 0.08)",
+      "shadow-elevation-2":
+        "inset 0 0 0 1px hsl(var(--border)), 0 2px 6px hsl(0 0% 0% / 0.12)",
+    },
+  },
+
+  motion: {
+    easing: "cubic-bezier(0.2, 0, 0.38, 0.9)",
+    durations: {
+      reveal: 240,
+      loop: 1200,
+      ambient: 0,
+    },
+    keyframes: {
+      "fade-in": {
+        css:
+          "from { opacity: 0; }\n" +
+          "to { opacity: 1; }",
+        defaultDuration: 110,
+        iteration: "once",
+        purpose: "Carbon fast tier (110ms) — popovers, tooltips, micro-interactions",
+      },
+      "expand-panel": {
+        css:
+          "from { opacity: 0; max-height: 0; }\n" +
+          "to { opacity: 1; max-height: 100vh; }",
+        defaultDuration: 240,
+        iteration: "once",
+        purpose: "Carbon moderate tier (240ms) — accordion panels, side-nav expansion, documentation reveals",
+      },
+      "slide-in": {
+        css:
+          "from { opacity: 0; transform: translateX(-8px); }\n" +
+          "to { opacity: 1; transform: translateX(0); }",
+        defaultDuration: 400,
+        iteration: "once",
+        purpose: "Carbon slow tier (400ms) — page transitions, modal entrance, large surface changes",
+      },
+    },
+    respectsReducedMotion: true,
+  },
+
+  density: "high",
+
+  patterns: {
+    button:
+      "Primary = solid IBM blue, white text, sharp rectangle (no border-radius), 16px padding-x, weight 600 " +
+      "(bg-primary text-primary-foreground rounded-none font-semibold px-4). " +
+      "Secondary = ghost with 1px IBM-blue border, IBM-blue text (border border-primary text-primary bg-transparent). " +
+      "Tertiary = IBM-blue text-link with underline-on-hover (text-primary hover:underline underline-offset-2). " +
+      "Sizes: small (h-8 px-3 text-sm) and default (h-10 px-4 text-sm). Carbon button heights are 32/40/48px.",
+    card:
+      "Sharp 0px corners (rounded-none), 1px gray-20 border, bg-card (gray-10). " +
+      "Padding 16px or 24px (p-4 lg:p-6). Header row inside card uses bottom border. " +
+      "Tables and code samples embed inline. No drop shadows beyond .shadow-elevation-1.",
+    input:
+      "Compact (h-10 text-sm), 1px gray-20 border, bg-background, rounded-none. " +
+      "Underline-only variant also valid (border-b only, bg-gray-10). " +
+      "Focus uses 2px IBM-blue ring. Label above; helper below in gray-70. " +
+      "Inline validation in red-60.",
+    cta:
+      "Primary = IBM-blue button. Secondary = ghost IBM-blue border. Tertiary = IBM-blue text-link. " +
+      "One primary CTA per surface; corporate documentation, not conversion theater. " +
+      "Marketing-style double-CTAs are forbidden.",
+  },
+
+  details: {
+    selectionBg: "hsl(var(--primary) / 0.2)",
+    selectionFg: "hsl(var(--foreground))",
+    focusRing: "2px solid hsl(var(--ring))",
+    scrollbarStyle: "thin",
+  },
+};