@pugi/cli 1.0.0-alpha.26 → 1.0.0-alpha.260

package/skills/od-craft/references/rtl-and-bidi.md

@@ -0,0 +1,188 @@
+<!-- Vendored from nexu-io/open-design@78d5637cb49d (craft/rtl-and-bidi.md), Apache-2.0, Copyright 2026 Open Design contributors. Modified by Pugi: this header line added; the text below is otherwise verbatim. Paths it names (apps/daemon/src/lint-artifact.ts, pnpm lint:craft, od.craft.requires) are upstream's, not Pugi's: the Pugi port of the linter is packages/opencode/src/session/design-lint.ts. See NOTICE.md in the skill root. -->
+
+# RTL and bidirectional craft rules
+
+Universal rules for right-to-left layout and bidirectional text. The
+active `DESIGN.md` decides brand visual language; this file decides
+how that language behaves when the script reads from the right or
+mixes direction within a line.
+
+> Grounded in primary sources: Unicode UAX #9 revision 51 (Sept 2025)
+> + Unicode 17.0, CSS Logical Properties Level 1, HTML Living Standard
+> (`dir`, `<bdi>`), Tailwind v4.0/v4.2 changelogs, W3C alreq,
+> Material 3 RTL guidance, Apple HIG internationalization.
+
+## Base direction and language
+
+Every full-page RTL artifact needs `<html dir="rtl" lang="ar">` (or
+the matching `lang` for Hebrew, Persian, Urdu). The `lang` attribute
+drives font-stack selection, hyphenation, locale-aware speech
+synthesis, and search-engine indexing — `dir` alone isn't enough.
+Three patterns cover the common cases:
+
+- **Full-page RTL.** `<html dir="rtl" lang="ar">`. Everything inside inherits.
+- **Mixed-language subtree.** Nest `<section dir="ltr" lang="en">…</section>` (or vice versa) when an embedded block uses a different script. Code samples, English citations, foreign brand names.
+- **User-generated content of unknown direction.** `dir="auto"` on the paragraph. The browser resolves direction from the first strong directional character in the run.
+
+Setting `lang` without `dir` is fine **at the document root in a
+default-LTR page** — English doesn't need `dir="ltr"` there because
+the bidi base direction is already LTR. Inside any opposite-direction
+ancestor, `lang` does not reset the inherited base direction, so set
+both `lang` and `dir` on the subtree (`<section dir="ltr" lang="en">`).
+Setting `dir` without `lang` is rarely correct — at minimum drop the
+appropriate ISO-639 tag in.
+
+## Logical properties first
+
+Hardcoded `left` / `right` is a bug for any layout that might render
+RTL. Use logical properties on the inline axis. Use them on the block
+axis when the writing-mode varies; physical otherwise.
+
+| Logical | LTR resolves to | RTL resolves to |
+|---|---|---|
+| `margin-inline-start` / `padding-inline-start` / `inset-inline-start` | left | right |
+| `margin-inline-end` / `padding-inline-end` / `inset-inline-end` | right | left |
+| `border-inline-start` | border-left | border-right |
+| `border-start-start-radius` | border-top-left-radius | border-top-right-radius |
+| `text-align: start` / `text-align: end` | left / right | right / left |
+| `inline-size` / `block-size` | width / height | width / height |
+
+Browser support: core inline-axis logical properties are Baseline
+Widely Available (Chrome 87, Safari 14.1, Firefox 66; ≥95% global as
+of 2026-05).
+
+**Tailwind v4 changes the answer for new projects.** v4.0 (2025-01-22)
+folded inline-axis logical utilities into core (`ms-*`, `me-*`, `ps-*`,
+`pe-*`, `start-*`, `end-*`). v4.2 (2026-02-18) added the block-axis
+set (`mbs-*`, `mbe-*`, `pbs-*`, `pbe-*`) and renamed the inset
+utilities: `start-*` / `end-*` are deprecated (still work) in favor
+of `inset-s-*` / `inset-e-*`. The `tailwindcss-rtl` plugin is obsolete.
+Don't write `[dir="rtl"]:` overrides for spacing on Tailwind v4.
+
+## Bidirectional text
+
+UAX #9 rev 51 (Sept 2025) is a version stamp for Unicode 17.0. No
+algorithm change; `max_depth = 125` is permanently locked forward.
+
+UAX #9 defines two distinct families of bidi formatting characters
+that solve different problems:
+
+- **Isolate controls** (modern, prefer these): U+2066 LRI, U+2067 RLI, U+2068 FSI — opened with these, all closed with U+2069 PDI. An isolated run does not affect, and is not affected by, the surrounding paragraph's bidi resolution. Use FSI when the embedded run's direction is unknown ahead of time.
+- **Embedding / override controls** (legacy): U+202A LRE, U+202B RLE, U+202D LRO, U+202E RLO — all closed with U+202C PDF. These nest within the surrounding paragraph rather than isolating from it; LRO/RLO additionally force a direction onto neutral characters. Newer code should use isolates; touch embeddings only when interoperating with text from systems that emit them.
+
+**Use `<bdi>` in HTML; in plain text, pick the isolate that matches
+what you know about the run.** UAX #9 §2.7: *"where available, markup
+should be used instead of the explicit formatting characters."*
+`<bdi>` has been Baseline Widely Available since January 2020.
+Reach for control characters only in plain-text contexts (logs,
+plain-text emails, terminal output). When you do:
+
+- **LRI U+2066 + PDI U+2069** for known-LTR runs (English name in an Arabic paragraph, code-style identifiers, phone numbers).
+- **RLI U+2067 + PDI U+2069** for known-RTL runs (Arabic name in an English paragraph).
+- **FSI U+2068 + PDI U+2069** for unknown direction (UGC where the author and language can vary).
+
+Don't reach for FSI as the default — it auto-detects from the first
+strong character, which is the wrong choice when you already know
+what direction the run should be.
+
+`dir="auto"` on a paragraph or `<bdi>` lets the browser detect
+direction from the first strong directional character. Best for
+user-generated content where direction isn't known at author time.
+
+## What mirrors and what doesn't
+
+Mirroring isn't universal. The rules below are unanimous across
+Material 3 RTL guidance and Apple HIG internationalization.
+
+**Must mirror:**
+
+- Directional arrows (back / forward / next / previous), navigation rail position, tab order, calendar-grid weekday order.
+- Slider fill direction and **non-media** progress-bar fill (a download progress bar, a form-completion bar, an upload status). Media scrubbers stay LTR — see the Media row below.
+- Checkbox-and-label position. Label sits to the right in LTR, to the left in RTL.
+- Phone-number and IBAN affordances when the surrounding paragraph is RTL but the value itself is LTR — wrap the value in `<bdi dir="ltr">` (or `<span dir="ltr">`) so the digits don't reflow. Bare `<bdi>` is not enough: phone numbers and account numbers contain mostly weak / neutral characters, so first-strong direction detection is unreliable. Force LTR explicitly.
+
+**Must not mirror:**
+
+- Clock faces. Clockwise is universal.
+- Circular refresh / sync / reload icons. Same reason.
+- Media playback controls (play / pause / fast-forward / rewind) **and the media scrubber / progress timeline**. They represent tape direction, not reading direction.
+- Charts and graphs. X-axis stays mathematical, not linguistic.
+- Photographs, brand logos, physical-object icons (camera, keyboard, headphones). Identity over direction.
+
+**Numerals are not a mirroring decision.** They follow locale, not
+paragraph direction. Arabic-Indic digits carry bidi class **AN**, not
+EN — affects how they sit inside mixed-direction lines but does not
+flip them.
+
+**Single live conflict between platforms:** the search icon. SF Symbols
+ships an RTL `magnifyingglass` variant (Apple flips it). Material 3
+says don't flip the magnifying glass (handle stays bottom-right).
+Decide per-platform; don't synthesize a single rule.
+
+## Typography rules anchored here
+
+Two RTL-coupled typography rules sit in this file because they cause
+breakage at the layout level. The full Arabic / Hebrew typography
+guide (font picks, harakat line-height, OpenType shaping, mixed-script
+fallback chains) belongs in a future `craft/arabic-hebrew-typography.md`.
+
+- **Never apply CSS `letter-spacing` to Arabic runs.** alreq treats
+  letter-spacing as a boundary concept, not a uniform tracking value.
+  Applying tracking breaks the cursive joining the script depends on.
+- **Body type for Arabic runs ~14-18 px with line-height 1.5-1.75** to
+  give harakat (diacritics) clearance. Latin defaults are too tight.
+
+## Native mobile RTL parity
+
+Web RTL handling does not auto-translate to mobile. Each platform has
+its own direction primitive. Skills that emit web-only artifacts can
+skim this section; it's the entry point for skills that ship to
+mobile (mobile-onboarding, mobile-app, etc.).
+
+| Platform | Direction primitive | Spacing |
+|---|---|---|
+| iOS UIKit | `semanticContentAttribute = .forceRightToLeft` | `NSDirectionalEdgeInsets` |
+| iOS SwiftUI | `.environment(\.layoutDirection, .rightToLeft)` | `EdgeInsets` with `leading` / `trailing` |
+| Android Compose | `CompositionLocalProvider(LocalLayoutDirection provides LayoutDirection.Rtl)` | `PaddingValues` accepts start / end |
+| Flutter | `Directionality(textDirection: TextDirection.rtl)` | `EdgeInsetsDirectional.fromSTEB(...)` |
+| React Native | `I18nManager.forceRTL(true)` (requires native reload; no `forceLTR` parity, no `react-native-web` support) | `marginStart` / `marginEnd` |
+
+The rule across all platforms: prefer the directional primitive over
+the absolute one. `EdgeInsets.left/right` in Flutter, `paddingLeft` /
+`paddingRight` in Android, leading-vs-trailing in iOS — these are bugs
+waiting for an Arabic deployment.
+
+## Forms in RTL
+
+Form fields commonly mix scripts. Three rules cover most of it.
+
+- **`<input dir="auto">`** for any field whose value's direction is uncertain (search boxes, comment fields, free-text inputs). The browser detects from the first strong directional character.
+- **Force LTR on intrinsically-LTR fields** even inside an RTL paragraph: email, URL, phone, IBAN, credit-card. `<input type="email" dir="ltr">`.
+- **Wrap rendered values in `<bdi>`** when displaying mixed-script content (a username inside a paragraph, a model number inside a description). Stops the surrounding direction from rearranging the embedded value. For values whose direction is fixed and weak-character-heavy (phone, IBAN, card number), use `<bdi dir="ltr">` rather than bare `<bdi>` so first-strong detection doesn't misclassify.
+
+## Common mistakes (lint these)
+
+Mechanically lintable items can be flagged from CSS / source alone.
+Script-aware items need to detect Arabic / Hebrew runs in the
+rendered text and have legitimate exceptions (chart axes, physical
+icons, platform-specific placement).
+
+**Mechanically lintable:**
+
+- Hardcoded `left` / `right` / `text-align: left` in new CSS — bug for any layout that may render RTL. Exceptions: chart x-axes, physical-object icons, platform-pinned UI like a status-bar clock. Lint with an allow-list rather than blanket banning.
+- "Tailwind v4.2 logical-utility rename is `inline-s-*` / `inline-e-*`" — wrong family. Those are size utilities. The inset rename is `inset-s-*` / `inset-e-*`.
+- "WebKit doesn't support U+2066-U+2069" — wrong, they're interoperable across modern browsers. The "still missing" claim traces to a stale 2015 W3C test snapshot.
+- Setting `dir="rtl"` without `lang="ar"` (or matching). Lint together; `dir` alone misses the font-stack and locale path.
+- Flutter `EdgeInsets.left/right` in code that needs to render RTL. Use `EdgeInsetsDirectional.start/end`.
+
+**Needs script detection (will false-positive without it):**
+
+- "Use `text-justify: kashida` for Arabic" — no browser implements it. CSS `text-align: justify` adds inter-word spacing and looks unnatural in Arabic; kashida elongation is the correct form, but it isn't shippable on the web today.
+- Italics on Arabic or Hebrew text. Neither script has an italic tradition.
+- CSS `letter-spacing` applied to Arabic. Breaks cursive joining (alreq treats it as a boundary concept, not a uniform tracking value).
+- Lorem Ipsum used for RTL prototyping. Arabic word lengths, connection behaviors, and vertical extents differ; use real Arabic / Hebrew text.
+
+**HTML semantics:**
+
+- Reaching for CSS bidi controls (`unicode-bidi: isolate` / `plaintext` / `embed`) for inline runs when `<bdi>` or a `dir`-bearing element does the job. Prefer semantic isolation in HTML for inline content; `unicode-bidi: plaintext` operates on a different surface (it changes how base direction is determined for each plaintext paragraph in a block) and should only be used when that block-level paragraph behavior is explicitly required and tested. The two are not drop-in equivalents — don't lint one as a replacement for the other.
+- Bare `<bdi>` around phone / IBAN / card numbers in an RTL paragraph. First-strong detection on weak/neutral characters is unreliable; force `dir="ltr"` explicitly.

package/skills/od-craft/references/state-coverage.md

@@ -0,0 +1,136 @@
+<!-- Vendored from nexu-io/open-design@78d5637cb49d (craft/state-coverage.md), Apache-2.0, Copyright 2026 Open Design contributors. Modified by Pugi: this header line added; the text below is otherwise verbatim. Paths it names (apps/daemon/src/lint-artifact.ts, pnpm lint:craft, od.craft.requires) are upstream's, not Pugi's: the Pugi port of the linter is packages/opencode/src/session/design-lint.ts. See NOTICE.md in the skill root. -->
+
+# State coverage craft rules
+
+Universal rules for what every interactive surface must render. The active
+`DESIGN.md` decides how each state looks; this file decides which states must
+exist and what they must contain. The single most reliable AI-design failure
+is shipping only the populated state.
+
+> Distilled from WCAG 2.2, NN/g, Material Design 3, Apple HIG, and Baymard
+> Institute checkout research.
+
+## The five required states
+
+Every surface that fetches, transforms, or accepts data must render all five.
+
+| State | Triggered when | Must contain |
+|---|---|---|
+| **Loading** | Data is in flight | Skeleton, spinner, or shell — plus a 15 s "taking longer than expected" fallback |
+| **Empty** | No records yet, or query returned nothing | Headline, plain explanation, primary CTA |
+| **Error** | Fetch failed, server failure, validation rejection | Plain-language cause, recovery action, preserved user input |
+| **Populated** | Data present, primary case | The state the design was actually drawn for |
+| **Edge** | Extreme volume, long strings, missing optional fields, RTL or long-word content, partial network | Layout that does not break |
+
+Render-and-screenshot test: every list, table, card, form, and panel in the
+artifact has all five. Missing states are the most common silent failure of
+AI-generated UI.
+
+**Test matrix.** Concrete edge scenarios the surface must survive:
+
+| Skill type | Edge scenario |
+|---|---|
+| Dashboard / table | 10,000+ rows, all numeric columns, sort + filter applied |
+| Mobile card / list | 200-char title, missing avatar, missing secondary CTA |
+| Form | All optional fields empty, all required fields at max length |
+| Search results | Single-character query, query with only special chars, 1,000+ result count |
+| Detail view | Missing all optional metadata, RTL primary content with LTR embeds |
+
+## Form-specific states
+
+Forms add three states on top of the five.
+
+| State | Triggered when | Behavior |
+|---|---|---|
+| **Untouched** | Field has not yet had focus | Default styling; no validation messages |
+| **Dirty (valid)** | User typed and field passes validation | Persistent helper text remains; no success-coloring |
+| **Submitted-pending** | Submit clicked, awaiting server | Submit button enters loading state; fields lock against re-submission |
+
+Validation timing: validate **on blur**, not on first keystroke. For password
+and similar live fields, validate on each keystroke *only after the first
+blur*. Remove the error message the instant input becomes valid.
+
+## Empty state composition
+
+Empty is not the absence of state. It is its own state with a job.
+
+- **First-use empty** — illustration + headline + value sentence + primary CTA. The empty is the onboarding moment.
+- **No-results empty** — echo the query, suggest alternatives, never leave a true blank.
+- **Cleared empty** — celebratory phrasing, optional next-action.
+- **Error-as-empty** — never. An error is its own state with recovery information; do not collapse error into empty.
+
+**Server-driven vs client-driven.** When a search or query API can return fallback content in the empty payload (suggestions, related categories, popular results), prefer that over a client-side echo. Algolia, Elastic, and most modern search backends support this — the server has more context for what "no results, but maybe try X" should mean.
+
+## Error state composition
+
+Every error must answer three questions, in this order:
+
+1. **What happened.** "Your card was declined." Not "Something went wrong."
+2. **Why, if knowable.** "Insufficient funds." Or "Network unreachable — check your connection."
+3. **What the user can do.** A retry button, an alternative path, or a support link.
+
+Preserve user input across the error. The form must not clear on submit
+failure.
+
+Severity tiers:
+
+- **Field-level** — red border, inline message, focus moves to the field.
+- **Form-level** — error summary banner at top + per-field markers.
+- **Section-level** — inline panel with retry, surrounding sections still functional.
+- **Page-level** — full error state with illustration and recovery CTA.
+- **App-level** — persistent banner or modal for critical loss-of-functionality.
+
+Match severity to surface scope. A field validation failure does not warrant
+a page-level error.
+
+**Retry discipline.** A retry surface is not a button alone. It has timing rules:
+
+- First retry fires immediately on user click.
+- Second and third retries use exponential backoff: 2 s, 4 s, 8 s max.
+- After 3 failed retries, replace "Retry" with "Contact support" plus a copyable error ID. The user has done their job; the system now needs a human.
+- Show "Last attempted: Xs ago" on the error surface after the first retry, so the user knows how stale the failure is.
+
+## Loading state thresholds
+
+Pick the indicator by expected duration, not by what's available in the
+component library.
+
+| Duration | Indicator |
+|---|---|
+| 0–300 ms | None. Render synchronously; users perceive no delay. |
+| 300 ms – 2 s | Subtle spinner or skeleton. |
+| 2 – 10 s | Skeleton matched to expected layout, or labelled spinner ("Loading payments…"). |
+| 10 – 30 s | Determinate progress bar with cancel option. |
+| 30 – 60 s | Progress bar with explicit cancel affordance. The "taking longer than expected" notice already appeared at 15 s; do not repeat it. |
+| 60 s+ | Stop animation. Show error with retry, cancel, or continue. |
+
+Never leave a spinner running indefinitely. Start a timeout on every request.
+
+## ARIA and focus rules
+
+State changes must be announced and focused correctly.
+
+| Change | ARIA | Focus action |
+|---|---|---|
+| Inline error on submit | `role="alert"` on the message | Move focus to first error field |
+| Toast / non-urgent confirmation | `role="status"` (polite live region) | Do not move focus |
+| Critical error or destructive confirmation | `role="alertdialog"` (assertive) | Move focus to dialog |
+| Loading begins | `role="status"` announcement ("Loading…") | Do not move focus to spinner |
+| Loading ends, content appears | — | Move focus to loaded content if action was user-initiated |
+
+Live region containers must exist in the DOM before content is injected.
+Adding `aria-live` simultaneously with content does not trigger an
+announcement.
+
+## Common mistakes (lint these)
+
+- Surface renders only the populated state; loading, empty, error, and edge are absent.
+- Empty state is a literal blank or "No data" text with no headline, explanation, or action.
+- Error message reads "Something went wrong" with no cause or recovery.
+- Spinner with no timeout; runs indefinitely on slow or failed requests.
+- Submit clears form fields on validation failure, forcing re-entry.
+- Inline validation fires on first keystroke instead of on blur.
+- Full-page loading replaces the chrome when only one section is fetching.
+- Toast appears at a different screen position than previous toasts in the same artifact.
+- Color alone conveys error state — no icon, no text label.
+- Auto-dismissing toast cannot be paused on hover or focus (WCAG SC 2.2.1).

package/skills/od-craft/references/typography-hierarchy-editorial.md

@@ -0,0 +1,184 @@
+<!-- Vendored from nexu-io/open-design@78d5637cb49d (craft/typography-hierarchy-editorial.md), Apache-2.0, Copyright 2026 Open Design contributors. Modified by Pugi: this header line added; the text below is otherwise verbatim. Paths it names (apps/daemon/src/lint-artifact.ts, pnpm lint:craft, od.craft.requires) are upstream's, not Pugi's: the Pugi port of the linter is packages/opencode/src/session/design-lint.ts. See NOTICE.md in the skill root. -->
+
+# 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 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
+
+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 for Latin display. At editorial display sizes
+(56 px+), tracking should be `-0.02em` to `-0.05em` (editorial override;
+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
+
+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 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 |
+
+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. Use `text-align: start` with a ragged inline-end edge — the
+natural 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` (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 |
+
+---
+
+## 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 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.
+
+---
+
+## 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+ (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 — 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).
+- [ ] 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.