④段整套同步（六节 ＋ P/S/F/J ＋ 模板）＋ open-design 移到技能根
一、④段整套同步（用户选候选 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。
This commit is contained in:
admin committed
1 parent
fa0a9026c8
commit
5afeb6b78a
4184 files changed
+326
-70
No files matched your search
@@ -0,0 +1,165 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user