github/nexu-io-open-design
1
0
Fork 0
mirror of https://github.com/nexu-io/open-design.git synced 2026-07-03 12:27:55 +08:00
Code Issues Packages Projects Releases Wiki Activity

add typography-hierarchy and typography-hierarchy-editorial craft rules (#975)

Browse Source 
* add typography-hierarchy and typography-hierarchy-editorial craft rules

Adds two layered craft files extending typography.md:

- typography-hierarchy.md: core hierarchy contract, vectors, failure modes,
  controlled violations, and lint checklist
- typography-hierarchy-editorial.md: editorial pacing, dramatic scale jumps,
  whitespace hierarchy, display tracking overrides, and editorial-specific lint

Both files are registered in craft/README.md with guidance on when to require them.
Includes a new editorial stack example showing the layered opt-in pattern.

Validation:
- pnpm guard: PASSED
- Universal craft knowledge (not brand-specific)
- Stable slugs: typography-hierarchy, typography-hierarchy-editorial
- No new dependencies or breaking changes

Passes craft additions lane per code-review-guidelines.md.

* wire typography base into editorial skills craft stack

All three editorial skills now require the complete layered stack:
  [typography, typography-hierarchy, typography-hierarchy-editorial, rtl-and-bidi]

The new hierarchy files (typography-hierarchy.md, typography-hierarchy-editorial.md)
explicitly extend typography.md and depend on its base contract (scale ranges,
tracking values, line-height guidance, weight system). Without typography in
requires[], the hierarchy rules arrive at runtime without their foundational
contracts, making them incomplete.

Skills updated:
- skills/blog-post/SKILL.md
- skills/docs-page/SKILL.md
- skills/digital-eguide/SKILL.md

This completes the craft injection for the editorial stack as documented in
craft/README.md and ensures both base typography and hierarchy extensions load
together at runtime.
This commit is contained in:
Vedank Vansia
2026-05-08 23:45:33 +05:30
committed by GitHub
parent 362b92c1a6
commit ebe3513ed4
6 changed files with 344 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
craft/README.md
View File

@@ -29,6 +29,15 @@ od:
requires: [typography, color, anti-ai-slop]
```
Use the layered stack for editorial skills that require authored hierarchy
and sustained reading behavior:
```yaml
od:
craft:
requires: [typography, typography-hierarchy, typography-hierarchy-editorial]
```
Allowed values match the file names in this directory minus the `.md`
extension. Unknown values are silently ignored (forward-compatible).
@@ -62,6 +71,8 @@ A purely behavioral craft file (state-coverage, animation-discipline) is guidanc
| File | Section name | When to require |
|---|---|---|
| `typography.md` | `typography` | Any skill that emits typed content (~all skills) |
| `typography-hierarchy.md` | `typography-hierarchy` | Any skill that emits typed content where hierarchy must feel authored, not assembled — especially surfaces with a strong entry point, varied levels, or intentional rhythm. Compose with `typography`. |
| `typography-hierarchy-editorial.md` | `typography-hierarchy-editorial` | Skills whose primary artifact is a sustained reading surface: `blog-post`, `docs-page`, `digital-eguide`. Requires `typography` + `typography-hierarchy`. |
| `color.md` | `color` | Any skill that emits styled output (~all skills) |
| `anti-ai-slop.md` | `anti-ai-slop` | Marketing pages, landing pages, decks |
| `state-coverage.md` | `state-coverage` | Any skill with stateful UI (dashboards, mobile apps, forms, list/table views) |

169
craft/typography-hierarchy-editorial.md Normal file
View File

@@ -0,0 +1,169 @@
# Editorial typography hierarchy craft rules
Extends `typography.md` + `typography-hierarchy.md`. Defines hierarchy
behavior for editorial surfaces: long-form articles, magazine layouts,
digital guides, editorial landing pages, and blog posts.
> Opt in via `od.craft.requires: [typography, typography-hierarchy, typography-hierarchy-editorial]`.
---
## What "editorial" means here
Editorial hierarchy means the pacing is authored the way a print art director
paces a spread: entry point, tension, rest, disruption, resolution. The reader
is moved through content rather than given a uniform reading surface. SaaS
hierarchy is additive — elements stack and each gets its turn. Editorial
hierarchy is compositional — elements are weighted against each other and
some are deliberately suppressed so others can breathe.
---
## Editorial hierarchy principles
### 1. Dramatic scale jumps
Editorial type scales are not gradual. The gap between display and body
is large — often 3–5× — because the display element is not just a heading,
it is a visual event.
| Level | Typical range | Notes |
|---|---|---|
| Display / lede | 56–96 px | (editorial override) May intentionally exceed the default `typography.md` display range |
| Deck / standfirst | 18–24 px | Large jump down — intentional |
| Body | 16–18 px | Close to deck is fine; they're in the same reading register |
| Pull quote | 28–40 px | Disrupts body rhythm; treated as a visual break, not a heading |
| Caption / label | 11–13 px | Minimal — never competes with body |
The gap between display and deck is the editorial signature. A small step
here reads as SaaS, not editorial.
### 2. Whitespace carries hierarchy
Editorial hierarchy is not announced by a heavy heading. It is created by
the space that surrounds an element. An article title in a moderate weight
surrounded by generous whitespace outranks a bold heading crammed against
its content.
Rules:
- Above-the-fold display element: minimum 2× the line-height in space above
and below before body begins.
- Pull quotes: full column margin on both sides, or break the grid entirely.
- Section breaks: use space alone. Do not add a rule, a divider, or a
decorative element. Space is enough.
- Caption clusters: tighter internal spacing, larger gap from the body above.
### 3. Restrained bold
Editorial systems use weight sparingly. The display element is often set in
a light or regular weight — hierarchy is carried by scale and space, not mass.
Bold in editorial context means: this word/phrase matters beyond the sentence.
It is not used for section labels, UI chrome, or navigation. One to two bold
phrases per 400 words of body copy is a working upper bound.
If everything important is bold, nothing is.
### 4. Display tracking
Negative tracking at large sizes is mandatory. At editorial display sizes
(56 px+), tracking should be `-0.02em` to `-0.05em` (editorial override;
see `typography.md` §display tracking for the default range). Light display
weights may go tighter within this range.
---
### 5. Pull quotes as rhythm disruption
A pull quote is not a blockquote. It is a visual interrupt.
| Property | Behavior |
|---|---|
| Scale | 28–40 px — above body, below display |
| Weight | Regular or light — never bold |
| Tracking | Slightly negative (`-0.01em`) or zero |
| Alignment | Break from body column — full width, or offset left/right |
| Spacing | Large above and below — equal to or greater than a section break |
| Color | May use `var(--accent)` as the only accent use on the page |
Pull quotes placed at regular intervals destroy their effect. One per
long-form article is usually correct. Two is a maximum.
### 6. Body measure and reading rhythm
Long-form body copy: 60–70 ch line length. Tighter than the `typography.md`
max because editorial reading is sustained, not scanning.
Line height: `1.6`–`1.7` for serif body. Slightly more generous than the
universal rule because editorial bodies are set at a reading size, not a UI
size.
Do not justify. Ragged right is the correct setting for editorial body copy
on screen.
### 7. Asymmetrical rhythm
Uniform section spacing reads as a template. Editorial pacing alternates
between compression and expansion:
- Dense section → spacious section → medium section.
- A tightly spaced image caption cluster immediately after a generous
body paragraph creates productive tension.
- The final section before a pull quote should tighten; after it, release.
---
## Editorial hierarchy table
| Element | Scale | Weight | Tracking | Leading | Spacing role |
|---|---|---|---|---|---|
| Display headline | 56–96 px | Light or regular | `-0.02em` to `-0.05em` | `1.0`–`1.1` | Event — generous above/below |
| Deck / standfirst | 18–24 px | Regular | `0` | `1.4`–`1.5` | Transitional — moderate gap below |
| Byline / dateline | 12–14 px | Regular or medium | `0.02em`–`0.04em` | `1.5` | Recedes — tight gap below |
| Body | 16–18 px | Regular | `0` | `1.6`–`1.7` | Baseline — rhythm carrier |
| Pull quote | 28–40 px | Regular or light | `-0.01em` | `1.2`–`1.3` | Interrupt — large above/below |
| Image caption | 12–13 px | Regular | `0.01em` | `1.5` | Recedes — tight cluster |
| Section label | 11–12 px | Medium | `0.06em`–`0.1em` (if caps) | `1.5` | Wayfinding only |
---
## Anti-patterns
- **Bold display headline** — editorial display is usually light or regular.
Bold display reads as billboard advertising. If the design system's display
weight is heavy, either use the regular cut or revisit the choice.
- **Uniform section padding** — every section has the same gap. No pacing.
The page reads as a list of content blocks.
- **Pull quote styled as a callout box** — border-left, background tint,
or card treatment. A pull quote is typographic. It does not need a container.
- **Deck set at body size** — the gap between headline and deck must be large
enough to read as a scale event. 18 px minimum for a deck below a 56 px+
headline.
- **Heading for every section** — editorial long-form does not require
a heading at every content shift. Space and pacing are allowed to do the
work. (guidance)
- **Positive tracking on display** — wide-tracked display headlines read as
a branding exercise. Tighten them.
- **UI chrome in the reading column** — buttons, tags, chip badges inside
the body text column. Keep the reading surface clean. UI elements live
outside the measure.
---
## Lint
- [ ] Display headline is light or regular weight unless the design system
specifies otherwise.
- [ ] Display tracking is within `-0.02em` to `-0.05em` at 56 px+.
- [ ] Gap between display and deck is a visible jump. (guidance)
- [ ] Body line height is `1.6`–`1.7`.
- [ ] Body measure is 60–70 ch.
- [ ] Pull quote, if present, breaks the body column (full width or offset).
- [ ] No more than 2 pull quotes in a single article surface. (long-form only)
- [ ] Section spacing alternates — at least one gap is meaningfully larger
than the others. (long-form only — guidance)
- [ ] Bold used ≤ 2 times per 400 words in body copy. (long-form only)
- [ ] `var(--accent)` used ≤ 2 times on the full editorial surface (see `color.md` §accent discipline).
- [ ] No divider rules or decorative elements used as section breaks.
Space alone is sufficient.
- [ ] Pull quote has no background, border, or container treatment.

159
craft/typography-hierarchy.md Normal file
View File

@@ -0,0 +1,159 @@
# 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 |
---
## 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 on compressed surfaces; one per surface on long-form. | 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 meaningfully larger
than the others.
- [ ] 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.