组件 / 展示

长文与代码

.zz-prose 负责正文：15px / 1.65 行高、次级文字色、宽度锁在var(--zz-measure)（48rem）；标题回落 sans 600、字距 -0.01em、上间距 2em。代码分两档：行内 code 坐 --zz-surface-2，整块代码坐--zz-bg-deep 凹槽并补 1px 描边。

长文

下面整块都是 .zz-prose 内的原生 HTML，没有任何额外类名。

为什么默认等宽

全站默认字体是 --font-mono，只有标题、卡片标题、表头、统计大数字和显式 UI 标签回到 sans。正文色是 --zz-text-secondary，需要强调时用strong 拉回 --zz-text；链接常驻下划线，下划线颜色是 --zz-brand，例如排版。

最大宽度锁在 48rem：等宽字体的行宽比比例字体更容易失控，超过这个宽度眼睛回行就会丢行。

面的三层

--zz-bg-deep：凹槽，代码块与媒体井
--zz-surface：面板，卡片与表头
--zz-surface-2：交互面，悬停底与行内 code

先选层级，再选颜色
圆角恒为 0
浮起只用 --zz-elevation

引用块只有一条 2px 品牌色左线，文字退回次级，不上斜体、不加引号图标。

行内代码与整块代码

行内的 --zz-measure 用 --zz-surface-2 底、0.86em、内距0.125rem 0.3125rem。

/* 整块代码：凹槽底 + 1px 描边，横向溢出自己滚 */
.zz-prose pre {
  background: var(--zz-bg-deep);
  box-shadow: var(--zz-elevation);
  padding: 1em 1.25em;
  overflow-x: auto;
}

元素	字号	颜色
正文	15px	次级
h2	1.25rem	主文字
图注	13px	muted

图注 13px，色 --zz-text-muted；正文图片自带 1px 内描边，和媒体井同一套规则。

提示块

提示块是长文里唯一的 2px 左线元素：默认品牌色，--note 退回控件级描边，--info / --warning / --danger / --success换状态色。底色统一是 --zz-surface，不叠透明色。

代码块

头栏是 0.75rem mono 的 --zz-text-muted，下边框发丝线；代码区1em 1.25em 内距、横向滚动。行号由 CSS 计数器生成，不写进内容，复制时不会带上数字。

astro

---import Card from '@/components/ui/Card.astro'--- <Card title="Tokyo Night" href="/themes" />

packages/design-system/src/styles/components/card.css

.zz-card {  box-shadow: var(--zz-elevation);  transition-duration: 150ms;  /* 悬停只换 elevation-hover：同一几何，只改 alpha */}

bash

pnpm add @hsinyau/design-system

用法

---
import Callout from '@/components/ui/Callout.astro'
import CodeBlock from '@/components/ui/CodeBlock.astro'
---

<div class="zz-prose">
  <h2>标题</h2>
  <p>正文……<a href="/foundations/color">链接</a>。</p>
</div>

<Callout variant="warning" title="注意">…</Callout>

<CodeBlock lang="ts" lineNumbers code="const a = 1" />

<CodeBlock title="packages/design-system/src/styles/tokens.css">
  <span class="zz-code__line"><span class="zz-tok-key">color</span>: <span class="zz-tok-num">0</span>;</span>
</CodeBlock>

用根槽给内容时，每一行包一个 .zz-code__line（可选外层.zz-code__lines）：行内容由 white-space: pre 保留缩进，行与行之间的换行不会多出空行。

类名与 token

类名	作用
`.zz-prose`	长文容器：15px / 1.65、`--zz-text-secondary`、`max-width: var(--zz-measure)`
`.zz-prose h2 \| h3 \| h4`	sans 600、`letter-spacing: -0.01em`、上间距 `2em`、字号 1.25 / 1.05 / 0.9375rem
`.zz-prose p`	下边距 `1em`（只有下边距，标题的上间距才不会被叠掉）
`.zz-prose ul \| ol`	方点标记（`::marker` 取 `--zz-text-muted`），缩进 `1.25em`
`.zz-prose blockquote`	2px `--zz-brand` 左线，文字 `--zz-text-secondary`
`.zz-prose code`	行内代码：`--zz-surface-2` 底、0.86em、内距 `0.125rem 0.3125rem`
`.zz-prose pre`	`--zz-bg-deep` 底 + `--zz-elevation` 描边、内距 `1em 1.25em`、横向滚动
`.zz-prose pre code`	清掉行内底与内距，字号继承整块设置
`.zz-prose img`	`--zz-img-outline` 的 1px 内描边，下边距 `1em`
`.zz-prose figcaption`	13px `--zz-text-muted`，上边距 `0.5rem`
`.zz-prose__callout` + `--note \| --brand \| --info \| --warning \| --danger \| --success`	提示块：2px 左线，`--warning` 用 `var(--zz-warning)`
`.zz-prose__callout__title`	提示块标题：0.8125rem sans 600，色 `--zz-text`
`.zz-code`	代码块外框：`--zz-border-subtle` 描边 + `--zz-bg-deep` 底 + `--zz-elevation`
`.zz-code__head`	头栏：0.75rem mono `--zz-text-muted`、下边框发丝线、内距 `0.5rem 1rem`
`.zz-code__pre` / `.zz-code__code`	代码区：0.8125rem / 1.7、横向滚动、`--zz-scroll-thumb` 细滚动条
`.zz-code--numbered`	行号：CSS 计数器，`::before` 宽 `2ch`、`user-select: none`
`.zz-code__line`	一行：`display: block` + `white-space: pre`（保留缩进）
`.zz-tok-key` / `.zz-tok-num` / `.zz-tok-muted`	语法着色只有三个类：青（`--zz-code-key`）、橙（`--zz-code-number`）、注释灰（`--zz-text-muted`）

可访问性

标题层级不跳级：正文里的第一层用 h2、其下用 h3，读屏用户靠这个建立目录。
代码块固定用 <pre><code>，行号是 ::before 的生成内容并对复制隐藏，读屏也不会把数字念进代码里。
链接文字要能单独读懂，避免"点这里"；链接常驻下划线，不靠颜色单独区分。
图注用 <figcaption> 而不是斜体段落；纯装饰图片写 alt=""。
提示块用 <aside>：它是旁注，读屏会作为补充区域处理；语义不能只靠左线颜色，标题里要写清是"注意"还是"危险"。
行与行之间的过渡只发生在颜色上，且都走 var(--zz-dur) var(--zz-ease)；系统开启"减弱动效"时不需要额外降级。