COMPONENTS

这里不只列 class name，而是说明这些原语在页面系统里各自承担什么职责

组件文档要回答三件事：这个 primitive 管什么、它和 token 的边界是什么、它在真实页面里怎么被 section 复用。

BACK TO OVERVIEW OPEN SCHEMA OPEN RECIPES

PRIMITIVE CATALOG

四组最关键的基础原语

这些原语已经足够支撑黑白 intro / hiring / docs 型站点。后面要扩，也优先沿着这四组扩。

Surface

site-panel / site-panel-strong

承接所有 block 的默认卡面和重点卡面。

Typography

site-kicker / site-label / site-copy / site-note

保证黑白站的层级和信息节奏稳定。

Action

site-button-primary / site-button-secondary / site-nav-link

按钮和导航保持统一的触感与状态切换。

Tag

site-chip / site-chip-active

用于主题切换、标签展示、状态筛选。

PRIMITIVE PREVIEW

基础原语先在同一个皮肤里看清楚

先确认 surface、文字层级、动作和导航的基准触感，再谈不同站点的内容差异。

LIVE PREVIEW

Shell primitives

这些不是一次性组件，而是未来所有页面的视觉公共语法。

TYPE RHYTHM

Panel + type scale

`site-copy` 和 `site-note` 不只控制字色，也控制阅读密度。黑白站一旦节奏乱了，再漂亮的版式也会很快散掉。

NAV

OVERVIEWCOMPONENTSSCHEMA

Buttons

OPENDETAIL

Chips

NOIRFRAME

Readability

所有 primitive 都应该服务于信息密度，而不是为了“好看”各自长成一套独立审美。

BLOCK CATALOG

block 级别组件直接复用真实 renderer

文档站不应手写一套“像 renderer 的假预览”。下面这些 live block 直接复用真实 section renderer。

REAL SECTION OUTPUT

当 block 出现在 docs 站和真实站时，应该是同一个 renderer 的产物，而不是两套视觉逻辑。

{
  kind: 'spotlight',
  id: 'next-step',
  kicker: 'SPOTLIGHT',
  title: 'Ready for the next action',
  summary: 'CTA or principle block',
  body: 'Keep the copy in data, not in renderer.',
  actions: [{ label: 'Open', href: '/styles' }],
  metrics: [{ label: 'Themes', value: '3' }]
}

LIVE PREVIEW

Metrics block

kind: metrics

METRICS

Metrics block

适合把几个强信号并排呈现。

Themes

Noir / Paper / Frame

Renderer

Same layout, different documents

Routes

Host-aware

Subsite rewrite ready

Docs

Overview + Components + Schema + Recipes

LIVE PREVIEW

Timeline block

kind: timeline

TIMELINE

Timeline block

适合经历、迭代过程、里程碑。

Phase 01

Tokenize

Theme

先把背景、边框、按钮、wash 这些视觉约束提成 token。

不要把品牌 copy 放进 theme
不要复制整套页面做明暗切换

Phase 02

Render

Renderer

renderer 只关心 block 怎么排布，不关心页面的真实业务内容。

section kind 扩展比复制 route 更优先

LIVE PREVIEW

Spotlight block

kind: spotlight

SPOTLIGHT

Spotlight block

适合章节中的 CTA、原则强调或一次性结论。

这是适合放在中后段的大块强调区。它介于 hero 和普通 section 之间，适合拿来承接转场或下一步动作。

Open Schema Open Recipes

Density

High

能装正文、动作、指标

Role

CTA / Principle

不必再单写一套特殊版式

SOURCE OF TRUTH

写新组件时的判断顺序

先决定它是不是 section kind，再决定是否只是 existing block 的一个数据变体。

NEED A NEW KIND?

只有当结构真的不同，才扩 `section.kind`。只是 copy 变化，不要加新 kind。

NEED A NEW TOKEN?

只有当皮肤规律真的不同，才扩 theme token。不要为了某一页特殊感受复制全主题。

NEED A ROUTE?

route 只是 document + renderer 的装配层。不要把业务文案堆回 route。

继续看 schema，才能知道什么时候该扩 renderer

component docs 只解决“长什么样”和“怎么复用”。要真正让系统稳定，还要回到 schema 看结构边界。

OPEN SCHEMA CATALOG