Wiki component library

@@ -2,143 +2,84 @@
schema: foundry-doc-v1
title: "Wiki component library"
slug: wiki-component-library
short_description: "Nine reusable interface components that compose a complete wiki article page on the PointSav knowledge platform, from masthead to footer, in a shared design vocabulary."
short_description: "The shared chrome — header, off-canvas mobile nav, left sidebar, and footer — plus the page templates it wraps, that together render every page on the PointSav knowledge platform."
category: design-system
type: topic
content_type: topic
index_group: wiki-surface-design
status: active
bcsc_class: public-disclosure-safe
last_edited: 2026-05-25
last_edited: 2026-08-22
editor: pointsav-engineering
paired_with: wiki-component-library.es.md
---

# Wiki component library

**Correction (2026-08-02):** the specific CSS-variable/API vocabulary cited throughout this article doesn't exist in the real render engine. The entire `--ps-wiki-*`/`--ps-surface-*`/`--ps-ink-*` variable family has zero hits anywhere in `app-mediakit-knowledge` — real tokens (`static/style.css`) use `--link`, `--font-display`, `--text-base`, etc. The real theme-persistence key is `wiki-theme` (`static/wiki.js`), not `ps-theme`, and the real toggle is a three-way Light/Dark/Auto "Appearance menu," not the two-state `aria-pressed` toggle described. The `wiki-drawer-mobile-nav` slide-in panel described doesn't exist — the real mobile nav is a fixed bottom tab bar with three items (Home/Search/Categories), with zero `inert`-attribute usage anywhere in the crate. The MCP search response shape is also wrong: real `mcp_search` returns `{results: [{slug, title, lede, score}]}`, not `{query, count, hits: [...]}`. Token files are real but at different paths than claimed (`static/tokens.css`/`static/style.css`, not `dist/tokens.css`). **Flagged, not resolved** — this needs a rewrite against the real render engine, not a wording fix.

The PointSav wiki component library defines nine reusable interface units that together render a complete wiki article page in the [[app-mediakit-knowledge]] wiki engine. Each component targets Wikipedia's established layout conventions — following the [[wikipedia-leapfrog-design|leapfrog design philosophy]] — while applying current accessibility standards and the [[design-system-substrate|PointSav token system]].

---

## Architecture overview

A wiki article page is composed from a stack of components:

```
┌─────────────────────────────────────────────────────┐
│  wiki-drawer-mobile-nav  (compact viewports only)   │
├─────────────────────────────────────────────────────┤
│  wiki-article-header  (breadcrumb + H1 + badge + meta)│
├──────────────────┬──────────────────────────────────┤
│                  │  wiki-toc-sidebar  (right rail)  │
│  Article body    │  (desktop only)                  │
│  (prose)         ├──────────────────────────────────┤
│                  │  wiki-badge-tag (quality/category)│
├──────────────────┴──────────────────────────────────┤
│  wiki-article-footer  (categories + refs + edit)    │
├─────────────────────────────────────────────────────┤
│  wiki-pagination  (prev/next article in category)   │
└─────────────────────────────────────────────────────┘

Overlays (triggered by user action):
  wiki-modal-dialog     — image lightbox, search overlay
  wiki-dark-mode-toggle — persistent theme switch (site header)

Search:
  wiki-search-results   — results list (own page or in modal)
```

---

## Components

### wiki-article-header

Top-of-article surface. Renders four elements in sequence: (1) slug breadcrumb showing the article's category path, (2) the article H1 title from frontmatter, (3) an optional quality badge, and (4) a byline showing last-edited date and a history link.

Quality grades: Featured Article (gold), Good Article (green), A-class (blue), B-class (light blue), C-class (grey), Stub (light grey). Ungraded articles omit the badge slot.

**Token:** `--ps-wiki-text-h1` = 2.25 rem (36 px at 17 px base).
The PointSav wiki is built from a small set of shared chrome elements — header, off-canvas mobile navigation, left sidebar, and footer — wrapped around one of several page templates, all composed in the [[app-mediakit-knowledge]] wiki engine. Class names follow a `k-*` manifest shared across every template, so styling one surface styles them all.

---

### wiki-article-footer
## Shared chrome

Bottom-of-article surface. Three sections: (1) category tag links, (2) a numbered references list using `<ol id="ref-N">` for in-article back-links, and (3) an edit-on-GitHub link for contributors.
### Header

---

### wiki-toc-sidebar

Sticky right-rail sidebar listing article headings (H2 and H3). On desktop (≥ 800 px) it uses `position: sticky; top: 1rem`. On compact viewports (≤ 799 px) it collapses to an inline `<details>` / `<summary>` toggle above the article body.

The active section is highlighted via a JavaScript `IntersectionObserver` watching all `[id]` heading anchors. When a heading enters the viewport, its table-of-contents entry receives `aria-current="true"` and the active visual style.

---
A sticky white header (`k-header`) with three regions: the site logo and wordmark on the left, a search box centred, and a controls cluster on the right — a light/dark theme toggle and a menu button that opens the mobile nav drawer.

### wiki-search-results
### Off-canvas mobile nav

Ordered list of search hits returned by the Tantivy search engine. Each result displays the article title as a link and a plain-text excerpt of approximately 180 characters, truncated at a word boundary. The component wraps in `aria-live="polite"` so assistive technologies announce result-count updates.
A left-side drawer (`k-nav-drawer`), not a bottom tab bar. The menu button in the header opens it as a modal dialog (`role="dialog"`, `aria-modal="true"`) with a dimming overlay behind it. Inside, a mobile copy of the search box sits above three link sections — Navigate, Resources, and PointSav network — each rendered as a labelled list. A close button and Escape both dismiss it.

**API shape:** `POST /mcp`, JSON-RPC 2.0, method `search`. Response: `{query, count, hits: [{slug, title, snippet}]}`. Snippets are plain text only. A zero-results state is toggled with the `[hidden]` attribute.
### Left sidebar

---
A single sticky sidebar (`k-sidebar`) on desktop, not a split left/right layout. It stacks, in order: a "Main page" link, a "Browse by area" category list, a "Guides" link (on wikis that serve how-to content), and — only on pages with headings — a table of contents built from the page's H2/H3s. The table of contents is part of this same sidebar, not a separate right-rail component.

### wiki-modal-dialog
### Footer

Overlay using the native `<dialog>` element with `showModal()`. The native dialog element provides a built-in focus trap: all content outside the dialog is unreachable by keyboard until the dialog closes. Used for image lightboxes, the search overlay, and confirmation prompts. Closes on Escape (native browser behaviour) and on backdrop click.
A site-wide footer (`k-footer`), not a per-article one. Three link columns — Browse, This site, Network — followed by a base row: city list and copyright on the left, a "Powered by" badge on the right. Category tags and reference lists are not footer elements; where an article has footnotes, they render inline in the article body as part of the same content pipeline that produces the rest of the prose.

---

### wiki-dark-mode-toggle
## Page templates

A toggle button that sets `data-theme="dark"` on `<html>` and persists the choice in `localStorage` under the key `ps-theme`. On each page load, an inline script reads this value before the stylesheet renders, preventing a flash of the unintended theme. Falls back to `prefers-color-scheme: dark` if no explicit choice is stored.
Each template wraps in the shared chrome above and fills the content region.

---
**Article** (`k-article`). A two-tab bar (Article / History), an optional "last updated" or point-in-time revision line, an optional historical-revision banner when viewing a past commit, the H1 title, and the rendered prose body.

### wiki-badge-tag
**History** (`k-history`). The article's revision list — one entry per commit, each linking to that revision's diff.

Dual-purpose chip: (1) article quality grade badge — a non-interactive `<span>` with `aria-label` providing the full grade name — and (2) category tag links using `<a>` chips. Used in the article header (quality badge) and article footer (category tags).
**Diff**. A single revision's line-by-line change view, reached from the History tab.

---
**Home** (`k-home`). The site lede, a total-article count, a "Browse by area" grid of category cards, and — where guides exist — a "How-to guides" list.

### wiki-pagination
**Category index / search results / special listings** (`k-catpage`). One shared template for four distinct listing views — a category's articles, search results, the full index of record, and recent changes — differing only in heading and source list.

Prev/Next article navigation within a category. The component is a three-column grid: previous article link (left), current category name link (centre), next article link (right). Each directional link carries `rel="prev"` / `rel="next"` for SEO and an `aria-label` providing the full adjacent article title for assistive technologies.
**404** (`k-catpage` variant). A minimal chrome-wrapped message page; the wiki never serves a bare error.

This component handles sequential article navigation. Numbered pagination for search results and category listings is a separate planned component.
There is no modal-dialog component, no numbered pagination between articles, and no quality-grade badge (Featured/Good/Stub, etc.) anywhere in this template set — none of the three exist in the current engine.

---

### wiki-drawer-mobile-nav
## Search

Slide-in left-panel navigation for compact (≤ 799 px) viewports. A hamburger trigger button opens the drawer. When open, the `inert` attribute is applied to the main content region and header, locking keyboard focus inside the drawer until it is dismissed. Closes on Escape or backdrop click.

The `inert` attribute is natively supported in Chrome 102+, Firefox 112+, and Safari 15.5+. A WICG polyfill (approximately 3 KB gzipped) covers older browsers.
Search is server-rendered, not an API a client calls separately: the header's search box submits to `/search?q=`, which renders through the same `k-catpage` template as a category listing, with a result count and one card per match.

---

## Mobile discipline

All nine components are designed mobile-first against a 375 px reference viewport. The Inter typeface (UI and headings) and Source Serif 4 (body prose) are loaded as variable fonts via `font-display: swap`; fallback system fonts render immediately on slow connections — see [[wiki-typography-system]].

Touch-target discipline applies across all interactive elements: trigger buttons, TOC entries, edit pencils, pagination links, toggle controls, and modal close targets each carry a 44 px × 44 px minimum touch target (WCAG 2.2 SC 2.5.8). No interaction depends on hover state — every hover affordance (page preview, citation tooltip, quality-badge popover) degrades to a tap-triggered equivalent.
Touch-target discipline applies across all interactive elements — the header's controls, sidebar links, drawer triggers, and tab links each carry a 44px × 44px minimum touch target (WCAG 2.2 SC 2.5.8).

Safe-area padding (`env(safe-area-inset-*)`) is applied to the shell chrome (`wiki-drawer-mobile-nav` trigger and footer region) to accommodate notched and dynamic-island displays. Content columns do not apply safe-area insets; only chrome elements that sit at the screen edge do.
---

## Token dependency

All nine components draw exclusively from the PointSav token system defined in `dist/tokens.css`. No component introduces raw colour or dimension values. New wiki pages and templates add components without introducing new CSS variables.
Every component draws its colours, spacing, and type from the `k-*` semantic tokens defined in [[design-system-substrate|the token vault]] — see [[wiki-dark-mode]] for the light/dark token pairs and [[wiki-typography-system]] for the type stack. No component introduces a raw colour or dimension value of its own.

---

## See also

- [[wiki-dark-mode]] — light and dark colour schemes with WCAG-verified palettes and theme persistence
- [[wiki-typography-system]] — Inter and Source Serif 4 type stack used across these components
- [[design-system-substrate]] — the token and component vault these nine components draw from
- [[app-mediakit-knowledge]] — the wiki engine that composes these components into rendered article pages
- [[component-recipes-vs-raw-tokens]] — the `recipe.json` component-tier data format, for components in the design-system's own registry rather than the wiki surface
- [[design-tokens-and-accessibility]] — how accessibility requirements are expressed as tokens rather than checked ad hoc
- [[wiki-dark-mode]] — the theme toggle in the header and the semantic tokens each mode swaps
- [[wiki-typography-system]] — the Inter/Source Serif 4 type stack these templates render with
- [[design-system-substrate]] — the token vault every component draws from
- [[app-mediakit-knowledge]] — the wiki engine that renders this chrome and these templates
- [[component-recipes-vs-raw-tokens]] — the design-system's own separate component registry, distinct from this wiki-surface chrome