admin
5afeb6b78a
一、④段整套同步（用户选候选 A）
- 新增 `references/stage-proto-doc/assets/产品文档模板.html`（16 KB／247 行，从备份拷、转 LF）。
- ④段 SKILL.md 换成备份 15:28 那版，并按模板口径改齐：
· 「产品文档框架」从「四块＋一附录」改成**六节** —— 页面结构／功能清单／使用场景／操作流程／
跨页与界面状态／待确认与偏离；与模板同构，⛔ 不从空白页重写结构。
· 编号从 R/S/F 改成 **P 页面／S 场景／F 功能／J 二级功能**，各自唯一、按展示顺序通排。
· 保留旧版有价值的要求：每项功能补齐 做什么／入口在哪／输入边界／异常与恢复；重点功能三处标红；
横向流程图每步写清页面／功能／操作／完成判据。
· 完成标准「七节」→「六节」，自查清单同步换掉「需求」那批条目，补模板与配图两条。
· 路径 `designs/<项目>/` → `docs/pm/<项目>/ui/`（2 处）。
· 补回本机那条「每份产出文档开头都要有一张图」的引用（指向主 skill，段内不复述）。
- 主 skill 同步：四段结构表④行、④段沿革、画图小节（④段画页面结构图 ＋ 用户路径）。
二、open-design 移到技能根（用户选候选 A）
- `git mv product-planning/references/stage-delivery/assets/open-design → open-design/`（4178 文件）。
- `.gitignore` 白名单加 `!/open-design/` —— 否则移出去就不再纳入版本控制。
- 引用改 11 处：路径形态 `assets/open-design/...` → `<技能根>/open-design/...`；
「随段携带的自带件」改称「同根技能」；「路径怎么找」那条改成自带件（段内相对路径）与
同根技能（`<技能根>/<技能名>/`）两类分开写。
- open-design 自己的 ATTRIBUTION.md 两处同步（它现在与 oil-ui-pro 同层）。
- 副作用（有益）：命名闸门读数由 2063 降到 225 —— 此前它把 open-design 里 919 个第三方 md
当成规则一起扫了；现在只扫本包 23 个 md。已确认④段的 H1 与 4a/4b/4c 子步仍在检查范围内。
三、验收
- check_naming.py --ws E:/ProgramData/AIProject/contentm_agent ＝ 通过 225 / 失败 0 / 提示 27。
- 活文件里 `assets/open-design` 残留 0；工作区 CRLF 文件 0。
166 lines
7.2 KiB
Markdown
166 lines
7.2 KiB
Markdown
# Typography hierarchy craft rules
|
||
|
||
Shared hierarchy contracts that layer on top of `typography.md`. This file does
|
||
not repeat scale ranges or tracking values — those live in `typography.md`.
|
||
This file defines how hierarchy *behaves*: entry points, rhythm, tension, and
|
||
the conditions under which controlled violations are allowed. This contract
|
||
applies per-surface (a page with multiple pacing resets may establish new
|
||
primaries at intentional intervals), not globally.
|
||
|
||
> Opt in via `od.craft.requires: [typography, typography-hierarchy]`.
|
||
> Aesthetic-specific variants (e.g. `typography-hierarchy-editorial`) extend this.
|
||
|
||
---
|
||
|
||
## The core contract
|
||
|
||
Every typographic surface must satisfy all three:
|
||
|
||
1. **One dominant entry point.** The eye needs a place to start. One element
|
||
wins the hierarchy — not two, not three. If everything competes, nothing leads.
|
||
2. **Intentional rhythm between levels.** Hierarchy is not a list of sizes.
|
||
It is the *contrast* between them. Adjacent levels that are too close
|
||
in scale, weight, or spacing produce a flat, undifferentiated surface.
|
||
3. **Recoverable information flow.** Hierarchy may be inverted, collapsed,
|
||
or disrupted — but a reader must still be able to reconstruct the content
|
||
structure without re-reading. If they can't, it's chaos, not tension.
|
||
|
||
---
|
||
|
||
## Hierarchy vectors
|
||
|
||
Scale is one lever. Use all five.
|
||
|
||
| Vector | What it controls | Hierarchy direction |
|
||
|---|---|---|
|
||
| Scale | Size contrast between levels | Large → small reads as primary → secondary |
|
||
| Weight | Mass contrast between levels | Heavier reads as primary (see Controlled violations for weight inversion) |
|
||
| Spacing | Breathing room around an element | More space = more visual importance |
|
||
| Tracking | Tension and velocity | Tighter = faster; wider = ceremonial, slower |
|
||
| Alignment | Relationship to the grid/edge | Breaking alignment signals importance |
|
||
|
||
No single vector is required. A heading may lead through spacing alone if
|
||
scale is deliberately suppressed. A pull quote may lead through alignment
|
||
break. Identify which vectors are active and make sure at least two are
|
||
working in the same direction for the dominant element.
|
||
|
||
---
|
||
|
||
## Semantic role ≠ visual role
|
||
|
||
Allowed. Not an error. Not a lint violation.
|
||
|
||
An `<h1>` may render visually quieter than a nearby `<p>` if the
|
||
composition requires it. Body copy may behave like display typography.
|
||
A label may visually outrank a heading.
|
||
|
||
**The condition:** information flow must remain intact. A user who reads
|
||
linearly must still understand what is important, what supports it, and
|
||
what is incidental — regardless of which element "wins" visually.
|
||
|
||
---
|
||
|
||
## Hierarchy rhythm — the two failure modes
|
||
|
||
### Flat hierarchy
|
||
|
||
Everything lands at roughly the same visual weight. The surface reads as
|
||
a wall. Usually caused by:
|
||
- Scale steps that are too close (e.g. 18 / 20 / 22 px for three levels)
|
||
- Weight used only once (everything is regular, or everything is medium)
|
||
- Uniform spacing between all elements
|
||
|
||
Fix: increase contrast between levels. Use at least two vectors simultaneously.
|
||
|
||
### Noise hierarchy
|
||
|
||
Too many elements fighting for dominance. Everything is bold, large, or
|
||
accented. The eye has no resting point and no path.
|
||
|
||
Fix: promote one element deliberately. Demote everything else — including
|
||
things that feel important. Hierarchy is relative, not absolute.
|
||
|
||
---
|
||
|
||
## Controlled violations
|
||
|
||
The following are explicitly allowed when the three core contracts are met:
|
||
|
||
| Violation | Allowed when |
|
||
|---|---|
|
||
| Body copy at display scale | It is the intended entry point and nothing else competes |
|
||
| Heading rendered lighter than body | Intentional visual inversion with intact information flow |
|
||
| Zero scale contrast between levels | Hierarchy is carried entirely by spacing or tracking |
|
||
| No heading-level element visible | Hierarchy is emergent from layout/spacing alone |
|
||
| Primary-level spacing applied to secondary element | Creates deliberate tension while maintaining information flow |
|
||
|
||
**"Information flow remains intact" safeguards:**
|
||
- DOM/reading order still matches content meaning (no layout inversion breaks narrative)
|
||
- Proximity groups the inverted element with its parent/context
|
||
- Only one primary exists in the visual region (no competing co-primaries)
|
||
- A quick scan can identify entry point / support / incidental roles without rereading
|
||
|
||
---
|
||
|
||
## Spacing as hierarchy
|
||
|
||
Spacing is a full hierarchy vector. A typographic level can be elevated
|
||
entirely through surrounding whitespace without changing its size or weight.
|
||
|
||
Rules:
|
||
- Space above an element signals its relationship to what came before.
|
||
- Space below an element signals its relationship to what follows.
|
||
- An isolated element with large surrounding space reads as display-level
|
||
regardless of its font size.
|
||
- Uniform spacing between all elements destroys spatial hierarchy.
|
||
|
||
---
|
||
|
||
## Three-level working model
|
||
|
||
Most surfaces can be mapped to three functional levels:
|
||
|
||
| Level | Role | Typical vectors |
|
||
|---|---|---|
|
||
| **Primary** | Entry point. One at a time per visual region; long-form surfaces may re-establish at intentional pacing resets. | Scale, spacing, or alignment break |
|
||
| **Secondary** | Structure. Subdivides or supports primary. | Weight, scale step, or tracking shift |
|
||
| **Tertiary** | Incidental. Labels, captions, metadata. | Scale reduction, weight reduction, or positive tracking |
|
||
|
||
More than three visible levels above the fold is usually a composition problem,
|
||
not a hierarchy opportunity. Collapse or demote before adding a fourth level.
|
||
|
||
**Long-form surfaces:** May re-establish a primary at intentional pacing resets
|
||
(e.g. a new section with its own headline and breathing room). Never maintain
|
||
two simultaneous primaries within the same visual region.
|
||
|
||
---
|
||
|
||
## Anti-patterns
|
||
|
||
- **Graduated weight ladder** — regular → medium → semibold → bold → extrabold,
|
||
each level one step heavier. Reads as a default scale, not authored hierarchy.
|
||
Weight should jump, not step.
|
||
- **Uniform section spacing** — every section gap is the same value. No
|
||
hierarchy information is carried by spacing. Vary it deliberately.
|
||
- **Heading as the only hierarchy vector** — the heading is large and bold;
|
||
everything else is flat. The heading does all the work. This is a sign
|
||
that spacing and tracking are not being used as vectors.
|
||
- **Symmetrical emphasis** — two elements receive equal visual weight as
|
||
co-primaries. Pick one. The other becomes secondary.
|
||
- **Size-only hierarchy** — all contrast is in font size alone. Weight,
|
||
spacing, tracking, and alignment are uniform across levels. Fragile —
|
||
any layout constraint that collapses the size contrast destroys the hierarchy.
|
||
|
||
---
|
||
|
||
## Lint
|
||
|
||
- [ ] One element is unambiguously dominant above the fold.
|
||
- [ ] At least two hierarchy vectors are active on the dominant element.
|
||
- [ ] No two adjacent levels share the same scale, weight, AND spacing.
|
||
- [ ] Spacing between levels varies — at least one gap is ≥1.5× the others or
|
||
represents one typographic scale step (e.g. one token unit like `gap-md` vs `gap-sm`). (guidance)
|
||
- [ ] Semantic/visual role inversions remain structurally readable.
|
||
- [ ] Flat hierarchy: scale steps between levels are ≥1.25× apart OR compensated by a weight or spacing jump. (guidance)
|
||
- [ ] Noise hierarchy: no more than one element reads as primary above the fold.
|