Start with the reading path
A reader may arrive from search halfway through an article, browse its headings on a phone, or enlarge the text before reading a code example. Keep the article in document order and let its controls adapt to the space around it.
The editable article-reading recipe composes Lumen’s Anchor, Collapsible, SkipLink, and ScrollProgress. A wider screen gets a contents rail. A narrow screen gets a native disclosure with a single border around the summary and chapter list. The chapter links have room to tap. Reading progress measures this article, so the site footer does not become part of the story.
On the released website, some tab, anchor, and progress behaviors were carried by a version-pinned consumer patch. The Lumen 5 candidate includes the shared fixes. Verify the upgrade against your own article before removing a patch.
Read the v4 to v5 migration guideConnect quotations and figures
The editorial appearance of Prose keeps paragraphs at a readable measure while media and technical examples use the available width. It styles the original headings, quotations, and captions without rewriting their content or IDs.
A clear reading path should survive a change in theme, language, or viewport.
Keep the quoted source in a native cite element. Write a useful image alternative independently of the visible caption, and keep figcaption inside the samefigure. Lumen components such as Code and charts retain their own figure styling.
---
import { Image, Prose } from '@santi020k/lumen-astro'
---
<Prose appearance="editorial">
<h2 id="principle">Keep the reading path clear</h2>
<blockquote>
<p>Your quoted passage.</p>
<footer>From <cite>The quoted work</cite></footer>
</blockquote>
<figure>
<Image src="/illustration.svg" alt="Describe the image" width="960" height="600" radius="none" />
<figcaption>Your authored caption.</figcaption>
</figure>
</Prose>Install the editable recipe
Add the Astro adapter and CLI, then copy the recipe into your application. The CLI owns installation and diagnostics. The copied composition belongs to your app, while its imports continue to receive package-owned primitive fixes.
pnpm add @santi020k/lumen-astro
pnpm add -D @santi020k/lumen
pnpm exec lumen add article-reading --target astronpm install @santi020k/lumen-astro
npm install -D @santi020k/lumen
npx lumen add article-reading --target astroMount the runtime once in your root layout. Astro components include their selective CSS.
---
import UIPrimitives from '@santi020k/lumen-astro/runtime'
---
<html lang="en">
<body>
<slot />
<UIPrimitives />
</body>
</html>Give each heading a stable, unique ID and pass the same IDs into the recipe.
---
import ArticleReading from '../lumen/article-reading.astro'
const chapters = [{ id: 'design', label: 'Design the reading path' }]
---
<ArticleReading articleId="story" chapters={chapters}>
<section id="design">
<h2>Design the reading path</h2>
<p>Your original article goes here.</p>
</section>
</ArticleReading>Keep code examples connected
Both package-manager examples on this page share one storageKey. Choose npm above and the verification commands below follow that choice. The group you activate keeps focus while the other updates in place. The complete source remains available for copying.
Use a shared key only for examples representing the same choice. Keep an unrelated language picker independent. Long lines scroll within their own named region, with a cue when more content lies outside it.
Explore CodeTabsGive wide tables room
This table preserves its caption and headers. Focus the scroll region and use the arrow keys at narrow widths. The surrounding article continues to fit the viewport.
| Layer | Maintains | Example |
|---|---|---|
| Lumen primitive | Keyboard behavior and semantic controls | Anchor, CodeTabs, ScrollProgress |
| Editable recipe | Responsive composition and local labels | Contents rail and mobile disclosure |
| Application | Writing, routing, localization, and content policy | Heading IDs and publishing decisions |
For Markdown-generated tables, apply the same contract during rendering.
Build the Markdown table integrationVerify enlarged text
Run a built preview locally and audit this route at 320px with 200% text. The opt-in text scale check reports clipped control text alongside document overflow. Review each finding in the rendered page, including controls inside disclosures and overlays after opening them.
pnpm add -D @playwright/test
pnpm exec playwright install chromium
pnpm exec lumen audit-rendered http://127.0.0.1:4321/guides/build-an-editorial-article --viewport 320x844 --text-scale 200 --jsonnpm install -D @playwright/test
npx playwright install chromium
npx lumen audit-rendered http://127.0.0.1:4321/guides/build-an-editorial-article --viewport 320x844 --text-scale 200 --jsonRepeat at desktop width and in both themes. Follow a contents link, switch package managers, copy a complete example, and navigate away and back. Disable JavaScript to verify that headings, the mobile disclosure, and source examples remain readable. Use keyboard and screen-reader checks to verify the reading order and focus destination.
Explore scoped reading progress