Posthog

---
version: alpha
name: "Posthog"
description: "Posthog 的 DESIGN.md 中文参考模板，保留原始 design token 与专业术语，覆盖 color system、typography、layout、components、motion 与 interaction states。"
language: zh-CN
sourceLanguage: en
---

## 概览
PostHog 的 marketing system 建立在品牌核心的视觉反差上：严肃的 open-source product analytics platform，却被呈现成友好的 engineering sketchbook。Chrome 使用 warm cream canvas（`{colors.canvas}` - `#eeefe9`），不是白色；每个页面都散落着手绘 hedgehog mascot，穿 lab coat、坐 lounge chair、使用 terminal 或戴 reading glasses，像教科书页边批注一样嵌在 layout 中。Type 使用 IBM Plex Sans Variable，body 为 olive-gray（`{colors.body}` - `#4d4f46`），headline 为 deep olive-charcoal（`{colors.ink}` - `#23251d`），通过 400、600、700、800 的紧密 weight ladder 建立 hierarchy，而不依赖颜色。单一饱和 yellow-orange pill（`{colors.primary}` - `#f7a501`）是品牌唯一响亮的 chromatic moment；其它都是 cream、olive、white card 与偶尔出现的 pastel callout band。

系统有鲜明的 **two-mode body layout**：marketing page（home、workflows、pricing）使用 alternating-pastel callout band 与 cream 上的 white feature tile；documentation page 增加 sticky 240px left sidebar，内含 圆角 outline-icon section list。Code sample 是 `{colors.surface-dark}` 上的 full-width dark block，嵌在 white doc card 里，形成系统最具辨识度的视觉瞬间：cream canvas 上的 white card 内漂浮一个 dark-on-dark code island，旁边有 hedgehog mascot 涂鸦。

区块 以 `{spacing.section}` (80px) rhythm 堆叠，cream canvas 从上到下连续铺开。唯一打断 cream 的色块是 doc article 内的 pastel `{component.banner-tip-blue}` / `-green` / `-red` / `-purple` callout panel，用于 "Tip"、"Success"、"Warning"、"Info" 等 inline annotation。没有 decorative gradient、mesh 背景 或 full-bleed dark hero chapter；cream canvas 连续贯穿页面，hedgehog 是全部视觉身份。

**Key Characteristics:**
- Warm cream canvas（`{colors.canvas}` - #eeefe9）贯穿全页，没有 section surface alternation。
- Single yellow-orange CTA pill（`{colors.primary}` - #f7a501），搭配 deep olive text（`{colors.on-primary}`），是唯一饱和品牌色。
- IBM Plex Sans Variable 覆盖所有文本角色，weights 为 400/500/600/700/800。
- Hand-drawn hedgehog mascots 是完整 decoration system；没有 gradient、mesh 或 atmospheric background。
- 卡片 vocabulary 集中在 4-8px radius：标准组件用 `{rounded.md}` (6px)，少量大 container 用 `{rounded.lg}` (8px)，pill chip 用 fully rounded。
- Pastel callout banner（`{colors.accent-blue-soft}`、`{colors.accent-green-soft}`、`{colors.accent-red-soft}`、`{colors.accent-purple-soft}`）用于 docs 内的 tips / warnings / info。
- Documentation page 增加 sticky 240px `{component.doc-sidebar}`，顶部有 "Ask PostHog AI" CTA。

## Colors

> **Source pages:** `/`、`/pricing`、`/docs/product-analytics`、`/workflows`。Chrome palette 四页一致，doc-specific accent 只在 docs experience 内出现。

### Brand & Accent
- **PostHog Yellow** (`{colors.primary}` - `#f7a501`): universal primary CTA。用于 top-right sticky "Get started - free" pill、hero CTA、pricing subscribe button、footer signup pill，是系统唯一饱和 chromatic moment。
- **Yellow Pressed** (`{colors.primary-pressed}` - `#dd9001`): primary pill pressed state。
- **Yellow Active** (`{colors.primary-active}` - `#b17816`): 深按黄色，也作为少见的 gold-toned 边框 accent。

### Surface
- **Canvas** (`{colors.canvas}` - `#eeefe9`): warm cream page background，是品牌最具辨识度的 surface choice。
- **Soft Surface** (`{colors.surface-soft}` - `#e5e7e0`): secondary button fill、sub-nav strip、inline-code chip background。
- **Surface Card** (`{colors.surface-card}` - `#ffffff`): 位于 cream canvas 上的 true white card / tile background。
- **Surface Doc** (`{colors.surface-doc}` - `#fcfcfa`): doc article body card 中的 warm-white，比纯白更柔和。
- **Surface Dark** (`{colors.surface-dark}` - `#23251d`): deep olive-charcoal code-block background，与 `{colors.ink}` 同 hex。
- **Hairline** (`{colors.hairline}` - `#bfc1b7`): card border、table rule、footer column divider。
- **Hairline Soft** (`{colors.hairline-soft}` - `#dcdfd2`): in-card row divider 与 soft inset rule。
- **On Dark** (`{colors.on-dark}` - `#ffffff`): `{colors.surface-dark}` code block 上的 primary text。

### Text
- **Ink** (`{colors.ink}` - `#23251d`): headline、button text、primary nav link。
- **Body** (`{colors.body}` - `#4d4f46`): default paragraph、doc article body、inline link before focus。
- **Charcoal** (`{colors.charcoal}` - `#33342d`): body 太软时的 emphasized body text。
- **Mute** (`{colors.mute}` - `#6c6e63`): metadata、footer link、in-list secondary annotation。
- **Ash** (`{colors.ash}` - `#9b9c92`): disabled-state 文本 与 lowest-emphasis utility。
- **Stone** (`{colors.stone}` - `#b6b7af`): least-emphasis caption 与 disabled icon color。

### Semantic Colors
- **Link Blue** (`{colors.link-blue}` - `#1d4ed8`): body prose 内 inline anchor link。
- **Link Teal** (`{colors.link-teal}` - `#1078a3`): doc article inline link variant。
- **Accent Blue** (`{colors.accent-blue}` - `#2c84e0`) + **Accent Blue Soft** (`{colors.accent-blue-soft}` - `#dceaf6`): docs 内 "Tip / Info" callout。
- **Accent Red** (`{colors.accent-red}` - `#cd4239`) + **Accent Red Soft** (`{colors.accent-red-soft}` - `#f7d6d3`): "Warning / Caution" callout。
- **Accent Green** (`{colors.accent-green}` - `#2c8c66`) + **Accent Green Soft** (`{colors.accent-green-soft}` - `#d9eddf`): "Success / Positive" callout。
- **Accent Purple** (`{colors.accent-purple}` - `#7c44a6`) + **Accent Purple Soft** (`{colors.accent-purple-soft}` - `#e7d8ee`): "Note / Reference" callout。
- **Focus Ring** (`{colors.focus-ring}` - `rgba(59,130,246,0.5)`): interactive element 周围的半透明 blue browser-default focus ring。

## Typography

### Font Family
**IBM Plex Sans Variable** 是系统 primary face，所有页面所有文本角色均使用，weights 包含 400 regular、500 medium、600 semibold、700 bold、800 extra-bold。Fallback chain 为 `IBM Plex Sans` -> `-apple-system` -> `system-ui` -> broad sans stack。

**ui-monospace** + **Source Code Pro** 承载 code sample 与 inline-code chip，尺寸 14px / 1.43 line-height。Source Code Pro 是显式 display monospace，ui-monospace 用于 inline `<code>` chip。

品牌特征来自 **mixed weight ladder**（400 / 500 / 600 / 700 / 800）。大多数 chrome 在 400-700 范围内，800 只保留给 home 与 pricing 上的大 display headline，让系统带有 engineering blog 感：hierarchy 主要来自 weight contrast。

### Hierarchy

| Token | Size | Weight | Line Height | Letter Spacing | 用途 |
|---|---|---|---|---|---|
| `{typography.display-xl}` | 36px | 700 | 1.5 | 0 | 英雄区 headline |
| `{typography.display-lg}` | 24px | 800 | 1.33 | -0.6px | 区块 headline、pricing tier name |
| `{typography.heading-lg}` | 21px | 700 | 1.4 | -0.5px | Sub-section heading、doc H2 |
| `{typography.heading-md}` | 20px | 700 | 1.4 | 0 | 卡片 group title、in-grid heading |
| `{typography.heading-sm}` | 18px | 700 | 1.5 | 0 (uppercase) | 区块 eyebrow |
| `{typography.heading-sm-mixed}` | 18px | 600 | 1.56 | 0 | Mixed-case card title |
| `{typography.body-md}` | 16px | 400 | 1.5 | 0 | 正文 copy、default paragraph |
| `{typography.body-strong}` | 16px | 600 | 1.5 | 0 | Inline emphasis、primary nav link |
| `{typography.body-sm}` | 15px | 400 | 1.71 | 0 | Doc body、marketing card description |
| `{typography.body-sm-strong}` | 15px | 600 | 1.71 | 0 | Doc article 内 sub-section emphasis |
| `{typography.body-xs}` | 14px | 500 | 1.43 | 0 | Doc sidebar item、metadata |
| `{typography.caption-md}` | 14px | 700 | 1.71 | 0 | 卡片 eyebrow、link cluster header |
| `{typography.caption-sm}` | 13px | 500 | 1.5 | 0 | Compact metadata caption |
| `{typography.caption-xs}` | 12px | 600 | 1.33 | 0 (uppercase) | Inline badge label |
| `{typography.utility-xs}` | 12px | 700 | 1.33 | 0 (uppercase) | 区块 eyebrow、footer category header |
| `{typography.link-md}` | 16px | 400 | 1.5 | 0 | Inline body anchor link |
| `{typography.button-md}` | 14px | 700 | 1.5 | 0 | Standard button label |
| `{typography.button-sm}` | 13px | 500 | 1 | 0 | Pill chip / compact CTA |
| `{typography.code-sm}` | 14px | 400 | 1.43 | 0 | Code block content |
| `{typography.code-xs}` | 14px | 500 | 1.43 | 0 | Inline code chip |

### Principles
Hierarchy 明确由 weight + size + occasional uppercase transform 构成；没有 italic、decorative display variant 或 proprietary face。最大 display moment 使用 weight 800 与 -0.6px tracking，body 固定在 400 / 1.5 line-height。区块 eyebrow（`{typography.heading-sm}` 与 `{typography.utility-xs}`）持续 uppercase，形成 textbook-chapter 感。

### Font Substitutes
IBM Plex Sans Variable 是开源且可从 Google Fonts 加载，优先直接使用。若必须替代，**Inter** 是五个 weight 上最接近的 geometric match；display size 可设置 -0.5 到 -0.6px letter-spacing。Monospace 可用 **JetBrains Mono** 近似 Source Code Pro。

## Layout

### Spacing System
- **Base unit:** 8px；2/4/6px 用于 callout banner 与 pill button 的 tight inline gap。
- **Tokens:** `{spacing.xxs}` (2px) · `{spacing.xs}` (4px) · `{spacing.sm}` (8px) · `{spacing.md}` (12px) · `{spacing.lg}` (16px) · `{spacing.xl}` (24px) · `{spacing.xxl}` (32px) · `{spacing.section}` (80px)。
- **Universal section rhythm:** major content block 之间使用 `{spacing.section}` (80px)。卡片 grid 使用 `{spacing.lg}` (16px) gutter；product card internal 内距 为 `{spacing.xl}` (24px)，pricing tier card 为 `{spacing.xxl}` (32px)。

### Grid & Container
- **Max width:** desktop content area 约 1280px，gutter 24px，ultrawide 约 48px。Doc article body max-width 约 720px，240px sidebar 将 article column 推到中心偏右。
- **Marketing card grid:** desktop 4-up，1024px 3-up，768px 2-up，480px 1-up；card 保持 1:1 或 4:3。
- **Pricing tier grid:** desktop 3-up，tablet 折为 2-up + 1，mobile 1-up。
- **Doc layout:** desktop 为 240px sticky left sidebar + 720px article body + optional 200px right TOC rail。
- **Footer:** desktop 6-column link grid，tablet 3-up，mobile 2-up。

### Whitespace Philosophy
Marketing page whitespace 宽松，doc page 更紧凑。Home 与 workflows 用 `{spacing.lg}` (16px) gutter 和 24px internal 内距 堆叠 feature tile；doc article 将 paragraph 间距压到 `{spacing.md}` (12px) 以提升信息密度。Cream canvas 连续穿过所有 section，没有 decorative divider 或 shaded section band；内容分隔主要依赖 eyebrow 下方 1px hairline 与 footer column rule。

## Elevation & Depth

| Level | Treatment | 用途 |
|---|---|---|
| 0 - Flat | No border, no shadow | Canvas-on-canvas block、hero text、body section |
| 1 - Hairline 边框 | 1px solid `{colors.hairline}` | Marketing card、pricing tier card、doc sidebar item、footer column rule |
| 2 - Hairline soft | 1px solid `{colors.hairline-soft}` | In-card adjacent row divider |
| 3 - Inverted dark code block | `{colors.surface-dark}` fill | Doc card 内 code sample；唯一通过颜色而非 shadow 实现的 elevated surface |

系统在 marketing / product chrome 中没有 drop-shadow elevation。卡片 平铺在 cream 上，只以 thin olive 边框 区分。唯一反相时刻是 doc article body card 内的 dark code-block surface。

### Decorative Depth
- **Hand-drawn hedgehog mascots**：各种装扮的角色作为 marginalia 散落在页面中，始终是 flat color illustration。
- **Pastel callout banners**：`{component.banner-tip-blue}` / `-green` / `-red` / `-purple` 作为 docs 内 soft tinted side-rail panel，配合 emoji icon。
- **Code blocks**：`{colors.surface-dark}` 上的 full-width dark olive-charcoal panel，白色 code text，是系统最 cinematic 的 surface。
- **Outline product icons**：doc sidebar 中的小 rounded-square mini-illustration 标记 product section。

## Shapes

### Border Radius Scale

| Token | Value | 用途 |
|---|---|---|
| `{rounded.none}` | 0px | Sub-nav strip、footer、doc sidebar、primary nav |
| `{rounded.xs}` | 2px | Inline `<code>` chip、micro-rule highlight |
| `{rounded.sm}` | 4px | Inline button、form input、micro chip |
| `{rounded.md}` | 6px | Marketing card、pricing card、doc card、code block、standard CTA |
| `{rounded.lg}` | 8px | Tab top corner 与 rare large container |
| `{rounded.full}` | 9999px | Pill chip 与 pill-style CTA |

Radius vocabulary 主要集中在 4-6px；唯一 fully-圆角 element 是 sticky nav CTA 与 inline pill chip。

### Photography Geometry
系统不使用 photography。Visual element 包括：
- **Hedgehog character illustrations**：80px 到 240px 的 flat-color cartoon hedgehog，保持 native aspect，不裁切到 frame。
- **Outline product icons**：doc sidebar 中 20-24px rounded-square illustration。
- **Inline emoji**：callout banner 内 14-16px，作为功能 iconography。
- **区块 illustrations**：home page feature row 中与功能主题配对的小 hedgehog vignette。

## Components

> 按 system policy 不记录 hover state。每个 spec 只覆盖 Default 与 Active/Pressed。

### Buttons

**`button-primary`** — universal PostHog CTA
- 背景 `{colors.primary}`，文本 `{colors.on-primary}`，字体 `{typography.button-md}`，内距 `8px 16px`，高度 `40px`，圆角 `{rounded.md}`。
- 用于 "Get started - free"、"Sign up"、"Try it free"、"Subscribe" 等 primary action。
- 按下状态 `button-primary-pressed` 将 背景 降到 `{colors.primary-pressed}`。

**`button-secondary`** — cream canvas 上的 soft alternative。
- 背景 `{colors.surface-soft}`，文本 `{colors.ink}`，字体 `{typography.button-md}`，内距 `8px 16px`，高度 `40px`，圆角 `{rounded.md}`。
- 用于 "Talk to sales"、"Read docs"、"Watch demo" 等 second-tier action。

**`button-tertiary`** — ghost 文本 button。
- 背景 transparent，文本 `{colors.ink}`，字体 `{typography.button-md}`，内距 `8px 12px`，圆角 `{rounded.md}`。
- 用于低强调 action，如 "See all docs ->"、"Browse all features"。

**`button-disabled`**
- 背景 `{colors.surface-soft}`，文本 `{colors.ash}`。

### Tabs & Chips

**`product-tab`** + **`product-tab-active`**
- 默认: transparent background，文本 `{colors.body}`，字体 `{typography.body-strong}`，内距 `8px 12px`，圆角 `{rounded.md}`。
- 激活: 背景 切为 `{colors.surface-card}`，文本 `{colors.ink}`，以 white tab card 从 cream canvas 上浮出作为 selection signal。

**`pill-tab`** + **`pill-tab-active`**
- 默认: transparent background，文本 `{colors.body}`，字体 `{typography.button-sm}`，内距 `6px 14px`，圆角 `{rounded.full}`。
- 激活: 背景 `{colors.ink}`，文本 `{colors.on-dark}`，selection 时完全反相。

**`badge-uppercase`**
- 背景 transparent，文本 `{colors.body}`，字体 `{typography.utility-xs}` uppercase，用作 category prefix。

**`badge-promo`**
- 背景 `{colors.accent-blue-soft}`，文本 `{colors.link-blue}`，字体 `{typography.caption-xs}`，内距 `2px 8px`，圆角 `{rounded.full}`。
- 用于 "New"、"Beta"、"Coming soon" 等小 pill label。

### Inputs & Forms

**`text-input`** + **`text-input-focused`**
- 默认: 背景 `{colors.surface-card}`，文本 `{colors.ink}`，1px solid `{colors.hairline}`，字体 `{typography.body-md}`，内距 `8px 12px`，高度 `36px`，圆角 `{rounded.md}`。
- 聚焦: surface 不变；2px solid `{colors.accent-blue}` 边框 替换 1px hairline，并加 translucent `{colors.focus-ring}` outline。

**`search-input`** — doc sidebar 与 "Ask PostHog AI" search field。
- 与 `text-input` 尺寸一致，左侧带 `{colors.mute}` magnifier glyph。

### Cards & Containers

**`product-card`** — marketing tile / feature card。
- 容器: 背景 `{colors.surface-card}`，1px solid `{colors.hairline}`，内距 `{spacing.xl}`，圆角 `{rounded.md}`。
- 布局: 顶部左侧小 hedgehog illustration，`{typography.heading-sm-mixed}` title，`{typography.body-sm}` description，可选 `{component.button-tertiary}` "Learn more ->"。

**`doc-card`** — doc article body card。
- 容器: 背景 `{colors.surface-doc}`，1px solid `{colors.hairline}`，内距 `{spacing.xl}`，圆角 `{rounded.md}`。
- 承载 doc page 内的 article body section、code block、callout banner 与 table。

**`feature-tile`** — small marketing feature tile。
- 容器: 背景 `{colors.surface-card}`，1px solid `{colors.hairline}`，内距 `{spacing.lg}` (20px)，圆角 `{rounded.md}`。
- 用于 home 与 workflows page 的 3-up / 4-up grid，配小 icon 与一行 description。

**`pricing-tier-card`**
- 容器: 背景 `{colors.surface-card}`，1px solid `{colors.hairline}`，内距 `{spacing.xxl}`，圆角 `{rounded.md}`。
- 布局: tier name 使用 `{typography.display-lg}`，大 price + period，feature checklist 带 check-icon bullet，底部 primary 或 secondary CTA。

**`hedgehog-mascot-card`** — margin-anchored hedgehog 的 feature card。
- Chrome 同 `{component.product-card}`，但手绘 hedgehog illustration 锚定在右侧 margin 或 top-right corner，是品牌 signature card variant。

### Callout Banners

**`banner-tip-blue`** + **`banner-tip-green`** + **`banner-tip-red`** + **`banner-tip-purple`**
- 背景 `{colors.accent-blue-soft}` / `{colors.accent-green-soft}` / `{colors.accent-red-soft}` / `{colors.accent-purple-soft}`，文本 `{colors.ink}`，字体 `{typography.body-md}`，内距 `16px 20px`，圆角 `{rounded.md}`。
- 每个 banner 前缀 inline emoji icon（💡 / ✅ / ⚠️ / 📘），后接 inline label 与 body copy。
- 只出现在 doc article body 内，是 long-form docs 的 tip / warning / info vocabulary。

### Code

**`code-block`** — doc card 内 dark code sample。
- 容器: 背景 `{colors.surface-dark}`，文本 `{colors.on-dark}` in `{typography.code-sm}`，内距 `16px 20px`，圆角 `{rounded.md}`。
- Syntax highlight 使用 muted accent（keyword blue、string green、number purple），不使用 callout banner 的 bright accent。

**`inline-code`** — inline `<code>` chip。
- 背景 `{colors.surface-soft}`，文本 `{colors.ink}` in `{typography.code-xs}`，内距 `2px 6px`，圆角 `{rounded.xs}`。
- 用于 body prose 中的 code snippet 与 identifier。

### 导航

**`primary-nav`**
- 背景 `{colors.canvas}`，文本 `{colors.ink}`，高度 `56px`，字体 `{typography.body-strong}`，圆角 `{rounded.none}`。
- Desktop layout: 左侧 PostHog wordmark + hedgehog logo，中间 nav menu cluster，右侧 search glyph、"Login" link 与黄色 `{component.button-primary}` "Get started - free"。

**`sub-nav-strip`**
- 背景 `{colors.surface-soft}`，文本 `{colors.body}` in `{typography.body-xs}`，高度 `40px`，圆角 `{rounded.none}`。
- 位于 workflows / product page 的 primary nav 下方，包含 section anchor link 与右侧 contextual "Get started ->"。

**`doc-sidebar`**
- 背景 `{colors.canvas}`，文本 `{colors.body}` in `{typography.body-xs}`，width `240px`，圆角 `{rounded.none}`。
- 布局: 顶部 search-input "Ask PostHog AI"，下方为带 圆角 outline-icon mini-illustration 的 section header list，active header 下缩进 nested item link。

**Top Nav (Mobile)**
- 左侧 hamburger，中央 PostHog wordmark + hedgehog，右侧 search + sticky yellow "Get started - free" CTA。Primary nav 折叠为从左侧滑入的 full-高度 drawer。

### Footer

**`footer-section`**
- 背景 `{colors.canvas}`，文本 `{colors.body}` in `{typography.body-xs}`，内距 `32px 24px`，圆角 `{rounded.none}`，顶部 1px `{colors.hairline}` rule。
- 布局: 6-column link grid，column header 用 `{typography.utility-xs}` uppercase，link list 用 `{typography.body-xs}` `{colors.body}`。
- Bottom row: PostHog wordmark + 小 hedgehog illustration，copyright 使用 `{typography.caption-xs}` `{colors.mute}`，social-icon row 在 far-right。

### Inline Elements

**`link-inline`**
- Body-prose anchor link 使用 `{colors.link-teal}` (`#1078a3`)，默认无 underline，focus 时出现 underline。它是品牌 primary inline link color。

## 使用建议与禁忌

### 应该
- 使用 `{colors.canvas}`（cream - `#eeefe9`）作为 page body，不要替换为 pure white。
- `{colors.primary}` 只保留给 primary CTA pill。"Get started - free" 是品牌锚点。
- Wordmark 需与 hedgehog illustration 一起呈现；hedgehog 本身就是 brand identity。
- 所有文本角色使用 IBM Plex Sans Variable：body 400，emphasis 600/700，display 800。
- 区块 以 `{spacing.section}` (80px) rhythm 堆叠，不加 decorative divider，让 cream canvas 连续铺开。
- `{component.banner-tip-blue}` / `-green` / `-red` / `-purple` 只用于 doc article body 的 tip / warning / note panel。
- Code sample 使用 dark `{component.code-block}`；inline `<code>` chip 使用 `{component.inline-code}`。
- Home 与 workflows 的 feature tile margin 中锚定 hedgehog mascot illustration，这是系统 signature decoration。

### 不要
- 不要给 card 添加 drop shadow。卡片 只以 thin olive 边框 平铺在 cream 上。
- 不要增加第二个饱和 CTA 色；yellow-orange 是唯一 loud color。
- 不要把 cream canvas 替换成 pure white 或 full-bleed dark hero band。
- 不要将四种 callout banner pastel 用作 marketing-card background，它们只属于 inline doc content。
- 不要用 generic icon set 代替 hedgehog illustration。
- 不要在 `{typography.heading-sm}`、`{typography.utility-xs}`、`{typography.caption-xs}` 之外使用 uppercase transform。
- 除 `{component.pricing-tier-card}` 外，不要给标准 card 使用 32px+ 全边 padding；standard card 内距为 24px。

## Responsive Behavior

### Breakpoints

| Name | Width | Key Changes |
|---|---|---|
| ultrawide | 1920px+ | Content max-width 保持 1280px；outer gutter 增至约 80px |
| desktop-large | 1440px | 默认 4-up feature tile grid，240px sticky doc sidebar 可见 |
| desktop | 1280px | 同 layout，但 outer gutter 更窄 |
| desktop-small | 1024px | 4-up tile 收为 3-up；doc sidebar 仍可见 |
| tablet | 768px | 3-up tile 收为 2-up；doc sidebar 折叠为 top accordion；primary nav 变为 hamburger |
| mobile | 480px | 全部单列；hero `{typography.display-xl}` 从 36px 缩到约 28px |
| mobile-narrow | 320px | 区块 内距 收紧到 32px |

### Touch Targets
所有 interactive element 满足 WCAG AA（>= 40x40px）。`{component.button-primary}` 与 `{component.button-secondary}` 高 40px；`{component.text-input}` 高 36px；`{component.pill-tab}` 通过 inline 内距 扩展到约 44px tappable；doc-sidebar item 以 14px text、约 32px line-高度 与 6px vertical 内距 形成约 44px tap row。

### Collapsing Strategy
- **Primary nav:** desktop horizontal cluster -> tablet 768px hamburger drawer。黄色 "Get started - free" CTA 全断点保持可见。
- **Sub-nav strip:** desktop horizontal anchor row -> tablet horizontal scroll -> mobile select dropdown。
- **Marketing card grid:** 4-up -> 3-up -> 2-up -> 1-up，断点为 1024、768、480px；mobile gutter 从 16px 降到 12px。
- **Pricing grid:** 3-up -> 2+1 -> 1-up。
- **Doc layout:** desktop 240px sidebar + 720px article -> tablet sidebar top accordion -> mobile fully collapsed accordion。
- **Footer:** 6-up column -> tablet 3-up -> mobile 2-up。
- **区块 padding:** `{spacing.section}` 80px desktop -> 64px tablet -> 48px mobile。
- **英雄区 headline:** `{typography.display-xl}` 36px desktop，mobile 约 28px，line-高度 保持 1.5。

### Image Behavior
系统唯一 imagery 是 hand-drawn hedgehog illustration，作为 inline SVG 渲染。它们在所有 breakpoint 保持自然 aspect，通过 CSS `width: auto; max-width: 100%` 缩放。不需要 responsive art-direction，因为没有 photography。

## Iteration Guide

1. 一次只聚焦 ONE component。读取其 YAML entry 并验证所有 property 可解析。
2. 直接引用 component name 与 token（`{colors.primary}`, `{component.button-primary-pressed}`, `{rounded.md}`），不要改写。
3. 修改后运行 `npx @google/design.md lint DESIGN.md`；`broken-ref`、`contrast-ratio`、`orphaned-tokens` warning 会暴露问题。
4. 新 variant 作为独立 component entry 添加（`-pressed`, `-disabled`, `-focused`），不要埋在 prose 内。
5. 正文 默认 `{typography.body-md}` (16px / 400 / 1.5)；emphasis 用 `{typography.body-strong}`；`{typography.display-lg}` 严格保留给 marketing display moment。
6. 每个 viewport 保持 `{colors.primary}` 稀缺，最多一个 yellow-orange pill per fold。
7. 新增 component 前先判断是否能用现有 card + 6px-radius + cream-canvas vocabulary 表达。系统强项是几乎不需要新 token。

## Known Gaps

- **Mobile screenshots not captured**：responsive behavior 基于 PostHog mobile pattern（hamburger drawer、single-column grid、doc sidebar accordion）与 breakpoint stack 推断。
- **Hover states not documented**：符合 system policy。
- **In-product app chrome**（dashboard、charts、session replay player）不在捕获范围；本文记录 marketing site。
- **Authenticated chrome**（login modal、account dashboard、billing settings）不在捕获页面中。
- **Form validation states**：除 focused-state input 外未捕获。
- **Marketing illustration set**：完整 hedgehog pose library 未枚举；已记录截图中可见的 lab coat、terminal、hammock 等特定姿态。