refine typography-hierarchy craft docs — clarify edge cases and make lint measurable (#979)

* 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

@@ -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.

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.

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.