vellum-editorial

用途

Vellum Editorial 用于搭建「编辑型文档站点」，即带有手稿／档案质感的文档、产品概览与技术说明页面。它输出静态 HTML，无需构建步骤，可部署到 Cloudflare Pages、GitHub Pages 或任意静态托管。配套提供脚手架脚本、设计令牌、组件目录与页面架构参考文档，并可与 beautiful-mermaid 技能结合，将 Mermaid 图表渲染为内联 SVG。

主题与视觉方向

提供两种主题变体，二者共享同一排版、组件库与布局系统，调色板仅通过 :root 自定义属性切换，无需改动结构性 CSS：

暖色（默认）：「羊皮纸手稿」——暖奶油色背景配轻微 SVG 交叉网格纹理，深墨棕色文字，铜色点缀，具权威书面感。
深色：「太空档案」——深蓝黑背景配 CSS 星空（box-shadow 星点加星云渐变），明亮金铜色点缀，冷蓝灰文字，具指挥中心或数字考古站点氛围。

主要能力

三种字体：Bodoni Moda（标题／展示，含斜体）、Source Serif 4（正文）、Inconsolata（等宽／标签／徽章），均来自 Google Fonts。
OKLCH 调色板，50 余个自定义属性，按语义颜色组织为 base/bg/border 三元组。核心调色板包括 --ink、--copper、--bg、--bg-warm、--bg-card、--border、--text-body、--text-label、--text-muted、--ghost；另含导航状态、严重度分级（--dealbreaker、--high、--moderate）、平台色（--subq、--claude、--cursor、--codex）、状态指示（--planned、--building、--shipped、--blocked）以及用于按时代或类别组织的 --era-* 三元组。
35 个组件，分 7 组：布局（面包屑、页内导航、页头、区块、页脚）、卡片（state-card、hook-card、cap-panel、further-card、quote-card、req-card）、数据展示（matrix、matrix-note、glossary、ring、debugger-panel）、指示器（status-dot、status-chip、tier-badge、chip）、编辑类（toc、pullquote、savings-callout、supersession、advantage-row、phase-timeline）、情报类（dossier、stat-stack、utterance、editorial-note、entity-flow、fact-block、sub-navigation、source-list）、媒体（subject-intro、stat-bar、带灯箱的 hero-image、gallery/masonry-grid、audio-player）。每个组件支持多种配色变体。
六种页面模式：落地页、深挖页、区块中心页、人物档案页、功能对比页、分析／影响页。
每个页面均包含跳过链接、_shared.css、_components.css、Google Fonts preconnect 与 Phosphor Icons CDN；启用时认证门脚本在 body 内容前加载，音频播放器脚本在 body 末尾加载。

使用方式

脚手架创建项目：

python3 ~/.claude/skills/vellum-editorial/scripts/init_project.py <project-name> \
  [--style editorial|instrument] [--template landing|one-pager] \
  [--pages N] [--theme warm|dark] [--auth] [--no-auth] \
  [--password <string>] [--deploy-ready] [--no-deploy-ready] \
  [--audio] [--no-audio]

样式控制视觉风格：editorial（默认，Bodoni Moda／Source Serif 4 排版，SVG 交叉网格纹理，学术手稿感）或 instrument（Manrope 排版，网格点纹理，精密仪表盘感，适合技术产品概览）。

模板控制内容结构：landing（默认，含概览、特性、对比的三区块页面）或 one-pager（含目录、状态卡网格、配置矩阵、阶段时间线与部署区块的八区块技术概览）。

定制化：编辑 _shared.css 中的 :root 自定义属性即可适配不同客户。主题选择在脚手架阶段确定；颜色替换约需 5 分钟（改 --copper 色相、调整 --ink/--bg 暖度、更新平台色）；语义重命名约 30 分钟（如将 --subq 改为 --brand-primary 并更新对应 CSS 类变体）；还可添加 --era-* 三元组及新组件变体。

图表（可选）：页面可内联由 beautiful-mermaid 生成的 SVG 图表，无 JavaScript 依赖。生成示例：

printf 'graph TD\n  A --> B --> C' | \
  node ~/.claude/skills/beautiful-mermaid/scripts/mermaid.mjs \
  -f svg -t vellum --transparent -o diagram.svg -

vellum 主题使用与设计系统一致的奶油／墨／铜色，--transparent 让面板的 --bg-card 背景透出；支持流程图、状态图、序列图、类图、ER 图。

部署到 Cloudflare Pages：

wrangler pages project create <project-name> --production-branch main
wrangler pages deploy <project-dir> --project-name <project-name>
curl -sI https://<project-name>.pages.dev/ | grep -iE 'x-robots|x-frame|content-security'

社交预览图（OG 图）：脚手架页面含指向 og-image.png 的 OG 与 Twitter Card 元标签，可用 ImageMagick 生成 1200x630 图片：

magick -size 1200x630 xc:'#111111' \
  -gravity West -font Inconsolata-Bold -pointsize 52 \
  -fill '#C4956A' -annotate +140+0 'Project Title' \
  -pointsize 22 -fill '#8A8A8A' -annotate +140+50 'Subtitle line' \
  og-image.png

QA 工作流

构建页面后按顺序运行：/design-audit（无障碍、性能、响应式、主题、反模式等技术检查）、/design-critique（基于 Nielsen 启发式、认知负荷、人物画像红旗的 UX 评审）、/design-polish（对齐、间距、交互状态、过渡的最终打磨）。

认证门

可选的客户端礼貌性门禁，使用 FNV-1a 哈希加 sessionStorage，并非真正安全，仅用于非公开文档的可见性控制。脚手架时用 --password <string> 设置密码，初始化脚本自动计算哈希并写入 auth.js；每个项目有唯一 sessionStorage 键（vellum_auth{project-name}）以避免跨站冲突。

适用场景

适合需要手稿或档案质感的文档站、产品概览、技术说明、功能对比与人物档案类页面。

限制与注意事项

认证门为客户端可见性门禁，不构成真正安全防护。
使用 --no-deploy-ready 可跳过 _headers 与 robots.txt，用于仅本地开发。
反模式要求：卡片不得使用左边框强调条纹（应使用如 state-card 的 ::before 顶栏）；不得使用渐变文字（background-clip: text）；不得使用 system-ui 或默认字体；必须包含 skip-link 与 prefers-reduced-motion；超过 6 个连续 state-card 需用 pullquote 或分节打断。
若 minoan-frontend-design 技能可用，可参阅其更广泛的美学原则。