diff --git a/craft/README.md b/craft/README.md index 79d2994bb..da96fa619 100644 --- a/craft/README.md +++ b/craft/README.md @@ -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) | diff --git a/craft/typography-hierarchy-editorial.md b/craft/typography-hierarchy-editorial.md new file mode 100644 index 000000000..4803d395f --- /dev/null +++ b/craft/typography-hierarchy-editorial.md @@ -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. diff --git a/craft/typography-hierarchy.md b/craft/typography-hierarchy.md new file mode 100644 index 000000000..a5e6afb6e --- /dev/null +++ b/craft/typography-hierarchy.md @@ -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 `

` may render visually quieter than a nearby `

` 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. diff --git a/skills/blog-post/SKILL.md b/skills/blog-post/SKILL.md index 61da55584..3c91c3359 100644 --- a/skills/blog-post/SKILL.md +++ b/skills/blog-post/SKILL.md @@ -26,7 +26,7 @@ od: requires: true sections: [color, typography, layout, components] craft: - requires: [rtl-and-bidi] + requires: [typography, typography-hierarchy, typography-hierarchy-editorial, rtl-and-bidi] --- # Blog Post Skill diff --git a/skills/digital-eguide/SKILL.md b/skills/digital-eguide/SKILL.md index 7a218b35a..7fe10b807 100644 --- a/skills/digital-eguide/SKILL.md +++ b/skills/digital-eguide/SKILL.md @@ -29,7 +29,9 @@ od: design_system: requires: true sections: [color, typography, layout, components] - example_prompt: "Design ‘The Creator's Style & Format Guide’ — cover page and one inside spread, lifestyle creator brand." + craft: + requires: [typography, typography-hierarchy, typography-hierarchy-editorial, rtl-and-bidi] + example_prompt: "Design 'The Creator's Style & Format Guide' — cover page and one inside spread, lifestyle creator brand." --- # Digital E-Guide Skill diff --git a/skills/docs-page/SKILL.md b/skills/docs-page/SKILL.md index 208da7055..9eb800aff 100644 --- a/skills/docs-page/SKILL.md +++ b/skills/docs-page/SKILL.md @@ -22,7 +22,7 @@ od: requires: true sections: [color, typography, layout, components] craft: - requires: [rtl-and-bidi] + requires: [typography, typography-hierarchy, typography-hierarchy-editorial, rtl-and-bidi] --- # Docs Page Skill