---
name: ui-doc
description: Build a DIDACTIC HTML document — a teaching page, one-pager, explainer, or briefing — to the Studio house design rules. Loads the full UI/UX rules (Teletubbies principle + Kennedy method + documentation patterns) and hands over the ready-made `documentation-kit.css` block vocabulary as the starting template. TRIGGER when a session is about to produce any teaching/explanatory HTML page, or when the user says "make a didactic page / one-pager / explainer for X", "/ui-doc", "build me a teaching page about X", "apply the UI/UX rules to <page>", "rework this page with the UI/UX rules", "make this page follow the UI rules", or asks to improve the readability of an existing document page. The UI/UX library lives online at https://smartrules.ai/studio. DO NOT use for branded citizen-facing pages that carry their own brand kit, for defining a product's app screens (that is a screens-first design job), or for markdown documents the reader will read directly (those stay markdown, not HTML).
---

*From Frank's Studio — studio.smartrules.ai · install: npx skills add gfrankgva/studio-skills*

# ui-doc — build a didactic HTML document to the house rules

Teaching documents (explainers, one-pagers, briefings for partners and government teams) must **read well and teach well**. This skill loads the design rules and gives you the ready material so you never start from a blank file.

## Step 0 — Is this the right skill?

- Teaching / explaining something on a page → **yes, continue.**
- A branded citizen-facing page with its own brand kit → stop, use that brand kit.
- Defining a product's app screens → stop, that is a screens-first design job, not a document.
- A report or note the reader will read as text → **do not build HTML at all** — those stay markdown. HTML is only for the product: pages shown to others.

## Step 1 — Load the rules (read these first, in order)

All online at [studio.smartrules.ai](https://smartrules.ai/studio):

1. The **front page** — the three layers: ① Teletubbies goal (the page must communicate before it is read: layout, color, shape carry the message; words confirm), ② Kennedy method, ③ tokens/auditors net. This order IS the method.
2. The **documentation-design** page — the didactic-page layer: reading measure, two body regimes, the orientation kit, and the block vocabulary. **This is your spec.**
3. The **Kennedy notes** — hierarchy-and-spacing, color, typography-and-fonts, intuitive-ux — as the page needs them.
4. Skim the **documentation compendium** — the live page that shows every rule and block in use. It is your worked example; copy from it.

Also honour the always-on house rules: project palette hex values, never CSS named colors; no AI-slop writing; collapsible `<details>` sections for long content; a light mode for any dark page; sentence case for all titles/labels/buttons (capitalize first word + proper nouns only).

## Step 2 — Start from the kit, not a blank file

Link or inline `references/documentation-kit.css` (bundled with this skill). It is hand-written on house-token CSS variables — no framework, no dependency, one file. It carries the whole block vocabulary:

`topnav` (the booklet top menu: collection name in accent › page, section links right — use on every multi-section document) · `segment` · `callout` (info/warning/success) · `steps` · `statistic` · `dl.desc-list` · `divider` · `label` · `figure.code` · sticky-header tables · `compare` grid · the `.doc-section` collapsible pattern · reading regimes (`.prose` / `.dense`) · the on-this-page rail · hover anchors.

Delete the blocks the page doesn't use. **Swap `--accent`** in `:root` if the document has its own colour; keep everything grayscale otherwise.

## Step 3 — Build, applying the method (not just the tokens)

1. **State the ONE job** of the page in a sentence. Per 100 readers, what happens ~95 times? De-emphasise everything else (squint test).
2. **Grayscale first.** Build hierarchy with size, weight and space. Add colour last, only where it means something (a warning, a link, a status). One accent, scarce.
3. **Double the whitespace.** Group gaps visibly larger than element gaps.
4. **Cap the reading measure** (~68ch prose column). Never full-width body text.
5. **Use the block vocabulary** for structure — a wall of text becomes segments, callouts, steps, a statistic, a comparison. Name classes like English (`callout warning`, `step active`).
6. **Every major section collapsible** — wrap in `<details open><summary>…</summary>…</details>` so any section folds for easy reading; link them from the on-this-page rail.
7. **Responsive from the start** — the kit's media queries handle rail/comparison/steps/tables; verify no horizontal body scroll at 375px.

## Step 4 — Self-check before delivering (in this order)

1. ONE job stated + everything else de-emphasised (squint test).
2. Grayscale check — hierarchy carries without colour (`filter:grayscale(1)` on `<body>`).
3. Locality + affordance-before-doing if anything is interactive.
4. Run the Studio auditors if you have them (`composition-audit.js` in the live page, `python3 token-audit.py <file>` — both on [studio.smartrules.ai](https://smartrules.ai/studio); 0 violations). Otherwise verify the token discipline by eye.
5. Responsive check at 375px — no sideways scroll; use headless/preview, never a visible window.
6. **The pleasure gate** — reading every part is easy and pleasant, or that part fails.

## Step 5 — Deliver

Open the finished page in the browser immediately — house rule, every produced HTML page, every time.

## Apply to an EXISTING page (retrofit mode)

Triggered by "/ui-doc apply `<path>`", "apply the UI/UX rules to this page", or "make this page read better". Do NOT rebuild from scratch — improve what is there:

1. **Read** the existing HTML in full.
2. **Load the rules** (Step 1) and **audit** the page against them. Report the findings first, in markdown, worst-first: measure not capped? hierarchy leaning on colour (fails grayscale)? walls of text that should be blocks (segment/callout/steps)? whitespace too tight? sections not collapsible? not responsive at 375px? token violations?
3. **Retrofit** against the findings: link/inline `references/documentation-kit.css`; replace ad-hoc structure with the block vocabulary; cap the prose column (~68ch); grayscale-first + one scarce accent; wrap major sections in `<details open>`; add the on-this-page rail if the page is long; fix responsiveness.
4. **Preserve the content** — retrofit is about form, not rewriting the message. Change words only to fix a readability anti-pattern, and say so.
5. **In place or new file?** Improving the page → edit in place. A *variant* the owner wants to compare → new file alongside (house rule: "new file, don't replace"). Ask if unsure.
6. **Verify + deliver** as in Step 4–5: token discipline clean, no horizontal scroll at 375px, grayscale check, then open in the browser.

## Knowledge loop

If you find a pattern the rules lack, or a source worth adding, note it wherever your team keeps its design rules — one home, never scattered — so the next page benefits.