WORK-660
ID:WORK-660Status:ready

Stop documenting heading eyebrows

ADR-046 decides that an eyebrow is a paragraph directly before the headline, never a heading. The docs still teach the heading form. The guide's only example of it uses hero, which renders it wrongly (BUG-047), and nineteen rune pages say "a short paragraph or heading" in the same boilerplate sentence.

The native page-section runes keep their grammar until each one is composed (ADR-046, decision 4), so some of them still accept the heading form. The docs stop recommending it anyway: it is not the direction, and documenting less than a rune accepts is safe where documenting more is not.

Priority:mediumComplexity:simpleMilestone:v0.44.0Source:ADR-046
claude/post-v0.43-roadmap-mf1ngx View source

Criteria completion

Criteria completion: 0 of 4 (0%) checked; tracking started on Oct 26, no incremental history yet0%25%50%75%100%Oct 26Oct 28

Tracking started Oct 26 — check back for trends.

History 2
  1. 0ec343f
    Content editedby bjornolofandersson
  2. 44496d2
    Created (ready)by bjornolofandersson

Acceptance Criteria

  • The "Heading eyebrow + headline" section of site/content/docs/authoring/page-sections.md is removed, and the guide says an eyebrow is a short paragraph directly before the headline
  • The boilerplate sentence on every rune page that links to page sections says "a short paragraph", not "a short paragraph or heading" (nineteen pages, found with grep -rn "paragraph or heading" site/content)
  • No page under site/content describes or shows two leading headings as an eyebrow and a headline
  • npm run format:md:check passes

Approach

Text-only. The nineteen pages share one sentence; change "Place a short paragraph or heading before …" to "Place a short paragraph before …" in each, keeping the rest of each sentence as it is. In the guide, delete the section and its example, and add one sentence to "Paragraph eyebrow

  • headline" saying a heading is never read as an eyebrow.

This fits beside WORK-656, which makes the eyebrow a section role and also touches the eyebrow docs, but it does not depend on it.

References

  • ADR-046: the resolved open question.
  • SPEC-160: D7, no heading eyebrow in the composed hero and cta.
  • BUG-047: the documented example renders wrongly today.