owflow 0.1.4 → 0.1.6

package/dist/skills/diagrams-mermaid/references/reference.md

@@ -0,0 +1,148 @@
+# Mermaid Diagram Reference
+
+Quick reference for selecting and writing diagrams in planning workflows.
+
+Hard rule for output artifacts:
+- Every diagram must be emitted only in fenced ` ```mermaid ` blocks.
+- Any other fenced diagram format (for example ` ```c4plantuml ` or ` ```plantuml `) is not allowed.
+
+## Quick Type Selector
+
+```mermaid
+flowchart TD
+  inputTask[TaskContext] --> needTime{NeedTimeOrder}
+  needTime -->|yes| seq[sequenceDiagram]
+  needTime -->|no| needState{NeedStateTransitions}
+  needState -->|yes| state[stateDiagram-v2]
+  needState -->|no| needArch{NeedArchitectureView}
+  needArch -->|yes| c4level{RequiredC4Level}
+  c4level -->|system| c4context[C4Context]
+  c4level -->|service| c4container[C4Container]
+  c4level -->|module| c4component[C4Component]
+  needArch -->|no| flow[flowchart]
+```
+
+## Minimal Templates
+
+### flowchart
+
+```mermaid
+flowchart TD
+  start[Start] --> decision{"Condition?"}
+  decision -->|"yes"| nextA[PathA]
+  decision -->|"no"| nextB[PathB]
+  nextA --> done[Done]
+  nextB --> done
+```
+
+### sequenceDiagram
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant ServiceA
+  participant ServiceB
+  User->>ServiceA: Request
+  alt ValidInput
+    ServiceA->>ServiceB: FetchData
+    ServiceB-->>ServiceA: Data
+    ServiceA-->>User: Success
+  else InvalidInput
+    ServiceA-->>User: ValidationError
+  end
+```
+
+### stateDiagram-v2
+
+```mermaid
+stateDiagram-v2
+  [*] --> Draft
+  Draft --> Review: submit
+  Review --> Approved: accept
+  Review --> Draft: request_changes
+  Approved --> [*]
+```
+
+### C4Context
+
+```mermaid
+C4Context
+  Person(user, "User")
+  System(targetSystem, "TargetSystem")
+  System_Ext(extSystem, "ExternalSystem")
+  Rel(user, targetSystem, "Uses")
+  Rel(targetSystem, extSystem, "Calls")
+```
+
+### C4Container
+
+```mermaid
+C4Container
+  Person(user, "User")
+  System_Boundary(boundary, "TargetSystem") {
+    Container(webApp, "WebApp", "React", "UI")
+    Container(apiService, "APIService", "Node.js", "Business logic")
+    ContainerDb(mainDb, "MainDB", "PostgreSQL", "Persistent storage")
+  }
+  Rel(user, webApp, "Interacts with")
+  Rel(webApp, apiService, "Calls")
+  Rel(apiService, mainDb, "Reads/Writes")
+```
+
+## Anti-Patterns
+
+1. **Domain hallucination (critical)**  
+   Adding systems/components not present in supplied context.
+
+2. **Abstraction mixing**  
+   Example: C4 context and function-level call chain in one chart.
+
+3. **Unbounded complexity**  
+   One giant diagram instead of split views.
+
+4. **Ambiguous naming**  
+   Non-semantic IDs (`A`, `B`, `step1`) without readable labels.
+
+5. **Sequence misuse**  
+   Interaction diagram without meaningful order/branches.
+
+6. **Non-Mermaid fenced output (hard failure)**  
+   Emitting any diagram in a non-`mermaid` fenced block.
+
+## "Bad -> Better" Examples
+
+### Inventing missing context
+
+Bad:
+- "Assume we also have Kafka and Redis" (not provided by user/context)
+
+Better:
+- "Current context is missing messaging/storage components. Please confirm whether any queue/cache exists."
+
+### Mixed detail levels
+
+Bad:
+- One diagram contains external systems, services, and method-level internals.
+
+Better:
+- Diagram 1: C4 context/container; Diagram 2: sequence for one critical interaction.
+
+## Parser Safety Notes
+
+- Use quoted labels for text with special characters.
+- Avoid fragile IDs and reserved keywords.
+- Prefer clear ASCII names for IDs.
+- Keep one diagram focused on one communication concern.
+
+## Integration Candidates
+
+Integrated into:
+- `src/skills/flow-init/SKILL.md` - Phase 6 (architecture and tech-stack doc refinement)
+- `src/skills/development/SKILL.md` - Phase 5 (spec refinement), Phase 7 (plan refinement)
+- `src/skills/research/SKILL.md` - Phase 5 (high-level design refinement)
+- `src/skills/performance/SKILL.md` - Phase 3 (spec refinement), Phase 5 (plan refinement)
+- `src/skills/migration/SKILL.md` - Phase 3 (spec refinement), Phase 4 (plan refinement)
+
+Reference files:
+- `src/skills/flow-init/references/architecture-template.md`
+- `src/skills/orchestrator-framework/references/orchestrator-patterns.md`

package/dist/skills/flow-init/SKILL.md

@@ -146,6 +146,21 @@ Fill templates using:
 
 Write each file to `.owflow/docs/project/`.
 
+**Diagram refinement (content-preserving, do NOT replace prose):**
+
+- If Architecture doc is selected and `.owflow/docs/project/architecture.md` exists:
+  1. Invoke Skill tool: `diagrams-mermaid`
+  2. Pass context from analysis + generated architecture content
+  3. Add Mermaid sections that **refine** the document:
+     - `## Visual Architecture Context` (prefer `C4Context` or `C4Container`)
+     - `## Component Communication Flow` (prefer `sequenceDiagram` or `flowchart`)
+  4. Keep existing architecture narrative intact; diagrams must supplement, not replace sections.
+
+- If Tech Stack doc is selected and `.owflow/docs/project/tech-stack.md` exists:
+  1. Invoke Skill tool: `diagrams-mermaid`
+  2. Add one lightweight visual section (e.g., runtime/build dependency flow) only if context is sufficient
+  3. If context is insufficient, keep text-only output and list missing details (no invented dependencies).
+
 ---
 
 ## PHASE 7: Validate

package/dist/skills/html-renderer/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: html-renderer
+description: Render a markdown plan, idea, RFC, or design note into a self-contained, share-ready HTML file using the warm editorial visual system bundled under `references/`. Use this skill whenever the user asks to "render", "convert", "turn into HTML", "make a nice HTML version", "share this as a page", or "make this look good" for a markdown file containing a plan, proposal, idea, brief, RFC, design note, or pitch — even if they don't explicitly say "HTML". The output is a single .html file with all CSS inlined, written next to the source .md, that visually matches the reference layout in `references/index.html` and uses tokens from `references/tokens.json`.
+disable-model-invocation: true
+user-invocable: true
+---
+
+# HTML Renderer
+
+Turn a markdown plan/idea/RFC into a single self-contained HTML page that follows the warm editorial design system bundled in this skill.
+
+## When to use
+
+The user gives you a markdown file (or pastes markdown) describing a plan, idea, proposal, RFC, design note, or brief, and wants a clean HTML representation they can share. Output is *always* a portable single-file `.html` with the stylesheet inlined — no external assets, no JS.
+
+This skill is opt-in: it does not auto-trigger. The user invokes it explicitly.
+
+## Inputs and outputs
+
+- **Input**: path to a `.md` file (or raw markdown content). If raw markdown is provided, ask for a filename stem.
+- **Output**: write `<source-basename>.html` in the same directory as the source `.md`. If the source is `~/notes/q4-plan.md`, output is `~/notes/q4-plan.html`.
+- **Self-contained**: inline the full stylesheet inside a single `<style>` block in `<head>`. Do not link to external CSS, fonts (use the font stacks already in tokens — they fall back to system fonts), or images that aren't already in the source. The one allowed external script is Mermaid (see "Mermaid diagrams" below), and only when the source contains at least one ` ```mermaid ` fence.
+- **Title**: use the first `# H1` from the markdown as `<title>`; if none, fall back to the file's basename humanized.
+
+## Reference files (read these before writing output)
+
+The `references/` folder is the source of truth for the visual system. Read each file once at the start of a rendering task so the output matches:
+
+- `references/index.html` — canonical reference page showing every component (heading scale, text block, cards, table, diagram, quote, highlights). Use it as the structural template: the output should look like a variant of this page filled with the user's content.
+- `references/styles.css` — every `hr-*` class definition. **Copy this verbatim into the inlined `<style>` block** of the output. Do not paraphrase, rewrite, or trim it; the classes you emit in the HTML must resolve against these exact rules.
+- `references/tokens.json` — design tokens (colors, spacing, radius, typography). The CSS already consumes these via `:root` variables, so tokens.json is mostly informational — consult it only if the user asks to tweak colors/spacing or when you need to add a new component that should harmonize with existing tokens.
+
+Reuse existing classes and tokens before inventing anything. If the user asks for something genuinely new, declare any new CSS variables in `:root` using the same naming pattern, and keep class names prefixed with `hr-`.
+
+## Workflow
+
+1. **Resolve input**: confirm the source markdown path; read the file.
+2. **Load references**: read `references/index.html` (structure), `references/styles.css` (full CSS to inline), and `references/tokens.json` (only if you need token values).
+3. **Plan structure**: scan the markdown and decide how to group content into `<section class="hr-section hr-stack">` blocks. Each top-level `##` typically opens a new section.
+4. **Map elements** using the mapping table below.
+5. **Assemble** a single HTML document:
+   - `<!doctype html>` + `<html lang="en">` + `<head>` with `<meta charset>`, `<meta viewport>`, `<title>`, and a `<style>` block containing the *entire* contents of `references/styles.css`.
+   - `<body>` containing `<main class="hr-page">` wrapping the sectioned content.
+6. **Write** the file as `<basename>.html` next to the source.
+7. **Verify**: re-open the output and confirm every `class="hr-..."` you emitted exists in the inlined CSS.
+
+## Markdown → HTML mapping
+
+| Markdown | HTML |
+|---|---|
+| `# Title` (first one) | `<h1 class="hr-heading-h1">` (also sets `<title>`) |
+| `##`, `###`, `####` | `<h2 class="hr-heading-h2">`, `<h3 class="hr-heading-h3">`, `<h4 class="hr-heading-h4">` |
+| Eyebrow line (italic small intro before H1, e.g. `_Reference Base_`) | `<span class="hr-heading-eyebrow">` |
+| Paragraphs & lists in narrative flow | wrap in `<div class="hr-text-block hr-stack">` |
+| Short summary paragraph right under H1 | `<p class="hr-text-muted">` |
+| Unordered/ordered lists | plain `<ul>`/`<ol>` inside `hr-text-block` |
+| `**bold**` / `*italic*` | `<strong>` / `<em>` |
+| Inline `` `code` `` | `<code>` |
+| Links `[text](url)` | `<a href="url">text</a>` |
+| Horizontal rule `---` | new `<section class="hr-section hr-stack">` (prefer sectioning over `<hr>`) |
+| Tables | `<div class="hr-table-wrap"><table class="hr-table">…</table></div>` |
+| Blockquote `>` | `<blockquote class="hr-quote">`; if the last line starts with `— `, render as `<footer>` |
+| ` ```mermaid ` code fence | `<div class="hr-diagram"><div class="mermaid">…raw mermaid source, **not** HTML-escaped…</div></div>` (also include the Mermaid script described in "Mermaid diagrams" below) |
+| Any other fenced code | `<pre><code>…</code></pre>` (escape `<`, `>`, `&`) |
+| Admonitions — lines starting with `> [!NOTE]`, `> [!WARNING]`, `> [!IMPORTANT]` (GitHub-style) or sections prefixed `**Note:**`, `**Warning:**`, `**Important:**` | `<aside class="hr-highlight hr-highlight-{note\|warning\|important}">` with `<p class="hr-highlight-title">` for the label |
+| Card-like content — a bolded title followed by 1–3 lines, especially in a list of similar items | `<article class="hr-card">` with `<h3 class="hr-card-title">` and `<p class="hr-card-text">`. Wrap multiple cards in `<div class="hr-grid">` (auto-fit). For fixed layouts use `hr-grid-2`, `hr-grid-3`, `hr-grid-4`, `hr-grid-feature` (2fr/1fr/1fr with `hr-card-featured` first), or `hr-grid-sidebar` (2fr/1fr). Mark the most important card as `hr-card-featured`. |
+| Tags / labels (e.g. `[Priority]`, `[Default]`) | `<span class="hr-badge">` |
+
+When the markdown is ambiguous (e.g., "is this a card or a paragraph?"), prefer the simpler choice: text block first, cards only when the content is clearly a set of parallel small items.
+
+## Rendering rules
+
+1. Every class you emit must be prefixed `hr-` and must exist in `references/styles.css`. If you need a new one, also add its rule to the inlined `<style>` and (if it relies on a new token) extend `:root`.
+2. No inline `style="…"` attributes unless the user explicitly asks for a one-off override.
+3. Favor semantic tags (`section`, `article`, `aside`, `blockquote`, `table`, `figure`) and apply `hr-*` classes on top of them.
+4. Escape HTML special characters in content (`<`, `>`, `&`) so user prose never breaks the page.
+5. **Keep the output a single file with zero external dependencies** — it must render correctly when opened directly in a browser. The one exception is the Mermaid CDN script, which is only injected when ` ```mermaid ` fences are present; users will need network access to see those diagrams render (the raw mermaid source remains in the DOM as a graceful fallback).
+
+## Mermaid diagrams
+
+When the source markdown contains one or more ` ```mermaid ` fences:
+
+1. Render each fence as:
+   ```html
+   <div class="hr-diagram">
+     <div class="mermaid">
+   …raw mermaid source, preserved verbatim, NOT HTML-escaped…
+     </div>
+   </div>
+   ```
+   Mermaid replaces the inner text with an SVG at page load, so the content must stay as plain text (do not wrap it in `<pre><code>` and do not escape `<`, `>`, `&` — mermaid needs the original characters).
+2. Inject the Mermaid script + initializer immediately before `</body>`, exactly once per document:
+   ```html
+   <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+   <script>
+     window.mermaid &&
+       mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+   </script>
+   ```
+3. If the markdown has no ` ```mermaid ` fences, **do not** add the script — keep the output fully offline.
+
+## Minimal example
+
+Input (`idea.md`):
+```markdown
+# Lightweight RFC inbox
+
+A small daily ritual to capture half-formed ideas without losing them.
+
+## Why
+Ideas evaporate within a day if there's no easy capture path.
+
+## How
+- One markdown file per idea
+- Rendered to HTML on demand for sharing
+
+> [!NOTE]
+> This is intentionally low-tech: no database, no auth.
+```
+
+Output (`idea.html`, abbreviated):
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Lightweight RFC inbox</title>
+    <style>/* entire contents of references/styles.css inlined here */</style>
+  </head>
+  <body>
+    <main class="hr-page">
+      <section class="hr-section hr-stack">
+        <h1 class="hr-heading-h1">Lightweight RFC inbox</h1>
+        <p class="hr-text-muted">A small daily ritual to capture half-formed ideas without losing them.</p>
+      </section>
+      <section class="hr-section hr-stack">
+        <h2 class="hr-heading-h2">Why</h2>
+        <div class="hr-text-block hr-stack">
+          <p>Ideas evaporate within a day if there's no easy capture path.</p>
+        </div>
+      </section>
+      <section class="hr-section hr-stack">
+        <h2 class="hr-heading-h2">How</h2>
+        <div class="hr-text-block hr-stack">
+          <ul>
+            <li>One markdown file per idea</li>
+            <li>Rendered to HTML on demand for sharing</li>
+          </ul>
+        </div>
+        <aside class="hr-highlight hr-highlight-note">
+          <p class="hr-highlight-title">Note</p>
+          <p>This is intentionally low-tech: no database, no auth.</p>
+        </aside>
+      </section>
+    </main>
+  </body>
+</html>
+```

package/dist/skills/html-renderer/references/index.html

@@ -0,0 +1,318 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>HTML Renderer Reference</title>
+    <link rel="stylesheet" href="./styles.css" />
+  </head>
+  <body>
+    <main class="hr-page">
+      <section class="hr-section hr-stack">
+        <span class="hr-heading-eyebrow">Reference Base</span>
+        <h1 class="hr-heading-h1">Warm editorial HTML component reference</h1>
+        <p class="hr-text-muted">
+          This page demonstrates all required building blocks for markdown to
+          HTML output.
+        </p>
+      </section>
+
+      <section class="hr-section hr-stack">
+        <h2 class="hr-heading-h2">Heading scale</h2>
+        <h1 class="hr-heading-h1">H1 Display Headline</h1>
+        <h2 class="hr-heading-h2">H2 Section Headline</h2>
+        <h3 class="hr-heading-h3">H3 Subsection Headline</h3>
+        <h4 class="hr-heading-h4">H4 Utility Headline</h4>
+      </section>
+
+      <section class="hr-section hr-stack">
+        <h2 class="hr-heading-h2">Text block</h2>
+        <div class="hr-text-block hr-stack">
+          <p>
+            Text blocks should carry the main narrative, with generous line
+            height and warm contrast against the canvas.
+          </p>
+          <p>
+            Lists remain simple and semantic, while styles stay tied to global
+            tokens.
+          </p>
+          <ul>
+            <li>Use one visual rhythm across all paragraphs.</li>
+            <li>Keep spacing and emphasis token-based.</li>
+            <li>Avoid local one-off colors in content blocks.</li>
+          </ul>
+        </div>
+      </section>
+
+      <section class="hr-section hr-stack">
+        <h2 class="hr-heading-h2">Cards</h2>
+        <div class="hr-grid">
+          <article class="hr-card">
+            <h3 class="hr-card-title">Default content card</h3>
+            <p class="hr-card-text">
+              Standard container for summaries, supporting notes, and grouped
+              metadata.
+            </p>
+            <span class="hr-badge">Default</span>
+          </article>
+
+          <article class="hr-card hr-card-featured">
+            <h3 class="hr-card-title">Featured surface card</h3>
+            <p class="hr-card-text">
+              High-emphasis card for key outcomes, strategic calls to action,
+              or highlighted analysis.
+            </p>
+            <span class="hr-badge">Priority</span>
+          </article>
+        </div>
+      </section>
+
+      <section class="hr-section hr-stack">
+        <h2 class="hr-heading-h2">Table</h2>
+        <div class="hr-table-wrap">
+          <table class="hr-table">
+            <thead>
+              <tr>
+                <th>Element</th>
+                <th>Purpose</th>
+                <th>Main token group</th>
+                <th>Priority</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr>
+                <td>Card</td>
+                <td>Grouped content blocks</td>
+                <td>surface + radius + spacing</td>
+                <td>High</td>
+              </tr>
+              <tr>
+                <td>Quote</td>
+                <td>Context and citations</td>
+                <td>primary + display typography</td>
+                <td>Medium</td>
+              </tr>
+              <tr>
+                <td>Highlight</td>
+                <td>Important callouts</td>
+                <td>semantic + border accent</td>
+                <td>High</td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </section>
+
+      <section class="hr-section hr-stack">
+        <h2 class="hr-heading-h2">Diagram container</h2>
+
+        <h3 class="hr-heading-h3">Flowchart</h3>
+        <div class="hr-diagram">
+          <div class="mermaid">
+flowchart TD
+  markdownInput[MarkdownInput] --> semanticParse[SemanticParse]
+  semanticParse --> componentSelect[ComponentSelect]
+  componentSelect --> tokenBind[TokenBinding]
+  tokenBind --> htmlOutput[HtmlOutput]
+          </div>
+        </div>
+
+        <h3 class="hr-heading-h3">Sequence diagram</h3>
+        <div class="hr-diagram">
+          <div class="mermaid">
+sequenceDiagram
+  participant U as User
+  participant CLI as Copilot CLI
+  participant S as html-renderer skill
+  participant FS as Filesystem
+  U->>CLI: render notes.md
+  CLI->>S: invoke skill
+  S->>FS: read notes.md + references/
+  S->>FS: write notes.html
+  S-->>CLI: done
+  CLI-->>U: open notes.html
+          </div>
+        </div>
+
+        <h3 class="hr-heading-h3">State diagram</h3>
+        <div class="hr-diagram">
+          <div class="mermaid">
+stateDiagram-v2
+  [*] --> Draft
+  Draft --> Review: submit
+  Review --> Draft: request changes
+  Review --> Approved: accept
+  Approved --> Published: publish
+  Published --> [*]
+          </div>
+        </div>
+
+        <h3 class="hr-heading-h3">Entity relationship</h3>
+        <div class="hr-diagram">
+          <div class="mermaid">
+erDiagram
+  AUTHOR ||--o{ DOCUMENT : writes
+  DOCUMENT ||--|{ SECTION : contains
+  SECTION ||--o{ BLOCK : contains
+  AUTHOR {
+    string id PK
+    string name
+  }
+  DOCUMENT {
+    string id PK
+    string title
+    string authorId FK
+  }
+          </div>
+        </div>
+      </section>
+
+      <section class="hr-section hr-stack">
+        <h2 class="hr-heading-h2">Grid templates</h2>
+
+        <h3 class="hr-heading-h3">Two columns</h3>
+        <div class="hr-grid hr-grid-2">
+          <article class="hr-card">
+            <h3 class="hr-card-title">Left column</h3>
+            <p class="hr-card-text">Equal-width cells. Good for compare/contrast pairs.</p>
+          </article>
+          <article class="hr-card">
+            <h3 class="hr-card-title">Right column</h3>
+            <p class="hr-card-text">Stacks to a single column under 720px.</p>
+          </article>
+        </div>
+
+        <h3 class="hr-heading-h3">Three columns</h3>
+        <div class="hr-grid hr-grid-3">
+          <article class="hr-card">
+            <h3 class="hr-card-title">Discover</h3>
+            <p class="hr-card-text">Frame the problem and surface signals.</p>
+          </article>
+          <article class="hr-card">
+            <h3 class="hr-card-title">Decide</h3>
+            <p class="hr-card-text">Pick an approach with a clear rationale.</p>
+          </article>
+          <article class="hr-card">
+            <h3 class="hr-card-title">Deliver</h3>
+            <p class="hr-card-text">Ship in small, verifiable steps.</p>
+          </article>
+        </div>
+
+        <h3 class="hr-heading-h3">Four columns</h3>
+        <div class="hr-grid hr-grid-4">
+          <article class="hr-card">
+            <h3 class="hr-card-title">Spec</h3>
+            <p class="hr-card-text">Define what success looks like.</p>
+          </article>
+          <article class="hr-card">
+            <h3 class="hr-card-title">Plan</h3>
+            <p class="hr-card-text">Sequence the work into task groups.</p>
+          </article>
+          <article class="hr-card">
+            <h3 class="hr-card-title">Build</h3>
+            <p class="hr-card-text">Implement against the plan.</p>
+          </article>
+          <article class="hr-card">
+            <h3 class="hr-card-title">Verify</h3>
+            <p class="hr-card-text">Prove the outcome with tests.</p>
+          </article>
+        </div>
+
+        <h3 class="hr-heading-h3">Featured + supporting (2 / 1)</h3>
+        <div class="hr-grid hr-grid-feature">
+          <article class="hr-card hr-card-featured">
+            <h3 class="hr-card-title">Primary outcome</h3>
+            <p class="hr-card-text">
+              A wide, high-emphasis card that anchors the section while the
+              two narrow cards carry supporting detail.
+            </p>
+            <span class="hr-badge">Priority</span>
+          </article>
+          <article class="hr-card">
+            <h3 class="hr-card-title">Supporting note</h3>
+            <p class="hr-card-text">Context that complements the primary outcome.</p>
+          </article>
+          <article class="hr-card">
+            <h3 class="hr-card-title">Supporting note</h3>
+            <p class="hr-card-text">Additional context, kept secondary.</p>
+          </article>
+        </div>
+
+        <h3 class="hr-heading-h3">Content + sidebar</h3>
+        <div class="hr-grid hr-grid-sidebar">
+          <article class="hr-card">
+            <h3 class="hr-card-title">Main content</h3>
+            <p class="hr-card-text">
+              A wider primary cell paired with a narrower companion. Use for
+              feature descriptions with quick-reference metadata to the side.
+            </p>
+          </article>
+          <aside class="hr-card">
+            <h3 class="hr-card-title">At a glance</h3>
+            <p class="hr-card-text">Status, owner, last update, links.</p>
+            <span class="hr-badge">Meta</span>
+          </aside>
+        </div>
+
+        <h3 class="hr-heading-h3">Auto-fit (default)</h3>
+        <div class="hr-grid">
+          <article class="hr-card">
+            <h3 class="hr-card-title">Auto-fit cell</h3>
+            <p class="hr-card-text">Reflows from 1 to N columns based on viewport width.</p>
+          </article>
+          <article class="hr-card">
+            <h3 class="hr-card-title">Auto-fit cell</h3>
+            <p class="hr-card-text">Each cell respects a 260px minimum.</p>
+          </article>
+          <article class="hr-card">
+            <h3 class="hr-card-title">Auto-fit cell</h3>
+            <p class="hr-card-text">Best default when card count is unknown.</p>
+          </article>
+        </div>
+      </section>
+
+      <section class="hr-section hr-stack">
+        <h2 class="hr-heading-h2">Quote</h2>
+        <blockquote class="hr-quote">
+          <p>
+            Great readability comes from predictable rhythm, not from visual
+            noise.
+          </p>
+          <footer>Design rule for long-form interface blocks</footer>
+        </blockquote>
+      </section>
+
+      <section class="hr-section hr-stack">
+        <h2 class="hr-heading-h2">Important highlights</h2>
+
+        <aside class="hr-highlight hr-highlight-note">
+          <p class="hr-highlight-title">Note</p>
+          <p>
+            Use this variant for neutral guidance and implementation tips.
+          </p>
+        </aside>
+
+        <aside class="hr-highlight hr-highlight-warning">
+          <p class="hr-highlight-title">Warning</p>
+          <p>
+            Use this variant for constraints that may break consistency or
+            accessibility.
+          </p>
+        </aside>
+
+        <aside class="hr-highlight hr-highlight-important">
+          <p class="hr-highlight-title">Important</p>
+          <p>
+            Use this variant for decisions that affect rendering output and
+            shared conventions.
+          </p>
+        </aside>
+      </section>
+    </main>
+    <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+    <script>
+      window.mermaid &&
+        mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+    </script>
+  </body>
+</html>