Hallmark 宏结构指南：用 Long Document 把产品页写成一篇“可读的文献“

Hallmark 宏结构指南：用 Long Document 把产品页写成一篇"可读的文献"

【免费下载链接】hallmarkAnti-AI-slop design skill for Claude Code, Cursor, and Codex.项目地址: https://gitcode.com/GitHub_Trending/hal/hallmark

Long Document 是 Hallmark（一套面向 Claude Code、Cursor、Codex 的 Anti-AI-slop 设计技能）内置的二十一种页面宏结构之一。本指南以 02-long-document.md 为核心骨架，系统讲解它的设计哲学、六个结构轴、适用边界与开场白技艺，并结合仓库内的三份真实参考实现（Streampipe CLI、Soroe 陶艺工作室、Coffeebox 订阅咖啡）与配套规则，给出可复制、可落地的实现方案。读完你能够判断"什么时候该把页面写成一篇文献"，并能按 Long Document 的规格直接产出符合 Hallmark 规范的 HTML/CSS 页面。

什么是 Long Document：把页面写成"关于产品的文学"

在 Hallmark 的宏结构体系中，macrostructures.md 将其定位为一句话：

Reads like a memo, a letter, or a journal entry. No marketing structure. Continuous prose with inline section heads. The page isliteratureabout the product.

Long Document 读起来像一份备忘录、一封私人信件或一篇日记体长文：没有营销结构，没有"主视觉 → 三栏特性 → CTA 横幅"的销售节奏。整页是连续的散文，章节标题内嵌在正文流中，页面本身就是关于产品的"文学"。

这与 structure.md 提出的核心观点一脉相承——大多数 AI 生成的 UI 在视觉上各不相同，但在结构上完全一致（hero → 三特性 → CTA → footer）。结构上的雷同才是 AI 指纹，而不是视觉上的雷同。Long Document 正是 Hallmark 用来打破这种结构同质化的武器之一：它把"营销落地页"改造成"一篇读得下去的文章"，从而让两个不同 brief 产出的页面看起来像两个不同网站，而不是同一模板的换色版本。

六个结构轴：Long Document 的一揽子决策

Long Document 一次性锁定了页面形状的六个关键轴。以下是原文档的核心规格，并补充了仓库源码中的实现证据。

1. 标题（Heading）：与正文内联

章节标题不独占一行成为"区块头"，而是从段落流中自然浮现，通常以小型大写（small caps）或加粗短语的形式出现。

<h2 class="inline">A small heading.</h2>

在 structure.md 的"章节标题位置"轴中，这对应Inline with body（无章节断裂，标题从段落流中浮现，对话式，参考 Medium 文章与长文随笔）。与之对照，被禁止的默认模式是"左侧边栏编号 + 右侧标题"的两栏式标题（slop-test 门 66 直接自动判负），Long Document 中即使使用编号也必须采用纵向堆叠（编号在标题上方单独一行）。

2. 正文（Body）：单栏、宽行距、收字宽

• 单栏布局（single column），这是叙事优先、阅读导向的默认形态；
• 行距 ≥ 1.65（generous line-height）；
• 行长（measure）控制在 60–65ch。

这在 typography.md 中有更细的支撑：正文行距推荐 1.5–1.65，显示级标题收紧到 1.05–1.2；行长（measure）始终位于 45–75 字符之间，默认max-width: 65ch。仓库中的 Streampipe 页面定义了--measure-prose: 64ch并应用line-height: 1.7（见 site/_tests/02-streampipe-cli/style.css），Soroe 陶瓷页则使用--lh-relaxed: 1.6与max-width: 52ch（见 site/_tests/11-soroe-ceramics/index.html），两者都是 Long Document 正文规格的直接落地。

3. 分隔线（Divider）：留白即分隔

Long Document 的分隔语言是负空间——区块之间的空隙本身就是分隔线，偶尔用一个居中的装饰性符号（ornament，如花星❦）作为强调。在 structure.md 的分隔轴中，这对应Negative space（无任何规则线，空隙即分隔，参考 Apple、Linen、现代极简风格）。Soroe 页面中大部分章节之间靠 padding 撑出 6.5rem（--space-3xl）的空隙，只在少数位置保留 1px hairline 作为节奏收束，正是这一轴的应用。

4. 按钮（Button）：段落内的排版型链接

CTA 不做独立按钮块，而是作为段落内部的排版型链接（typographic link）出现。仓库的组件目录专门收录了这一形态——c3-typographic-link.md：

Just a word, an arrow, and a 1-px underline. No box, no fill. Use when: the page is editorial / Long Document; CTAs should not shout.

<a class="link">Read the case study →</a>

对应 structure.md 按钮轴中的Unstyled link（下划线单词，无边框，信任排版）与Typographic-only（特定字重/字号/颜色的单词，无规则线无边框，看起来像一个恰好可点击的标题）。注意不要与 C1 Outlined chip（带边框的描边胶囊）混淆。

5. 图片（Image）：内联、按文本度量缩放，绝不通栏

图片以文本宽度内联出现，永远不做 full-bleed 通栏。这对应 structure.md 图片轴中的Inline with text（图片在段落节奏中流动，尺寸对齐文本度量，参考 Editorial、Newsprint）。如果页面需要展示截图或产品演示，应嵌入在散文流中，而不是像 Workbench 宏结构那样做成带边框的浮层演示。

6. 呈现（Reveal）：无。页面就"在那里"

Long Document 没有任何滚动/加载动效——页面从第一屏起就完整呈现，不做 fade-up、不做 type-unmask。microinteractions.md 把 Long Document 明确列为**默认关闭动效（default-off）**的宏结构之一，与 Editorial、Manifesto、Letter、Quote-Led 同组。这也是它有别于 Bento Grid、Stat-Led 等"默认开启 2–3 个微交互"的宏结构的关键差异：文字本身就是唯一的运动。

什么时候用它，什么时候必须避开

适合使用 Long Document 的场景

原文档明确列出了四类典型用途：

• 案例研究（case studies）
• 创始人文章（founder posts）
• 使命宣言页（mission pages）
• 销售本质上是"哲学性"的产品——卖的是理念、品味、生活方式，而非功能清单

核心判断标准一句话：brief 要求"讲一个故事"（tell a story），而不是"列出功能"（list features）。

structure.md 的"领域 → 三选一"映射表给出了更细的触发线索，Long Document 出现在以下领域的推荐候选中：

必须避免的场景

原文档给出了明确的反向警告：

Avoid when there's a single decisive action to take — Long Document hides CTAs, which is wrong for transactional pages.

当页面存在唯一的关键行动（注册、购买、下单）时不要使用 Long Document——它天然隐藏 CTA，把按钮藏进段落文本里，这对交易型页面是错误的。像"立即购买""马上注册"这类需要强转化指令的落地页，应当选择 Bento Grid、Stat-Led、Workbench 或 Marquee Hero 等 SaaS 型宏结构。

开场白的技艺：模仿"具体性"，而非措辞

Long Document 的成败往往在第一段。原文档提供了三句范例，并要求"模仿它们的具体性（specificity），而不是字面措辞"：

"Saturday, 6:14 a.m. The dough went in at midnight."—— 以时间戳开场；品牌把自己介绍为一天中的某个时刻

"A monthly art publication featuring contributions by some of the most engaged thinkers working today."—— e-flux.com/journal，名词短语直陈身份

"We design everything for everyone."—— pentagram.com，拒绝动词，把设计当作普遍实践

这三个开头的共同点是立即给出可触摸的细节——一个精确的时刻、一个具体的身份定义、一个近乎宣言的立场陈述——而不是"Welcome to our platform"式的空泛开场。

仓库里的三份 Long Document 实现，开场白与主题高度咬合：

• Streampipe（终端风格）：以命令为开场白。<h1 class="lede">直接打出$ streampipe — a small, fast, single-binary CLI for parsing log and event streams from stdin.后跟一个闪烁光标（--caret），产品自我介绍就是一条可执行的命令（见 site/_tests/02-streampipe-cli/index.html）。
• Soroe 陶艺工作室（编辑风格）：以信件为开场白。"A letter to collectors" 眉题下是Six vessels, this spring — then the kiln rests until July.，落款— Mariko, the studio.（见 site/_tests/11-soroe-ceramics/index.html）。
• Coffeebox（自定义主题）：以时间戳为开场白。Sunday — 6:14 a.m.直接复刻了原文档的第一句范例节奏："The first roast of the week leaves the drum."（见 site/_tests/custom/01-coffeebox/index.html）。

最小可实现结构：HTML 骨架

原文档给出了 Long Document 的完整骨架，这是一个可直接套用的最小结构：

<article class="prose"> <p class="lede">…</p> <p>…</p> <h2 class="inline">A small heading.</h2> <p>…</p> <blockquote>…</blockquote> <p>… <a href="">read more →</a> …</p> </article>

各元素的职责与仓库实现对照：

在实现细节上，Streampipe 页面还展示了 Long Document 的两种进阶内容形态：编号注释行（.note网格，如"1.0 Stream in, stream out"）和内联终端代码块（.term，作为<pre>嵌入散文，而非浮动的浏览器框架演示）。这两种形态都保持了"内容在行文中流动"的 Long Document 特征。

仓库实战验证：三份参考实现拆解

仓库的site/_tests/目录保存了多份 Long Document 的真实产出，是学习该宏结构的最佳活教材。

1. Streampipe CLI——Long Document × Terminal 主题

见 site/_tests/02-streampipe-cli/index.html 与 site/_tests/02-streampipe-cli/style.css。页面结构完全遵循 Long Document 的散文节奏：

• 开场：$ streampipe …命令式 salutation + 闪烁光标；
• 正文：两段散文介绍（读 stdin、管道化、Rust 单二进制、1.2 MB、无守护进程），中间内联一段tail -f access.log | streampipe parse --format nginx --filter 'status >= 500' --out json的终端示例；
• 章节：Install（3 种安装方式）、How it works（3 条编号注释）、Flags（6 行参数表）；
• 收尾：colophon（MIT 许可、版权行）。

CSS 印章（stamp）如实记录了宏结构选择：

/* Hallmark · macrostructure: Long Document · H5 hero knobs: salutation=command, body=2 paragraphs, signoff=mit-license * theme: Terminal · accent: phosphor-green ~6% (functional, not decorative) * enrichment: Tier-A inline CSS-art terminal blocks (no sticky pin, no Lottie) * studied: no · context: explicit · v0.6.0 */

注意它的"hero knobs"——salutation=command、body=2 paragraphs、signoff=mit-license——说明 Long Document 的"英雄区"不是一个视觉主视觉，而是一组开场白参数。

2. Soroe 陶艺工作室——Long Document × Studio 主题

见 site/_tests/11-soroe-ceramics/index.html。这是 Long Document 用于"产品目录化叙事"的变体：

• Masthead：Soroe.字标 +Spring 2026 · No. ix元信息；
• Letter opening："A letter to collectors" + 大标题Six vessels, this spring — then the kiln rests until July.+ 落款；
• Index：六件器皿的编号清单，每件配一个 Tier-A 手绘 SVG 轮廓、名称、一句说明和价格状态（Available / Reserved）；
• Visit：地址与开放时间段落；
• Colophon：字体声明（Fraunces italic & Geist）。

这证明了 Long Document 的弹性：它既能承载纯散文的 CLI 说明页，也能承载带商品索引的叙事型展示页——只要整体保持"可读的文献"节奏。

3. Coffeebox——Long Document × 自定义主题

见 site/_tests/custom/01-coffeebox/index.html。这是 recipes.md 中 00 号"canonical try-it prompt"的产出，也是判断 Hallmark 是否正确接线的最快试验：

• Salutation：Sunday — 6:14 a.m.时间戳 + 一句陈述；
• Letter：两段散文（"The bag goes in the post on Monday morning…"）；
• Notes：§ Three things, then we'll go三条编号说明；
• Signoff：— A. Coelho, head roaster；
• Colophon：地址、邮箱与两个排版型链接（subscribe、read the email）。

它的 CSS 印章（见 site/_tests/custom/01-coffeebox/style.css）是自定义主题 Long Document 的规范格式：

/* Hallmark · macrostructure: Long Document · H5 hero knobs: salutation=time-stamp, body=2 paragraphs, signoff=initials * theme: custom · vibe: "archival warmth, hand-set, no varnish" · paper: oklch(94% 0.020 65) · accent: oklch(58% 0.16 35) * display: Fraunces italic · body: Source Serif 4 · axes: light / italic-serif / chromatic-terracotta */

配套纪律：与 Hallmark 全局规则协同

Long Document 并非独立存在，它在 Hallmark 的完整流程中与其他纪律协同工作。

选型与轮换规则

根据 SKILL.md 的流程：在进入任何视觉规则之前，先通过 macrostructures.md 索引选出一个宏结构，再只加载对应的单个 per-macro 文件。Long Document 同时受两条强制性轮换规则约束：

1. 宏结构轮换：如果目标代码库中已存在/* Hallmark · macrostructure: <name> · … */印章，你的选择必须是不同的宏结构；
2. 主题轮换：连续两次输出在纸面明度带（paper band）/ 显示风格（display style）/ 强调色相（accent hue）三个轴上至少要有一项不同。

macrostructures.md 同时规定：如果 brief 含糊不清，不要默认，而要从类别上完全不同的三组中各提供一个选项（如一个网格型 Bento、一个文档型 Long Document、一个海报型 Manifesto），让用户挑。

预览块（Preview block）

preview-examples.md 给出了 Long Document 的标准预览块范本：

• Macrostructure· Long Document
• Theme· Linen (cool slate paper · steel-blue accent · geometric sans)
• Enrichment· Tier-B hand-built SVG (a 60-line coffee bean with@property --rise6 s breathing-loop)
• Sections· Masthead · Letter · Three Notes · Visit · Colophon
• Motion· breathing-loop on bean only (respectsprefers-reduced-motion)
• Slop test· 69 / 69 ✓
• Diversification· first run for this project

注意"Motion"行的克制——Long Document 是默认关闭动效的宏结构，即使有动效也只作用于单个富化元素（如咖啡豆 SVG 的呼吸循环），且必须尊重prefers-reduced-motion。

文字与排印纪律

• 字号限制：正文不小于 16px，全局不低于 14px；行距 1.5–1.65，行长 45–75 字符（默认 65ch）；
• 单字族收缩是允许的：typography.md 明确指出，Editorial · Letter · Manifesto ·Long Document可以收缩到单一字族——因为正文的声音本身就承载品牌，字标靠"排版得体"而非"装饰"赢得分量（Streampipe 页面就是全 IBM Plex Mono 单字族设计，见其 style.css）；
• 眉题（eyebrow）默认关闭：anti-patterns.md 规定，只有当宏结构是 Long Document / Manifesto / Catalogue 编号且内容真正有序时才允许使用编号，且全页最多 1–2 处、必须纵向堆叠；
• 诚实文案：Long Document 的文学化风格不豁免"禁止编造数据"的纪律——统计、评价、案例数都必须真实或使用占位符。

如何在你的项目中启用 Long Document

通过默认设计流启用

在安装 hallmark 技能的项目中，向 Claude Code / Cursor / Codex 发出一个带叙事信号的 brief 即可。以下是可以直接复制使用的提示词（来自 recipes.md 的工作示例）：

"Build me a landing page for Streampipe — a small, fast, single-binary CLI for parsing log and event streams from stdin. Filter, transform, route. Composes with anything that emits lines. Audience: developers. Use: install + read docs. Tone: technical. Use the Terminal theme."

技能会依次执行预检 → 设计上下文门 → 宏结构选型 → 主题选型 → 预览 → 构建 → slop 测试，并在产出 CSS 首行盖上印章、把记录写入.hallmark/log.json供下次轮换使用。若要明确引导到 Long Document，可以在 brief 中加入"tell a story""reads like a letter"等信号，或在技能询问时从候选列表中指名。

关键纪律自查清单

产出 Long Document 页面时，对照以下清单自查：

1. 章节标题是否内联在正文流中（而非独立两栏头部）？
2. 正文是否单栏、行距 ≥ 1.65、行长 60–65ch？
3. 分隔是否以留白为主，而非每节一根通栏规则线？
4. CTA 是否以段落内排版型链接形式出现（如 c3-typographic-link.md 所示），而非独立按钮块？
5. 图片是否内联且按文本度量缩放，绝无 full-bleed？
6. 页面是否没有任何滚动/加载动效？
7. 页面是否存在"唯一关键行动"需求？若有，应立即改用其他宏结构。

结语

Long Document 是 Hallmark 宏结构目录中最"反营销"的一页形态。它用散文的密度替代功能的罗列，用时间戳、落款与具体细节替代Welcome to式的空话，用段落内链接替代按钮横幅。仓库中的 Streampipe、Soroe 与 Coffeebox 三份实现证明：无论产品是一个 CLI 工具、一间陶艺工作室还是一家订阅咖啡，只要 brief 是"讲一个故事"，Long Document 都能把页面变成一篇值得读完的文献——而这恰恰是大多数 AI 生成页面最稀缺的品质。若你的页面需要读者做一次明确的购买或注册，请记住原文档的警告：Long Document 隐藏 CTA，交易型页面请另选它法。

【免费下载链接】hallmarkAnti-AI-slop design skill for Claude Code, Cursor, and Codex.项目地址: https://gitcode.com/GitHub_Trending/hal/hallmark