cognitive-html-effectiveness

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cognitive HTML Effectiveness

认知型HTML文档效能

Generate self-contained HTML files that people actually read — not walls of markdown they skim and ignore.

生成真正会被用户阅读的独立HTML文件——而非被用户略读甚至忽略的冗长markdown内容。

When to use

使用场景

This skill fires when the user asks for any of:

"crea un reporte", "haz un status", "post-mortem", "incident report"
"compara approaches", "tradeoffs", "qué opción es mejor"
"explícame cómo funciona X", "recorrido del código", "walkthrough"
"slides", "presentación", "deck", "demo"
"diagrama", "flujo", "flowchart", "arquitectura"
"prototipo", "animación", "transición"
"design system", "colores", "tipografía", "componentes"
"tablero", "triage", "kanban", "drag and drop"
"revisa este PR", "analiza este diff"
Or any request where the user would benefit from visual layout, color coding, interaction, or progressive disclosure instead of linear text.

当用户提出以下任意需求时，触发此技能：

"crea un reporte"（生成报告）、"haz un status"（更新状态）、"post-mortem"（事后分析）、"incident report"（事故报告）
"compara approaches"（对比方案）、"tradeoffs"（权衡分析）、"qué opción es mejor"（哪个选项更好）
"explícame cómo funciona X"（讲解X的工作原理）、"recorrido del código"（代码走查）、"walkthrough"（流程讲解）
"slides"（幻灯片）、"presentación"（演示文稿）、"deck"（演示文档）、"demo"（演示）
"diagrama"（图表）、"flujo"（流程）、"flowchart"（流程图）、"arquitectura"（架构图）
"prototipo"（原型）、"animación"（动画）、"transición"（过渡效果）
"design system"（设计系统）、"colores"（颜色）、"tipografía"（排版）、"componentes"（组件）
"tablero"（看板）、"triage"（分类处理）、"kanban"（敏捷看板）、"drag and drop"（拖拽）
"revisa este PR"（评审此PR）、"analiza este diff"（分析此差异）
或任何用户可从视觉布局、颜色编码、交互功能或渐进式信息披露中获益，而非线性文本的需求。

Core principles

核心原则

These are non-negotiable. Every HTML file you produce must respect them.

#	Principle	What it means
1	Self-contained	Zero external dependencies. All CSS in `<style>` , all JS in `<script>` , all SVG inline. The file opens directly in any browser — no server, no build step, no CDN.
2	TL;DR first	The most important information occupies the first viewport. Use a TL;DR box, summary band, or executive summary. Answer "what happened" or "what this is" before anything else.
3	Progressive disclosure	Show the big picture first, hide details behind collapsible sections, tabs, or scroll. The reader should never feel overwhelmed.
4	Color has meaning	Warm colors (clay, rust) = attention, warning, danger. Cool colors (olive) = success, safety, good. Grays = structure, metadata, neutral. Never use color as the ONLY signal — always pair with text or shape.
5	Typography hierarchy	Serif for headings (authority), sans for body (readability), mono for code and metadata. At least three levels of visual hierarchy on every page.
6	Mobile-first	Assume the first real viewport is a phone around `390px` wide. The first-pass layout must work there without zoom, horizontal drift, or hover-only logic. Desktop is the enhancement layer.
7	Review empathy	Design for the person who will read this Monday morning. They're busy, they're scanning, and 80% of them may be doing it from a phone. They need to know if this matters to them in 5 seconds.
8	Export always	Every interactive page ends with a button that exports the final state as markdown, JSON, or plain text. The artifact must leave the page.

这些原则不可妥协。所有生成的HTML文件必须遵守以下原则：

序号	原则	具体含义
1	独立完整	零外部依赖。所有CSS置于 `<style>` 标签内，所有JS置于<script>标签内，所有SVG均为内联形式。文件可直接在任意浏览器中打开——无需服务器、构建步骤或CDN。
2	先展示核心信息	最重要的信息需占据首屏视野。使用TL;DR模块、摘要栏或执行摘要。先回答“发生了什么”或“这是什么”，再展示其他内容。
3	渐进式信息披露	先展示整体概览，将细节隐藏在可折叠区域、标签页或滚动内容后。绝不能让读者感到信息过载。
4	颜色具备语义	暖色调（土色、铁锈红）= 注意、警告、危险。冷色调（橄榄绿）= 成功、安全、良好。灰色系= 结构、元数据、中性。绝不能仅用颜色传递信号——始终搭配文本或图形。
5	排版层级清晰	标题使用衬线字体（体现权威性），正文使用无衬线字体（提升可读性），代码和元数据使用等宽字体。每页至少包含三级视觉层级。
6	移动端优先	假设首屏设备为宽度约 `390px` 的手机。初始布局必须在此尺寸下正常工作，无需缩放、无横向滚动、无仅支持 hover 的逻辑。桌面端为增强层。
7	共情式阅读设计	为周一早上阅读文档的用户设计。他们时间紧张、快速浏览，且80%的用户可能通过手机阅读。他们需要在5秒内判断这份文档是否与自己相关。
8	支持导出功能	每个交互式页面末尾需添加按钮，可将最终状态导出为markdown、JSON或纯文本。生成的成果必须可脱离页面保存。

Workflow

工作流程

Step 1: Detect palette

步骤1：检测调色板

Read

references/palette-override.md

for the full protocol. In short:

Check if
```
AGENTS.md
```
exists in the project root.

Look for the block delimited by

<!-- cognitive-html:palette -->

and

<!-- /cognitive-html:palette -->

If found, parse the YAML inside. Merge overrides with defaults.
If not found, use the full default palette from
```
assets/design-tokens.css
```
.

阅读

references/palette-override.md

获取完整规则。简而言之：

检查项目根目录是否存在
```
AGENTS.md
```
文件。

查找由

<!-- cognitive-html:palette -->

和

<!-- /cognitive-html:palette -->

界定的代码块。

若找到，解析其中的YAML内容，将自定义配置与默认配置合并。
若未找到，使用
```
assets/design-tokens.css
```
中的完整默认调色板。

Step 2: Load the foundation system

步骤2：加载基础系统

Before choosing a pattern, establish one shared base for the whole page. Every HTML output starts from the same foundation layer:

Page shell:

body

→

.page

→

.page-header

.page-main

.page-footer

Mobile baseline: validate the shell at roughly
```
390px
```
wide before thinking about tablet or desktop
Type scale: use the tokens from
```
assets/design-tokens.css
```
for display, headings, body, small text, and metadata
Spacing scale: compose spacing from
```
--space-1
```
through
```
--space-8
```
; do not invent arbitrary paddings/margins
Reading width: prose-heavy sections stay near
```
--container-reading
```
; dashboards and diagrams can expand toward
```
--container-page
```
Shared components: cards, callouts, code panels, tables, badges, and nav must reuse the documented component variants

Read

assets/design-tokens.css

as the source of truth for typography, spacing, borders, shadows, and semantic surfaces.

在选择模式前，为整个页面建立统一的基础层。所有HTML输出均从同一基础层开始：

页面框架：

body

→

.page

→

.page-header

.page-main

.page-footer

移动端基准：在考虑平板或桌面端布局前，先验证框架在约
```
390px
```
宽度下的表现
字体比例：使用
```
assets/design-tokens.css
```
中的变量定义标题、正文、小字和元数据的字体
间距比例：使用
```
--space-1
```
至
```
--space-8
```
的间距变量组合布局；禁止使用任意自定义内边距/外边距
阅读宽度：以文本为主的区域保持在
```
--container-reading
```
宽度附近；仪表盘和图表可扩展至
```
--container-page
```
宽度
共享组件：卡片、提示框、代码面板、表格、徽章和导航必须复用已文档化的组件变体

请以

assets/design-tokens.css

作为排版、间距、边框、阴影和语义化容器的唯一权威来源。

Step 3: Choose pattern

步骤3：选择模式

Read

references/decision-tree.md

for the full table. Match the user's request to one of the 10 patterns:

Pattern	File	For...
Comparison	`patterns/comparison.md`	Side-by-side tradeoff analysis
Walkthrough	`patterns/walkthrough.md`	Code flow, architecture tour
Review	`patterns/review.md`	Annotated diff, PR analysis
Design System	`patterns/design-system.md`	Colors, typography, spacing tokens
Prototyping	`patterns/prototyping.md`	Animation sandbox, clickable flow
Diagram	`patterns/diagram.md`	Flowchart, architecture diagram
Deck	`patterns/deck.md`	Slide presentation
Explainer	`patterns/explainer.md`	Feature explanation, concept teaching
Report	`patterns/report.md`	Status update, post-mortem
Editor	`patterns/editor.md`	Interactive board, triage, drag-drop

阅读

references/decision-tree.md

获取完整对照表。将用户需求匹配至以下10种模式之一：

模式	文件	适用场景
Comparison	`patterns/comparison.md`	并排权衡分析
Walkthrough	`patterns/walkthrough.md`	代码流程、架构讲解
Review	`patterns/review.md`	带注释的差异分析、PR评审
Design System	`patterns/design-system.md`	颜色、排版、间距变量展示
Prototyping	`patterns/prototyping.md`	动画沙箱、可点击流程演示
Diagram	`patterns/diagram.md`	流程图、架构图
Deck	`patterns/deck.md`	幻灯片演示
Explainer	`patterns/explainer.md`	功能讲解、概念教学
Report	`patterns/report.md`	状态更新、事后分析报告
Editor	`patterns/editor.md`	交互式看板、分类处理、拖拽操作

Step 4: Read the pattern file

步骤4：阅读模式文件

Each pattern file in

references/patterns/

contains:

When to use — signal phrases that match this pattern
Structure blueprint — the exact HTML skeleton
Component prescriptions — which components from
```
references/components.md
```
to use
Full worked example — a complete, self-contained HTML file you can study

references/patterns/

目录下的每个模式文件包含：

适用场景 —— 匹配此模式的关键词
结构蓝图 —— 精确的HTML骨架
组件规范 —— 需使用
```
references/components.md
```
中的哪些组件
完整示例 —— 可参考的完整独立HTML文件

Step 5: Compose from components

步骤5：基于组件构建

Build the page using the component catalog in

references/components.md

. Do not invent new component patterns unless absolutely necessary. The catalog has 15 proven components: TL;DR box, summary band, tradeoff table, chips, timeline, collapsible snippets, code panels, tabs, callouts, action items, data tables, progress bars, decision cards, FAQ, and sidebar navigation.

All components must inherit from the same visual language:

serif/display for headings, sans for prose, mono for metadata and code
semantic surfaces and borders from tokens only
consistent padding, radius, and shadow levels
accessible focus states on interactive controls
touch targets at or above
```
44px
```
when something is tappable
no ad hoc color math inside component CSS unless it is tokenized first

使用

references/components.md

中的组件库构建页面。除非绝对必要，否则禁止创建新的组件模式。组件库包含15种经过验证的组件：TL;DR模块、摘要栏、权衡表、标签、时间线、可折叠代码片段、代码面板、标签页、提示框、行动项、数据表、进度条、决策卡片、FAQ和侧边导航。

所有组件必须遵循统一的视觉语言：

标题使用衬线/展示字体，正文使用无衬线字体，元数据和代码使用等宽字体
仅使用变量定义语义化容器和边框
内边距、圆角和阴影层级保持一致
交互式控件具备可访问的焦点状态
可点击元素的触摸目标尺寸不小于
```
44px
```
组件CSS中禁止使用临时颜色计算，除非已先定义为变量

Step 6: Apply quality checklist

步骤6：执行质量检查

Before delivering, run through

references/quality-checklist.md

. Every item is a gate:

Self-contained? Opens in any browser? Responsive?
Still clear and usable at
```
390px
```
wide?
Language matches the prompt?
TL;DR visible in first viewport?
Palette respected (no hardcoded colors)?
Interactive? → has export button?

交付前，对照

references/quality-checklist.md

逐一检查。每一项均为必过门槛：

是否独立完整？能否在任意浏览器中打开？是否响应式？
在
```
390px
```
宽度下是否仍清晰可用？
语言是否与用户提示一致？
TL;DR是否在首屏可见？
是否遵守调色板规则（无硬编码颜色）？
若为交互式页面，是否包含导出按钮？

Step 7: Deliver

步骤7：交付

Return the HTML file. The filename should be descriptive and kebab-case (e.g.,

incident-report-sync-502.html

comparison-debounce-approaches.html

). If the user asked for multiple things, generate one file per pattern — each self-contained.

返回HTML文件。文件名需具有描述性并使用短横线命名法（kebab-case）（例如：

incident-report-sync-502.html

、

comparison-debounce-approaches.html

）。若用户提出多项需求，为每种模式生成一个独立文件——每个文件均需独立完整。

Language rule

语言规则

Detect the language of the user's prompt and generate ALL visible text in that same language. This includes: headings, labels, descriptions, TL;DR content, button text, captions, tooltips, alt text, chart labels, placeholder text, and navigation labels.

Code, file paths, technical identifiers, CSS class names, and variable names remain in English.

Example:

Prompt in Spanish → "Informe de incidente", "Línea de tiempo", "Elementos de acción"
Prompt in English → "Incident Report", "Timeline", "Action Items"
Prompt in Portuguese → "Relatório de incidente", "Linha do tempo", "Itens de ação"

检测用户提示的语言，并将所有可见文本生成为该语言。 包括：标题、标签、描述、TL;DR内容、按钮文本、说明文字、工具提示、替代文本、图表标签、占位符文本和导航标签。

代码、文件路径、技术标识符、CSS类名和变量名保持英文。

示例：

西班牙语提示 → "Informe de incidente"、"Línea de tiempo"、"Elementos de acción"
英语提示 → "Incident Report"、"Timeline"、"Action Items"
葡萄牙语提示 → "Relatório de incidente"、"Linha do tempo"、"Itens de ação"

File naming

文件命名

Generated HTML files use descriptive kebab-case names in the language of the content:

```
informe-incidente-502.html
```
```
comparacion-enfoques-busqueda.html
```
```
status-engineering-semana-11.html
```
```
como-funciona-rate-limiting.html
```

Place files in the current working directory unless the user specifies otherwise.

生成的HTML文件使用符合内容语言的描述性短横线命名法（kebab-case）：

```
informe-incidente-502.html
```
```
comparacion-enfoques-busqueda.html
```
```
status-engineering-semana-11.html
```
```
como-funciona-rate-limiting.html
```

除非用户指定，否则将文件放置在当前工作目录。

The default design system

默认设计系统

These are the default design tokens. They define the visual identity. Every generated file embeds them in a

<style>

block. Reference components by semantic variable name, never by raw hex value.

--ivory:    #FAF9F5   ← page background
--slate:    #141413   ← primary text
--clay:     #D97757   ← accent, warnings
--oat:      #E3DACC   ← secondary surfaces
--olive:    #788C5D   ← success, positive
--rust:     #B04A3F   ← danger, high severity
--gray-100: #F0EEE6   ← subtle backgrounds
--gray-300: #D1CFC5   ← borders
--gray-500: #87867F   ← secondary text
--gray-700: #3D3D3A   ← body text
--white:    #FFFFFF   ← card backgrounds
--serif: ui-serif, Georgia, serif
--sans:  system-ui, sans-serif
--mono:  ui-monospace, monospace

In addition, generated files should expose:

--text-display / --text-h1 / --text-h2 / --text-h3 / --text-body / --text-small
--space-1 through --space-8
--container-reading / --container-page
--shadow-1 / --shadow-2 / --focus-ring
--surface-page / --surface-card / --surface-muted / --surface-accent / --surface-inverse

Use these tokens to create a recognizably consistent visual system across every pattern.

以下为默认设计变量，定义了视觉标识。所有生成的文件均会将这些变量嵌入

<style>

块中。请通过语义化变量名引用组件，绝不要使用原始十六进制值。

--ivory:    #FAF9F5   ← page background
--slate:    #141413   ← primary text
--clay:     #D97757   ← accent, warnings
--oat:      #E3DACC   ← secondary surfaces
--olive:    #788C5D   ← success, positive
--rust:     #B04A3F   ← danger, high severity
--gray-100: #F0EEE6   ← subtle backgrounds
--gray-300: #D1CFC5   ← borders
--gray-500: #87867F   ← secondary text
--gray-700: #3D3D3A   ← body text
--white:    #FFFFFF   ← card backgrounds
--serif: ui-serif, Georgia, serif
--sans:  system-ui, sans-serif
--mono:  ui-monospace, monospace

此外，生成的文件应暴露以下变量：

--text-display / --text-h1 / --text-h2 / --text-h3 / --text-body / --text-small
--space-1 through --space-8
--container-reading / --container-page
--shadow-1 / --shadow-2 / --focus-ring
--surface-page / --surface-card / --surface-muted / --surface-accent / --surface-inverse

使用这些变量在所有模式中创建具有一致辨识度的视觉系统。

Mobile-first contract

移动端优先约定

Start every layout in a single column. Add columns only when the viewport earns them.
The first viewport to optimize is a phone around
```
390px
```
wide.
Primary body copy should stay around
```
16px
```
or larger. Do not make the user zoom to read.
Anything tappable should target roughly
```
44px
```
height/width.
Sidebars become stacked sections, drawers, or collapsibles on mobile — not permanently tiny side rails.
Tables, code panels, tabs, and diagrams must define a mobile fallback instead of hoping
```
overflow-x: auto
```
is enough.
The first screen on mobile still needs the TL;DR or equivalent summary signal.

所有布局从单列开始。仅当视口足够宽时才添加多列。
优先优化的首屏设备为宽度约
```
390px
```
的手机。
正文主文本应保持在
```
16px
```
或更大字号。绝不能让用户缩放阅读。
可点击元素的目标尺寸约为
```
44px
```
高/宽。
在移动端，侧边栏应变为堆叠区域、抽屉或可折叠组件——而非永久存在的窄侧边栏。
表格、代码面板、标签页和图表必须定义移动端 fallback 方案，不能仅依赖
```
overflow-x: auto
```
。
移动端首屏仍需展示TL;DR或等效的摘要信息。

Anti-patterns

反模式

Do NOT link to external CSS frameworks (Bootstrap, Tailwind CDN, etc.). The file must work offline.
Do NOT use external JavaScript libraries. If you need interaction, write vanilla JS.
Do NOT generate markdown files with "HTML-like" formatting. The output must be valid HTML.
Do NOT use inline styles (
```
style="..."
```
attributes) for static presentation. Keep styles in the
```
<style>
```
block. Data-driven SVG geometry and narrowly scoped CSS custom properties are acceptable only when they encode runtime data rather than visual decoration.
Do NOT hardcode hex colors. Always use CSS variables from the palette.
Do NOT ship desktop-first layouts that merely collapse as an afterthought. Mobile is the default target.
Do NOT rely on hover as the only way to reveal meaning, controls, or navigation.
Do NOT create sidebars, 3+ column grids, or dense tables without a declared mobile behavior.
Do NOT skip the TL;DR. Every page needs a "why should I care" signal at the top.
Do NOT create pages without an export mechanism if they are interactive.
Do NOT mix multiple patterns in one file unless the pattern explicitly supports it (e.g., report pattern can include a timeline). When in doubt, one file per intent.

禁止链接外部CSS框架（如Bootstrap、Tailwind CDN等）。文件必须可离线使用。
禁止使用外部JavaScript库。若需交互功能，请编写原生JS。
禁止生成带有“类HTML”格式的markdown文件。输出必须为有效的HTML。
禁止使用内联样式（
```
style="..."
```
属性）实现静态展示。样式需置于
```
<style>
```
块中。仅当编码运行时数据而非视觉装饰时，才允许使用数据驱动的SVG几何图形和范围狭窄的CSS自定义属性。
禁止硬编码十六进制颜色。始终使用调色板中的CSS变量。
禁止先开发桌面端布局再事后适配移动端。移动端为默认目标。
禁止仅依赖hover效果展示信息、控件或导航。
禁止创建侧边栏、3列及以上网格或密集表格时不声明移动端适配行为。
禁止省略TL;DR模块。每页顶部都需要一个“为何我要关注”的信号。
禁止交互式页面不提供导出机制。
禁止在单个文件中混合多种模式，除非该模式明确支持（例如：报告模式可包含时间线）。如有疑问，每个意图对应一个文件。

Foundation rules

基础规则

Start every page from one shell: a centered
```
.page
```
container with generous top/bottom spacing and section gaps from the spacing scale.
Start from the phone, then expand upward.
```
390px
```
is the first-class viewport, not an edge case.
Keep long-form paragraphs near
```
--container-reading
```
; only data-heavy zones should span the full page width.
Use at least 3 levels of hierarchy on every page: page title, section title, body/meta.
Use one of the documented surface levels for every block: page, card, muted, accent, or inverse.
Interactive controls need visible hover, focus, and active states.
Interactive controls also need touch-sized hit areas and should remain usable with thumb scrolling.
Tables, code panels, pills, and callouts should look like members of the same family, not mini one-off designs.

所有页面从统一框架开始：居中的
```
.page
```
容器，使用间距比例中的值设置顶部/底部间距和区块间隙。
从手机端开始设计，再向上扩展。
```
390px
```
是首要视口，而非边缘案例。
长篇段落保持在
```
--container-reading
```
宽度附近；仅数据密集区域可使用全页面宽度。
每页至少包含3级层级：页面标题、章节标题、正文/元数据。
每个区块使用已文档化的容器层级之一：页面、卡片、弱化、强调或反向。
交互式控件需具备可见的hover、focus和active状态。
交互式控件还需具备适合触摸的点击区域，并支持拇指滚动操作。
表格、代码面板、标签和提示框应看起来属于同一体系，而非独立的临时设计。

Reference files

参考文件

This skill uses progressive disclosure. Read reference files only as needed:

```
references/decision-tree.md
```
— full pattern selection guide with examples
```
references/components.md
```
— catalog of 15 reusable UI components with HTML + CSS
```
references/palette-override.md
```
— how to customize colors and core theme tokens per project via AGENTS.md
```
references/quality-checklist.md
```
— pre-delivery validation checklist
```
references/patterns/*.md
```
— one file per pattern, each with structure blueprint + worked example

When you need a specific pattern, read that one file — not all of them. When you need a component, reference

components.md

— do not guess the CSS.

此技能采用渐进式信息披露。仅在需要时阅读参考文件：

```
references/decision-tree.md
```
—— 完整的模式选择指南及示例
```
references/components.md
```
—— 包含15种可复用UI组件的组件库，附HTML + CSS代码
```
references/palette-override.md
```
—— 如何通过AGENTS.md按项目自定义颜色和核心主题变量
```
references/quality-checklist.md
```
—— 交付前的验证清单
```
references/patterns/*.md
```
—— 每种模式对应一个文件，包含结构蓝图 + 完整示例

当需要特定模式时，仅阅读该模式文件——无需全部阅读。当需要组件时，请参考

components.md

——不要自行猜测CSS代码。