Token 系统

所有公开 CSS 变量统一使用 --scribdown- 前缀,避免与宿主环境或第三方样式发生命名冲突。整体设计入口见 设计导览,组件消费方式见 组件规范

Token 的唯一来源是 packages/ui-handdrawn/src/styles/tokens.css,本页只做说明。改 Token 一律改那个文件,不要在应用层重新定义色值。

主题机制

Token 分两层:

  • 调色板层 --scribdown-palette-light-* / --scribdown-palette-dark-*:两套主题的原始值,各定义一次。
  • 语义层 --scribdown-color-* 等:组件实际消费的变量,只做 var() 映射,不直接写色值。

主题切换即切换语义层指向哪套调色板,优先级从低到高:

场景触发方式生效规则
默认无需处理浅色
跟随系统系统开启深色@media (prefers-color-scheme: dark) 切到暗色
宿主强制根元素加 scribdown-theme-dark / scribdown-theme-light覆盖系统偏好

强制主题的两个 class 名在 @scribdown/shared 中以 SCRIBDOWN_THEME_DARK_CLASS_NAME / SCRIBDOWN_THEME_LIGHT_CLASS_NAME 导出,宿主应引用常量而非硬编码字符串。文档站的明暗按钮就是通过它接上的。

调色板层仅供 Token 内部映射使用,组件请消费语义层变量。

颜色

Token浅色暗色说明
--scribdown-color-bg#ebe1c8#1e1915主背景,暖纸色 / 夜间暖褐近黑
--scribdown-color-surface#f8f0db#2a241f卡片与内容块背景
--scribdown-color-text-primary#2f2620#ebdfcc正文主文字
--scribdown-color-text-secondary#786758#ae9b85辅助说明、次标题
--scribdown-color-accent#436b5b#7ebbab主题强调色,重点与交互态
--scribdown-color-link#355a7d#94b8de链接
--scribdown-color-link-visited#6a527b#b39bcd链接 visited 态
--scribdown-color-mark#d7ab48#d3aa57<mark> 高亮背景色
--scribdown-color-border#c5ad8a#5a4a39轻描边与分隔线
--scribdown-color-danger#a8504a#db847a错误态
--scribdown-color-warning#8d6432#d3a45fUnsupported 态
--scribdown-color-code-ink#5e5483#beacdc代码块墨色,与正文文字色区分

引用块的四个颜色由上表派生,两套主题的配比不同:

Token浅色配比暗色配比
--scribdown-color-blockquote-bgborder 18% + surfaceborder 28% + surface
--scribdown-color-blockquote-texttext-secondary 88% + surfacetext-secondary 90% + bg
--scribdown-color-blockquote-linklink 86% + text-primarylink 88% + text-primary
--scribdown-color-blockquote-link-visitedlink-visited 86% + text-primarylink-visited 88% + text-primary

纸面与阴影

Token浅色暗色说明
--scribdown-paper-grainrgba(132, 96, 44, 0.10)rgba(211, 170, 87, 0.10)纸面颗粒噪点
--scribdown-paper-fiberrgba(67, 107, 91, 0.06)rgba(126, 187, 171, 0.07)纸面纤维丝纹
--scribdown-shadow-sm2px 3px 0 rgba(47, 38, 32, 0.13)2px 3px 0 rgba(0, 0, 0, 0.36)轻浮起感
--scribdown-shadow-md4px 6px 0 rgba(47, 38, 32, 0.18)4px 6px 0 rgba(0, 0, 0, 0.48)卡片与代码块

阴影采用零模糊的偏移写法,保留手绘"墨晕"感,不做厚重浮层投影。

字体

TokenValue说明
--scribdown-font-body"Noto Serif SC Variable", "Songti SC", serif正文阅读字体,由本地 WOFF2 资产覆盖中英文
--scribdown-font-heading"LXGW WenKai Screen", "Kaiti SC", serif标题与局部强调字体,由本地 WOFF2 资产覆盖中英文
--scribdown-font-code"JetBrains Mono", "Fira Code", monospace代码字体

圆角

圆角值采用轻微不规则的四角独立写法,以呼应手绘感。同层级组件只能使用同一组半径。

TokenValue用途
--scribdown-radius-sm8px 10px 9px 11px行内元素与轻组件
--scribdown-radius-md14px 16px 13px 17px卡片、引用块、容器级背景块

间距

统一采用 4 的倍数体系。

TokenValue说明
--scribdown-space-14px最小间距
--scribdown-space-28px细小间距
--scribdown-space-312px紧凑组件间距
--scribdown-space-416px默认组件内边距
--scribdown-space-524px块级元素间距
--scribdown-space-632px大块间距
--scribdown-space-748px区域间距

动效

所有交互过渡统一走 Token,不写散落 magic number。

TokenValue说明
--scribdown-duration-fast120ms轻量反馈(hover、图标着色)
--scribdown-duration-base200ms普通过渡(侧栏开合、下拉展开)
--scribdown-easing-standardcubic-bezier(0.4, 0, 0.2, 1)默认状态切换曲线

资源与运行时变量

Token写入位置说明
--scribdown-toc-toggle-icontokens.css目录折叠箭头 SVG,inline [TOC] 与工具栏抽屉共用
--scribdown-content-width运行时写入 <html>正文最大宽度,由工具栏"页面宽度"菜单切换并持久化
--scribdown-toc-width运行时写入 .scribdown-toc-host目录侧栏宽度,默认 280px,可拖拽调整(范围 180px640px,且不超过宿主宽度的 70%)

组件内部还有一批局部变量(如代码块、表格、手绘边框的贴图与尺寸),它们定义在各自的组件样式内、作用域仅限该组件,不属于全局 Token,不应被应用层消费。

排版

正文与标题的字号阶梯定义在 markdown.css,代码相关定义在 code.css / inline.css

样式字号行高字重用途
正文16px1.65400默认正文
h134px1.2700文档主标题
h226px1.3700一级章节
h321px1.35600二级章节
h418px1.4600三级章节
h516px1.5600四级章节(同正文字号,字重区分层级)
h614px1.5600五级章节
代码块14px1.65500围栏与缩进代码块
行内代码0.86em1.2600随上下文缩放

工具栏、图注、目录等组件的字号在各自组件样式内定义,不进入本表。

落地规则

类别规则
颜色只消费语义层 --scribdown-color-*,不直接引用 --scribdown-palette-*,更不要写字面色值
主题宿主强制主题时使用 @scribdown/shared 导出的 class 常量,不硬编码字符串
间距统一采用 4 的倍数体系,容器内边距优先使用 162432
字号严格使用上表中已定义文本样式,不新增自由字号
圆角允许轻微不规则感,但同层级组件只能使用同一组半径
阴影以轻阴影或偏移感为主,不做厚重浮层投影
动效所有交互过渡统一走 Token,不写散落 magic number