From ee3ca5f4f031dd7fd69c9294a51e50342dcc608e Mon Sep 17 00:00:00 2001 From: Vedank Vansia <75930855+itsmeved24@users.noreply.github.com> Date: Sat, 9 May 2026 05:43:35 +0530 Subject: [PATCH] =?UTF-8?q?refine=20typography-hierarchy=20craft=20docs=20?= =?UTF-8?q?=E2=80=94=20clarify=20edge=20cases=20and=20make=20lint=20measur?= =?UTF-8?q?able=20(#979)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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. * refine craft docs for clarity and edge cases Address P2/P3 reviewer feedback: - typography-hierarchy-editorial.md §4: Add script-aware exception for Arabic/Hebrew/Persian tracking (cursive joining breaks with negative letter-spacing; use scale/space instead) - typography-hierarchy.md Controlled violations: Add concrete safeguards for 'information flow remains intact' (reading order, proximity grouping, single primary, quick scanability) - typography-hierarchy-editorial.md §2 Whitespace: Qualify 'no divider' rule to allow separators for publication identity, not just space alone - typography-hierarchy-editorial.md Anti-patterns: Add docs-page carve-out for 'UI chrome' (functional controls in code/API blocks are OK; decorative badges belong outside measure) - typography-hierarchy-editorial.md Lint: Make checks measurable — display/deck ratio >=1.5x, section spacing ratio rules (one gap >=1.5x baseline, another <=1.2x), separator identity check, and explicit guidance markers for auditability * address P1/P2/P3 reviewer feedback: RTL conflicts, script accuracy, tracking scope, measurability P1 — RTL physical-direction conflicts: - typography-hierarchy-editorial.md: Change 'ragged right' to 'text-align: start with ragged inline-end' for RTL compatibility - Separators in RTL: Add note on logical directions (inline-start/inline-end) - skills/digital-eguide/SKILL.md: Replace 'cover left, spread right' with 'inline-start/inline-end' and 'pinned right-side' with 'pinned to inline-end' P2 — Script-group accuracy: - Split script groups correctly: Arabic/Persian/Urdu cursive-joining (letter-spacing 0); Hebrew is RTL but not cursive-joining P2 — Tracking exception scope: - Extend script exception to pull-quote tracking row (was only on display) - Mark both as Latin-only with joining-script carve-out P2 — Primary-count inconsistency: - Clarify 'one at a time per visual region' with explicit long-form pacing resets note P3 — Measurable lint: - Replace vague 'meaningfully larger' with >=1.5x baseline rhythm OR one token scale step P3 — Orphaned reference: - Fix cross-ref to 'typography.md §letter-spacing' (was §display tracking) P3 — Markdown typo: - Fix backtick nesting in '1.6–1.7' line-height range * fix: RTL logical 'ragged' wording; make digital-eguide pull-quote script-aware; align section-separators lint with prose * fix(P2): include Persian/Urdu in pull-quote script exception; remove 'space' from section-separators lint * fix: align pull-quote bullet indentation in digital-eguide SKILL.md * fix: align digital-eguide pull-quote bullet nesting * fix: use logical pull-quote alignment wording in editorial craft --- craft/typography-hierarchy-editorial.md | 47 ++++++++++++++++--------- craft/typography-hierarchy.md | 12 +++++-- skills/digital-eguide/SKILL.md | 10 +++--- 3 files changed, 45 insertions(+), 24 deletions(-) diff --git a/craft/typography-hierarchy-editorial.md b/craft/typography-hierarchy-editorial.md index 4803d395f..c579579e4 100644 --- a/craft/typography-hierarchy-editorial.md +++ b/craft/typography-hierarchy-editorial.md @@ -49,8 +49,10 @@ 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. +- Section breaks: use space as the default hierarchy signal. Separators (rules, dingbats, + folios, chapter marks) are allowed only when they reinforce publication identity or + distinguish unrelated content. For RTL layouts, mirror or adapt separators using + logical directions (inline-start, inline-end) rather than physical (left, right). - Caption clusters: tighter internal spacing, larger gap from the body above. ### 3. Restrained bold @@ -66,11 +68,17 @@ If everything important is bold, nothing is. ### 4. Display tracking -Negative tracking at large sizes is mandatory. At editorial display sizes +Negative tracking at large sizes is mandatory for Latin display. 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 +see `typography.md` §letter-spacing for the default range). Light display weights may go tighter within this range. +**Script-aware exception:** For Arabic, Persian, and Urdu (cursive-joining scripts), +keep tracking at `0` — negative letter-spacing breaks cursive joining (see `rtl-and-bidi`). +Hebrew uses logical spacing rules but is not cursive-joining; consult `rtl-and-bidi` +for right-to-left baseline adjustments. Hierarchy in these scripts is carried by size, +weight, and whitespace, not tracking. + --- ### 5. Pull quotes as rhythm disruption @@ -82,7 +90,7 @@ A pull quote is not a blockquote. It is a visual interrupt. | 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 | +| Alignment | Break from body column — full width, or offset inline-start/inline-end | | 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 | @@ -98,8 +106,8 @@ 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. +Do not justify. Use `text-align: start` with a ragged inline-end edge — the +natural setting for editorial body copy on screen. ### 7. Asymmetrical rhythm @@ -121,7 +129,7 @@ between compression and expansion: | 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 | +| Pull quote | 28–40 px | Regular or light | `-0.01em` (Latin only; 0 for joining scripts) | `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 | @@ -144,9 +152,10 @@ between compression and expansion: 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. +- **UI chrome in the reading column** — buttons, tags, chip badges interrupting + prose flow inside the body text column. Functional controls (inline code-copy, + API anchors, callout toggles) may live inside code and API blocks, but decorative + badges and UI chrome should live outside the reading measure to keep prose focus clear. --- @@ -154,16 +163,20 @@ between compression and expansion: - [ ] 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) +- [ ] Display tracking is within `-0.02em` to `-0.05em` at 56 px+ (Latin only; + 0 for Arabic/Persian/Urdu joining scripts; see `rtl-and-bidi` for Hebrew). (guidance) +- [ ] Pull-quote tracking: `-0.01em` (Latin only; 0 for joining scripts). (guidance) +- [ ] Gap between display and deck: display/deck ratio ≥ 1.5× or absolute px delta + ≥ 24 px to read as a scale event. (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) +- [ ] Section spacing alternates — one gap ≥ 1.5× baseline rhythm while another + is ≤ 1.2×. (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. +- [ ] Section separators (rules, dingbats) are used only when they + reinforce publication identity or clearly mark unrelated-content boundaries; + they must not be used as a hierarchy fallback. (guidance) - [ ] Pull quote has no background, border, or container treatment. diff --git a/craft/typography-hierarchy.md b/craft/typography-hierarchy.md index a5e6afb6e..59079be6d 100644 --- a/craft/typography-hierarchy.md +++ b/craft/typography-hierarchy.md @@ -94,6 +94,12 @@ The following are explicitly allowed when the three core contracts are met: | 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 @@ -116,7 +122,7 @@ 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 | +| **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 | @@ -152,8 +158,8 @@ two simultaneous primaries within the same visual region. - [ ] 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. +- [ ] 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. diff --git a/skills/digital-eguide/SKILL.md b/skills/digital-eguide/SKILL.md index 7fe10b807..807b43a90 100644 --- a/skills/digital-eguide/SKILL.md +++ b/skills/digital-eguide/SKILL.md @@ -36,8 +36,8 @@ od: # Digital E-Guide Skill -Produce a two-page digital guide preview side-by-side. Cover on the left, -inside spread on the right. Lifestyle creator tone, lots of negative space, +Produce a two-page digital guide preview side-by-side. Cover on the inline-start, +inside spread on the inline-end. Lifestyle creator tone, lots of negative space, serif display headings, careful column rhythm. ## Workflow @@ -64,8 +64,10 @@ serif display headings, careful column rhythm. - Display sub-title ("Write like you talk — only sharper."). - 2-column body: opening paragraph + a numbered 4-step list ("01 Pick the rule", "02 Drop the filler"…). - - Pull-quote pinned right-side: large italic display, accent color, with - attribution. + - Pull-quote pinned to inline-end: for Latin scripts use large italic display + and accent color; for Arabic, Persian, and Urdu use regular or light + emphasis (no italics); for Hebrew use regular or light emphasis (no + italics). Include attribution. (script-aware) - Bottom strip with "EXERCISE" callout (mono label + 1 sentence prompt in italic). - Footer: chapter title + page 18 mono.