@selesai/code 0.13.13 → 0.13.14

package/dist/skills/brutalist/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: brutalist
+description: Raw mechanical interfaces fusing Swiss typographic print with military terminal aesthetics. Rigid grids, extreme type scale contrast, utilitarian color, analog degradation effects. For data-heavy dashboards, portfolios, or editorial sites that need to feel like declassified blueprints.
+---
+
+# SKILL: Industrial Brutalism & Tactical Telemetry UI
+
+## 1. Skill Meta
+**Name:** Industrial Brutalism & Tactical Telemetry Interface Engineering
+**Description:** Advanced proficiency in architecting web interfaces that synthesize mid-century Swiss Typographic design, industrial manufacturing manuals, and retro-futuristic aerospace/military terminal interfaces. This discipline requires absolute mastery over rigid modular grids, extreme typographic scale contrast, purely utilitarian color palettes, and the programmatic simulation of analog degradation (halftones, CRT scanlines, bitmap dithering). The objective is to construct digital environments that project raw functionality, mechanical precision, and high data density, deliberately discarding conventional consumer UI patterns.
+
+## 2. Visual Archetypes
+The design system operates by merging two distinct but highly compatible visual paradigms. **Pick ONE per project and commit to it. Do not alternate or mix both modes within the same interface.**
+
+### 2.1 Swiss Industrial Print
+Derived from 1960s corporate identity systems and heavy machinery blueprints.
+*   **Characteristics:** High-contrast light modes (newsprint/off-white substrates). Reliance on monolithic, heavy sans-serif typography. Unforgiving structural grids outlined by visible dividing lines. Aggressive, asymmetric use of negative space punctuated by oversized, viewport-bleeding numerals or letterforms. Heavy use of primary red as an alert/accent color.
+
+### 2.2 Tactical Telemetry & CRT Terminal
+Derived from classified military databases, legacy mainframes, and aerospace Heads-Up Displays (HUDs).
+*   **Characteristics:** Dark mode exclusivity. High-density tabular data presentation. Absolute dominance of monospaced typography. Integration of technical framing devices (ASCII brackets, crosshairs). Application of simulated hardware limitations (phosphor glow, scanlines, low bit-depth rendering).
+
+## 3. Typographic Architecture
+Typography is the primary structural and decorative infrastructure. Imagery is secondary. The system demands extreme variance in scale, weight, and spacing.
+
+### 3.1 Macro-Typography (Structural Headers)
+*   **Classification:** Neo-Grotesque / Heavy Sans-Serif.
+*   **Optimal Web Fonts:** Neue Haas Grotesk (Black), Inter (Extra Bold/Black), Archivo Black, Roboto Flex (Heavy), Monument Extended.
+*   **Implementation Parameters:**
+    *   **Scale:** Deployed at massive scales using fluid typography (e.g., `clamp(4rem, 10vw, 15rem)`).
+    *   **Tracking (Letter-spacing):** Extremely tight, often negative (`-0.03em` to `-0.06em`), forcing glyphs to form solid architectural blocks.
+    *   **Leading (Line-height):** Highly compressed (`0.85` to `0.95`).
+    *   **Casing:** Exclusively uppercase for structural impact.
+
+### 3.2 Micro-Typography (Data & Telemetry)
+*   **Classification:** Monospace / Technical Sans.
+*   **Optimal Web Fonts:** JetBrains Mono, IBM Plex Mono, Space Mono, VT323, Courier Prime.
+*   **Implementation Parameters:**
+    *   **Scale:** Fixed and small (`10px` to `14px` / `0.7rem` to `0.875rem`).
+    *   **Tracking:** Generous (`0.05em` to `0.1em`) to simulate mechanical typewriter spacing or terminal matrices.
+    *   **Leading:** Standard to tight (`1.2` to `1.4`).
+    *   **Casing:** Exclusively uppercase. Used for all metadata, navigation, unit IDs, and coordinates.
+
+### 3.3 Textural Contrast (Artistic Disruption)
+*   **Classification:** High-Contrast Serif.
+*   **Optimal Web Fonts:** Playfair Display, EB Garamond, Times New Roman.
+*   **Implementation Parameters:** Used exceedingly sparingly. Must be subjected to heavy post-processing (halftone filters, 1-bit dithering) to degrade vector perfection and create textural juxtaposition against the clean sans-serifs.
+
+## 4. Color System
+The color architecture is uncompromising. Gradients, soft drop shadows, and modern translucency are strictly prohibited. Colors simulate physical media or primitive emissive displays.
+
+**CRITICAL: Choose ONE substrate palette per project and use it consistently. Never mix light and dark substrates within the same interface.**
+
+### If Swiss Industrial Print (Light):
+*   **Background:** `#F4F4F0` or `#EAE8E3` (Matte, unbleached documentation paper).
+*   **Foreground:** `#050505` to `#111111` (Carbon Ink).
+*   **Accent:** `#E61919` or `#FF2A2A` (Aviation/Hazard Red). This is the ONLY accent color. Used for strike-throughs, thick structural dividing lines, or vital data highlights.
+
+### If Tactical Telemetry (Dark):
+*   **Background:** `#0A0A0A` or `#121212` (Deactivated CRT. Avoid pure `#000000`).
+*   **Foreground:** `#EAEAEA` (White phosphor). This is the primary text color.
+*   **Accent:** `#E61919` or `#FF2A2A` (Aviation/Hazard Red). Same red, same rules.
+*   **Terminal Green (`#4AF626`):** Optional. Use ONLY for a single specific UI element (e.g., one status indicator or one data readout) — never as a general text color. If it doesn't serve a clear purpose, omit it entirely.
+
+## 5. Layout and Spatial Engineering
+The layout must appear mathematically engineered. It rejects conventional web padding in favor of visible compartmentalization.
+
+*   **The Blueprint Grid:** Strict adherence to CSS Grid architectures. Elements do not float; they are anchored precisely to grid tracks and intersections.
+*   **Visible Compartmentalization:** Extensive utilization of solid borders (`1px` or `2px solid`) to delineate distinct zones of information. Horizontal rules (`<hr>`) frequently span the entire container width to segregate operational units.
+*   **Bimodal Density:** Layouts oscillate between extreme data density (tightly packed monospace metadata clustered together) and vast expanses of calculated negative space framing macro-typography.
+*   **Geometry:** Absolute rejection of `border-radius`. All corners must be exactly 90 degrees to enforce mechanical rigidity.
+
+## 6. UI Components and Symbology
+Standard web UI conventions are replaced with utilitarian, industrial graphic elements.
+
+*   **Syntax Decoration:** Utilization of ASCII characters to frame data points.
+    *   *Framing:* `[ DELIVERY SYSTEMS ]`, `< RE-IND >`
+    *   *Directional:* `>>>`, `///`, `\\\\`
+*   **Industrial Markers:** Prominent integration of registration (`®`), copyright (`©`), and trademark (`™`) symbols functioning as structural geometric elements rather than legal text.
+*   **Technical Assets:** Integration of crosshairs (`+`) at grid intersections, repeating vertical lines (barcodes), thick horizontal warning stripes, and randomized string data (e.g., `REV 2.6`, `UNIT / D-01`) to simulate active mechanical processes.
+
+## 7. Textural and Post-Processing Effects
+To prevent the design from appearing purely digital, simulated analog degradation is engineered into the frontend via CSS and SVG filters.
+
+*   **Halftone and 1-Bit Dithering:** Transforming continuous-tone images or large serif typography into dot-matrix patterns. Achieved via pre-processing or CSS `mix-blend-mode: multiply` overlays combined with SVG radial dot patterns.
+*   **CRT Scanlines:** For terminal interfaces, applying a `repeating-linear-gradient` to the background to simulate horizontal electron beam sweeps (e.g., `repeating-linear-gradient(0deg, transparent, transparent 2px, rgba(0,0,0,0.1) 2px, rgba(0,0,0,0.1) 4px)`).
+*   **Mechanical Noise:** A global, low-opacity SVG static/noise filter applied to the DOM root to introduce a unified physical grain across both dark and light modes.
+
+## 8. Web Engineering Directives
+1.  **Grid Determinism:** Utilize `display: grid; gap: 1px;` with contrasting parent/child background colors to generate mathematically perfect, razor-thin dividing lines without complex border declarations.
+2.  **Semantic Rigidity:** Construct the DOM using precise semantic tags (`<data>`, `<samp>`, `<kbd>`, `<output>`, `<dl>`) to accurately reflect the technical nature of the telemetry.
+3.  **Typography Clamping:** Implement CSS `clamp()` functions exclusively for macro-typography to ensure massive text scales aggressively while maintaining structural integrity across viewports.

package/dist/skills/design-references/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: design-references
+category: design
+description: Design-reference lookup from VoltAgent's Awesome DESIGN.md collection. Use when the user asks for design references or inspiration, or wants a page/product to feel like a known site or brand (Linear, Stripe, Apple, etc.).
+license: MIT
+---
+
+# Design References
+
+[VoltAgent/awesome-design-md](https://github.com/voltagent/awesome-design-md) is a curated collection of `DESIGN.md` files extracted from real websites — color roles, typography, components, layout, depth, responsive rules, do/don'ts. Use it to ground design decisions in an analyzed real system instead of generic output.
+
+## Procedure
+
+1. **Fetch the collection index.** `grep_app_fetch` `README.md` from `voltagent/awesome-design-md`. Its Collection section is the single source of truth — never work from a memorized site list.
+   Done when: the Collection section is in context, or the fetch failed twice and you say so, labelling anything after as unfetched.
+   Locally vendored references (e.g. `references/clickhouse/DESIGN.md`) may be used in place of a fetch for those slugs.
+2. **Select references.**
+   - Named brand ("make it feel like X"): find that site's row; the link path is the slug (`getdesign.md/linear.app/design-md` → `linear.app`).
+   - Open-ended ("give me references"): pick 2–3 whose category and one-line description match the brief's audience, industry, and interface density. Each pick needs a reason tied to the brief. If two candidates lead to genuinely different builds, ask one choice question.
+   Done when: every pick has a stated reason (named branch: the named site, or a stated closest match).
+3. **Fetch each `design-md/<slug>/DESIGN.md`** via `grep_app_fetch` (`repo: voltagent/awesome-design-md`).
+   Done when: every recommended reference was fetched this session, or was confirmed absent — then offer the closest same-category alternatives instead.
+4. **Distill, don't dump.** Extract only what transfers: palette roles, type hierarchy, spacing/layout, component treatment, depth/motion, do/don'ts. Never paste a whole DESIGN.md into chat or project files.
+   Done when: you can state 2–3 principles per reference you will actually apply.
+5. **Report, then build.** One-line direction; then per reference: why it fits, what to borrow, and its `https://getdesign.md/<slug>/design-md` URL. If the user named a site, deliver the distillation as an implementable mini-brief and build from it; otherwise present the options and proceed with the strongest fit.
+
+## Guardrails
+
+- Cite only references fetched this session — never claim you examined one you didn't.
+- Adapt, don't imitate: transfer principles; never lift a brand's logo, imagery, or distinctive identity.
+- Accessibility is non-negotiable: contrast, focus states, keyboard access, touch targets.
+- Write a project-root `DESIGN.md` only if asked; if asked, author a project-specific one informed by the references, not a copy.

package/dist/skills/design-references/references/clickhouse/DESIGN.md

@@ -0,0 +1,544 @@
+---
+version: alpha
+name: ClickHouse-design-analysis
+description: A high-performance database interface anchored on near-pure black canvas with electric yellow as the brand voltage. White typography in confident sans, yellow CTAs, and yellow-text stat numbers carry the brand voice across every page. Code blocks and product UI fragments embed directly in dark cards. The yellow + black pairing (and yellow used scarcely as accent) is the system's signature — brand identity without atmospheric decoration.
+
+colors:
+  primary: "#faff69"
+  primary-active: "#e6eb52"
+  primary-disabled: "#3a3a1f"
+  ink: "#ffffff"
+  body: "#cccccc"
+  body-strong: "#e6e6e6"
+  muted: "#888888"
+  muted-soft: "#5a5a5a"
+  hairline: "#2a2a2a"
+  hairline-strong: "#3a3a3a"
+  canvas: "#0a0a0a"
+  surface-soft: "#121212"
+  surface-card: "#1a1a1a"
+  surface-elevated: "#242424"
+  surface-yellow-band: "#faff69"
+  on-primary: "#0a0a0a"
+  on-dark: "#ffffff"
+  on-yellow: "#0a0a0a"
+  accent-emerald: "#22c55e"
+  accent-rose: "#ef4444"
+  accent-blue: "#3b82f6"
+  success: "#22c55e"
+  warning: "#f59e0b"
+  error: "#ef4444"
+
+typography:
+  display-xl:
+    fontFamily: "Inter, sans-serif"
+    fontSize: 72px
+    fontWeight: 700
+    lineHeight: 1.05
+    letterSpacing: -2.5px
+  display-lg:
+    fontFamily: "Inter, sans-serif"
+    fontSize: 56px
+    fontWeight: 700
+    lineHeight: 1.1
+    letterSpacing: -2px
+  display-md:
+    fontFamily: "Inter, sans-serif"
+    fontSize: 40px
+    fontWeight: 700
+    lineHeight: 1.15
+    letterSpacing: -1.5px
+  display-sm:
+    fontFamily: "Inter, sans-serif"
+    fontSize: 32px
+    fontWeight: 700
+    lineHeight: 1.2
+    letterSpacing: -1px
+  title-lg:
+    fontFamily: "Inter, sans-serif"
+    fontSize: 24px
+    fontWeight: 700
+    lineHeight: 1.3
+    letterSpacing: -0.3px
+  title-md:
+    fontFamily: "Inter, sans-serif"
+    fontSize: 18px
+    fontWeight: 600
+    lineHeight: 1.4
+    letterSpacing: 0
+  title-sm:
+    fontFamily: "Inter, sans-serif"
+    fontSize: 16px
+    fontWeight: 600
+    lineHeight: 1.4
+    letterSpacing: 0
+  stat-display:
+    fontFamily: "Inter, sans-serif"
+    fontSize: 56px
+    fontWeight: 700
+    lineHeight: 1.0
+    letterSpacing: -1.5px
+  body-md:
+    fontFamily: "Inter, sans-serif"
+    fontSize: 16px
+    fontWeight: 400
+    lineHeight: 1.55
+    letterSpacing: 0
+  body-sm:
+    fontFamily: "Inter, sans-serif"
+    fontSize: 14px
+    fontWeight: 400
+    lineHeight: 1.55
+    letterSpacing: 0
+  caption:
+    fontFamily: "Inter, sans-serif"
+    fontSize: 13px
+    fontWeight: 500
+    lineHeight: 1.4
+    letterSpacing: 0
+  caption-uppercase:
+    fontFamily: "Inter, sans-serif"
+    fontSize: 12px
+    fontWeight: 600
+    lineHeight: 1.4
+    letterSpacing: 1.5px
+  code:
+    fontFamily: "JetBrains Mono, ui-monospace, monospace"
+    fontSize: 14px
+    fontWeight: 400
+    lineHeight: 1.55
+    letterSpacing: 0
+  button:
+    fontFamily: "Inter, sans-serif"
+    fontSize: 14px
+    fontWeight: 600
+    lineHeight: 1
+    letterSpacing: 0
+  nav-link:
+    fontFamily: "Inter, sans-serif"
+    fontSize: 14px
+    fontWeight: 500
+    lineHeight: 1.4
+    letterSpacing: 0
+
+rounded:
+  xs: 4px
+  sm: 6px
+  md: 8px
+  lg: 12px
+  pill: 9999px
+  full: 9999px
+
+spacing:
+  xxs: 4px
+  xs: 8px
+  sm: 12px
+  md: 16px
+  lg: 24px
+  xl: 32px
+  xxl: 48px
+  section: 96px
+
+components:
+  button-primary:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.on-primary}"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+    padding: 12px 20px
+    height: 40px
+  button-primary-active:
+    backgroundColor: "{colors.primary-active}"
+    textColor: "{colors.on-primary}"
+    rounded: "{rounded.md}"
+  button-primary-disabled:
+    backgroundColor: "{colors.primary-disabled}"
+    textColor: "{colors.muted}"
+    rounded: "{rounded.md}"
+  button-secondary:
+    backgroundColor: "{colors.surface-card}"
+    textColor: "{colors.on-dark}"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+    padding: 12px 20px
+    height: 40px
+  button-text-link:
+    backgroundColor: transparent
+    textColor: "{colors.on-dark}"
+    typography: "{typography.button}"
+  button-icon-circular:
+    backgroundColor: "{colors.surface-card}"
+    textColor: "{colors.on-dark}"
+    rounded: "{rounded.full}"
+    size: 36px
+  text-link:
+    backgroundColor: transparent
+    textColor: "{colors.primary}"
+    typography: "{typography.body-md}"
+  top-nav:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.on-dark}"
+    typography: "{typography.nav-link}"
+    height: 64px
+  hero-band:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.on-dark}"
+    typography: "{typography.display-xl}"
+    padding: 96px
+  hero-stat-card:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.primary}"
+    typography: "{typography.stat-display}"
+  feature-card-yellow:
+    backgroundColor: "{colors.surface-yellow-band}"
+    textColor: "{colors.on-yellow}"
+    typography: "{typography.title-md}"
+    rounded: "{rounded.lg}"
+    padding: 32px
+  feature-card-dark:
+    backgroundColor: "{colors.surface-card}"
+    textColor: "{colors.on-dark}"
+    typography: "{typography.title-md}"
+    rounded: "{rounded.lg}"
+    padding: 32px
+  code-window-card:
+    backgroundColor: "{colors.surface-card}"
+    textColor: "{colors.on-dark}"
+    typography: "{typography.code}"
+    rounded: "{rounded.lg}"
+    padding: 24px
+  product-mockup-card:
+    backgroundColor: "{colors.surface-card}"
+    textColor: "{colors.on-dark}"
+    typography: "{typography.title-md}"
+    rounded: "{rounded.lg}"
+    padding: 24px
+  pricing-tier-card:
+    backgroundColor: "{colors.surface-card}"
+    textColor: "{colors.on-dark}"
+    typography: "{typography.title-lg}"
+    rounded: "{rounded.lg}"
+    padding: 32px
+  pricing-tier-card-featured:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.on-primary}"
+    typography: "{typography.title-lg}"
+    rounded: "{rounded.lg}"
+    padding: 32px
+  stat-callout:
+    backgroundColor: transparent
+    textColor: "{colors.primary}"
+    typography: "{typography.stat-display}"
+  cta-band-yellow:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.on-primary}"
+    typography: "{typography.display-md}"
+    rounded: "{rounded.lg}"
+    padding: 64px
+  text-input:
+    backgroundColor: "{colors.surface-card}"
+    textColor: "{colors.on-dark}"
+    typography: "{typography.body-md}"
+    rounded: "{rounded.md}"
+    padding: 10px 14px
+    height: 40px
+  text-input-focused:
+    backgroundColor: "{colors.surface-card}"
+    textColor: "{colors.on-dark}"
+    rounded: "{rounded.md}"
+  category-tab:
+    backgroundColor: transparent
+    textColor: "{colors.muted}"
+    typography: "{typography.nav-link}"
+    rounded: "{rounded.md}"
+    padding: 8px 14px
+  category-tab-active:
+    backgroundColor: "{colors.surface-card}"
+    textColor: "{colors.on-dark}"
+    typography: "{typography.nav-link}"
+    rounded: "{rounded.md}"
+  badge-pill:
+    backgroundColor: "{colors.surface-card}"
+    textColor: "{colors.on-dark}"
+    typography: "{typography.caption}"
+    rounded: "{rounded.pill}"
+    padding: 4px 12px
+  badge-yellow:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.on-primary}"
+    typography: "{typography.caption-uppercase}"
+    rounded: "{rounded.pill}"
+    padding: 4px 12px
+  events-card:
+    backgroundColor: "{colors.surface-card}"
+    textColor: "{colors.on-dark}"
+    typography: "{typography.title-md}"
+    rounded: "{rounded.lg}"
+    padding: 24px
+  customer-logo-strip:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.muted}"
+    typography: "{typography.body-md}"
+    padding: 32px
+  footer:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.muted}"
+    typography: "{typography.body-sm}"
+    padding: 64px
+---
+
+## Overview
+
+ClickHouse's marketing surface is the highest-contrast interface in the database / data-platform category. The base atmosphere is **near-pure black canvas** (`{colors.canvas}` — #0a0a0a) with **electric yellow** (`{colors.primary}` — #faff69) as the singular brand voltage. The yellow handles every primary CTA, every stat-callout number, every "GET STARTED" badge — used scarcely on individual elements but generously on full-bleed yellow CTA cards. White typography in confident weight-700 sans-serif anchors the editorial body.
+
+The yellow + black pairing is what makes ClickHouse instantly recognizable. Where Snowflake uses cool blue gradients and Databricks uses red + slate, ClickHouse leans hard into one electric yellow that does all the brand work. Code blocks, terminal output, and product UI fragments embed directly in dark `{colors.surface-card}` (#1a1a1a) cards across every page.
+
+Type voice runs **Inter** at confident weights — 700 for display headlines (with negative letter-spacing -1 to -2.5px), 600 for sub-titles and buttons, 400 for body. The system has no display-serif counter-voice; everything is one geometric humanist sans, scaled and weighted for hierarchy.
+
+**Key Characteristics:**
+- Near-pure black canvas (`{colors.canvas}` — #0a0a0a) with white type. The system has no light-mode marketing surface.
+- Electric yellow primary (`{colors.primary}` — #faff69). Used on primary CTAs, large stat-callout numbers ("2.8k+", "74k+"), and full-bleed yellow CTA bands.
+- Inter at weight 700 for display, weight 600 for sub-titles + buttons, weight 400 for body. No serif counterpoint.
+- Dark surface cards (`{colors.surface-card}` — #1a1a1a) for feature cards, code windows, and product mockups. Cards barely lighter than canvas — color-block contrast is subtle.
+- Code blocks render in JetBrains Mono inside `{colors.surface-card}`. SQL syntax-highlighted in muted blues / yellows / grays.
+- Stat numbers in yellow + sans-700 + huge size carry the credibility moment ("779+", "2.8k+", "47k+" community / contributor / star counts).
+- Border radius is hierarchical: `{rounded.md}` (8px) for buttons, `{rounded.lg}` (12px) for content cards. No pill except in tag badges.
+- Section rhythm `{spacing.section}` (96px) between major editorial bands.
+
+## Colors
+
+### Brand & Accent
+- **Primary (Electric Yellow)** (`{colors.primary}` — #faff69): The signature brand color. All primary CTA backgrounds, large stat-callout numbers, full-bleed yellow CTA cards. The yellow is the brand.
+- **Primary Active** (`{colors.primary-active}` — #e6eb52): Press / hover-darker variant.
+- **Primary Disabled** (`{colors.primary-disabled}` — #3a3a1f): Desaturated dark-yellow on dark canvas.
+
+### Surface
+- **Canvas** (`{colors.canvas}` — #0a0a0a): The default page floor. Near-pure black.
+- **Surface Soft** (`{colors.surface-soft}` — #121212): Section dividers, very-soft band tints.
+- **Surface Card** (`{colors.surface-card}` — #1a1a1a): Feature cards, code windows, product mockups, pricing tier cards.
+- **Surface Elevated** (`{colors.surface-elevated}` — #242424): Nested cards inside larger dark cards.
+- **Surface Yellow Band** (`{colors.surface-yellow-band}` — #faff69): The yellow CTA card / band fill — same hex as primary.
+- **Hairline** (`{colors.hairline}` — #2a2a2a): 1px borders on cards.
+- **Hairline Strong** (`{colors.hairline-strong}` — #3a3a3a): Heavier divider on input underlines and emphasis.
+
+### Text
+- **Ink / On Dark** (`{colors.on-dark}` — #ffffff): All headline and primary text.
+- **Body** (`{colors.body}` — #cccccc): Default running-text color.
+- **Body Strong** (`{colors.body-strong}` — #e6e6e6): Emphasized paragraphs.
+- **Muted** (`{colors.muted}` — #888888): Footer links, captions, breadcrumbs.
+- **Muted Soft** (`{colors.muted-soft}` — #5a5a5a): Tertiary text — fine print.
+- **On Primary / On Yellow** (`{colors.on-primary}` / `{colors.on-yellow}` — #0a0a0a): Black text on yellow CTAs and yellow CTA bands. The high-contrast yellow + black combo is the brand action signal.
+
+### Semantic / Accent
+- **Accent Emerald** (`{colors.accent-emerald}` — #22c55e): Success states, "active" status indicators in product UI.
+- **Accent Rose** (`{colors.accent-rose}` — #ef4444): Error states, "down" indicators.
+- **Accent Blue** (`{colors.accent-blue}` — #3b82f6): Info states, code-syntax highlighting.
+
+## Typography
+
+### Font Family
+The system runs **Inter** for everything — display, body, navigation, buttons, captions. **JetBrains Mono** handles code blocks. The fallback stack walks `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif`.
+
+The single-family approach is deliberate: Inter at weight 700 + 600 + 400 covers the entire hierarchy without needing a serif or display counter-voice. The geometric humanist character of Inter at confident bold weight gives ClickHouse a precise, engineered feel that matches the database's performance-first positioning.
+
+### Hierarchy
+
+| Token | Size | Weight | Line Height | Letter Spacing | Use |
+|---|---|---|---|---|---|
+| `{typography.display-xl}` | 72px | 700 | 1.05 | -2.5px | Homepage h1 ("The leading database for AI") |
+| `{typography.display-lg}` | 56px | 700 | 1.1 | -2px | Section heads |
+| `{typography.display-md}` | 40px | 700 | 1.15 | -1.5px | Sub-section heads, CTA-band heads |
+| `{typography.display-sm}` | 32px | 700 | 1.2 | -1px | Card titles, pricing tier prices |
+| `{typography.title-lg}` | 24px | 700 | 1.3 | -0.3px | Pricing plan names, larger feature titles |
+| `{typography.title-md}` | 18px | 600 | 1.4 | 0 | Card titles, intro paragraphs |
+| `{typography.title-sm}` | 16px | 600 | 1.4 | 0 | Small card titles, list labels |
+| `{typography.stat-display}` | 56px | 700 | 1.0 | -1.5px | Stat callouts ("779+", "47k+") — ALWAYS yellow |
+| `{typography.body-md}` | 16px | 400 | 1.55 | 0 | Default running-text |
+| `{typography.body-sm}` | 14px | 400 | 1.55 | 0 | Footer body, fine-print |
+| `{typography.caption}` | 13px | 500 | 1.4 | 0 | Badge labels, captions |
+| `{typography.caption-uppercase}` | 12px | 600 | 1.4 | 1.5px | Section labels, "NEW" badges |
+| `{typography.code}` | 14px | 400 | 1.55 | 0 | Code blocks — JetBrains Mono |
+| `{typography.button}` | 14px | 600 | 1.0 | 0 | Standard button labels |
+| `{typography.nav-link}` | 14px | 500 | 1.4 | 0 | Top-nav menu items |
+
+### Principles
+Display weights stay at 700 across all sizes. Negative letter-spacing (-1 to -2.5px) is essential — Inter at weight 700 without negative tracking reads as too wide / Apple-marketing. The tightened tracking gives ClickHouse the precise, engineered feel.
+
+Body and labels stay at weights 400 / 500 / 600. The hierarchy is built on size + weight, not on family contrast.
+
+### Note on Font Substitutes
+Inter is open-source and the documented choice. **Söhne** is a close commercial alternative if licensed. **Geist** is another modern alternative.
+
+## Layout
+
+### Spacing System
+- **Base unit:** 4px.
+- **Tokens:** `{spacing.xxs}` 4px · `{spacing.xs}` 8px · `{spacing.sm}` 12px · `{spacing.md}` 16px · `{spacing.lg}` 24px · `{spacing.xl}` 32px · `{spacing.xxl}` 48px · `{spacing.section}` 96px.
+- **Section padding:** `{spacing.section}` (96px) between major bands.
+- **Card internal padding:** `{spacing.xl}` (32px) for feature cards, pricing tiers; `{spacing.lg}` (24px) for code-window cards and event cards.
+
+### Grid & Container
+- **Max content width:** ~1280px centered.
+- **Editorial body:** Single 12-column grid; hero often uses 7/5 split (h1 left, code mockup right).
+- **Feature card grids:** 3-up at desktop, 2-up at tablet, 1-up at mobile.
+- **Pricing grid:** 3-4 up at desktop, 1-up at mobile.
+
+### Whitespace Philosophy
+ClickHouse uses dense, slightly-compressed whitespace appropriate for a developer-tooling brand — generous enough to read editorially, tight enough to feel "engineering-grade" rather than "marketing-soft." Section rhythm at 96px is standard; card internal padding stays at 32px for feature cards.
+
+## Elevation & Depth
+
+| Level | Treatment | Use |
+|---|---|---|
+| Flat | No shadow, no border | Body sections, top nav, hero |
+| Soft hairline | 1px `{colors.hairline}` border | Code-window cards, content cards |
+| Surface card | `{colors.surface-card}` background — no shadow | Feature cards, pricing tiers, event cards |
+| Yellow band | `{colors.primary}` background — no shadow | Full-bleed yellow CTA cards / bands |
+
+The system uses no drop shadows. Depth comes from the contrast between black canvas and `{colors.surface-card}` (a barely-lighter-than-canvas tone) — the contrast is subtle, more like an "engineering-grade dim panel" than an "elevated card."
+
+### Decorative Depth
+- Code-window cards carry their own internal product chrome — line numbers, syntax highlighting, status bars at the bottom — adding visual density without external shadows.
+- The yellow-on-black contrast does most of the elevation work for CTAs.
+
+## Shapes
+
+### Border Radius Scale
+
+| Token | Value | Use |
+|---|---|---|
+| `{rounded.xs}` | 4px | Reserved for badge accents |
+| `{rounded.sm}` | 6px | Small inline buttons |
+| `{rounded.md}` | 8px | Standard CTA buttons, text inputs |
+| `{rounded.lg}` | 12px | Content cards, code-window cards, pricing tiers |
+| `{rounded.pill}` | 9999px | Badge pills |
+| `{rounded.full}` | 9999px / 50% | Avatars, icon buttons |
+
+## Components
+
+### Top Navigation
+
+**`top-nav`** — Black nav bar pinned to top. 64px tall, `{colors.canvas}` background. Carries the ClickHouse logo + wordmark at left, primary horizontal menu (Product, Use Cases, Pricing, Resources, Customers) center-left, right-side cluster with "Sign in" + "Get Started" `{component.button-primary}` (yellow). Menu items in `{typography.nav-link}` (Inter 14px / 500).
+
+### Buttons
+
+**`button-primary`** — The signature yellow CTA. Background `{colors.primary}` (#faff69), text `{colors.on-primary}` (black), type `{typography.button}` (Inter 14px / 600), padding 12px × 20px, height 40px, rounded `{rounded.md}` (8px). The yellow + black combination is iconic.
+
+**`button-secondary`** — Dark surface card button. Background `{colors.surface-card}`, text `{colors.on-dark}`, same shape as primary.
+
+**`button-text-link`** — Inline text button, no background. Used for "Sign in" and inline link CTAs.
+
+**`text-link`** — Inline body links in `{colors.primary}` (yellow on dark). Underlined.
+
+**`button-icon-circular`** — 36 × 36 circular icon button on dark.
+
+### Cards & Containers
+
+**`hero-band`** — Black-canvas hero with 7-5 grid: h1 + sub-headline + button row on the left, code-window or product mockup on the right. Vertical padding `{spacing.section}` (96px).
+
+**`hero-stat-card`** — Yellow stat-display numbers ("779+", "47k+") inline on the canvas. No card surface — just yellow text in `{typography.stat-display}` (56px / 700).
+
+**`feature-card-yellow`** — Full-bleed yellow card ("Built for every modern data challenge"). Background `{colors.primary}`, text `{colors.on-yellow}` (black), rounded `{rounded.lg}` (12px), padding `{spacing.xl}` (32px). The yellow card IS the visual emphasis.
+
+**`feature-card-dark`** — Standard dark feature card. Background `{colors.surface-card}`, text `{colors.on-dark}`, rounded `{rounded.lg}`, padding `{spacing.xl}` (32px).
+
+**`code-window-card`** — Dark card showing a SQL code block. Background `{colors.surface-card}`, code in JetBrains Mono with syntax highlighting, rounded `{rounded.lg}`, padding `{spacing.lg}` (24px). Often the hero's right-side artifact on developer-focused pages.
+
+**`product-mockup-card`** — Card showing actual ClickHouse product UI (query editor, dashboard, monitoring panel). Same shape as `{component.feature-card-dark}` but with embedded product chrome inside.
+
+**`pricing-tier-card`** — Standard tier card. Background `{colors.surface-card}`, rounded `{rounded.lg}`, padding `{spacing.xl}` (32px).
+
+**`pricing-tier-card-featured`** — The featured tier flips to `{colors.primary}` (yellow). The yellow surface IS the featured signal.
+
+**`stat-callout`** — Inline yellow stat numbers ("779+", "2.8k+", "47k+"). Transparent background, text `{colors.primary}`, type `{typography.stat-display}`. Used as a flat layout block, not a card with surface.
+
+**`events-card`** — Used on /company/events. Dark card with event title, date in `{typography.caption-uppercase}`, location, and a "Register" CTA. Rounded `{rounded.lg}`, padding `{spacing.lg}`.
+
+**`customer-logo-strip`** — Horizontal monochrome customer-logo strip. Background `{colors.canvas}`, logos in `{colors.muted}`, vertical padding `{spacing.xl}` (32px).
+
+### Inputs & Forms
+
+**`text-input`** — Dark text input. Background `{colors.surface-card}`, text `{colors.on-dark}`, rounded `{rounded.md}` (8px), padding 10px × 14px, height 40px.
+
+**`text-input-focused`** — Border thickens to `{colors.primary}` (yellow) for emphasis.
+
+### Tags / Badges
+
+**`badge-pill`** — Small dark pill label. Background `{colors.surface-card}`, text `{colors.on-dark}`, type `{typography.caption}`, rounded `{rounded.pill}`.
+
+**`badge-yellow`** — Yellow pill for "NEW", "GET STARTED" emphasis. Background `{colors.primary}`, text `{colors.on-primary}`, type `{typography.caption-uppercase}`, rounded `{rounded.pill}`.
+
+### Tab / Filter
+
+**`category-tab`** + **`category-tab-active`** — Dark tab navigation. Inactive: transparent + muted text. Active: surface-card background + on-dark text. Padding 8px × 14px, rounded `{rounded.md}`.
+
+### CTA / Footer
+
+**`cta-band-yellow`** — A pre-footer "Deploy your way" CTA band. Full yellow fill, black type, rounded `{rounded.lg}`, padding 64px. Carries an h2 in `{typography.display-md}` and a CTA — usually a black-button on the yellow surface.
+
+**`footer`** — Black footer that closes every page. Background `{colors.canvas}`, text `{colors.muted}`. 4-column link list at desktop covering Product / Use Cases / Resources / Company. Vertical padding 64px. The ClickHouse wordmark sits at the top in `{colors.on-dark}`.
+
+## Do's and Don'ts
+
+### Do
+- Anchor every page on the black canvas. The yellow + black pairing is the brand voltage.
+- Reserve `{colors.primary}` (yellow) for primary CTAs, stat-callout numbers, and full-bleed yellow CTA bands. The yellow's scarcity at the element level + abundance at the band level is what makes it powerful.
+- Use Inter at weight 700 for every display headline, with -1 to -2.5px letter-spacing.
+- Show actual SQL code blocks inside `{component.code-window-card}` — ClickHouse is a database; show the query, don't paint marketing illustrations of queries.
+- Use `{component.stat-callout}` numbers to establish credibility (community size, contributors, performance benchmarks). The yellow stat numbers are signature.
+- Anchor every band with `{spacing.section}` (96px) vertical rhythm.
+
+### Don't
+- Don't introduce a second brand color. ClickHouse is monochromatic + yellow.
+- Don't bold display weight beyond 700 or use weight 500 for headlines. The hierarchy depends on size, not on weight gradation.
+- Don't use yellow for body text or large surface fills outside of intentional yellow cards.
+- Don't use rounded buttons / pills outside of small badges. The standard button radius is 8px (md).
+- Don't repeat the same surface mode in two consecutive bands. Black canvas → dark feature card → yellow CTA card → black canvas → code-window card.
+- Don't replace SQL code mockups with abstract illustrations. The code IS the marketing voltage.
+- Don't add hover state styling beyond what the system already encodes.
+
+## Responsive Behavior
+
+### Breakpoints
+
+| Name | Width | Key Changes |
+|---|---|---|
+| Mobile | < 768px | Hamburger nav; hero h1 72→36px; code-window-card stacks below; feature grids 1-up; pricing 1-up |
+| Tablet | 768–1024px | Top nav tightens; feature cards 2-up; pricing 2-up |
+| Desktop | 1024–1440px | Full top-nav; 3-up feature cards; 3-4 up pricing tiers |
+| Wide | > 1440px | Same as desktop with more breathing room; max content 1280px |
+
+### Touch Targets
+- `{component.button-primary}` at minimum 40 × 40px.
+- `{component.button-icon-circular}` at exactly 36 × 36 — slightly under WCAG 44, visually centered.
+- `{component.text-input}` height is 40px.
+
+### Collapsing Strategy
+- Top nav collapses to hamburger at < 768px.
+- Hero 7-5 grid → single-column on mobile.
+- Feature card grids reduce columns rather than scaling.
+- Code-window cards retain font-size; horizontal scroll inside the card on mobile.
+- Pricing tier cards collapse 4 → 2 → 1; featured tier yellow stays distinct.
+
+### Image Behavior
+- Code blocks inside dark mockups stay at fixed font-size; horizontal scroll on mobile rather than wrapping.
+- Customer logos in monochrome strip retain native widths; row wraps on mobile.
+
+## Iteration Guide
+
+1. Focus on ONE component at a time. Reference its YAML key (`{component.code-window-card}`, `{component.pricing-tier-card-featured}`).
+2. Variants of an existing component (`-active`, `-disabled`, `-focused`) live as separate entries.
+3. Use `{token.refs}` everywhere — never inline hex.
+4. Never document hover. Default and Active/Pressed states only.
+5. Display headlines stay Inter 700 with negative letter-spacing. Body stays Inter 400.
+6. The yellow + black pairing is the brand contract. Don't soften with secondary accents.
+7. When in doubt about emphasis: bigger Inter 700 before adding color.
+
+## Known Gaps
+
+- The exact yellow hex (#faff69) was sampled from the screenshot; ClickHouse may publish an official brand color slightly differently.
+- Inter weight axis values beyond 400 / 500 / 600 / 700 are not formalized — only the static weights observed are documented.
+- Animation and transition timings (code typewriter effects, stat counter animations) are not in scope.
+- Form validation states beyond `{component.text-input-focused}` are not extracted.
+- The actual ClickHouse Cloud product surface (query console, monitoring dashboards, table browser) shares some tokens with the marketing site but adds many product-specific components that are out of scope.
+- The customer logo strip's exact opacity / treatment varies — the muted gray is approximate.