@luz-ds/docs 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024–2026 Fernando Muñoz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# @luz-ds/docs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The pieces of a documentation page: the shell (the sidebar, the content and a rail), the page head, the rail ("On this page" and the page's actions), the frame of a live example and its code, do and don't, Previous / Next and the page foot. Each is a class on a native element, on `@luz-ds/core`'s objects and components (`.o-shell`, `.o-main`, `.luz-sidebar`, `.luz-code-block`); docs adds only its layout, its skin and its rhythm. `@luz-ds/site` is optional: its search goes in the header.
+
+> **Beta, version 0.x.** Docs has a version of its own, apart from tokens, core and site, and grows in minor versions while it is 0.x: any of them may change a class. Pin an exact version and read the changelog before you upgrade.
+
+## When to use it
+
+- You write the documentation of a library, a product or an API, one page per thing, with a sidebar of pages.
+- You show live examples with their markup, and say what to do and what not to do.
+- Not for a landing page (`@luz-ds/landing`), a blog (`@luz-ds/cms`) or a web application (`@luz-ds/app`).
+
+The shell has three columns from 80 rem (the sidebar 16.5 rem, the content, the rail 14 rem), two from 60 rem (the rail above the content, in its column) and one below, where core's sidebar is a drawer at 768 px and below when it is a popover. The content keeps to a measure of 46 rem (`--luz-docs-measure`).
+
+## Prerequisites
+
+Requires `@luz-ds/tokens` and `@luz-ds/core`, version `^0.1.0`, declared as peer dependencies, loaded in that order before this package. `@luz-ds/site` (`^0.1.0`) is an optional peer: load it before this package if you use its search; the patterns work without it.
+
+## Installation
+
+```bash
+npm install @luz-ds/tokens @luz-ds/core @luz-ds/site @luz-ds/docs
+```
+
+## Usage
+
+### Via npm/bundler
+
+```js
+import '@luz-ds/tokens/css'
+import '@luz-ds/core/css'
+import '@luz-ds/site/css'
+import '@luz-ds/docs/css'
+```
+
+### Via CDN
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/tokens@0.1.0/dist/luz-tokens.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/core@0.1.0/dist/luz.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/site@0.1.0/dist/site.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/docs@0.1.0/dist/docs.min.css">
+```
+
+There is no script: "On this page" is a native `<details>`, the rail stays in view with native sticky positioning and the drawer is core's popover. Core's script is optional: with it, the sidebar and the rail mark the section in view.
+
+## Package exports
+
+- **`./css`** → `docs.css` — the patterns, in the cascade layer `luz.docs`, after `luz.app` (`./css/min` for the minified twin)
+- **`./components/*`** → `dist/components/` — one stylesheet per pattern, `<name>.css` and `<name>.min.css`, each in `luz.docs`, for a page that loads only what it uses
+
+## Classes included
+
+- `.luz-docs-shell` (with `.luz-docs-nav` and `.luz-docs-main`) — The page: core's `.o-shell` with the header, the sidebar, the content, the rail and the footer in three, two or one column; sets `--luz-docs-measure`. [Docs](https://nandovejer.github.io/luz/docs/documentation/shell/)
+- `.luz-docs-page-head` (`__eyebrow`, `__lead`, `__meta`) — The area and group, the h1, one sentence and a row of chips (the files, the script, the modes, the known issues). [Docs](https://nandovejer.github.io/luz/docs/documentation/page-head/)
+- `.luz-docs-rail` (`__inner`, `__onpage`, `__fold`, `__title`, `__list`, `__sub`, `__link`, `__actions`) — "On this page" and the page's actions in one inner box, in view while the page scrolls and never over the footer. [Docs](https://nandovejer.github.io/luz/docs/documentation/rail/)
+- `.luz-docs-example` (`__preview`, `__frame`, `__code`) — A live example and its code in one frame; `--luz-docs-example-w` narrows the frame. [Docs](https://nandovejer.github.io/luz/docs/documentation/example/)
+- `.luz-docs-dodont` (`__item`, `__item--do`, `__item--dont`, `__verdict`, `__stage`) — A Do and a Don't, side by side when there is room, told apart by a word, a mark and the frame. [Docs](https://nandovejer.github.io/luz/docs/documentation/dodont/)
+- `.luz-docs-pager` (`__prev`, `__next`, `__link`, `__label`, `__title`) — Previous and Next as two link blocks. [Docs](https://nandovejer.github.io/luz/docs/documentation/pager/)
+- `.luz-docs-page-foot` — Last updated, Edit this page, Report a problem. [Docs](https://nandovejer.github.io/luz/docs/documentation/page-foot/)
+
+<!-- luz:ai-agents:start -->
+## For AI agents
+
+`@luz-ds/docs` 0.1.0 is in beta: any release may break anything. Read the breaking changes below before you update, and use only what the files under "Read first" list.
+
+### Breaking changes
+
+First release of `@luz-ds/docs`. Nothing breaks inside @luz-ds. Coming from `@cai-ds/*`: see the migration note in `CHANGELOG.md`.
+
+Older versions: https://github.com/nandovejer/luz/blob/main/packages/docs/CHANGELOG.md
+
+### Read first
+
+1. `dist/classes.json` in this package: the classes and custom properties its CSS defines. Write only those.
+2. https://nandovejer.github.io/luz/llms.txt: the index of the documentation, short enough for a small context.
+3. https://nandovejer.github.io/luz/llms-full.txt: the same pages in full.
+4. https://nandovejer.github.io/luz/examples/: one standalone page of markup for each component and pattern.
+
+### Load order
+
+This package needs `@luz-ds/tokens` and `@luz-ds/core` loaded first.
+
+`@luz-ds/site` is optional: the CSS of this package works with the packages above alone.
+
+### Check what you write
+
+Run `npx @luz-ds/check <files>` on every HTML and CSS file you write, and fix what it reports. To copy the accessibility reviewer into your project: `npx @luz-ds/check agent > .claude/agents/luz-accessibility-reviewer.md`.
+
+<!-- luz:ai-agents:end -->
+
+## License
+
+MIT

package/dist/classes.json

@@ -0,0 +1,47 @@
+{
+  "schema": 1,
+  "package": "@luz-ds/docs",
+  "version": "0.1.0",
+  "classes": [
+    { "name": "luz-docs-dodont", "kind": "pattern", "layer": "luz.docs", "files": ["components/dodont.css"], "defined": true, "block": "luz-docs-dodont" },
+    { "name": "luz-docs-dodont__item", "kind": "pattern", "layer": "luz.docs", "files": ["components/dodont.css"], "defined": true, "block": "luz-docs-dodont", "part": "item" },
+    { "name": "luz-docs-dodont__item--do", "kind": "pattern", "layer": "luz.docs", "files": ["components/dodont.css"], "defined": true, "block": "luz-docs-dodont", "modifier": "do", "part": "item" },
+    { "name": "luz-docs-dodont__item--dont", "kind": "pattern", "layer": "luz.docs", "files": ["components/dodont.css"], "defined": true, "block": "luz-docs-dodont", "modifier": "dont", "part": "item" },
+    { "name": "luz-docs-dodont__stage", "kind": "pattern", "layer": "luz.docs", "files": ["components/dodont.css"], "defined": true, "block": "luz-docs-dodont", "part": "stage" },
+    { "name": "luz-docs-dodont__verdict", "kind": "pattern", "layer": "luz.docs", "files": ["components/dodont.css"], "defined": true, "block": "luz-docs-dodont", "part": "verdict" },
+    { "name": "luz-docs-example", "kind": "pattern", "layer": "luz.docs", "files": ["components/example.css"], "defined": true, "block": "luz-docs-example" },
+    { "name": "luz-docs-example__code", "kind": "pattern", "layer": "luz.docs", "files": ["components/example.css"], "defined": true, "block": "luz-docs-example", "part": "code" },
+    { "name": "luz-docs-example__frame", "kind": "pattern", "layer": "luz.docs", "files": ["components/example.css"], "defined": true, "block": "luz-docs-example", "part": "frame" },
+    { "name": "luz-docs-example__preview", "kind": "pattern", "layer": "luz.docs", "files": ["components/example.css"], "defined": true, "block": "luz-docs-example", "part": "preview" },
+    { "name": "luz-docs-main", "kind": "pattern", "layer": "luz.docs", "files": ["components/shell.css"], "defined": true, "block": "luz-docs-main" },
+    { "name": "luz-docs-nav", "kind": "pattern", "layer": "luz.docs", "files": ["components/shell.css"], "defined": true, "block": "luz-docs-nav" },
+    { "name": "luz-docs-page-foot", "kind": "pattern", "layer": "luz.docs", "files": ["components/page-foot.css"], "defined": true, "block": "luz-docs-page-foot" },
+    { "name": "luz-docs-page-head", "kind": "pattern", "layer": "luz.docs", "files": ["components/page-head.css"], "defined": true, "block": "luz-docs-page-head" },
+    { "name": "luz-docs-page-head__eyebrow", "kind": "pattern", "layer": "luz.docs", "files": ["components/page-head.css"], "defined": true, "block": "luz-docs-page-head", "part": "eyebrow" },
+    { "name": "luz-docs-page-head__files", "kind": "pattern", "layer": "luz.docs", "files": ["components/page-head.css"], "defined": true, "block": "luz-docs-page-head", "part": "files" },
+    { "name": "luz-docs-page-head__lead", "kind": "pattern", "layer": "luz.docs", "files": ["components/page-head.css"], "defined": true, "block": "luz-docs-page-head", "part": "lead" },
+    { "name": "luz-docs-page-head__meta", "kind": "pattern", "layer": "luz.docs", "files": ["components/page-head.css"], "defined": true, "block": "luz-docs-page-head", "part": "meta" },
+    { "name": "luz-docs-pager", "kind": "pattern", "layer": "luz.docs", "files": ["components/pager.css"], "defined": true, "block": "luz-docs-pager" },
+    { "name": "luz-docs-pager__label", "kind": "pattern", "layer": "luz.docs", "files": ["components/pager.css"], "defined": true, "block": "luz-docs-pager", "part": "label" },
+    { "name": "luz-docs-pager__link", "kind": "pattern", "layer": "luz.docs", "files": ["components/pager.css"], "defined": true, "block": "luz-docs-pager", "part": "link" },
+    { "name": "luz-docs-pager__next", "kind": "pattern", "layer": "luz.docs", "files": ["components/pager.css"], "defined": true, "block": "luz-docs-pager", "part": "next" },
+    { "name": "luz-docs-pager__prev", "kind": "pattern", "layer": "luz.docs", "files": ["components/pager.css"], "defined": true, "block": "luz-docs-pager", "part": "prev" },
+    { "name": "luz-docs-pager__title", "kind": "pattern", "layer": "luz.docs", "files": ["components/pager.css"], "defined": true, "block": "luz-docs-pager", "part": "title" },
+    { "name": "luz-docs-rail", "kind": "pattern", "layer": "luz.docs", "files": ["components/rail.css", "components/shell.css"], "defined": true, "block": "luz-docs-rail" },
+    { "name": "luz-docs-rail__actions", "kind": "pattern", "layer": "luz.docs", "files": ["components/rail.css"], "defined": true, "block": "luz-docs-rail", "part": "actions" },
+    { "name": "luz-docs-rail__fold", "kind": "pattern", "layer": "luz.docs", "files": ["components/rail.css"], "defined": false, "block": "luz-docs-rail", "part": "fold" },
+    { "name": "luz-docs-rail__inner", "kind": "pattern", "layer": "luz.docs", "files": ["components/rail.css"], "defined": true, "block": "luz-docs-rail", "part": "inner" },
+    { "name": "luz-docs-rail__link", "kind": "pattern", "layer": "luz.docs", "files": ["components/rail.css"], "defined": true, "block": "luz-docs-rail", "part": "link" },
+    { "name": "luz-docs-rail__list", "kind": "pattern", "layer": "luz.docs", "files": ["components/rail.css"], "defined": true, "block": "luz-docs-rail", "part": "list" },
+    { "name": "luz-docs-rail__onpage", "kind": "pattern", "layer": "luz.docs", "files": ["components/rail.css"], "defined": false, "block": "luz-docs-rail", "part": "onpage" },
+    { "name": "luz-docs-rail__sub", "kind": "pattern", "layer": "luz.docs", "files": ["components/rail.css"], "defined": true, "block": "luz-docs-rail", "part": "sub" },
+    { "name": "luz-docs-rail__title", "kind": "pattern", "layer": "luz.docs", "files": ["components/rail.css"], "defined": true, "block": "luz-docs-rail", "part": "title" },
+    { "name": "luz-docs-shell", "kind": "pattern", "layer": "luz.docs", "files": ["components/shell.css"], "defined": true, "block": "luz-docs-shell" }
+  ],
+  "properties": [
+    { "name": "--luz-docs-measure", "scope": "component", "layer": "luz.docs", "files": ["components/shell.css"] },
+    { "name": "--luz-docs-nav-w", "scope": "component", "layer": "luz.docs", "files": ["components/shell.css"] },
+    { "name": "--luz-docs-rail-top", "scope": "component", "layer": "luz.docs", "files": ["components/shell.css"] },
+    { "name": "--luz-docs-rail-w", "scope": "component", "layer": "luz.docs", "files": ["components/shell.css"] }
+  ]
+}

package/dist/components/dodont.css

@@ -0,0 +1,85 @@
+@layer luz.tokens, luz.themes, luz.settings, luz.generic, luz.elements, luz.objects, luz.components, luz.utilities, luz.site, luz.landing, luz.cms, luz.app, luz.docs, luz.print;
+@layer luz.docs {
+/* ==========================================================================
+   LUZ DOCS: do and don't.
+   div.luz-docs-dodont > figure.__item.__item--do, then --dont, each a
+   figcaption > strong.__verdict ("Do", "Don't") and its reason, then a
+   div.__stage (the example, inert and aria-hidden: the caption says what it
+   shows) or a code block. Side by side when there is room, stacked below.
+   The verdict is a word; the mark before it (a tick, a cross) and the
+   frame (solid, dashed) are extra cues, never the only one, and so is the
+   colour (green, red).
+   ========================================================================== */
+
+.luz-docs-dodont {
+	display: grid;
+	grid-template-columns: repeat(auto-fit, minmax(min(100%, 17.5rem), 1fr));
+	gap: var(--luz-space-md);
+}
+
+.luz-docs-dodont__item {
+	display: grid;
+	grid-template-rows: auto 1fr;
+	gap: var(--luz-space-sm);
+	min-inline-size: 0;
+	margin: 0;
+	padding: var(--luz-space-sm);
+	border: 2px solid var(--luz-divider);
+	border-radius: var(--luz-radius-md);
+	background: var(--luz-surface);
+	color: var(--luz-text-primary);
+}
+
+.luz-docs-dodont__item--do {
+	border-color: var(--luz-color-success);
+}
+
+.luz-docs-dodont__item--dont {
+	border-style: dashed;
+	border-color: var(--luz-color-danger);
+}
+
+.luz-docs-dodont__item > :where(figcaption) {
+	font-style: normal;
+}
+
+.luz-docs-dodont__verdict {
+	display: block;
+	color: var(--luz-color-success);
+	font-family: var(--luz-font-sans);
+}
+
+.luz-docs-dodont__item--dont .luz-docs-dodont__verdict {
+	color: var(--luz-color-danger);
+}
+
+/* The mark is decoration: the word says it. A browser without alternative
+   text for content reads the first value */
+.luz-docs-dodont__verdict::before {
+	content: "\2713  ";
+	content: "\2713  " / "";
+}
+
+.luz-docs-dodont__item--dont .luz-docs-dodont__verdict::before {
+	content: "\2715  ";
+	content: "\2715  " / "";
+}
+
+.luz-docs-dodont__stage {
+	display: grid;
+	gap: var(--luz-space-sm);
+	align-content: center;
+	min-inline-size: 0;
+	padding: var(--luz-space-md);
+	border: 1px solid var(--luz-divider);
+	border-radius: var(--luz-radius-sm);
+	background: var(--luz-surface-page);
+	color: var(--luz-text-primary);
+	overflow-wrap: anywhere;
+}
+
+.luz-docs-dodont__stage > :where(*) {
+	margin-block: 0;
+}
+
+}

package/dist/components/dodont.min.css

@@ -0,0 +1 @@
+@layer luz.tokens,luz.themes,luz.settings,luz.generic,luz.elements,luz.objects,luz.components,luz.utilities,luz.site,luz.landing,luz.cms,luz.app,luz.docs,luz.print;@layer luz.docs{.luz-docs-dodont{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,17.5rem),1fr));gap:var(--luz-space-md)}.luz-docs-dodont__item{display:grid;grid-template-rows:auto 1fr;gap:var(--luz-space-sm);min-inline-size:0;margin:0;padding:var(--luz-space-sm);border:2px solid var(--luz-divider);border-radius:var(--luz-radius-md);background:var(--luz-surface);color:var(--luz-text-primary)}.luz-docs-dodont__item--do{border-color:var(--luz-color-success)}.luz-docs-dodont__item--dont{border-style:dashed;border-color:var(--luz-color-danger)}.luz-docs-dodont__item>:where(figcaption){font-style:normal}.luz-docs-dodont__verdict{display:block;color:var(--luz-color-success);font-family:var(--luz-font-sans)}.luz-docs-dodont__item--dont .luz-docs-dodont__verdict{color:var(--luz-color-danger)}.luz-docs-dodont__verdict:before{content:"\2713  ";content:"\2713  " / ""}.luz-docs-dodont__item--dont .luz-docs-dodont__verdict:before{content:"\2715  ";content:"\2715  " / ""}.luz-docs-dodont__stage{display:grid;gap:var(--luz-space-sm);align-content:center;min-inline-size:0;padding:var(--luz-space-md);border:1px solid var(--luz-divider);border-radius:var(--luz-radius-sm);background:var(--luz-surface-page);color:var(--luz-text-primary);overflow-wrap:anywhere}.luz-docs-dodont__stage>:where(*){margin-block:0}}

package/dist/components/example.css

@@ -0,0 +1,46 @@
+@layer luz.tokens, luz.themes, luz.settings, luz.generic, luz.elements, luz.objects, luz.components, luz.utilities, luz.site, luz.landing, luz.cms, luz.app, luz.docs, luz.print;
+@layer luz.docs {
+/* ==========================================================================
+   LUZ DOCS: example.
+   figure.luz-docs-example > div.__preview (the live markup, in a
+   div.__frame) + an optional div.__code (core's pre.luz-code-block). One
+   frame for both: the code sits under the preview, across its width, and a
+   long line scrolls inside its own box. The frame is as wide as the
+   preview, or as --luz-docs-example-w says (a width selector sets it:
+   20rem is a phone), never wider; it is a size container, so what is in it
+   answers to the frame.
+   ========================================================================== */
+
+.luz-docs-example {
+	display: grid;
+	grid-template-columns: minmax(0, 1fr);
+	margin: 0;
+	padding: 0;
+	border: 1px solid var(--luz-divider);
+	border-radius: var(--luz-radius-md);
+	background: var(--luz-surface);
+}
+
+.luz-docs-example__preview {
+	padding: var(--luz-space-md);
+}
+
+.luz-docs-example__frame {
+	inline-size: min(100%, var(--luz-docs-example-w, 100%));
+	margin-inline: auto;
+	container-type: inline-size;
+}
+
+.luz-docs-example__code {
+	min-inline-size: 0;
+	border-block-start: 1px solid var(--luz-divider);
+}
+
+/* The frame draws the edge: the code block keeps only its inner corners */
+.luz-docs-example__code > :where(pre) {
+	margin: 0;
+	border: 0;
+	border-radius: 0 0 calc(var(--luz-radius-md) - 1px) calc(var(--luz-radius-md) - 1px);
+}
+
+}

package/dist/components/example.min.css

@@ -0,0 +1 @@
+@layer luz.tokens,luz.themes,luz.settings,luz.generic,luz.elements,luz.objects,luz.components,luz.utilities,luz.site,luz.landing,luz.cms,luz.app,luz.docs,luz.print;@layer luz.docs{.luz-docs-example{display:grid;grid-template-columns:minmax(0,1fr);margin:0;padding:0;border:1px solid var(--luz-divider);border-radius:var(--luz-radius-md);background:var(--luz-surface)}.luz-docs-example__preview{padding:var(--luz-space-md)}.luz-docs-example__frame{inline-size:min(100%,var(--luz-docs-example-w, 100%));margin-inline:auto;container-type:inline-size}.luz-docs-example__code{min-inline-size:0;border-block-start:1px solid var(--luz-divider)}.luz-docs-example__code>:where(pre){margin:0;border:0;border-radius:0 0 calc(var(--luz-radius-md) - 1px) calc(var(--luz-radius-md) - 1px)}}

package/dist/components/page-foot.css

@@ -0,0 +1,31 @@
+@layer luz.tokens, luz.themes, luz.settings, luz.generic, luz.elements, luz.objects, luz.components, luz.utilities, luz.site, luz.landing, luz.cms, luz.app, luz.docs, luz.print;
+@layer luz.docs {
+/* ==========================================================================
+   LUZ DOCS: page foot.
+   p.luz-docs-page-foot: "Last updated" and a <time>, then "Edit this page"
+   and "Report a problem", separated by a middle dot in the text. Small
+   print under the content, after the pager; it wraps on a narrow screen
+   and each link is a 28px target.
+   ========================================================================== */
+
+.luz-docs-page-foot {
+	margin: 0;
+	padding-block-start: var(--luz-space-md);
+	border-block-start: 1px solid var(--luz-divider);
+	font-family: var(--luz-font-sans);
+	font-size: var(--luz-text-sm);
+	color: var(--luz-text-secondary);
+}
+
+.luz-docs-page-foot > :where(a) {
+	display: inline-flex;
+	align-items: center;
+	min-block-size: var(--luz-control-sm);
+}
+
+/* The date in the size of the line, not core's smaller <time> */
+.luz-docs-page-foot > :where(time) {
+	font-size: inherit;
+}
+
+}

package/dist/components/page-foot.min.css

@@ -0,0 +1 @@
+@layer luz.tokens,luz.themes,luz.settings,luz.generic,luz.elements,luz.objects,luz.components,luz.utilities,luz.site,luz.landing,luz.cms,luz.app,luz.docs,luz.print;@layer luz.docs{.luz-docs-page-foot{margin:0;padding-block-start:var(--luz-space-md);border-block-start:1px solid var(--luz-divider);font-family:var(--luz-font-sans);font-size:var(--luz-text-sm);color:var(--luz-text-secondary)}.luz-docs-page-foot>:where(a){display:inline-flex;align-items:center;min-block-size:var(--luz-control-sm)}.luz-docs-page-foot>:where(time){font-size:inherit}}

package/dist/components/page-head.css

@@ -0,0 +1,99 @@
+@layer luz.tokens, luz.themes, luz.settings, luz.generic, luz.elements, luz.objects, luz.components, luz.utilities, luz.site, luz.landing, luz.cms, luz.app, luz.docs, luz.print;
+@layer luz.docs {
+/* ==========================================================================
+   LUZ DOCS: page head.
+   header.luz-docs-page-head > p.__eyebrow (the area · the group), h1,
+   p.__lead (one sentence), ul.__meta (chips: the files, the script or "No
+   JavaScript", the modes, whether it is tested, its known issues). A chip
+   is a word in a rounded outline; a link in one is a 28px target. A page
+   that is not a component says its files in p.__files instead, one quiet
+   line ("Files: <code>…</code>"), without the chips.
+   ========================================================================== */
+
+.luz-docs-page-head {
+	display: grid;
+	grid-template-columns: minmax(0, 1fr);
+	gap: var(--luz-space-sm);
+}
+
+.luz-docs-page-head > :where(h1) {
+	margin: 0;
+	font-size: var(--luz-text-4xl);
+	line-height: 1.1;
+	text-wrap: balance;
+}
+
+.luz-docs-page-head__eyebrow {
+	margin: 0;
+	font-family: var(--luz-font-sans);
+	font-size: var(--luz-text-xs);
+	font-weight: 500;
+	letter-spacing: 0.1em;
+	text-transform: uppercase;
+	color: var(--luz-text-secondary);
+}
+
+/* A package name in it keeps its own case: @luz-ds/core */
+.luz-docs-page-head__eyebrow :where(code) {
+	letter-spacing: 0;
+	text-transform: none;
+}
+
+/* Spacing between letters breaks the joins of Arabic script */
+.luz-docs-page-head__eyebrow:lang(ar) {
+	letter-spacing: 0;
+}
+
+.luz-docs-page-head__lead {
+	margin: 0;
+	font-size: var(--luz-text-lg);
+	color: var(--luz-text-secondary);
+}
+
+.luz-docs-page-head__meta {
+	display: flex;
+	flex-wrap: wrap;
+	gap: var(--luz-space-xs);
+	margin: 0;
+	padding: 0;
+	list-style: none;
+	font-family: var(--luz-font-sans);
+	font-size: var(--luz-text-xs);
+	color: var(--luz-text-secondary);
+}
+
+.luz-docs-page-head__meta > :where(li) {
+	display: inline-flex;
+	align-items: center;
+	min-block-size: var(--luz-control-sm);
+	padding-inline: var(--luz-space-sm);
+	border: 1px solid var(--luz-divider);
+	border-radius: var(--luz-radius-full);
+	overflow-wrap: anywhere;
+}
+
+.luz-docs-page-head__meta :where(a) {
+	display: inline-flex;
+	align-items: center;
+	min-block-size: var(--luz-control-sm);
+}
+
+.luz-docs-page-head__files {
+	margin: 0;
+	font-family: var(--luz-font-sans);
+	font-size: var(--luz-text-xs);
+	color: var(--luz-text-secondary);
+	overflow-wrap: anywhere;
+}
+
+@media (max-width: 640px) {
+	.luz-docs-page-head > :where(h1) {
+		font-size: var(--luz-text-2xl);
+	}
+
+	.luz-docs-page-head__lead {
+		font-size: var(--luz-text-base);
+	}
+}
+
+}

package/dist/components/page-head.min.css

@@ -0,0 +1 @@
+@layer luz.tokens,luz.themes,luz.settings,luz.generic,luz.elements,luz.objects,luz.components,luz.utilities,luz.site,luz.landing,luz.cms,luz.app,luz.docs,luz.print;@layer luz.docs{.luz-docs-page-head{display:grid;grid-template-columns:minmax(0,1fr);gap:var(--luz-space-sm)}.luz-docs-page-head>:where(h1){margin:0;font-size:var(--luz-text-4xl);line-height:1.1;text-wrap:balance}.luz-docs-page-head__eyebrow{margin:0;font-family:var(--luz-font-sans);font-size:var(--luz-text-xs);font-weight:500;letter-spacing:.1em;text-transform:uppercase;color:var(--luz-text-secondary)}.luz-docs-page-head__eyebrow :where(code){letter-spacing:0;text-transform:none}.luz-docs-page-head__eyebrow:lang(ar){letter-spacing:0}.luz-docs-page-head__lead{margin:0;font-size:var(--luz-text-lg);color:var(--luz-text-secondary)}.luz-docs-page-head__meta{display:flex;flex-wrap:wrap;gap:var(--luz-space-xs);margin:0;padding:0;list-style:none;font-family:var(--luz-font-sans);font-size:var(--luz-text-xs);color:var(--luz-text-secondary)}.luz-docs-page-head__meta>:where(li){display:inline-flex;align-items:center;min-block-size:var(--luz-control-sm);padding-inline:var(--luz-space-sm);border:1px solid var(--luz-divider);border-radius:var(--luz-radius-full);overflow-wrap:anywhere}.luz-docs-page-head__meta :where(a){display:inline-flex;align-items:center;min-block-size:var(--luz-control-sm)}.luz-docs-page-head__files{margin:0;font-family:var(--luz-font-sans);font-size:var(--luz-text-xs);color:var(--luz-text-secondary);overflow-wrap:anywhere}@media(max-width:640px){.luz-docs-page-head>:where(h1){font-size:var(--luz-text-2xl)}.luz-docs-page-head__lead{font-size:var(--luz-text-base)}}}

package/dist/components/pager.css

@@ -0,0 +1,70 @@
+@layer luz.tokens, luz.themes, luz.settings, luz.generic, luz.elements, luz.objects, luz.components, luz.utilities, luz.site, luz.landing, luz.cms, luz.app, luz.docs, luz.print;
+@layer luz.docs {
+/* ==========================================================================
+   LUZ DOCS: pager.
+   nav[aria-label] > ul.luz-docs-pager > li.__prev / li.__next >
+   a.__link[rel] > span.__label ("Previous", "Next") + span.__title (the
+   page). Two link blocks side by side, Next at the end, the whole block the
+   link; stacked at 640px and below. Name each link from its visible text
+   first ("Previous: Badge").
+   ========================================================================== */
+
+.luz-docs-pager {
+	display: grid;
+	grid-template-columns: repeat(2, minmax(0, 1fr));
+	gap: var(--luz-space-md);
+	margin: 0;
+	padding: 0;
+	list-style: none;
+}
+
+.luz-docs-pager__prev {
+	grid-column: 1;
+}
+
+.luz-docs-pager__next {
+	grid-column: 2;
+	text-align: end;
+}
+
+.luz-docs-pager__link {
+	display: grid;
+	grid-template-columns: minmax(0, 1fr);
+	gap: var(--luz-space-3xs);
+	block-size: 100%;
+	padding: var(--luz-space-sm) var(--luz-space-md);
+	border: 1px solid var(--luz-divider);
+	border-radius: var(--luz-radius-md);
+	text-decoration: none;
+}
+
+.luz-docs-pager__link:hover {
+	border-color: var(--luz-outline);
+	background: var(--luz-surface-hover);
+}
+
+.luz-docs-pager__link:hover .luz-docs-pager__title {
+	text-decoration: underline;
+}
+
+.luz-docs-pager__label {
+	font-size: var(--luz-text-sm);
+	color: var(--luz-text-secondary);
+}
+
+.luz-docs-pager__title {
+	font-size: var(--luz-text-lg);
+	font-weight: 600;
+}
+
+@media (max-width: 640px) {
+	.luz-docs-pager {
+		grid-template-columns: minmax(0, 1fr);
+	}
+
+	.luz-docs-pager__next {
+		grid-column: 1;
+	}
+}
+
+}

package/dist/components/pager.min.css

@@ -0,0 +1 @@
+@layer luz.tokens,luz.themes,luz.settings,luz.generic,luz.elements,luz.objects,luz.components,luz.utilities,luz.site,luz.landing,luz.cms,luz.app,luz.docs,luz.print;@layer luz.docs{.luz-docs-pager{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:var(--luz-space-md);margin:0;padding:0;list-style:none}.luz-docs-pager__prev{grid-column:1}.luz-docs-pager__next{grid-column:2;text-align:end}.luz-docs-pager__link{display:grid;grid-template-columns:minmax(0,1fr);gap:var(--luz-space-3xs);block-size:100%;padding:var(--luz-space-sm) var(--luz-space-md);border:1px solid var(--luz-divider);border-radius:var(--luz-radius-md);text-decoration:none}.luz-docs-pager__link:hover{border-color:var(--luz-outline);background:var(--luz-surface-hover)}.luz-docs-pager__link:hover .luz-docs-pager__title{text-decoration:underline}.luz-docs-pager__label{font-size:var(--luz-text-sm);color:var(--luz-text-secondary)}.luz-docs-pager__title{font-size:var(--luz-text-lg);font-weight:600}@media(max-width:640px){.luz-docs-pager{grid-template-columns:minmax(0,1fr)}.luz-docs-pager__next{grid-column:1}}}