# Template Interface: Product Requirements Document

This document is the single source of truth for what Template Interface is, why it
exists, who it is for, and how it is built. It consolidates product intent,
curriculum design, roadmap, metrics, operations, technical architecture,
security posture, and public-facing framing into one file so that the
project can be understood end to end without reading any code.

---

## 1. Problem statement

Most people who build websites, including experienced developers, learn UI
and UX by imitation: copying a template, cloning a competitor's layout, or
following a tutorial's exact steps, without ever learning the underlying
reasoning for why a given layout, spacing choice, or color pairing works.
This produces sites that look acceptable until they diverge from the
original template, at which point the builder has no principled way to
decide what to do next.

Separately, AI coding assistants that generate or review websites have no
single, reliable, offline place to look up a specific, well-defined design
concept (for example, "what is correct contrast ratio guidance" or "how
should a form's validation timing work") in a format built for machine
consumption rather than prose written for casual human skimming.

Template Interface solves both problems with one system: a from-first-principles UI
and UX curriculum, structured so that a human can learn it at their own
pace and an AI model can query any single concept precisely and reliably,
paired with a small library of templates that put the curriculum's lessons
into practice.

## 2. Target users

1. **The site's maintainer.** Learning and referencing UI/UX fundamentals
   while building this site and future ones. Comfortable with HTML, CSS,
   and JavaScript, but wants a durable, personal reference for design
   reasoning rather than scattered notes or half-remembered tutorials.
   Primary need: a place to look something up mid-project and trust the
   answer.
2. **AI coding assistants.** Tools such as Claude Code that generate or
   review websites and need to ground a design decision in a specific,
   citable concept. Primary need: a predictable file path, anchor, and
   index format that removes any guesswork about where a concept lives or
   how it is structured.
3. **Other self-directed learners.** People without a design background who
   want to understand why good web design works the way it does, not just
   copy a finished result. Primary need: an explanation that builds from
   fundamentals, with an interactive demo rather than a static screenshot,
   and no obligation to follow a rigid, forced course order.

## 3. Goals

- Build a self-contained, public UI/UX learning resource that explains the
  reasoning behind good design decisions, not just finished examples.
- Structure every piece of educational content so that it is trivially and
  reliably queryable by AI models, using a fixed, documented contract rather
  than ad hoc formatting.
- Provide a small, high quality library of general purpose website templates
  that each demonstrate specific concepts taught in the Education section,
  in a folder structure that scales to many more templates without any code
  change to the showcase page.
- Document every template so completely that a reader who has never opened
  the folder, a person or a model, can understand how it is composed and
  rebuild it as a live site: what its regions are, what it depends on, what
  its script binds to, which parts are placeholder content, which parts are
  deliberately non-functional, and which structural decisions exist for a
  reason and should survive the rebuild. This is the templates layer's
  equivalent of the Education layer's AI queryability contract in section
  12.3, and it is why the templates exist at all: they are starting points
  to be copied out and turned into real sites, not screenshots to admire.
- Run entirely from static files under the `file://` protocol in Chrome, with
  zero external dependencies, zero build tooling, and zero network access.
- Make every visual decision swappable later by centralizing all styling in
  design tokens, so the site's own theme can be revised once the education
  content that covers color, typography, and accessibility exists.

## 4. Non-goals

- Template Interface is not a CMS, authoring tool, or drag and drop site builder.
- Template Interface does not need a server, database, account system, or analytics.
- Template Interface does not target mobile app design, native app UX, or print
  design as a discipline (posters, brochures, print layouts). Scope is website
  UI/UX only. How a web page prints is in scope: it is one of the three
  surfaces in the Web Design Standard (section 13.16).
- Template Interface does not aim to be exhaustive on day one. The curriculum and
  template library are both designed to grow, not to ship complete forever.
- Template Interface does not currently need multi-language content, versioned
  content per user, or user accounts.
- Template Interface has no server-side code, database, account system or
  analytics. It is published at `templateinterface.com` as plain static
  files, and every page still works opened from disk; see Constraints.
- Template Interface does not teach UX research methodology (user interviews,
  personas, journey mapping, usability testing protocols, discovery
  processes) or business/product strategy (roadmapping, competitive
  analysis, team process, project management). This was confirmed as a
  deliberate scope boundary during the section 12.5 curriculum research
  pass: Template Interface teaches the visual, interaction, and content design
  principles needed to build a good website, a distinct and narrower
  discipline than the full UX research and strategy process taught by
  sources like the Interaction Design Foundation's beginner UX course.
  Nothing in this non-goal prevents a future, explicitly separate module
  on research methodology; it simply is not part of the current curriculum.

## 5. Tenets

Ordered by priority. When two tenets conflict, the higher one wins.

1. **Education before templates, always.** Phase 2 never starts before
   Phase 1's curriculum and AI queryability contract are complete, even if
   a compelling template idea exists. This exists because templates without
   a finished teaching foundation would just be more unexplained examples,
   the exact problem Template Interface is meant to solve.
2. **Offline and dependency-free is non-negotiable.** Any feature that
   would require a build step, a server, a CDN link, or `fetch()` is
   rejected outright, even when it would be materially easier to build the
   conventional way. The value of double-click-to-open, forever, outweighs
   any convenience a dependency would add.
3. **Machine queryability is a first class requirement, not a nice to
   have.** Every new concept follows the fixed heading, anchor, and index
   contract even when it feels like overhead for a single small concept.
   Skipping the contract once means an AI model can no longer trust the
   contract at all.
4. **The theme is provisional until the lessons that explain it exist.**
   Visual polish is deliberately deferred in favor of finishing the color,
   typography, and accessibility concepts first, so the eventual theme
   revision is grounded in the site's own teaching rather than taste alone.
5. **Additive, not hardcoded.** Every list-like structure (modules,
   concepts, templates) must support a new entry without editing unrelated
   files. If adding one item requires touching more than its own folder
   plus one index or registry file, that is treated as a design defect.
6. **Ask before guessing on presentation.** When a fix or feature involves a
   real design tradeoff, such as how a wide table should reflow on a narrow
   screen, that choice is confirmed with the maintainer before
   implementation. Pure bug fixes with one obviously correct answer do not
   require this; genuine presentation decisions do.
7. **The site follows its own Color Standard.** Every color on every page,
   site pages and all templates alike, follows the Template Interface
   Color Standard (section 13.13). A site that publishes a standard and
   breaks it teaches the opposite. Where a template's brand needs a color
   the palette lacks, the color goes through the standard's brand fitter
   into the accent roles; it never skips the contrast rules. Added
   2026-10-04 at the maintainer's request.

## 6. Writing style

All copy in this project, across every markdown file, HTML page, and code
comment, follows one punctuation rule: **no em dashes, in any form, and no
double dashes used as punctuation.**

This is checked in both places an em dash can hide, since a search for one
will not catch the other:

- The literal Unicode em dash character, `—`.
- The HTML entity form, `&mdash;`.

It also covers a double hyphen used as punctuation, `--`, for example
`the fix -- while simple -- took an hour`. This prohibition does **not**
apply to CSS custom property syntax, where a leading double hyphen is valid
CSS variable syntax and must never be altered, for example `--color-accent`
or `--space-4`. When auditing for this rule, a double hyphen adjacent to a
CSS variable name (inside backticks, a code block, or a `:root` declaration)
is left untouched; a double hyphen used mid-sentence as punctuation is not.

**Replacement methodology.** Every instance found is replaced with the
alternative that best fits the surrounding sentence:

- **Comma**: the most natural replacement in most cases; keeps the sentence
  flowing without drawing attention to the fix.
- **Colon**: good when introducing a list, explanation, or elaboration after
  a complete clause.
- **Semicolon**: useful when connecting two closely related independent
  clauses that could each stand alone as a sentence.
- **Parentheses**: work well for an aside or supplementary detail that is
  not central to the sentence's main point.
- **Period**: sometimes the cleanest fix is splitting one sentence into two;
  shorter sentences are often clearer regardless.

There is no single default substitution. Each instance is judged on the
sentence it appears in.

**Audit cadence.** This rule is checked, not assumed. Whenever documentation
is edited or new HTML content is authored, an em dash and double dash sweep
runs across all markdown files and all HTML pages before that content is
considered final. See section 21, Documentation and Audit Process, for how
this fits into the project's recurring review cycle.

## 7. User stories

- As the site's maintainer, I want to look up why a spacing choice feels
  off so that I can fix it with a principle instead of guessing.
- As the site's maintainer, I want the curriculum to work from a local
  copy so that I can reference it while working without an internet
  connection.
- As an AI coding assistant, I want a stable file path and anchor for any
  named concept so that I can cite it precisely instead of paraphrasing.
- As an AI coding assistant, I want a single machine readable index so that
  I can discover every available concept without crawling the whole site.
- As a self-directed learner, I want to start at any concept that interests
  me without being forced through a strict linear course.
- As a self-directed learner, I want an interactive demo for a concept, not
  just a paragraph describing it, so that the effect is visible, not just
  described.
- As anyone browsing the Templates section, I want to see what a template
  looks like and when to use it before opening it, so that I can pick the
  right starting point for a new site.
- As a future contributor to this project, I want a documented folder and
  registry contract so that adding a new template or concept does not
  require guessing at conventions or editing unrelated files.

## 8. Feature list

### MVP (must ship, in order)

1. Design token system (`theme.css`) and shared base/component styles.
2. Sidebar navigation rendered at runtime from `nav-data.js` via `nav.js`.
3. All seven Education modules and fourteen concepts (section 12), each with
   an HTML page, a markdown mirror, and an entry in `concepts-index.js`.
4. `education/INDEX.md`, the human readable mirror of the concept index.
5. The Education overview page as a coherent wiki style introduction.
6. All Phase 1 acceptance criteria (section 12.4) verified.
7. All five starter templates (section 13.2), each satisfying the folder
   contract (section 13.3).
8. `templates-registry.js` and the portfolio style showcase page.
9. All Phase 2 acceptance criteria (section 13.4) verified.

### Future (post-launch, not scoped in this version)

- Additional modules beyond Module 07, such as data visualization patterns
  or e-commerce specific UX.
- Templates beyond the 20 built under milestone M9 (section 13.5); the
  original "5 to 20" expansion is complete, added through the existing
  registry contract with no existing file modified.
- A full theme revision, informed by the completed `color-and-contrast`,
  `typography`, and `accessibility-and-wcag-basics` concepts (DESIGN.md
  section 10). Complete as of milestone M8; see DESIGN.md section 10.1.
- Any tooling that helps regenerate `education/INDEX.md` from
  `concepts-index.js` automatically, provided it runs as a local script and
  never becomes a build step required to use the site.

## 9. Constraints

- **Vanilla HTML, CSS, and JavaScript only.** No frameworks, no build step,
  no npm, no package of any kind.
- **Must run by double clicking an `.html` file in Google Chrome** under the
  `file://` protocol. This rules out `fetch()`, ES module imports, XHR to a
  local JSON file, and service workers, since Chrome restricts or blocks
  each of these under `file://`.
- **All paths are relative.** No CDN links, no external fonts, no external
  images. System font stack only. Icons are inline SVG. Template previews
  are CSS and inline SVG, never image files.
- **Second exception: the brand folder (2026-10-04).** `brand/` holds
  the brand identity deliverables (PNG and ICO icons, social images,
  render checks, mockup crops, a PDF). They are files to hand to other
  people and services, not site pages, so the raster rule does not apply
  inside `brand/`. No site page links them until the maintainer decides
  to roll the identity out.
- **Single named exception: the favicon.** `favicon.png` at the project
  root is the one raster image file permitted anywhere in this project,
  referenced by a relative `<link rel="icon">` on every page. This
  exception exists because the favicon is a specific, already-designed
  piece of artwork the maintainer supplied, not a generated shape, and
  because it does not participate in the theme token system the way every
  other icon does (see DESIGN.md section 7). It does not extend to any
  other icon, callout, control, or template preview; every one of those
  remains inline SVG for the reasons in DESIGN.md section 7's rationale.
  If the favicon is ever redesigned, it stays a single small local image
  file; it must never be fetched from a CDN or external host.
- **No `localStorage` dependency for core content.** It is used only for
  optional preferences and must degrade gracefully if unavailable or
  cleared.
- **No live deployment.** Template Interface is never hosted on a server or given a
  public URL; every constraint above exists specifically to preserve
  double-click-to-open portability.
- **Phase order is fixed.** Phase 2 cannot begin before Phase 1's
  acceptance criteria are fully met; see Tenet 1.

## 10. Assumptions

- The maintainer has Google Chrome installed and available locally; no
  other browser is verified against or supported.
- A single contributor (the maintainer, optionally assisted by an AI coding
  agent) does the work; there is no multi-contributor coordination process
  defined, since none is currently needed.
- File system case sensitivity is not a concern for this project's target
  environment (Windows), but slugs are still kept lowercase kebab-case
  throughout so the project also behaves correctly if ever opened on a
  case-sensitive file system.
- The five starter templates chosen in section 13.2 are broad enough that,
  together, they exercise every concept in the curriculum at least once;
  this was a deliberate design choice, not a coincidence, and should be
  revisited if a future concept is added that none of the five templates
  cover.

## 11. Success criteria

- Every concept in the curriculum has a page, a markdown mirror, and an
  index entry that agree with each other field for field.
- An AI coding assistant can be given only a concept slug and correctly
  derive its file path, anchor, and markdown mirror path without being told
  any of them directly, using only the contract in section 12.3.
- The site opens with zero browser console errors from the root
  `index.html`, every Education page, and every template's `index.html`.
- Every interactive demo described in section 12.2 works fully offline and
  is operable by keyboard alone.
- The showcase page renders correctly regardless of how many templates are
  registered, verified with both a one-entry and an eight-entry registry.
- No `.md` or `.html` file in the project contains an em dash in either
  form, or a double dash used as punctuation, per section 6.

---

## 12. Product definition: Phase 1, the Education layer

Phase 1 must be fully fleshed out and defined, including the entire concept
curriculum and the AI queryability contract, before any template work
begins.

### 12.1 Curriculum structure

The curriculum is organized into **modules**, ordered beginner to advanced.
Each module contains one or more **concepts**. There is no forced linear
path through the material, but the module and concept order below is always
shown as the recommended path in the sidebar and on the Education overview
page.

Module folder naming: `NN-module-slug` (two digit zero padded order prefix,
kebab case slug). Concept file naming: `concept-slug.html`, always inside
its module's folder. The numeric prefix on module folders encodes
recommended order for navigation and skimming; it is not a hard gate, since
the site explicitly supports learning at your own pace.

#### Module 01: Foundations (Beginner)

| Concept | Slug |
|---|---|
| What Is UI/UX Design | `what-is-ui-ux` |
| Visual Hierarchy | `visual-hierarchy` |

#### Module 02: Layout and Structure (Beginner to Intermediate)

| Concept | Slug |
|---|---|
| Layout and Grid Systems | `layout-and-grid-systems` |
| Spacing and Rhythm | `spacing-and-rhythm` |
| Responsive and Mobile First Thinking | `responsive-and-mobile-first-thinking` |

#### Module 03: Typography and Color (Beginner to Intermediate)

| Concept | Slug |
|---|---|
| Typography | `typography` |
| Color and Contrast | `color-and-contrast` |
| Web Safe Colors | `web-safe-colors` |

#### Module 04: Accessibility (Intermediate)

| Concept | Slug |
|---|---|
| Accessibility and WCAG Basics | `accessibility-and-wcag-basics` |

#### Module 05: Navigation and Content (Intermediate)

| Concept | Slug |
|---|---|
| Navigation and Information Architecture | `navigation-and-information-architecture` |
| Content Design and Microcopy | `content-design-and-microcopy` |

#### Module 06: Interaction and Forms (Intermediate to Advanced)

| Concept | Slug |
|---|---|
| Forms and Inputs | `forms-and-inputs` |
| Interaction States and Feedback | `interaction-states-and-feedback` |
| Motion | `motion` |

#### Module 07: Critique (Advanced)

| Concept | Slug |
|---|---|
| Common Design Mistakes | `common-design-mistakes` |

This covers every concept required by the original brief, plus one entry
level concept (`what-is-ui-ux`) that gives absolute beginners a starting
point before `visual-hierarchy`. Additional concepts and even additional
modules can be appended at any point without renumbering existing modules,
since each module folder owns its own two digit prefix and new modules
simply take the next unused number.

### 12.2 Concept definitions

Each concept below is defined with what it teaches, its difficulty,
prerequisite concepts by slug, what its interactive or visual demo would
look like, and which future templates it maps to. Template names here are
the five defined in section 13.2.

**`what-is-ui-ux`**
- Teaches: The distinction between UI (the interface a user touches) and UX
  (the end to end experience of using it), and why both matter together.
- Difficulty: Beginner
- Prerequisites: None
- Demo: A single screen shown twice, once as a UI-only pass (looks fine in
  isolation) and once with a UX problem exposed (a confusing multi step
  flow), toggled by a control.
- Maps to: All five templates conceptually; no single template isolates it.

**`visual-hierarchy`**
- Teaches: How size, weight, color, contrast, and position tell a viewer
  what to look at first, second, and last on a page.
- Difficulty: Beginner
- Prerequisites: `what-is-ui-ux`
- Demo: A sample page with a hierarchy strength slider; increasing the
  slider exaggerates size and contrast differences between heading, subhead,
  and body text, decreasing it flattens them until the page becomes hard to
  scan.
- Maps to: Landing Page, Portfolio Site

**`layout-and-grid-systems`**
- Teaches: Column grids, gutters, alignment, and how CSS Grid and Flexbox
  express layout intent rather than pixel pushing.
- Difficulty: Beginner to Intermediate
- Prerequisites: `visual-hierarchy`
- Demo: A live grid overlay toggle on a sample card layout, switching
  between a 12 column grid, a 4 column grid, and no grid, showing how content
  reflows against visible column and gutter lines.
- Maps to: Portfolio Site, Documentation Site

**`spacing-and-rhythm`**
- Teaches: Consistent spacing scales, vertical rhythm, and why uneven
  whitespace reads as sloppy even when colors and type are correct.
- Difficulty: Beginner to Intermediate
- Prerequisites: `layout-and-grid-systems`
- Demo: The same content block rendered with three spacing scales: a
  consistent 4px based scale, a loosely eyeballed inconsistent scale, and a
  too-tight scale, selectable by tabs.
- Maps to: Portfolio Site, Blog and Article Site

**`responsive-and-mobile-first-thinking`**
- Teaches: Designing from the smallest viewport upward, fluid layout versus
  fixed breakpoints, and touch target sizing.
- Difficulty: Intermediate
- Prerequisites: `layout-and-grid-systems`, `spacing-and-rhythm`
- Demo: A resizable demo frame (drag handle) showing a sample page reflow
  live across the breakpoints defined in DESIGN.md, with the active
  breakpoint name labeled.
- Maps to: Landing Page, Small Business Site

**`typography`**
- Teaches: Type scales, line length, line height, font pairing restraint,
  and legibility over decoration.
- Difficulty: Beginner to Intermediate
- Prerequisites: `visual-hierarchy`
- Demo: A live type scale control that adjusts a sample paragraph and
  heading between a well-tuned scale and a poorly tuned one (too many sizes,
  bad line height), with measured line length shown in characters per line.
- Maps to: Blog and Article Site, Documentation Site

**`color-and-contrast`**
- Teaches: Color roles (background, surface, text, accent), contrast ratios,
  and using color to reinforce hierarchy rather than decorate.
- Difficulty: Intermediate
- Prerequisites: `visual-hierarchy`
- Demo: A live contrast checker showing two swatches with a computed
  contrast ratio and a pass and fail indicator against WCAG AA thresholds,
  adjustable via color inputs.
- Maps to: Landing Page, Blog and Article Site

**`web-safe-colors`** (added in v0.20.0, at the maintainer's request)
- Teaches: The 216 color web safe palette of early browsers, why it
  existed (256 color screens and dithering), how its hex codes are built
  from six steps per channel, short hex, grays, and that a safe color is
  not an accessible one.
- Difficulty: Beginner
- Prerequisites: `color-and-contrast`
- Demo: The full chart as 216 swatches in six panels (one per red level;
  green down, blue across), one tab stop with arrow keys, Page Up and
  Page Down; a selected color shows hex, short hex, RGB and its contrast
  on white and on the site background, with a copy button; a color input
  snaps any color to the nearest web safe one.
- Source: the codes were fetched from htmlcolorcodes.com's web safe color
  chart (2026-10-04) and checked against the definition; the text and
  layout are this site's own.
- Maps to: none; no template is limited to the palette.

**`accessibility-and-wcag-basics`**
- Teaches: Semantic HTML, alt text, keyboard operability, focus states, and
  the core WCAG AA success criteria relevant to everyday site building.
- Difficulty: Intermediate
- Prerequisites: `color-and-contrast`, `typography`
- Demo: A short interactive checklist walking through a sample component
  (a card with an image and a button) and flagging missing alt text, missing
  focus outline, and insufficient contrast, one at a time, with a fix applied
  after each step.
- Maps to: Documentation Site, Blog and Article Site

**`navigation-and-information-architecture`**
- Teaches: Grouping content into a logical structure, choosing navigation
  patterns (top nav, sidebar, breadcrumbs), and labeling clearly.
- Difficulty: Intermediate
- Prerequisites: `layout-and-grid-systems`
- Demo: A site map diagram builder where dragging pages into or out of
  groups shows how a flat list versus a grouped hierarchy changes how many
  clicks it takes to find a given page.
- Maps to: Documentation Site, Portfolio Site

**`content-design-and-microcopy`**
- Teaches: Writing for scanning, button and form label clarity, error
  message tone, and cutting unnecessary words.
- Difficulty: Intermediate
- Prerequisites: `navigation-and-information-architecture`
- Demo: A before and after toggle on the same UI (a signup form) rewriting
  vague labels and error text into specific, actionable copy.
- Maps to: Small Business Site, Landing Page

**`forms-and-inputs`**
- Teaches: Label placement, input sizing, validation timing, required field
  marking, and grouping related fields.
- Difficulty: Intermediate to Advanced
- Prerequisites: `content-design-and-microcopy`, `accessibility-and-wcag-basics`
- Demo: A live form with a toggle between inline validation (errors shown as
  you type, debounced) and submit-time validation, showing the difference in
  perceived friction.
- Maps to: Small Business Site, Documentation Site

**`interaction-states-and-feedback`**
- Teaches: Hover, focus, active, disabled, and loading states, and giving
  the user confirmation that an action registered.
- Difficulty: Intermediate to Advanced
- Prerequisites: `forms-and-inputs`
- Demo: A button with every state exposed as a labeled row (default, hover,
  focus-visible, active, disabled, loading), plus a live button that cycles
  through them on click.
- Maps to: Landing Page, Small Business Site

**`motion`**
- Teaches: Using animation to communicate state change and direction rather
  than for decoration, duration and easing basics, and respecting reduced
  motion preferences.
- Difficulty: Advanced
- Prerequisites: `interaction-states-and-feedback`
- Demo: The same panel transition shown with no motion, subtle motion tuned
  to the site's transition tokens, and exaggerated motion, plus a toggle that
  simulates `prefers-reduced-motion` to show the fallback.
- Maps to: Portfolio Site, Landing Page

**`common-design-mistakes`**
- Teaches: A capstone review of recurring failure patterns pulled from every
  prior module (low contrast text, inconsistent spacing, unclear navigation,
  motion without purpose, vague microcopy), framed as a self-audit checklist.
- Difficulty: Advanced
- Prerequisites: All other concepts in Modules 01 through 06
- Demo: A single deliberately flawed sample page with numbered flags; each
  flag expands to name the mistake, link to the concept that explains the
  correct approach, and show a corrected version of that section.
- Maps to: All five templates, used as the review pass for each.

**`choosing-the-right-chart`** (Module 08, added in M23)
- Teaches: Start from the reader's question (compare, trend, share), then
  pick the chart that answers it: bars on a zero baseline to compare, a
  line for change over ordered time, a part-to-whole chart only for a few
  shares that differ clearly.
- Difficulty: Intermediate
- Prerequisites: `visual-hierarchy`, `color-and-contrast`
- Demo: One small data set drawn as a bar, line or pie chart against three
  reader questions; a verdict says whether the chosen chart answers the
  chosen question and why.
- Maps to: `admin-dashboard`.

**`color-in-charts`** (Module 08, added in M23)
- Teaches: Neutral for context and one accent for the point; never rely on
  hue alone, so label series directly or pair color with text.
- Difficulty: Intermediate
- Prerequisites: `choosing-the-right-chart`, `color-and-contrast`
- Demo: A bar chart with a rainbow, focus or grayscale palette and an
  optional direct-labels switch; the readout explains what a reader can
  and cannot tell in each state.
- Maps to: `admin-dashboard`.

**`product-pages`** (Module 09, added in M23)
- Teaches: A product page sells by answering the buyer's last questions
  beside the button: the total price, availability, delivery and returns,
  and clear option states.
- Difficulty: Intermediate
- Prerequisites: `visual-hierarchy`, `content-design-and-microcopy`
- Demo: A product card with switches for each piece of information; a
  count shows how many buyer questions are still unanswered.
- Maps to: `ecommerce-product`.

**`cart-and-checkout`** (Module 09, added in M23)
- Teaches: Guest checkout, the full total shown early, and only the fields
  the order needs; surprise costs on the payment step lose orders.
- Difficulty: Intermediate
- Prerequisites: `product-pages`, `forms-and-inputs`
- Demo: A checkout drawn as steps and fields with three switches (guest
  checkout, full total in the cart, lean fields); a count of steps,
  fields and surprises updates as each is turned on.
- Maps to: `ecommerce-storefront`, `ecommerce-product`.

### 12.3 AI queryability contract

This contract is what guarantees a model can extract any concept cleanly
without executing JavaScript, running a server, or parsing prose
heuristically.

**Heading hierarchy (fixed, every concept page).** Every concept HTML page
uses exactly one `<h1>` and the same ordered set of `<h2>` sections. Sections
that do not apply to a given concept are still present with a one line note
rather than omitted, so the position of a section in the document never
depends on the concept:

1. Overview
2. Why It Matters
3. Core Principles
4. Interactive Demo
5. Common Mistakes
6. Related Concepts
7. Used In Templates
8. Summary

**Anchor ID convention.** All IDs are kebab-case and derived directly from
the concept slug, with no numeric or module prefix baked into the ID itself
(module and order live in the index, not the anchor):

- `<h1 id="{slug}">` for the concept title.
- `<h2 id="{slug}-overview">`, `<h2 id="{slug}-why-it-matters">`, and so on
  for each fixed section, using the exact section names above in kebab case.
- Every concept file name is `{slug}.html`, so the concept's canonical
  reference is always `education/{module-folder}/{slug}.html#{slug}`.

Because the ID suffixes are fixed strings, a model that already knows a
concept's slug can construct a deep link to any of its eight sections
without reading the file first.

**Machine readable index.** `/assets/js/concepts-index.js` assigns a single
global array, safe to open and read as plain text without executing it:

```js
window.WIREFRAME_CONCEPTS = [
  {
    id: "visual-hierarchy",
    title: "Visual Hierarchy",
    module: "01-foundations",
    moduleTitle: "Foundations",
    order: 2,
    difficulty: "beginner",
    prerequisites: ["what-is-ui-ux"],
    file: "education/01-foundations/visual-hierarchy.html",
    mdMirror: "education/md-mirror/01-foundations/visual-hierarchy.md",
    summary: "How size, weight, color, and position tell a viewer what to look at first.",
    templatesDemonstratedIn: ["landing-page", "portfolio-site"]
  }
  // one object per concept, in recommended order
];
```

**Human readable index.** `/education/INDEX.md` mirrors the same fields as a
single markdown table, regenerated by hand whenever `concepts-index.js`
changes, so a model or person reading only markdown files still has a
complete, structured map of every concept without needing to read
JavaScript.

**Plain text and markdown mirror.** Every concept HTML page has a
corresponding `.md` file under `/education/md-mirror/{module-folder}/{slug}.md`
using the same fixed heading order above, with `##` for each fixed section.
This is the preferred entry point for a model that only needs the written
content and not the interactive demo or styling.

**Predictable naming, summarized.**

| Element | Pattern | Example |
|---|---|---|
| Module folder | `NN-module-slug` | `02-layout-and-structure` |
| Concept file | `{slug}.html` | `grid-systems.html` (see note below) |
| Concept anchor | `#{slug}` | `#layout-and-grid-systems` |
| Section anchor | `#{slug}-{section-slug}` | `#layout-and-grid-systems-core-principles` |
| Markdown mirror | `education/md-mirror/{module-folder}/{slug}.md` | `education/md-mirror/02-layout-and-structure/layout-and-grid-systems.md` |
| Index entry | one object per concept, same order as sidebar | see JSON shape above |

Note: the concept file name always exactly equals `{slug}.html`, where
`{slug}` is the same string used as the concept's ID and its
`concepts-index.js` `id` field. There is exactly one slug per concept, reused
everywhere.

### 12.4 Phase 1 acceptance criteria

Phase 1 is complete when all of the following are true:

- Every concept listed in section 12.2 has an HTML page following the fixed
  heading hierarchy and anchor convention in section 12.3.
- Every concept has a corresponding markdown mirror file with matching
  content and heading structure.
- `concepts-index.js` contains one correctly filled entry per concept, and
  `education/INDEX.md` matches it field for field.
- Every module has an overview `index.html` describing what the module
  covers and listing its concepts in recommended order.
- The sidebar navigation renders on every education page from `nav-data.js`
  and correctly reflects recommended order without manual duplication of
  the nav markup per page.
- Every interactive demo described in section 12.2 is implemented, keyboard
  operable, and functions fully offline with no `fetch`, imports, or XHR.
- The Education overview page (`education/index.html`) reads as a coherent
  wiki style introduction to the whole curriculum, not a bare table of
  contents.
- All pages open correctly by double clicking the relevant `.html` file in
  Chrome with no console errors.
- No em dash, `&mdash;`, or punctuation double dash appears anywhere in the
  page's copy, per section 6.
- The page passes the responsive QA methodology in DESIGN.md section 8 at
  every listed breakpoint.
- Section 12.5's curriculum research and validation record exists and is
  dated before that concept's page was written, not after.

### 12.5 Curriculum research and validation (milestone M2.9)

Before any concept page is written (section 12.2's concepts, module by
module), the curriculum itself is checked against established UI/UX
educational sources rather than shipped purely on the maintainer's
judgment. This is a distinct milestone (M2.9 in section 14's roadmap),
scheduled after the navigation shell (M2) and before the first concept page
is written (M3), so the curriculum is validated once, up front, rather than
patched piecemeal as concept pages are written.

**What this milestone produces.** For each of the 14 concepts in section
12.2, a short validation note, added to this section as it is completed,
stating:

- Whether the concept's current definition, difficulty placement, and
  prerequisite chain (as currently written in section 12.2) is confirmed by
  at least one source in section 12.5.1, or was revised, with the revision
  and its reasoning recorded here.
- Whether any source treats a concept as foundational that section 12.1's
  module structure is currently missing, and if so, whether that concept is
  added to the curriculum or explicitly deferred with a stated reason.
- Whether any source would place a current concept at a meaningfully
  different difficulty level or module than section 12.1 currently does,
  and if so, whether the curriculum is reordered or the placement is kept
  with a stated reason for disagreeing with the source.

This validation record is written before, not after, the affected concept
page is authored in M3, so the page is written against a checked
curriculum rather than checked after the fact.

#### 12.5.1 Research sources

This is the fixed source list for the M2.9 research pass. The list is
closed for this milestone so the research has a defined scope and a
defined stopping point; expanding it is a deliberate decision for a future
milestone, not an ongoing open-ended search.

Figma resource library (design fundamentals, referenced for terminology and
concept framing consistency with how the wider design industry teaches
these ideas):

- https://www.figma.com/resource-library/design-basics/
- https://www.figma.com/resource-library/prototype-and-wireframe/
- https://www.figma.com/resource-library/web-design/
- https://www.figma.com/resource-library/typography/
- https://www.figma.com/resource-library/print-design/
- https://www.figma.com/resource-library/color-theory/
- https://www.figma.com/resource-library/ux-and-communication-strategy/
- https://www.figma.com/resource-library/difference-between-ui-and-ux/
- https://www.figma.com/resource-library/color-combinations/
- https://www.figma.com/resource-library/ux-validation/
- https://www.figma.com/resource-library/what-is-product-design/
- https://www.figma.com/resource-library/design-tokens/
- https://www.figma.com/resource-library/pricing-page-best-practices/
- https://www.figma.com/resource-library/button-states/
- https://www.figma.com/resource-library/ux-for-product-managers/
- https://www.figma.com/resource-library/ai-website-examples/
- https://www.figma.com/resource-library/landing-page-examples/
- https://www.figma.com/resource-library/static-vs-dynamic-website/
- https://www.figma.com/resource-library/portfolio-website-examples/
- https://www.figma.com/resource-library/how-to-start-a-presentation/
- https://www.figma.com/resource-library/best-sans-serif-fonts/
- https://www.figma.com/resource-library/what-is-ux-design/
- https://www.figma.com/resource-library/responsive-website-design/
- https://www.figma.com/resource-library/what-is-graphic-design/
- https://www.figma.com/resource-library/how-to-design-an-app/
- https://www.figma.com/resource-library/what-is-design-thinking/
- https://www.figma.com/resource-library/web-design-and-development/
- https://www.figma.com/resource-library/personal-website-examples/
- https://www.figma.com/resource-library/types-of-color-palettes/
- https://www.figma.com/resource-library/user-flow/
- https://www.figma.com/resource-library/what-is-ui-design/
- https://www.figma.com/resource-library/ui-design-principles/
- https://www.figma.com/resource-library/what-is-wireframing/
- https://www.figma.com/resource-library/wireframe-vs-mockup/
- https://www.figma.com/resource-library/what-is-a-minimum-viable-product/
- https://www.figma.com/resource-library/what-is-web-design/
- https://www.figma.com/resource-library/mobile-website-design/
- https://www.figma.com/resource-library/design-system-examples/
- https://www.figma.com/resource-library/wedding-font-pairings/

Independent, non-vendor sources (weighted more heavily than the Figma
resource library above, since Template Interface's `common-design-mistakes` and
`accessibility-and-wcag-basics` concepts in particular benefit from sources
that are not themselves promoting a single design tool):

- https://www.nngroup.com/articles/ (Nielsen Norman Group, usability
  research)
- https://www.dailyui.co/ (applied UI practice examples)
- https://ux.stackexchange.com/ (practitioner Q&A, useful for surfacing
  common real-world mistakes and edge cases)
- https://ixdf.org/courses/user-experience-the-beginner-s-guide (Interaction
  Design Foundation's beginner UX course, useful as a second opinion on
  curriculum sequencing from beginner to advanced)

**How these sources map to Template Interface's curriculum.** Not every source maps
to every concept. As a starting point for the M2.9 research pass:

- `what-is-ui-ux`: `what-is-ux-design`, `what-is-ui-design`,
  `difference-between-ui-and-ux`, `what-is-product-design`, IxDF beginner
  guide.
- `visual-hierarchy`, `layout-and-grid-systems`, `spacing-and-rhythm`:
  `design-basics`, `ui-design-principles`, `what-is-graphic-design`.
- `responsive-and-mobile-first-thinking`: `responsive-website-design`,
  `mobile-website-design`, `static-vs-dynamic-website`.
- `typography`: `typography`, `best-sans-serif-fonts`,
  `wedding-font-pairings` (as a font-pairing case study, not a literal
  wedding-site concept).
- `color-and-contrast`: `color-theory`, `color-combinations`,
  `types-of-color-palettes`.
- `accessibility-and-wcag-basics`: Nielsen Norman Group articles,
  `button-states`, `ux-validation`.
- `navigation-and-information-architecture`: `user-flow`,
  `design-system-examples`, `what-is-wireframing`,
  `prototype-and-wireframe`, `wireframe-vs-mockup`.
- `content-design-and-microcopy`: `ux-and-communication-strategy`,
  `how-to-start-a-presentation` (structuring a message for an audience).
- `forms-and-inputs`, `interaction-states-and-feedback`: `button-states`,
  `pricing-page-best-practices`, `ux-for-product-managers`.
- `motion`: no single Figma resource library article maps directly; sourced
  primarily from Nielsen Norman Group and ux.stackexchange.com discussion
  of when motion helps versus harms.
- `common-design-mistakes`: ux.stackexchange.com and Nielsen Norman Group,
  since real, observed mistakes are better sourced from practitioner
  discussion and usability research than from a single vendor's framing.
- Template mapping cross-check (section 13.2): `landing-page-examples`,
  `portfolio-website-examples`, `personal-website-examples`,
  `ai-website-examples`, `design-system-examples`.

#### 12.5.2 Cross-cutting findings

Before the per-concept notes, six findings surfaced during research that
apply across more than one concept. Findings 1 through 4 come from the
initial pass across the fixed source list; findings 5 and 6 come from a
follow-up pass that went one level deeper, into the category pages'
individual articles rather than the category index pages themselves, per
an explicit request to actually read the linked articles rather than stop
at the overview page.

1. **Several fixed-list category pages are indexes, not articles in their
   own right.** The Figma resource library's category URLs (for example
   `color-theory/`, `typography/`, `ux-and-communication-strategy/`,
   `design-basics/`) mostly list links to individual articles rather than
   containing the guidance directly. The follow-up pass (findings 5 and 6)
   fetched the actual linked articles for the categories that mattered
   most; `ux.stackexchange.com` still could not be fetched at all
   (blocked) and remains open for a future manual spot-check.
2. **Nielsen's 10 Usability Heuristics is a widely cited foundational
   framework with no explicit home in the current curriculum.** Confirmed
   directly from `nngroup.com/articles/ten-usability-heuristics/` (fetched
   in the follow-up pass), which gives the exact, citable list: visibility
   of system status, match between system and the real world, user control
   and freedom, consistency and standards, error prevention, recognition
   rather than recall, flexibility and efficiency of use, aesthetic and
   minimalist design, help users recognize/diagnose/recover from errors,
   and help and documentation. Rather than add a new concept or module for
   this (which would violate Tenet 5 for a framework that overlaps
   existing concepts), the M3 authoring requirement is a precise mapping:
   `common-design-mistakes` cites error prevention, aesthetic and
   minimalist design, and error recovery; `interaction-states-and-feedback`
   cites visibility of system status, user control and freedom, and error
   recovery; `navigation-and-information-architecture` cites match with
   the real world, consistency and standards, recognition rather than
   recall, and help and documentation. Each must name its heuristic
   explicitly as attributed source material, not just describe the
   behavior informally.
3. **Fitts's Law is a second named-citation gap**, surfaced from
   `ui-ux-design-principles/`: target size and distance affect selection
   speed and error rate. This is directly relevant to `forms-and-inputs`,
   `interaction-states-and-feedback`, and the touch-target-sizing content
   already scoped into `responsive-and-mobile-first-thinking`. Same
   treatment as finding 2: name it explicitly during M3 authoring rather
   than add a concept for it.
4. **A small, genuine cross-validation**: the `button-states` article's
   recommended interaction feedback timing, "keep animations between 100ms
   and 200ms," matches Template Interface's own `--transition-base: 150ms ease`
   token already defined in DESIGN.md section 3, written before this
   research pass ran. Recorded here as a positive signal that the existing
   design system tokens already align with external guidance, not as a
   change.
5. **Typography now has real, specific numbers to cite**, from
   `typography-in-design/` (found by drilling into the `typography/`
   category's actual article list): body text at 16px with H1 around 48px,
   scaled as multiples of the body size; line height between 1.125 and
   1.2 times the font size; line length of roughly 40 to 60 characters
   including spaces and punctuation. This upgrades `typography` from
   source-limited to confirmed with citable mechanics, and is also a
   DESIGN.md observation, not a required change: DESIGN.md section 2.2
   already defines `--font-size-4xl` at 3rem/48px, currently reserved for
   template hero headlines only; whether the wiki article `<h1>` should
   also use it instead of `--font-size-3xl` (2.25rem/36px) is a candidate
   for the theme revisit in DESIGN.md section 10, not a change made here.
6. **Color-and-contrast now has real functional-role guidance**, from
   `what-is-color-theory/` and `color-combinations/` (found by drilling
   into the `color-theory/` category): backgrounds should use lighter or
   muted tones for readability, text/primary elements should use darker
   tones for contrast, and accents/calls-to-action should use brighter,
   saturated tones to draw attention. This is the same background, text,
   and accent role split `color-and-contrast` already teaches, and matches
   the functional split DESIGN.md section 2.1 already uses (dark canvas,
   light text, saturated teal accent), just confirmed independently rather
   than only by internal consistency. Neither article gave a specific
   numeric WCAG contrast ratio, which is expected: that is a technical
   accessibility standard, not typically covered by design-audience
   articles, and DESIGN.md section 6.2 already states it directly (4.5:1
   body text, 3:1 for large or bold text).

No concept's placement, difficulty level, or prerequisite chain was
reordered as a result of this pass. Every source checked either confirmed
the current curriculum or was too shallow to confirm or contradict it; none
argued for a different sequence.

#### 12.5.3 Per-concept validation notes

| Concept | Result | Note |
|---|---|---|
| `what-is-ui-ux` | Confirmed | `difference-between-ui-and-ux` explicitly backs the UI-as-subset-of-UX framing and the beginner, no-prerequisite placement. |
| `visual-hierarchy` | Confirmed, refined | `ui-design-principles` confirms hierarchy as foundational. It also names "Proximity" (grouping related elements) as a related perceptual principle; folded into `spacing-and-rhythm`'s content scope for M3 rather than added as a separate concept. |
| `layout-and-grid-systems` | Confirmed | `ui-design-principles` backs alignment and grid systems at this placement. |
| `spacing-and-rhythm` | Confirmed, refined | `what-is-graphic-design` treats space as a basic, foundational element rather than a distinct intermediate topic, which if anything supports keeping this concept's placement at beginner-to-intermediate rather than later. Proximity (finding above) is now explicitly part of this concept's scope for M3. |
| `responsive-and-mobile-first-thinking` | Confirmed | `responsive-website-design` strongly backs the definition, the intermediate placement, and both prerequisites. |
| `typography` | Confirmed | `typography-in-design` (found by drilling into the `typography/` category, see finding 5) gives citable mechanics: roughly 16px body scaling to 48px H1, 1.125 to 1.2 times line height, 40 to 60 character line length. `best-sans-serif-fonts` separately supports the legibility-over-decoration framing. |
| `color-and-contrast` | Confirmed | `what-is-color-theory` and `color-combinations` (found by drilling into the `color-theory/` category, see finding 6) confirm the background/text/accent functional-role split this concept teaches, and independently match DESIGN.md's own token roles. Numeric WCAG contrast ratios are not covered by either article, which is expected of design-audience content; DESIGN.md section 6.2 already states the ratios directly. |
| `accessibility-and-wcag-basics` | Confirmed, refined | `ux-validation/` treats accessibility as a final-stage audit activity rather than a foundational practice, a known anti-pattern. The curriculum's existing prerequisite chain (after `color-and-contrast` and `typography`, not at the end of the whole curriculum) already avoids this; M3 authoring should additionally add "Related Concepts" backlinks from `color-and-contrast` and `typography` pointing here, so accessibility reads as integrated rather than bolted on. |
| `navigation-and-information-architecture` | Confirmed | `what-is-wireframing` supports layout/grid understanding preceding IA work; no reordering indicated. |
| `content-design-and-microcopy` | Confirmed | The original `ux-and-communication-strategy/` mapping was a mismatch (see the prior note, preserved in PATCHNOTES v0.4.1); a targeted follow-up search under the ongoing intake process in section 12.5.4 found `nngroup.com/articles/3-is-of-microcopy/`, which gives a direct, citable framework: microcopy's three goals are Inform (headings, tooltips, context), Influence (calls to action, brand tone), and Interact (button/link labels, placeholder text, state indicators). Directly supports the concept's scope on button/label clarity and cutting unnecessary words; M3 should cite this framework by name. |
| `forms-and-inputs` | Confirmed, source-limited | `pricing-page-best-practices` supports CTA clarity and touch-target sizing but has little on label placement or validation timing specifically; general industry consensus (also see Fitts's Law, finding 3) still supports the current scope and placement. |
| `interaction-states-and-feedback` | Confirmed, refined | `button-states` confirms the five core states and the prerequisite ordering after `forms-and-inputs`; adds "success," "error," and "selected/toggled" as additional states worth naming in M3 content. |
| `motion` | Confirmed | The fixed source list had nothing on motion (checked again by drilling into `prototype-and-wireframe/`'s real articles, still nothing). A targeted follow-up search under section 12.5.4 found NN/G's two-part animation series: `animation-purpose-ux/` (motion should communicate feedback, state change, or affordance, not decoration) and `animation-duration/` (roughly 100ms for simple feedback like toggles, 200 to 300ms for modals and larger transitions, an upper ceiling around 400 to 500ms, ease-out for entrances, and an explicit requirement to respect reduced-motion preferences). This directly confirms Template Interface's own `--transition-fast` (100ms), `--transition-base` (150ms), and `--transition-slow` (250ms) tokens as sitting correctly inside NN/G's recommended ranges, and gives concrete, citable content for this concept's page. |
| `common-design-mistakes` | Confirmed | `nngroup.com/articles/` surfaced concrete, real examples (a design-pattern regression in iOS, presentation mistakes in UX deliverables) consistent with a practitioner-grounded capstone; also the origin of finding 2 above. |

Template mapping (section 13.2) was spot-checked against
`landing-page-examples` and `portfolio-website-examples`: both sources
emphasize conversion clarity, trust signals, and case-study narrative more
than pure visual mechanics. No change to the concepts-demonstrated lists in
section 13.2, since the currently listed concepts remain accurate; M3 and
Phase 2 content authoring should avoid overstating "design mechanics" in
template copy at the expense of why the content works. The 5-template,
grow-later approach was also checked against `what-is-a-minimum-viable-product`
and aligns with standard MVP and Lean Startup framing (ship a minimal
core, iterate), supporting Tenet 5 and the Roadmap's deferred-items
approach in section 14.

#### 12.5.4 Ongoing curriculum research intake

The source list in section 12.5.1 was closed for the M2.9 milestone so that
milestone had a defined scope and a defined stopping point, but Template Interface's
curriculum research is not a one-time event. New sources and principles
can be proposed at any time, and this section defines how they get
triaged so the curriculum keeps growing deliberately rather than
accumulating scope creep.

**Relevance filter.** A proposed source or principle is in scope if it
teaches a visual, interaction, or content design principle applicable to
building a website's UI/UX. It is out of scope if it is primarily about
business or product strategy, team process, project management, AI
tooling and workflows, or UX research methodology, per the non-goal added
to section 4 as a direct result of this milestone.

**Outcome per source reviewed.** Every source checked against the filter
gets one of three outcomes, logged either inline (for an existing
concept) or in the candidate backlog below (for a new one):

1. **Confirms or refines an existing concept.** Logged inline in that
   concept's row in section 12.5.3.
2. **Candidate for a future concept or module.** Logged in the backlog
   below, not built immediately; becoming an actual concept still goes
   through the normal additive process in section 12.1 (a new module takes
   the next unused two-digit prefix; a new concept is appended to its
   module).
3. **Out of scope.** Logged with a one-line reason in the backlog below so
   the same source is not re-litigated on a future pass.

**First logged pass (this version).** The following 24 Figma resource
library category pages were reviewed against the relevance filter, in
addition to the fixed section 12.5.1 list:

`building-with-ai`, `ai-tools-workflows`, `ai-for-product-managers`,
`ai-research-testing`, `design-basics` (duplicate of section 12.5.1),
`ui-ux-design-principles`, `prototype-and-wireframe` (duplicate),
`web-design` (duplicate), `typography` (duplicate), `print-design`
(duplicate), `color-theory` (duplicate), `brand-and-storytelling`,
`strategic-planning`, `business-frameworks`, `competitive-analysis`,
`ux-and-communication-strategy` (duplicate), `project-management`,
`team-productivity`, `higher-education`, `design-research`,
`team-management`, `classroom-tools`, `team-collaboration`,
`productivity-strategies`.

**Candidate backlog:**

| Source or principle | Outcome | Reason |
|---|---|---|
| `ui-ux-design-principles` | Reviewed, findings folded in | Surfaced Fitts's Law and design tokens/systems, see below and finding 3 in section 12.5.2. |
| Design tokens (design-to-code systems) | Candidate for a future concept | Directly relevant since Template Interface's own theme is a token system, but adding it now would teach implementation detail ahead of the current curriculum's visual/interaction focus. Strong candidate for a future module (tentatively "Systems and Implementation") once Modules 01 to 07 are built and validated. |
| Design systems (consistency and scale frameworks) | Candidate for a future concept | Same reasoning and same tentative future module as design tokens; the two are closely related and would likely ship together. |
| Golden ratio, Fitts's Law, human-computer interaction (HCI) as an academic frame | Out of scope as standalone concepts | Each is a real, citable principle, but each is a supporting detail of an existing concept (Fitts's Law belongs in `forms-and-inputs` and `interaction-states-and-feedback`, per finding 3; the golden ratio and HCI are supplementary framing for `visual-hierarchy` and `what-is-ui-ux` respectively) rather than a concept in its own right. |
| `design-thinking`, `design-research` | Out of scope | Both are UX research and problem-framing methodology, which section 4's new non-goal explicitly excludes. |
| `building-with-ai`, `ai-tools-workflows`, `ai-for-product-managers`, `ai-research-testing` | Out of scope | About using AI as a design tool or workflow, not a UI/UX design principle. Distinct from the already-scoped `ai-website-examples` template-mapping source, which is about designing sites that showcase AI products, not about AI-assisted design tooling. |
| `brand-and-storytelling` | Candidate, deferred | Plausibly relevant to `content-design-and-microcopy`, but brand voice is a broader topic than microcopy; worth a dedicated look if that concept's M3 page needs more source depth, per its "source-limited" note in section 12.5.3. |
| `strategic-planning`, `business-frameworks`, `competitive-analysis`, `project-management`, `team-productivity`, `team-management`, `team-collaboration`, `productivity-strategies` | Out of scope | Business strategy and team-process topics, excluded by the non-goal in section 4. |
| `higher-education`, `classroom-tools` | Out of scope | About using design tools in an education-sector context, not about UI/UX design principles themselves. |
| `nngroup.com/articles/3-is-of-microcopy/` | Confirms and refines `content-design-and-microcopy` | Found via targeted search after the fixed list's mapping to this concept turned out to be a mismatch. Logged inline in section 12.5.3. |
| `nngroup.com/articles/animation-purpose-ux/` and `nngroup.com/articles/animation-duration/` | Confirms and refines `motion` | Found via targeted search after the fixed list yielded nothing on motion. Logged inline in section 12.5.3; also cross-validates the `--transition-*` tokens in DESIGN.md section 3. |

**Status.** Milestone M2.9 is complete as of this version, including two
follow-up passes: one that drilled into several fixed-list category pages
for their actual articles (section 12.5.2 findings 5 and 6), and one that
used this section's own intake process to search for and confirm sources
for the two concepts (`content-design-and-microcopy`, `motion`) the first
pass could not validate. As a result, all 14 concepts in section 12.5.3 are
now Confirmed, none required a structural change, and the curriculum in
section 12.1 and 12.2 is unchanged in structure; the refinements are
content-authoring requirements for M3. The candidate backlog stays open
and grows over time as new sources are reviewed; it is not re-closed the
way section 12.5.1's fixed list was for this specific milestone.

---

## 13. Product definition: Phase 2, the Templates layer

Phase 2 does not begin until Phase 1 acceptance criteria are met in full.

### 13.1 Templates showcase page

`/templates/index.html` is a portfolio style showcase, not a wiki page. It
renders one showcase card per entry in `templates-registry.js`, in whatever
order the registry lists them, with no assumption about how many entries
exist. Each card shows a CSS and inline SVG generated visual preview, a
title, and a description of what the template is and when to use it. See
DESIGN.md for the showcase card component spec and the portfolio grid
layout rules.

### 13.2 The five starter templates

Each template demonstrates a deliberately distinct combination of Phase 1
concepts so that, together, the five starter templates exercise every
concept in the curriculum at least once.

**1. Landing Page** (folder: `landing-page`)
- Purpose: A single page marketing or product launch site with a hero
  section, a short feature list, social proof, and a call to action.
- When to use: Announcing a single product, service, or event where the
  goal is one clear conversion action.
- Page structure: Hero (headline, subhead, primary CTA), then feature
  highlights (3 to 4 items), then supporting detail or social proof, then a
  final call to action, then footer.
- Concepts demonstrated: `visual-hierarchy`, `color-and-contrast`,
  `responsive-and-mobile-first-thinking`, `content-design-and-microcopy`,
  `interaction-states-and-feedback`, `motion`.

**2. Portfolio Site** (folder: `portfolio-site`)
- Purpose: A personal or small studio site showcasing a body of work, with
  an about section and a contact point.
- When to use: An individual or small team presenting past projects to
  potential clients or employers.
- Page structure: Intro and about, then a project grid, then a project
  detail pattern (an in-page expand or a linked detail section), then
  contact.
- Concepts demonstrated: `visual-hierarchy`, `layout-and-grid-systems`,
  `spacing-and-rhythm`, `navigation-and-information-architecture`, `motion`.

**3. Blog and Article Site** (folder: `blog-article`)
- Purpose: A reading focused site with a post listing and a long form
  article reading view.
- When to use: Ongoing written content such as a blog, changelog, or
  documentation adjacent writing where readability is the top priority.
- Page structure: Post listing (title, date, excerpt), then an article page
  (title, metadata, body, prior and next navigation).
- Concepts demonstrated: `typography`, `spacing-and-rhythm`,
  `color-and-contrast`, `accessibility-and-wcag-basics`,
  `navigation-and-information-architecture`.

**4. Documentation Site** (folder: `documentation-site`)
- Purpose: A multi page reference site with persistent sidebar navigation
  and a search input, structurally similar to Template Interface's own Education
  section.
- When to use: Product documentation, internal wikis, or any content that
  benefits from a fixed navigation structure across many pages.
- Page structure: Persistent sidebar (sections and pages), then article
  content area, then an on-page table of contents for long pages.
- Concepts demonstrated: `layout-and-grid-systems`,
  `navigation-and-information-architecture`, `forms-and-inputs` (search),
  `accessibility-and-wcag-basics`, `typography`.

**5. Small Business and Local Service Site** (folder: `small-business`)
- Purpose: A multi-section marketing site for a local or service based
  business, covering services offered, credibility, and how to get in touch.
- When to use: A business with a physical location, service area, or booked
  appointments that needs hours, services, testimonials, and a contact form.
- Page structure: Hero with a primary action (call, book, or contact), then
  services list, then testimonials, then hours and location, then contact
  form.
- Concepts demonstrated: `forms-and-inputs`,
  `interaction-states-and-feedback`,
  `responsive-and-mobile-first-thinking`,
  `content-design-and-microcopy`, `common-design-mistakes` (used as an
  explicit before and after section within the template's own README).

### 13.3 Template folder and registry contract

Every template, present or future, must satisfy this contract for the
showcase page to pick it up correctly.

**Folder contract.** Each template lives at `/templates/{template-slug}/`
and contains at minimum:

```
templates/{template-slug}/
  index.html      Entry point, opens directly in Chrome
  manifest.js      window.WIREFRAME_TEMPLATE_MANIFEST, this template's metadata
  styles.css       Template specific styles, built on the shared theme tokens
  script.js        Template specific behavior, if any
  README.md        What the template is, when to use it, setup notes
```

**Manifest shape.** `manifest.js` assigns one object, in the same shape
required by the registry:

```js
window.WIREFRAME_TEMPLATE_MANIFEST = {
  id: "landing-page",
  title: "Landing Page",
  folder: "landing-page",
  description: "A single page marketing site with a hero, feature highlights, and a call to action.",
  whenToUse: "Announcing a single product, service, or event with one clear conversion goal.",
  conceptsDemonstrated: [
    "visual-hierarchy",
    "color-and-contrast",
    "responsive-and-mobile-first-thinking",
    "content-design-and-microcopy",
    "interaction-states-and-feedback",
    "motion"
  ],
  previewType: "css-svg",
  version: "1.0.0",
  status: "stable"
};
```

**Registry.** `/assets/js/templates-registry.js` assigns a single global
array of manifest objects, one per template, in showcase display order:

```js
window.WIREFRAME_TEMPLATES = [
  // one manifest object per template, copied in from that template's manifest.js
];
```

Adding a new template is a two step, additive only process: create the new
`/templates/{template-slug}/` folder following the contract above, then
append its manifest object to `templates-registry.js`. No existing file is
modified, no page hardcodes a template count, and the showcase grid,
DESIGN.md layout rules, and card component all render correctly for any
array length, including zero.

### 13.4 Phase 2 acceptance criteria

Phase 2 is complete for its initial scope when all of the following are
true:

- All five starter templates exist, each satisfying the folder contract in
  section 13.3.
- Each template's `index.html` opens correctly by double clicking in
  Chrome, with no console errors and no dependency on Phase 1 files.
- Each template's CSS and inline SVG preview renders correctly on the
  showcase page without any image assets.
- `templates-registry.js` contains one correctly filled entry per template,
  matching that template's own `manifest.js`.
- The showcase page renders correctly with any number of registry entries,
  verified by temporarily testing with a registry of one entry and a
  registry of eight entries.
- Each template's README.md states what the template is and when to use it
  in copy consistent with the showcase card description.
- No em dash, `&mdash;`, or punctuation double dash appears anywhere in the
  template's copy, per section 6.
- Each template passes the responsive QA methodology in DESIGN.md section
  8 at every listed breakpoint.

### 13.5 Template library expansion (milestone M9)

The initial five templates in section 13.2 were chosen specifically to
exercise every Phase 1 concept at least once, not to be the library's
final size. With Phase 2's initial scope built and verified (M5 through
M7), the next scope for the Templates section is a deliberate expansion
from 5 to 20 templates, using the same additive folder and registry
contract from section 13.3 that already made this possible without
touching a single existing file.

**Why 20, and why now.** Five templates proved the contract works; twenty
is enough breadth to cover the general-purpose website types a visitor
(human or AI) is likely to actually need, without drifting into
niche-specific templates that belong in a future, separate expansion
rather than this one. This milestone originally scheduled itself right
after M7, since the contract, the showcase page, and the registry needed
to be proven correct at small scale (5 entries, tested up to 8 in M6's
acceptance pass) before committing to triple that scale.

**Rescheduled after M10.** Once M10 (DESIGN.md section 11) expanded to
cover the full site, including the template library's own presentation,
M9 moved to after M10 instead: the 15 new templates should be built
directly in whatever the redesigned system turns out to be, once, rather
than built in the current design and then redesigned a second time along
with the original 5. See section 14's recommended build order.

**The 15 new templates, built as of this version.** Each is mapped to the
existing 14 Phase 1 concepts; no new concept was required to support this
expansion, consistent with Tenet 5 (additive, not hardcoded) and the
scope discipline in section 4's non-goals. This list started as a draft
for M9 to confirm or adjust, the same way section 12.5.1's source list was
a draft the actual M2.9 research pass then validated; it was built as
originally proposed, with no changes to the candidate list itself.

| # | Template | Folder | Concepts demonstrated |
|---|---|---|---|
| 6 | E-commerce Product Page | `ecommerce-product` | `visual-hierarchy`, `color-and-contrast`, `forms-and-inputs`, `interaction-states-and-feedback`, `responsive-and-mobile-first-thinking` |
| 7 | E-commerce Storefront | `ecommerce-storefront` | `layout-and-grid-systems`, `navigation-and-information-architecture`, `spacing-and-rhythm`, `responsive-and-mobile-first-thinking` |
| 8 | SaaS Pricing Page | `pricing-page` | `visual-hierarchy`, `content-design-and-microcopy`, `color-and-contrast`, `interaction-states-and-feedback` |
| 9 | Event and Conference Site | `event-site` | `typography`, `visual-hierarchy`, `forms-and-inputs`, `navigation-and-information-architecture` |
| 10 | Nonprofit and Charity Site | `nonprofit-site` | `content-design-and-microcopy`, `color-and-contrast`, `forms-and-inputs`, `interaction-states-and-feedback` |
| 11 | Restaurant and Menu Site | `restaurant-site` | `typography`, `layout-and-grid-systems`, `responsive-and-mobile-first-thinking`, `navigation-and-information-architecture` |
| 12 | Real Estate Listing Site | `real-estate-listing` | `layout-and-grid-systems`, `spacing-and-rhythm`, `navigation-and-information-architecture`, `forms-and-inputs` |
| 13 | Online Course Landing Page | `course-landing` | `visual-hierarchy`, `content-design-and-microcopy`, `interaction-states-and-feedback`, `motion` |
| 14 | Personal Resume and CV Site | `resume-site` | `typography`, `spacing-and-rhythm`, `accessibility-and-wcag-basics`, `visual-hierarchy` |
| 15 | Community and Forum Homepage | `community-forum` | `navigation-and-information-architecture`, `layout-and-grid-systems`, `content-design-and-microcopy`, `interaction-states-and-feedback` |
| 16 | Newsletter and Waitlist Signup Page | `waitlist-signup` | `content-design-and-microcopy`, `forms-and-inputs`, `interaction-states-and-feedback`, `motion` |
| 17 | Multi-step Onboarding Flow | `onboarding-flow` | `forms-and-inputs`, `interaction-states-and-feedback`, `content-design-and-microcopy`, `motion` |
| 18 | Internal Dashboard and Admin Panel | `admin-dashboard` | `layout-and-grid-systems`, `navigation-and-information-architecture`, `accessibility-and-wcag-basics`, `forms-and-inputs` |
| 19 | Job Board and Careers Page | `careers-page` | `content-design-and-microcopy`, `navigation-and-information-architecture`, `visual-hierarchy`, `responsive-and-mobile-first-thinking` |
| 20 | FAQ and Help Center Page | `help-center` | `navigation-and-information-architecture`, `content-design-and-microcopy`, `typography`, `accessibility-and-wcag-basics`, `forms-and-inputs` |

**Process.** Identical to section 13.3's existing contract, run fifteen
times: for each template, create `/templates/{template-slug}/` with
`index.html`, `manifest.js`, `styles.css`, `script.js`, and `README.md`,
then append its manifest object to `templates-registry.js`. No existing
template, page, or script was modified to add a new one; this was true at
5 templates and stayed true at 20.

**M9 acceptance criteria.** Phase 2's expanded scope is complete when:

- All 20 templates (the original 5 plus the 15 above) exist, each
  satisfying the folder contract in section 13.3. **Met**: verified by
  script, every one of the 20 folders contains all 5 required files.
- Every item in section 13.4's acceptance criteria passes for all 20
  templates, not just the original 5. **Met for what can be checked
  statically**: no broken links, no dangling JavaScript element
  references, and no writing style violations anywhere in the 15 new
  templates (one real one, an `&mdash;` in a testimonial attribution,
  was caught and fixed before this version shipped). Live browser
  verification of the 15 new templates has not been run by the
  maintainer yet, unlike the original 5 (see M7's status).
- The showcase page (`templates/index.html`) renders all 20 correctly in
  a single grid with no layout break, confirming the `auto-fill` grid in
  DESIGN.md section 5.2 holds at this scale, not just the one-to-eight
  range tested in M6. **Structurally met**: the grid and preview system
  are unchanged from M6 and read the registry length dynamically, with a
  distinct CSS/SVG preview layout added for each of the 15 new template
  ids; live confirmation in a real browser is the same open item as
  above.
- Every relevant Education concept page's "Used In Templates" section is
  updated to include any of the 15 new templates that demonstrate it,
  the same way M6 updated all 14 concept pages for the original 5.
  **Met**: all 14 concept pages and their markdown mirrors updated.

### 13.6 Template composition and recreation contract

Section 12.3 guarantees a model can extract any *concept* cleanly. This
section is its counterpart for the Templates layer, and it guarantees
something harder: that a reader who has never opened a template folder,
person or model, can understand how that template is composed and rebuild
it as a working site without guessing.

The reason this is a contract and not a nicety is in section 3's goals.
These templates exist to be copied out and turned into real sites. A
template whose composition is undocumented is a screenshot with extra
steps: someone can copy the files, but they cannot tell which parts are
load-bearing, which are placeholder, and which are deliberately inert. So
the record of how a template is built is treated as part of the template.

**Fixed README sections (every template).** Every `README.md` under
`/templates/` uses the same `##` sections in the same order, so the same
fact is always in the same place:

1. When to use
2. Page structure
3. Composition
4. Concepts demonstrated
5. Recreating this as a live site
6. Setup notes

A template may add sections beyond these; it may not omit or reorder
them. Every template also carries the design notes panel of section
13.9, and its Recreating section says to remove the panel when copying. `templates/TEMPLATE_CONTRACT.md` holds the field-level detail of
what Composition and Recreating must each contain.

**The two indexes.** Mirroring the Education layer's pair exactly:

- `/assets/js/templates-index.js` assigns a single global array,
  `window.WIREFRAME_TEMPLATE_INDEX`, one record per template, safe to
  open and read as plain text without executing it. Each record carries
  the entry file, every page in the folder, the shared CSS and JS it
  depends on, the region outline, the layout grids, the breakpoints, the
  events the script binds, the ids and selectors it resolves, the
  elements carrying a non-functional demo notice, and the concepts
  demonstrated.
- `/templates/INDEX.md` mirrors the same data as markdown, so a reader
  working only in markdown still gets a complete map of the library
  without reading JavaScript.

This is deliberately the same shape as `concepts-index.js` and
`education/INDEX.md`. A model that has learned how to read the Education
layer already knows how to read this one.

**Derived, not remembered.** Every field in both indexes, and everything
under a README's Composition heading, is a fact about the files and is
re-derived by reading them. No tool ships to do this: section 9 rules out
a build step, and the README promises the project needs no runtime
installed. `TEMPLATE_CONTRACT.md` therefore states the derivation rules
precisely enough that two readers get the same answer, and requires empty
fields to be written as empty arrays so "none" is distinguishable from
"not recorded".

**Honest about what does not work.** Section 18 already requires that no
form or control silently pretend to submit. This section adds the
reporting half: every element carrying such a notice is named by id in
the index and in the template's own README, under Wire up. A rebuild is
expected to replace that message with a real result, not to delete it.

**Acceptance criteria.**

- Every template's README carries the six sections above, in order.
- Every record in `templates-index.js` corresponds to a real folder, and
  every folder has a record.
- `templates/INDEX.md` lists the same templates with the same data.
- Every id named in a `nonFunctionalTargets` field exists in that
  template's HTML and is written to by its script.
- No template's Composition section describes markup, hooks, or
  breakpoints that its files do not contain.

### 13.7 Site interface redesign (milestone M15)

*Status.* Done in v0.17.0 (2026-10-04). Agreed with the maintainer on
2026-09-22. What was built is listed under "Built" at the end of this
section.

*Decisions, 2026-10-04.* The maintainer reviews once, at the end, after
all three sections are built and verified. The root page's hero shows a
mosaic of the template previews. Previews are CSS drawings, as below.
A click on a showcase card opens the quick view first.

**Why.** After M14 the templates are 21 finished sites with their own
identities, and the site that presents them has fallen behind. Screenshots
of the root page, the showcase and the Education pages at 1440px, taken on
2026-09-22, show four problems:

- **The showcase hides the library.** Every preview is the same teal
  outline wireframe, so 21 visually distinct templates look identical
  until opened. This is the largest gap.
- **The root page describes the product without showing it.** A centred
  headline, two step cards and a curriculum strip, with a lot of empty
  space at desktop width and nothing from the library or the lessons on
  screen. (It also said "5 starter templates" after there were 21; that
  line was corrected on 2026-09-22.)
- **Education reads as one narrow column.** Wide empty margins at 1440px,
  no search, no "on this page" contents, and no previous and next links
  through the curriculum.
- **The accent has lost its meaning.** Teal marks links, tags, buttons
  and every preview box, so it no longer points at anything in
  particular.

**Direction.** The site stays dark. The fix is interface, not palette,
and each section borrows the pattern from the template that already
solved its problem. Those templates were built and verified in M14, so
the patterns are proven, not speculative.

1. **Templates showcase, from `ecommerce-storefront`.**
   - Filter chips by concept and by page type, with live counts; a text
     search; a sort.
   - A quick view dialog that shows the template itself, with its
     description, concepts and a link to open it.
   - Previews drawn in each template's own palette and shapes, so a dark
     Relaywise card and a cream Amaro card look like the sites they lead
     to. Drawn in CSS from per-template preview data kept with the
     registry, not screenshots: `favicon.png` stays the only raster file
     in the project.
2. **Root page, from `landing-page`.**
   - A split hero: the pitch on the left, and on the right a live mosaic
     of the real template previews from item 1, or a small working lesson
     demo.
   - Figures with the true counts (14 concepts, 7 modules, 21 templates),
     derived from `nav-data.js` and `templates-registry.js` rather than
     typed, so they cannot go stale again.
   - A tabbed "how it works" and a closing call to action.
3. **Education, from `documentation-site`, restyled dark.**
   - A top bar with search across every concept page (`/` and Ctrl+K),
     built from the pages' own headings and text, as Parcelpoint does.
   - The grouped module rail on the left, kept from `nav.js`.
   - The article at a fixed reading width, with an "on this page" column
     that marks the section being read, collapsing under the title at
     narrower widths.
   - Previous and next links in curriculum order, from `nav-data.js`.
   - One shared layout change in `wiki-layout.css` and `nav.js`, so all
     seven module pages and fourteen concept pages move together. Every
     interactive demo keeps working unchanged.

**Colour, kept dark.**

- Keep the current base palette in `theme.css`.
- Add one more surface elevation step, so panels, cards and dialogs
  separate by lightness rather than by borders alone.
- Teal stays the single accent, used only for actions, the current
  location and focus.
- Tags become neutral pills. That change alone calms the page and gives
  the accent its meaning back.
- One shared accent keeps the three sections one site; the layouts give
  each its own character.

**Order.** Showcase first (the most visible and the biggest gap), then
the root page (which reuses the showcase's new previews), then Education
(the largest, since it touches every lesson page and its demos).

**Constraints.** Everything in section 17 still holds: vanilla HTML, CSS
and JS, no build step, working under `file://` in Chrome with no fetch,
XHR or ES modules, no external resources, relative paths only, and the
writing-style rules in section 6. The markdown mirrors and the
`concepts-index.js` and `templates-index.js` contracts in sections 12.3
and 13.6 are unchanged; if a hook they record moves, the index moves
with it.

**Risk: the templates share the site's stylesheets.** Every template
links `theme.css`, `base.css` and `components.css`. The templates set
their own colours, and only `wiki-portal` reads site colour tokens
directly (three uses), but the shared files still give default colours
to links, focus rings and tables that a template may rely on without
saying so. Any change to those three files requires the M14 checks to be
re-run on all 21 templates, not only on the pages being redesigned. New
interface styles belong in `portfolio-layout.css`, `wiki-layout.css` or
a new site-only stylesheet wherever possible, so the shared three change
as little as they can.

**Acceptance criteria.**

- The showcase shows every template with a preview in its own palette;
  filters and search narrow the list with correct live counts; the quick
  view opens and closes from the keyboard with focus returned.
- The root page's figures match the counts in `nav-data.js` and
  `templates-registry.js`.
- Every Education page has working search, an "on this page" list that
  marks the current section, and previous and next links in curriculum
  order; every interactive demo behaves as before.
- Teal appears only on actions, the current location and focus.
- Every redesigned page, and all 21 templates, meet the M14 evidence
  bar: screenshots at 1440 and 375px; no horizontal overflow at the eight
  documented widths or the widths between; no console errors; 0 measured
  contrast failures; a visible focus ring on every tab stop at 3:1
  against its surface; controls driven with real key and mouse events;
  reduced motion checked by emulation.
- DESIGN.md records the new components and the accent rule, PATCHNOTES
  records the changes and what was verified, and the README status table
  reflects M15.

**Built (v0.17.0).**

- *Showcase* (`templates/index.html`, `portfolio-layout.css`): a filter
  column with page-type chips (marketing, shop, content, local business,
  personal, app) and a "Teaches" list of the 14 concepts, each with a
  live count that ignores its own group; a search; a sort (featured, A to
  Z, most concepts); cards whose whole area opens a quick view dialog,
  which shows the large preview, the description, every concept and an
  "Open template" link, takes focus and returns it to the card. Filters
  collapse behind a button under 900px.
- *Previews* (`assets/js/template-previews.js`, `assets/css/previews.css`):
  `WIREFRAME_TEMPLATE_PREVIEWS` holds each template's page type, brand
  name, headline, layout and palette, taken from its `styles.css`;
  `WireframePreview.build(id)` draws one of 21 layouts in that palette in
  plain elements sized in container units. Decorative, so `aria-hidden`.
- *Root page* (`index.html`, `assets/css/home.css`): a split hero with a
  mosaic of six previews, figures counted from `WIREFRAME_NAV` and
  `WIREFRAME_TEMPLATES`, tabs for "how it works" (WAI-ARIA tabs with arrow
  keys), the module list from `nav-data.js`, and a closing call to
  action.
- *Education* (`nav.js`, `wiki-layout.css`): an Overview link and
  `aria-current` in the rail; a sticky top bar with breadcrumbs and a
  search button; an "On this page" column from 1200px that marks the
  section being read, folding into a closed list under the title below
  that; previous and next links in curriculum order; a search dialog
  (`/` or Ctrl+K) over `assets/js/search-index.js`, which
  `tools/build-search-index.py` generates from the pages' titles,
  headings and text. The index is loaded only when search first opens.
- *Colour*: `--color-surface-raised` and `--color-tag-bg` added to
  `theme.css` (new tokens only, so the templates are unaffected); tags,
  eyebrows and difficulty badges are neutral.

**Verified (v0.17.0).** Headless Edge: the root, showcase and Education
index and 14 concept pages at eight widths with no overflow and no
console errors; all 21 templates and `article.html` at 375 and 1440px
with no overflow, no errors and the return bar present; about a hundred
driven checks (filters, counts, search, sort, quick view focus, tabs,
search dialog keys, contents marking, pager order, mobile menu and
Escape) all passing. Contrast: 0 failures outside two lesson demos that
are low contrast on purpose (the "Ceramic mug" caption in the
accessibility demo and the "Our services" heading in the critique demo).

### 13.8 Rename to Template Interface (milestone M16)

*Status.* Done in v0.15.0. The going-live wording was rewritten in
v0.15.0: the root page has the agreed meta description, its hero no
longer calls the site offline, and the README and PRD describe a public
site that still works from disk. Choosing a host and deploying remain the
maintainer's steps. The visible rename was done in v0.14.0 at the
maintainer's request on 2026-10-01, ahead of the domain: every page
title, wordmark, sidebar title and visible mention, and the docs,
now say Template Interface, with the script identifiers and dated
history kept as below. The root page's header now wraps its nav below
the longer wordmark at narrow widths. Still to do: the going-live
wording below (the site still calls itself offline) and the meta
description, once the domain is live.

**Why.** "Wireframe" means a rough outline of a page, which described
the templates when they were one-screen sketches. Since v0.12.0 they are
21 complete, working sites, and the name undersells them. The domain
`wireframe.com` is also taken. The new name is **Template Interface**,
at `templateinterface.com`: "template" says the site hands you starting
points, "interface" says what they are and what the lessons teach. The
tagline carries the learning half: "Template Interface: learn why good
design works, then build with it."

**Prerequisite.** The maintainer registers `templateinterface.com` (and,
if available, `templateinterfaces.com` and the hyphenated form, pointed
at it). If the singular cannot be had, the plural is the fallback and
this section's name changes with it.

**Scope: what changes.** Every place a reader sees the name. A search on
2026-09-27 found "wireframe", in any case, 268 times across 75 files:
125 in 28 HTML files, 34 in 32 JS files, 109 in 15 Markdown files, none
in CSS.

- The header wordmark and every page `<title>` (for example
  "Education - Wireframe" becomes "Education - Template Interface").
- Visible copy on the root page, the Education pages and the showcase.
- The README, PRD, DESIGN, `templates/INDEX.md`, `education/INDEX.md`,
  `templates/TEMPLATE_CONTRACT.md`, the review prompt, and the markdown
  mirrors, where they name the project.
- Template text that names the project: registry and manifest
  descriptions, README sections, and `<title>` suffixes such as
  "Wireframe template".
- The findings doc's references to the project by name, going forward.

**Scope: what deliberately stays.**

- **Script identifiers.** `WIREFRAME_BASE_PATH`, `WIREFRAME_CURRENT_PAGE`,
  `WIREFRAME_TEMPLATE_MANIFEST`, `WIREFRAME_TEMPLATE_INDEX`,
  `WIREFRAME_CONCEPTS`, `WIREFRAME_NAV`, `WIREFRAME_TEMPLATES`,
  `WireframeMotion` and `WireframeDemo` are internal names no visitor
  sees. They appear on every page and in the two index contracts
  (sections 12.3 and 13.6), and a model or script reading the project
  relies on them. Renaming them costs a full re-verification of every
  page for no visible gain. They stay, and the README and DESIGN note
  once that the prefix is the project's former name.
- **History.** Earlier PATCHNOTES entries, milestone records and the
  findings doc's past entries say "Wireframe" because that was the name
  then. They are not rewritten.
- **The project folder.** The local folder can be renamed whenever the
  maintainer likes; nothing in the project depends on its name, since
  every path is relative.

**Going live.** The project is also moving from an offline tool to a
public website at the new domain, agreed on 2026-09-27. The code needs
no change for that: every page is plain static files with relative
paths, so it can be served as is, and it must keep working when opened
from disk under `file://`, since section 17's constraints still hold.
What changes is how the project describes itself. A search on
2026-09-27 found offline or not-hosted wording in `index.html` (two
places, including the hero line "a fully offline curriculum"), the
README (two), and the PRD (eighteen). In particular:

- Section 4's non-goal "Wireframe is not a hosted product. It has no
  live URL, no deployment target" is reversed: the site is hosted at
  `templateinterface.com`. The neighbouring non-goal stays true in
  substance (no server-side code, database, account system or
  analytics) and is reworded to say so without implying the site is
  offline.
- Copy that sells the site as offline ("no server, no tracking, just the
  files on this disk") is rewritten for a public site. The description
  agreed for listings and the root page's `<meta name="description">`:
  "Template Interface is a free guide to UI and UX design. Learn why
  good design works through 14 hands-on lessons with live demos, then
  build with 21 complete website templates, each one showing the lessons
  it puts into practice. No account needed: pick a template, see how
  it's made, and make it yours."
- Section 15 (metrics) and section 22's note about it assume a
  single-user offline tool; both are revisited for a public site, still
  with no analytics unless the maintainer decides otherwise.
- Anything else that assumes the reader has the files locally
  ("double-click the file", "on this disk") is checked, and kept only
  where it describes working on a copy.

Choosing a host and deploying are the maintainer's steps and are not
part of this milestone; the milestone makes the project ready for them.

**Order.** Register the domain; rename the visible text on the site and
rewrite its offline claims; rename the docs; then sweep, so the site and
its description never disagree for long.

**Constraints.** Section 17 and the writing-style rules in section 6
still hold. The name is written as two words, "Template Interface", in
text; the joined form is only for the address.

**Acceptance criteria.**

- A case-insensitive search for "wireframe" finds it only in the script
  identifiers listed above, in dated history, and in the one note
  explaining the prefix.
- Every page's `<title>` and header show Template Interface.
- The registry, `templates-index.js`, `templates/INDEX.md` and each
  manifest still agree, re-checked by the section 13.6 script checks.
- Every page loads with no console errors and no horizontal overflow at
  the section 8.1 widths, and the header wordmark fits at 320px.
- No page or doc describes the project as offline-only or not hosted,
  except where it describes opening a copy from disk, and section 4 no
  longer lists hosting as a non-goal.
- The root page has a `<meta name="description">` carrying the agreed
  description.
- Every template's address that a design notes prompt links
  (`https://templateinterface.com/templates/<id>/`, section 13.9)
  loads the live template and its files.
- PATCHNOTES records the rename, the README status and version reflect
  it, and section 22 has no open item referring to the old name.

### 13.9 Template design notes (milestone M17)

*Status.* Done in v0.15.0. Agreed with the maintainer on 2026-09-27 and
piloted on five templates (`admin-dashboard`, `landing-page`,
`nonprofit-site`, `portfolio-site`, `restaurant-site`) in v0.13.0. At
the maintainer's request the other sixteen were added together in
v0.15.0 rather than a few per session. Every prompt also carries the
M18 line for dark and light mode (section 13.10).

**Why.** Each template's content is an invented business, which shows the
layout working with real-looking copy but says nothing about why the
layout is the way it is. The project's purpose (section 3) is to teach
why good design works and to hand people templates they can use. A
template that explains its own reasoning, and gives a reader a ready
prompt to rebuild it on their own site, serves both.

**The design philosophy every template follows.** This is a standing
rule. Any template added after M17 ships with its design notes, and a
template without them does not pass review.

1. **Design from the use case.** A template starts from a named audience
   and what they need to do on the page (the brief). Section order,
   the primary action, density and tone follow from that brief, and the
   notes say how.
2. **Show the reasoning.** The notes record the design process as
   steps, and each claim about why the result suits the use case names
   the design choice that achieves it.
3. **Tie it to the lessons.** The notes link the concept pages the
   template puts into practice (its `conceptsDemonstrated`).
4. **Layout is the template; branding belongs to the site.** A template
   provides structure, interface and behaviour. Its palette and type are
   a sample identity for the demo. When it is applied to a real site
   that already has branding, that branding (colours, logo, typefaces,
   imagery, voice) is kept and mapped onto the layout's colour roles;
   the template's palette is used only for a site with none. Every
   recreation prompt states this rule first, and says it overrides
   the rest of the prompt.
5. **Reproducible by prompt.** Every template carries a prompt that
   rebuilds it with Claude Code in someone else's project, closed by
   default, with a copy button.

**What each template gets.** A panel at the foot of `index.html`, after
the footer, headed "How this template was designed" and marked "Design
notes", visually separate from the template (DESIGN.md section 4.11). In
order:

- **Recreate it with Claude Code:** a `details` element, closed by
  default, with instructions and the prompt, and a Copy prompt button at
  the right of its header that works without opening it. It
  comes first, above the "Design notes" label, so the action a reader
  most often wants is the first thing in the panel (maintainer's
  request, v0.13.1);
- a short line saying the content above is invented and this panel is
  not part of the template;
- **The brief:** the audience and what they need;
- **The design process:** four to six numbered steps;
- **Why it suits the use case:** three or four bold claims, each with
  its reason;
- **Lessons it puts into practice:** links to the concept pages.

**The prompt.** Written in the reader's voice, in plain text, and
self-contained (it must work pasted into a project that has never seen
this one). It has, in order:

1. what to rebuild, in one sentence;
2. the template's live address,
   `https://templateinterface.com/templates/<id>/`, with an instruction
   to open it and read it through in detail before writing code: the
   rendered page and its `index.html`, `styles.css` and `script.js`,
   analysing section order, grid and breakpoints, components, spacing
   and type, states and script behaviour, and summarising the findings
   first. The live template is the source of truth for layout and
   interface but never for branding, and if it cannot be loaded the
   model says so and works from the written description. The address
   resolves once the site goes live (section 13.8); until then the
   fallback applies;
3. the branding rule (point 4 above): read the existing site's styles
   first, list its brand colours and fonts, map them onto the layout's
   roles (background, surface, text, muted text, accent, accent hover,
   border, success, error), derive any missing role from the brand
   rather than the template, adjust shade not hue to meet WCAG AA, and
   use the template's palette only if the site has no branding;
4. the page structure, section by section, with breakpoints where they
   matter;
5. the design direction, labelled as applying only without existing
   branding;
6. the behaviour of each interactive part;
7. the shared build rules: plain HTML, CSS and JS unless the project
   already uses something else, mobile first from 320px, semantic
   landmarks and labels, designed states, reduced motion, visible demo
   notices on forms without a backend, the reader's real content or
   clearly marked placeholders, and a closing check at 375px and 1440px.

**How it is built.** Two shared files, `assets/css/design-notes.css` and
`assets/js/design-notes.js`, linked by every template, so each template
keeps exactly five files (section 13.3). The panel uses only
`theme.css` tokens and `dn-` classes, names no product (so the M16
rename does not touch it), and contains no em dashes or inline styles
(section 6 and 17). The panel is recorded like any other region: in the
README's region outline and shared dependencies, in `templates/INDEX.md`
and in the `templates-index.js` record. Each README's Recreating section
tells the reader to delete the panel when copying the template.

**Rollout.**

1. Pilot on five templates of different kinds (a local business, a
   product launch, an internal tool, a portfolio, a charity). Done in
   v0.13.0.
2. The maintainer reviews the pilot pages and prompts, including by
   pasting a prompt into Claude Code against a site with existing
   branding.
3. Apply to the remaining sixteen gradually, over many sessions, a few
   templates at a time, so each set of notes gets the same care and
   each session stays small. Each batch is verified with the checks
   below, recorded in PATCHNOTES, and added to the list in
   `templates/INDEX.md`. Suggested order, varied by kind:
   `blog-article`, `ecommerce-product`, `event-site`;
   `documentation-site`, `pricing-page`, `small-business`;
   `careers-page`, `course-landing`, `help-center`; `community-forum`,
   `ecommerce-storefront`, `onboarding-flow`; `real-estate-listing`,
   `resume-site`, `waitlist-signup`, `wiki-portal`. Multi-page
   templates (`blog-article`) get the panel on `index.html` only.
4. When all 21 have it, remove the "being rolled out" notes from
   `templates/INDEX.md` and `TEMPLATE_CONTRACT.md` and mark M17
   complete.

**Acceptance criteria.**

- All 21 templates end with the panel, with every part listed above.
- Every prompt begins its rules with the branding rule.
- The prompt is closed on load; Copy prompt reports success in the
  status line when clicked in Chrome or Edge, including under `file://`.
- On every template: no console errors, no horizontal overflow at 320px
  and 375px, and every text pairing in the panel at 4.5:1 or better.
- The panel looks the same on every template (no template rule leaks
  into it).
- Every README, `templates/INDEX.md` and `templates-index.js` record the
  panel, and the section 13.6 checks still pass.

### 13.10 Dark and light mode on every template (milestone M18)

*Status.* Done in v0.15.0. Agreed with the maintainer on 2026-10-01;
the shared script and the pilot template (`restaurant-site`) shipped in
v0.13.4, and the other twenty followed in v0.15.0 in four batches. The
four dark-by-design templates (`admin-dashboard`, `event-site`,
`pricing-page`, `wiki-portal`) gained a light palette and still open
dark.

**What.** Every template gets a dark and light mode toggle: a single
button showing a sun emoji or a moon emoji. Every template opens in dark
mode by default.

**The button.**

- One `button` in each template's header, at the right end of the header
  row, inside the header's own layout so it never overlaps the
  navigation or the menu button at any width from 320px up.
- It shows the mode it switches to: a sun (U+2600 U+FE0F) while the page
  is dark, a moon (U+1F319) while it is light. The emoji is
  `aria-hidden="true"`; the button's accessible name says the action
  ("Switch to light mode" or "Switch to dark mode"). It has no
  `aria-pressed`: a toggle whose label changes must not also report a
  pressed state, or screen readers announce a contradiction.
- The markup is `<button class="xx-theme-btn theme-toggle" type="button"
  aria-label="Switch to light mode"><span class="theme-toggle-icon"
  aria-hidden="true">&#x2600;&#xFE0F;</span></button>`; the shared script
  finds every `.theme-toggle` and keeps its icon and label in step.
- At least 44px square, with the template's own focus ring and hover
  state. No other icon set or image.

**How it works.**

- The mode is a `data-theme="dark"` or `data-theme="light"` attribute on
  the `html` element. Dark is the default, so a page with no stored
  choice, or with storage blocked, is dark.
- The choice is remembered in `localStorage` under the key
  `template-theme`, shared by every template, so a
  visitor's choice follows them across templates. Every read and write
  is wrapped in try/catch, and the page works without storage.
- A small shared script, `assets/js/theme-toggle.js`, loaded in the
  `head` before the stylesheets apply, sets the attribute before first
  paint so the page never flashes the wrong mode. The same file binds
  the button. Each template keeps its five files (section 13.3).
- It does not follow `prefers-color-scheme`: the maintainer chose dark
  as the default for everyone.

**The palettes.** This is most of the work. Most templates were designed
light (a paper or white ground), and each declares its own prefixed
tokens (`--am-*`, `--nl-*` and so on). For each template:

- The current palette becomes the light mode, unchanged.
- Raw colours in rules that change between modes (form fields, badges,
  the surfaces of light sections, the select arrow) first become
  prefixed role tokens with their current values, so the dark block can
  redefine them. Text that sits on a fill which does not change (a red
  button, a green band) gets its own token that stays light, rather than
  borrowing the paper colour. Drawn illustrations keep their colours.
- Header items must still fit one row from 320px with the button added.
  `restaurant-site` shortens its header "Book a table" to "Book" below
  420px (the rest stays for screen readers) to make room.
- A dark palette is designed for it under
  `:root[data-theme="dark"] .xx-page` (or the template's equivalent),
  redefining only that template's prefixed tokens. It keeps the
  template's identity in dark form (the same accent hue, the same type,
  the same character) rather than becoming a generic dark grey. No
  `theme.css` token is redefined (section 9).
- Every text, control and focus pairing meets WCAG AA in both modes;
  charts, maps, drawn illustrations and status colours are checked in
  both, since many are drawn in CSS or SVG with fixed colours.
- Templates that are already dark (`admin-dashboard`, `event-site`,
  `pricing-page`, `wiki-portal`) get a light palette instead, under
  `:root[data-theme="light"]`, and dark stays their default. Accent
  colours used as text get their own `--xx-*-text` tokens so one mode
  can deepen or lighten them while fills keep the brand colour.
- `resume-site`'s print stylesheet always prints light.
- The design notes panel (section 13.9) stays on the site's own dark
  theme in both modes.

**Effect on other milestones.** M17's Claude Code prompts gain one line
for templates that have the toggle: build the same toggle, deriving both
modes from the site's own branding, dark by default. M15's redesign of
the site's own pages is unaffected; those pages stay dark only.

**Rollout.** Like M17, a few templates per session, each batch verified
and recorded in PATCHNOTES. Step one, the shared script with
`restaurant-site` as the pilot, is done (v0.13.4). The rest follow the
pilot's pattern, light templates first, in the same order as M17's
rollout, with `admin-dashboard` (dark already, gaining a light palette)
last.

**Acceptance criteria.**

- All 21 templates have the toggle in the header, showing a sun when
  dark and a moon when light, and open in dark mode on first visit.
- The choice persists across reloads and templates, and the page still
  works, in dark mode, with storage blocked.
- No flash of the wrong mode on load.
- In both modes, on every template: no console errors, no horizontal
  overflow at the section 8.1 widths, and every text pairing at 4.5:1
  or better (3:1 for large text and focus rings).
- The button is reachable by keyboard, shows the template's focus ring,
  and has an accessible name that states the action.
- Each template's README, `templates/INDEX.md` and `templates-index.js`
  record the shared script and the two palettes.

### 13.11 One site bar on every page (no milestone)

*Status.* Done in v0.19.0, at the maintainer's request on 2026-10-04
("one main navigation bar interface similar to azqato.github.io").
Replaces the v0.14.0 return bar and the separate headers of the root
page and the showcase.

Every page (the root, the showcase, the Color Standard, all 23
Education pages, all 21
templates and `blog-article/article.html`) opens with the same bar,
`nav.site-nav` labelled "Site": the favicon and "Template Interface",
linking home, then Home, Education, Templates and Standards, all aligned left
(v0.19.1). The page's
section is teal (`aria-current="page"` on a section's front page,
`.is-section` inside it). Under 640px the links fold behind a menu
button (`site-nav.js`; Escape or a link closes it); without the script
they stay visible and wrap. On site pages it sticks to the top, blurred,
and the Education rail, top bar and "On this page" column sit below it
(`--site-nav-h`, 56px); the rail no longer repeats the site name. On
template pages it scrolls away (`.site-nav--static`), so sticky template
headers keep the top of the screen.

`tools/build-site-nav.py` stamps it between `<!-- site-nav -->` comments
as the first element in `body` (after `wiki-portal`'s skip link, decision
D6) and links `assets/css/site-nav.css` and `assets/js/site-nav.js`;
re-running changes nothing. At its right edge sits a light and dark
switch (M23, section 13.14) that shares the templates' stored choice;
on phones it sits just left of the menu button. The styles read `theme.css` tokens only and
double every class, so templates cannot restyle it, and it is hidden in
print. It belongs to the site, not the template: a README's Recreating
section says to remove it when copying. Any new page gets it by running
the script.

### 13.12 Template Interface Color Standard (no milestone)

*Status.* Version 1.0 published in v0.21.0, at the maintainer's request
on 2026-10-04: "create that standard together that we should direct
everyone to follow ... with a focus on google chrome and github
initially". Decisions: its own top-level section (Standards, in the site
bar), a graded palette of this site's own, ten hues, named "Template
Interface Color Standard".

`standards/color/index.html` publishes, in order: six rules (WCAG 2.2
1.4.3, 1.4.11 and 1.4.1, roles over raw colors, light and dark together,
one accent); the grade system (0 white to 100 black, luminance
`1.05 * 21^(-g/100) - 0.05`, so a 40 grade gap is at least 3:1, 50 is
4.5:1 and 70 is 7:1, checked across every pair); the palette (gray,
blue, teal, green, yellow, orange, red, pink, purple, brown, each at
grades 5, 10, 20 to 90, and 95, generated in OKLCH); fifteen roles with
light and dark values and live specimens; the 42 required pairings,
measured; a side by side with GitHub Primer (`@primer/primitives`
11.10.0) and Google Chrome's default theme (Chromium `ui/color`
`ref_color_mixer.cc` and `sys_color_mixer.cc`); a brand color fitter;
usage; a checklist; sources and version.

Downloads: `tokens.css` (`--ti-<hue>-<grade>` primitives,
`--ti-color-<role>` roles, dark under `prefers-color-scheme` or
`data-theme`) and `tokens.json` (W3C design tokens format). Generator:
`tools/color-standard/build.py` (palette.py builds and asserts the
guarantees; sources.json holds the reference colors), then
`tools/build-site-nav.py`. The site's own theme is not changed by this
release; adopting the standard on the site is a separate decision.

### 13.13 Following the Color Standard everywhere (milestone M22)

*Status.* Requirement set 2026-10-04 at the maintainer's request ("update
documentation ... that the site should follow the standard, including
everything in the templates"). Done in v0.22.0 (2026-10-05): every site
page and all 21 templates follow the standard in both modes.

**What "follows the standard" means.** The standard is the published
page, `standards/color/index.html`, version 1.0, and its tokens in
`standards/color/tokens.css`. A page follows it when all of these hold:

1. **Rules 1 to 3 hold everywhere.** Text is 4.5:1 or more on every
   background it sits on (3:1 for large text); control borders, icons that
   carry meaning and focus rings are 3:1 or more against what is next to
   them; no state or status is shown by color alone.
2. **Colors come from roles.** Site pages use the `--ti-color-*` roles
   (or site tokens that are defined from them), not raw hex values.
   Templates keep their own prefixed tokens (`--xx-*`) so each brand
   stays distinct, but every prefixed token is assigned to one standard
   role (canvas, surface, text, muted text, border, strong border, accent,
   accent fill, on accent, accent tint, success, warning, danger, info,
   focus) and documented as such.
3. **Both modes pass.** Every template already has dark and light mode
   (section 13.10); both meet the 42 required pairings on the standard's
   page. Site pages gain a light mode that follows the visitor's setting,
   with the standard's role values, and keep dark as the look they open
   in when the setting is dark.
4. **Brand colors are fitted, not forced.** A template's or the site's
   brand color may stay as it is where it passes. Where it does not, the
   standard's brand fitter gives the same hue at grade 60 (light) and 40
   (dark), which is used instead.
5. **Status colors mean only status.** Green, yellow, red and teal (or a
   template's equivalents mapped to those roles) are not reused for
   decoration.

**Scope.** Every page the site bar reaches: the root, the showcase, the
23 Education pages including lesson demos, the Color Standard page
itself, and all 21 templates with `blog-article/article.html`. The
template previews drawn on the showcase and root page
(`template-previews.js`) follow their templates. `brand/` is a separate
identity deliverable and is out of scope, though its contrast table
already meets rule 1.

**Known gaps (measured 2026-10-04, site pages).** `--color-border-default`
(`#30363d`) is 1.55:1 on the canvas and 1.42:1 on the surface: fine for
decoration, but below 3:1 wherever it outlines a control (inputs, the
search button, filter chips). Site pages have no light mode. Site CSS
uses `--color-*` tokens that are not yet defined from the standard's
roles. The teal accent (`#00d4a0`, 9.85:1 on the canvas) passes as a
brand accent in dark; its light mode value must come from the fitter.
The 21 templates have not been audited against the standard yet.

**Done (v0.22.0, 2026-10-05).** M22 ran as eight checkpoints, each ticked
in `docs/reviews/m22-checkpoints.md`, committed and pushed, with testing
held to an audit at the start, one verification at the end and a final
review of every edit before the docs, at the maintainer's request.

- Site: `assets/css/theme.css` imports `standards/color/tokens.css` and
  defines every `--color-*` token from a role (DESIGN.md section 15). New
  tokens `--color-border-strong` (control outlines), `--color-on-accent`,
  `--color-info`, `--color-focus`, `--color-scrim`, `--color-shadow` and
  `--color-bar`. Site pages follow the visitor's light or dark setting;
  templates set it with their toggle. Teal stays `#00d4a0` in dark and is
  teal 60 in light. The site bar and design notes panel pin the site
  accent so a template cannot recolor them.
- Templates: input, select and search outlines in 16 templates now use
  their muted text token (3:1 or more); the pricing page no longer dims
  over-limit prices with opacity; the wiki portal's masthead turns light
  in light mode. Every README's Composition section lists its color roles.
- Lessons: the Visual Hierarchy demo changes the label's weight, not its
  opacity; the accessibility demo's photo placeholder was given a
  readable background.
- Verification: `tools/color-standard/audit.py`, 12,146 checks in both
  modes; the five remaining rows are deliberate samples or boundaries on
  gradients confirmed by screenshot (`docs/reviews/color-standard-audit.md`).
  The site bar check passes on every site page.

**How M22 is done.**
1. Audit: for every page, in both modes, list each color pairing in use
   and measure it (headless Edge, computed, as in section 25), and map
   every template token to a role. Record results in
   `docs/reviews/color-standard-audit.md`.
2. Site pages: define the site's tokens from `standards/color/tokens.css`
   (one mapping block, DESIGN.md section 15), add `border-strong` for
   control outlines, add light mode, fit the teal accent.
3. Templates: add a role map to each README's Composition section, fix
   every failing pairing in its own prefixed tokens, keep its identity.
4. Verify: every pairing measured again in both modes, screenshots of
   each page in both modes looked at, the site bar check and lesson
   checks rerun. A page is done only with zero failures.

**Acceptance criteria.** Zero failing pairings across the scope in both
modes; every template README names its role map; site CSS has no raw hex
values outside the one token mapping block; the template contract and
review prompt require the standard (done in v0.21.1).

**Going forward.** Any new page or template follows the standard from the
start (template contract, "Color"). A new version of the standard is
applied across the scope in the same release that publishes it.

### 13.14 Pre-launch pass (milestone M23)

*Status.* Approved by the maintainer on 2026-10-05, in answer to "anything
else on the roadmap before go live?": all five proposed items. Done
(v0.23.0, 2026-10-05); checkpoints in `docs/reviews/m23-checkpoints.md`.

1. **Check scripts in the repository.** The headless Edge checks (site
   bar, lesson and Color Standard checks, the color audit) move from a
   scratch folder to `tools/checks/`, with one runner, so anyone can rerun
   them. Closes the "no automated test suite" debt in section 38.
2. **A light and dark switch in the site bar,** aligned right, on every
   page. It shares its stored choice with the templates' own toggles, so
   one choice holds across the site. With no stored choice, site pages
   follow the visitor's setting and templates open dark, as before.
3. **Module 08, Data Visualization:** "Choosing the Right Chart" and
   "Color in Charts", from the anticipated modules in sections 8 and 22.
4. **Module 09, E-commerce UX:** "Product Pages" and "Cart and Checkout".
5. **Search index rebuilt** with `tools/build-search-index.py` once the
   new lessons exist, and the **documentation audit rerun** (section 40)
   last, so it checks the finished state.

### 13.15 Template coverage by business concept (milestone M24)

*Status.* Requested by the maintainer on 2026-10-05. Done (v0.24.0,
2026-10-05): 43 new templates, so all 100 concepts now have a template
scoring 9.0 or higher and the library holds 64. Checkpoints are in
`docs/reviews/m24-checkpoints.md`; the temporary scoring file has been
removed and its results are recorded below.

1. **Brainstorm 100 business concepts** in a temporary markdown file,
   covering as many industries and business models as possible (retail,
   services, software, hospitality, health, nonprofit, creative,
   industrial, subscription, marketplace and so on).
2. **Score the fit.** For each concept, name the best existing template
   and rate how well it fits on a scale of 1 to 10, honestly and
   directly, with a one-line reason.
3. **Fill the gaps.** Every concept with no template scoring 9.0 or
   higher gets a new template. Where one new template would score 9.0 or
   higher for several concepts, only that one is built (maintainer,
   2026-10-05), following
   the template contract and the Color Standard like every other template.
4. **Close out.** Registries, search index and documentation updated; the
   temporary file is removed once its results are recorded here.

*How the scores were set.* 10: the template could be reskinned for the
business with no structural change. 9: one small section is missing. 7
to 8: the skeleton fits but a core task of the business is absent. 5 to
6: a borrowed layout that would need its main section rebuilt. Below 5:
the business needs something no template had.

*Result.* 22 of the 100 concepts already scored 9.0 or higher, each with
the template written for it (for example emergency plumber and
electrician with `small-business` at 9.6 and 9.4, trattoria with
`restaurant-site` at 9.6, personal tech blog with `blog-article` at 9.2).
The 78 gaps clustered in appointments, memberships and subscriptions,
media, and calculator or date based bookings. Grouping concepts that
share a core task, only where the shared template still scores 9.0 or
higher for every member, turned 78 gaps into 43 templates:

| New template | Serves (concept, score) |
|---|---|
| `appointment-booking` | Salon 9.5, personal trainer 9.0, therapist 9.0, tutor 9.0, driving school 9.0, dog walker 9.5, cleaning company 9.0, car repair 9.0 |
| `clinic-practice` | Dental 9.5, vet 9.5, telehealth 9.0 |
| `class-studio` | Gym 9.5, yoga studio 9.5 |
| `subscription-box` | Meal kit 9.5, pet food autoship 9.0, veg box 9.0 |
| `stays-booking` | Boutique hotel 9.5, holiday cottage 9.5 |
| `timed-tickets` | Cinema 9.5, escape room 9.0, theatre 9.0, museum 9.0 |
| `spaces-to-hire` | Coworking 9.0, wedding venue 9.0 |
| `news-front-page` | Local newspaper 9.5 |
| `creator-subscription` | Podcast 9.0, paid newsletter 9.0 |
| `band-artist` | Band 9.5 |
| `app-launch` | Indie game 9.5, mobile game 9.5, consumer app 9.0 |
| `professional-firm` | Law 9.5, accountancy 9.0, consultancy 9.5, financial adviser 9.0 |
| `quote-calculator` | Mortgage broker 9.5, insurance broker 9.0, solar installer 9.0 |
| `project-gallery` | Construction 9.5, landscaper 9.5 |
| `creative-packages` | Wedding photographer 9.5, event planner 9.0, tattoo studio 9.0 |
| `order-ahead` | Bakery 9.5, coffee shop 9.0, food truck 9.0 |
| `drinks-producer` | Taproom 9.0, winery 9.5 |
| `two-sided-marketplace` | Freelancer marketplace 9.0, course marketplace 9.0 |
| `school-site` | Primary school 9.5, nursery 9.0 |
| `programme-catalogue` | University department 9.0, language school 9.0 |
| `b2b-industrial` | Parts manufacturer 9.0, freight company 9.0 |
| `architecture-studio`, `item-rentals`, `vehicle-listings`, `supply-signup`, `crowdfunding-campaign`, `faith-community`, `political-campaign`, `animal-adoption`, `council-services`, `status-page`, `open-source-project`, `ai-tool`, `fintech-app`, `market-tracker`, `florist`, `bookshop`, `pharmacy`, `care-home`, `self-storage`, `car-wash-membership`, `sports-club`, `property-management` | One concept each (architecture studio, peer to peer rentals, car dealership, delivery app drivers, crowdfunding, church, political campaign, animal shelter, local council, status page, open source project, AI writing tool, neobank, stock tracker, florist, bookshop, pharmacy, care home, self storage, car wash, sports club, property management), each 9.5 |

Overlaps tested and rejected, because the shared template would score
below 9.0 for one side: hair salon with dental (insurers and forms), gym
with coworking (timetable against tours), car wash with class studio
(locations against classes), self storage with quote calculator (unit
sizes are the page, not a calculation), peer rentals with stays (items
against rooms), church with nonprofit (service times are the main task),
architecture with project gallery (editorial against trade tone).

*How they were built.* All 43 come from small spec files run through
a generator in `tools/m24/` (see its README), so they share one tested
skeleton: tokens only, dark and light palettes, the site bar, a
validating demo form and the design notes panel. Five were first built
by hand (`appointment-booking`, `clinic-practice`, `class-studio`,
`subscription-box`, `two-sided-marketplace`) and later ported to specs
(v0.24.1); change a template by editing its spec and rebuilding, not
the generated files. Every one was checked headless
for contrast in both modes, overflow at 375 and 1280px, console errors,
and a driven pass over every button, select and form.

### 13.16 Template Interface Web Design Standard (no milestone)

*Status.* Version 1.0 published 2026-11-22 (v0.25.0), at the
maintainer's request: add print to the page design review alongside
desktop and mobile, and "document this page design best practice method
... similar to how we have standards for colors".

`standards/web-design/index.html` publishes, in order: eight rules (three
surfaces, evidence not reading, no sideways scrolling from 320px, every
state designed, works for everyone, color follows the Color Standard,
honest controls, prints clean and complete); the surfaces and widths
(320, 375, 700, 900, 1023, 1150, 1440, 1920, and print on US Letter
fitting A4); the eight-step review method from
`docs/TEMPLATE_DESIGN_REVIEW_PROMPT.md` and DESIGN.md section 8; print
guidance (what to leave out, what to keep, rules of thumb, a starting
CSS block, and the `restaurant-site` before and after); the recurring
bug patterns from DESIGN.md section 8.2 plus six print patterns; the
headless commands and the traps that make a check lie; a checklist;
sources and version.

It is a hand-written page, not generated. It reuses the Color
Standard's `standard.css` and adds `web-design.css` (two-column lists and
the page's own print rules). Both standards link to each other through a
"Standards: Color · Web design" line; the site bar's Standards link still
opens the Color Standard. The page itself was checked by its own method:
no overflow at 1440, 768, 375 and 320px (one 320px overflow from an
unbreakable inline code path was found and fixed), no console errors, and
an 8-page Letter PDF with no split units.

**Print, first application.** `restaurant-site` had no print styles. It
printed 9 pages in dark mode with one of five menu courses (the rest sat
in hidden tab panels), a frozen "Open now" line and two full-page
illustrations. Its print block now prints every course under its own
heading, ink on white, without live state or controls, in 6 pages, each with a header whose center title names the section on that page and a "Page N of M" footer. The
shared design notes panel (`assets/css/design-notes.css`) is hidden in
print on every template; the rule needed the panel's doubled-class
selector (`.dn-notes.dn-notes`) to take effect.

**Gaps (2026-11-22).** 14 templates have no `@media print` block
(`admin-dashboard`, `careers-page`, `community-forum`, `course-landing`,
`ecommerce-product`, `ecommerce-storefront`, `event-site`, `help-center`,
`nonprofit-site`, `onboarding-flow`, `pricing-page`,
`real-estate-listing`, `waitlist-signup`, `wiki-portal`). Of the other
49 that have one, 43 are five lines or fewer (typically hiding the
header and toggle), only 2 set colours for print, and none has been
checked against section 4 of the standard. Site pages have no print
rules apart from hiding the site bar, so in dark mode they print light
text. Milestone M26 covers all of this.

---

## 14. Roadmap

**Current phase.** Both phases are built and verified. Phase 1
(Education): the design system, the navigation shell, the curriculum
research record, and all 14 concept pages with their markdown mirrors
exist. Phase 2 (Templates): all five starter templates exist, the
registry and showcase page render them, and every concept page links to
the templates that demonstrate it. *(Discrepancy, 2026-10-04: 21
templates exist, not five, and M8 to M19 are complete; see section
36.)* The live browser and
responsive-breakpoint verification pass (M4 and M7) that this session
could not run directly was confirmed working by the maintainer in an
actual browser. Both phases are complete as of this version.

### Milestone table

| Milestone | Description | Status |
|---|---|---|
| M0 | Documentation scaffold: README, PRD, DESIGN, PATCHNOTES | Complete |
| M1 | Design system implementation: `theme.css`, `base.css`, `components.css` | Complete |
| M2 | Education navigation shell: `nav-data.js`, `nav.js`, module index pages | Complete |
| M2.9 | Curriculum research and validation pass against UI/UX educational literature | Complete |
| M3 | All Module 01 to 07 concept pages, markdown mirrors, `concepts-index.js` | Complete |
| M4 | Phase 1 acceptance criteria verification pass, including responsive and writing style audits | Complete |
| M5 | Five starter templates built | Complete |
| M6 | `templates-registry.js` and the templates showcase page | Complete |
| M7 | Phase 2 acceptance criteria verification pass | Complete |
| M8 | Theme revisitation using the site's own completed lessons | Complete |
| M10 | Presentation and marketing redesign, full scope: Education, Templates, and root (DESIGN.md section 11) | Complete |
| M9 | Template library expansion, 5 to 20 templates (section 13.5) | Complete; all 15 verified in a browser, one defect found and fixed (`admin-dashboard`, see PATCHNOTES v0.11.1) |
| M11 | `wiki-portal`, the twenty-first template, and defect D1 below | Complete; verified in a browser at seven widths, D1 confirmed fixed, one further defect found and fixed (see PATCHNOTES v0.11.1) |
| M12 | Template composition and recreation contract (section 13.6): the two indexes, the README contract, and the two new sections across all 21 template READMEs | Complete; all five acceptance criteria in section 13.6 verified by script |
| M13 | Browser verification of the whole project: console, interaction, and responsive overflow | Complete; 46 pages swept, defects D2 to D5 found and fixed (PATCHNOTES v0.11.1 to v0.11.3) |
| M14 | Template design review against `docs/TEMPLATE_DESIGN_REVIEW_PROMPT.md`: every template taken to a shippable, fully fleshed out site with its own identity | Complete; 20 templates rebuilt, `wiki-portal` fixed in place, all 21 verified by screenshot, automated audit and driven interaction (PATCHNOTES v0.12.0; evidence in `docs/reviews/template-design-review-findings.md`). D6 below is decided: keep |
| M15 | Site interface redesign (section 13.7): the showcase, the root page and Education rebuilt on patterns from `ecommerce-storefront`, `landing-page` and `documentation-site`, staying dark | Done in v0.17.0 (2026-10-04) |
| M16 | Rename to Template Interface (section 13.8): every visible use of the name, keeping internal script identifiers and dated history | Done in v0.15.0; visible rename in v0.14.0, going-live wording in v0.15.0 |
| M17 | Template design notes (section 13.9): a panel on every template explaining its brief, process and fit, with a brand-preserving Claude Code prompt; a standing rule for new templates | Done: pilot on 5 templates in v0.13.0, the other 16 in v0.15.0 |
| M18 | Dark and light mode on every template (section 13.10): a sun or moon emoji toggle button, dark by default, with a dark palette designed for each template | Done: pilot in v0.13.4, the other 20 templates in v0.15.0 |
| M19 | Documentation audit: run the Documentation Prompt (`docs/TODO.md` item 1) against this project | Complete (v0.16.0, 2026-10-04): sections 23 to 40 |
| M22 | Follow the Color Standard everywhere (section 13.13): every site page and all 21 templates, both modes | Done (v0.22.0, 2026-10-05) |
| M23 | Pre-launch pass (section 13.14): check scripts in the repository, site bar light and dark switch, Modules 08 and 09, search index rebuild, documentation audit rerun | Done (v0.23.0, 2026-10-05) |
| M24 | Template coverage by business concept (section 13.15): 100 business concepts scored against the best template, 43 new templates so every concept has one scoring 9.0 or higher | Done (v0.24.0, 2026-10-05); 64 templates |
| M25 | Page metadata and sharing tags: bring every page in line with sections 31 and 41 (add `og:site_name`, meta descriptions of 150 to 160 characters, one validated JSON-LD block per page, and the `text/markdown` alternate link where a plain-text source exists), with check scripts in `tools/checks/` | Planned (added 2026-10-22); before M20 |
| M26 | Print on every page (section 13.16): bring all 64 templates and the site pages up to section 4 of the Web Design Standard (14 templates have no print styles, 43 more have five lines or fewer, site pages print light text in dark mode), and add a print-to-PDF check to `tools/checks/` | Planned (added 2026-11-22); before M20 |
| M20 | Go live: GitHub Pages (or another static host) serving `main`, with `templateinterface.com` as the custom domain. Right before release, rewrite the offline and not-hosted wording listed in section 36 | Deferred by the maintainer (2026-10-04); the stopping point, last in the order below |
| M21 | Brand Identity prompt: add a `/brand/index.html` showcase page (`docs/TODO.md` item 2). Work happens in the prompts project, not here. Decided 2026-10-04: `brand/index.html` is a separate, committed front page that links to `presentation.html`; it is a 16:9 consulting slide deck with a switch to a scrolling report; the updated prompt is tested by running it on Template Interface | Done in v0.18.0: prompt updated (prompts v1.110.0) and run on this site; results in `brand/` and the Brand Identity sections |

The table above is listed in recommended execution order below M7, not
strict ID order: M10 comes before M9 even though its number is higher.
This is intentional, not a mistake; the reasoning is immediately below.

### Recommended order of the remaining work (set 2026-10-04)

Everything up to M18 is done. What remains runs in this order, which
again differs from ID order:

1. **M19, documentation audit.** Run the Documentation Prompt
   (https://azqato.github.io/prompts/p/documentation.html) on this
   project. It goes first because it is cheap and it sets the rules
   every later milestone is documented under: it checks README, PRD,
   DESIGN and PATCHNOTES against the code, keeps `docs/TODO.md` as the
   ideas list, and adds what a public site needs and this project lacks
   (`LICENSE.md`, `robots.txt`, `sitemap.xml`). It also leaves a
   verification checklist that M15's checks can work through.
2. **D6, the `wiki-portal` skip link.** Decided 2026-10-04: kept. A decision, not a build: keep it
   and allow it in the review brief, or remove it and its README line.
   It is settled before M15 because M15 re-runs the template checks on
   all 21 templates. The recommendation is to keep it, since a page with
   112 tab stops before its content is the case a skip link exists for.
3. **M15, site interface.** Done in v0.17.0. The largest piece of remaining work. It
   comes before going live so the public site opens with the redesigned
   showcase, root page and Education rather than being redesigned after
   people have seen it.
4. **M21, Brand Identity prompt.** Done in v0.18.0. Lives in the prompts project and does
   not touch this site. Placed before going live at the maintainer's
   request (2026-10-04), so it is finished before launch.
5. **M22, follow the Color Standard everywhere.** Done in v0.22.0
   (section 13.13). Confirmed before M20 by the maintainer
   (2026-10-04): go-live is deferred; it is the stopping point, and as
   much development as possible is done first.
6. **M23, pre-launch pass.** Done (v0.23.0, section 13.14).
7. **M24, template coverage by business concept.** Done (v0.24.0,
   section 13.15): 43 new templates, 64 in all.
8. **M20, go live.** Deploy `main` as static files and point
   `templateinterface.com` at it. Last because it publishes the result
   of everything above; the code already needs no change to be served.
   Registering the domain and adding its DNS records are the
   maintainer's steps.

### Open defects

**D1. `wiki-portal`: the masthead artwork breaks at the rail boundary.**

*Symptom.* Where the navigation rail meets the content column, the
decorative masthead does not read as one continuous band. Two things are
visible at that boundary: a light vertical scrollbar track running the
full height of the rail, and a colour mismatch between the artwork inside
the rail and the artwork to its right. The reference layouts this
template draws on show one unbroken band from the logo across the whole
header.

*Cause.* Three independent causes, all of which have to be removed:

1. The rail is its own scroll container (`position: fixed` plus
   `overflow-y: auto` in `templates/wiki-portal/styles.css`). Its content
   is taller than the viewport, so Chrome renders a classic scrollbar
   inside the rail's 168px. On Windows that scrollbar takes layout width
   rather than overlaying, so it both narrows the rail's content box and
   paints a light track exactly where the artwork should be continuous.
   `scrollbar-width: thin` styles that track; it does not stop it from
   occupying space.
2. The artwork is painted twice, into two boxes of very different widths:
   `.wiki-rail::before` (168px) and `.wiki-masthead` (the full content
   column). The gradient uses percentage positions and sizes, and
   percentages resolve against each element's own box, so the same
   declaration produces different colours in each. The two halves cannot
   line up at the seam no matter how the scrollbar is handled.
3. The rail's copy of the artwork lives *inside* the rail's scrolling
   box, so it slides upward as soon as the rail is scrolled, while the
   column's copy stays put.

*Solution.* Move to a single-scroll layout, which removes all three
causes at once rather than patching each:

- `.wiki-layout` becomes a two-track grid
  (`var(--wiki-rail-width) minmax(0, 1fr)`), and the rail becomes a
  normal static grid item: no `position: fixed`, no `overflow-y`, no
  scroll container, therefore no scrollbar and nothing to drift.
- The artwork becomes one element spanning both tracks, painted once, so
  the gradient resolves against a single box and is continuous by
  construction.
- The rail's own background stays, but its top section becomes
  transparent so the single band shows through.

*Cost, and why it is still the right fix.* The rail stops being pinned:
it scrolls away with the page instead of staying in view. That matches
the reference behaviour, and it is consistent with the header chrome,
which already scrolls away. It does mean two changes beyond the CSS: the
narrow-width drawer in `script.js` needs the rail to become
`position: fixed` only under the existing 760px media query, and the
template's README and its
`navigation-and-information-architecture` note both currently describe
the rail as persistent chrome and must be reworded.

*Status.* Fixed. The single-scroll option was chosen by the maintainer and
implemented: `.wiki-layout` is now a two-track grid, the rail is a static
grid column whose background is transparent for exactly
`--wiki-masthead-height`, and `.wiki-masthead` is one absolutely
positioned element spanning both tracks. The rail is `position: fixed`
with a scroll of its own in one place only, the drawer under the 760px
media query, where it sits over the content and so has no seam to break.
The template's README and its `layout-and-grid-systems` note were
reworded, since the rail is no longer persistent chrome. Live browser
confirmation of the result is still outstanding, the same category of gap
noted against M9.

**D6. `wiki-portal`: a skip link the review brief says not to add.**

*Symptom.* `wiki-portal` has a "Skip to main content" link
(`.wiki-skip`), and its README lists it under
`accessibility-and-wcag-basics`. The template design review brief says
templates must not add skip links, and none of the other 20 has one.

*Status.* Decided 2026-10-04: keep it. The maintainer chose to keep the
link, and the review brief now allows it in `wiki-portal` only.

*Earlier status.* Open, awaiting a decision. The link predates the brief and
works, so the review left it alone rather than remove an accessibility
feature on its own authority. Either the brief should allow it here
(a directory page with 112 tab stops, whose navigation rail comes
before the content, is the case a skip link exists for), or the link and the README line come out
together.

### Recommended build order: M8, then M10, then M9

The milestone IDs no longer run in numeric order once M10's scope grew to
cover the whole site. M8 and M10 are both complete as of this version,
executed in this order for the reasons below; M9 remains the one planned
item left, and the same reasoning still applies to it.

1. **M8 first (complete).** The token revisit is the narrowest,
   fastest-to-verify change (`:root` values only, no markup), and it
   directly informed M10: there was no point designing a professional,
   marketable site on top of theme values that were about to change. The
   audit found and fixed one real contrast failure before M10 started;
   see DESIGN.md section 10.1.
2. **M10 second (complete).** With finalized tokens in hand, the full
   redesign, root, both section overviews, and motion applied across all
   14 concept pages and the template library, happened once. Because M10
   included the template library's own presentation, doing it before M9
   means the eventual 20-template library will be built directly into
   the already-redesigned system rather than built in the old look and
   redesigned again later. See DESIGN.md section 11 for the full record
   of what changed.
3. **M9 third (built).** The 15 new templates were built directly inside
   the redesigned system from M10, the same reasoning that put M2.9
   (curriculum research) before M3 (writing concept pages): finalize the
   foundation before producing volume on top of it. Live browser
   verification of the new templates is the one item still open; see
   section 13.5's acceptance criteria.

### Feature breakdown per milestone

- **M1**: every design token in DESIGN.md section 2 implemented exactly in
  `theme.css`, plus `base.css` (resets, base typography, shared focus
  ring) and `components.css` (sidebar, nav toggle, code block,
  callout, button, table), scoped to what M1 and M2 actually need; the
  card, demo container, and interactive control specs were added to
  `components.css` in M3, when the concept pages first needed them; the
  template showcase card spec remains unimplemented until Phase 2 needs
  it.
- **M2**: `nav-data.js` holds the full 7-module, 14-concept structure from
  section 12.1 as plain data; `nav.js` renders it into any page's
  `#sidebar-nav` container, reading two page-level globals each page sets
  before loading it, `WIREFRAME_BASE_PATH` (the relative path back to the
  project root) and `WIREFRAME_CURRENT_PAGE` (that page's root-relative
  path, used to mark the active link and auto-expand its module group).
  The root `index.html`, the Education overview, and all seven module
  overview pages are built on this shell and `wiki-layout.css`. Every
  concept link in the sidebar and in each module's concept table correctly
  points to `{slug}.html`, per the naming contract in section 12.3, even
  though none of those files exist until M3; this is expected, not a bug.
- **M2.9**: before any concept page is written, the curriculum in section
  12.1 and 12.2 is checked against established UI/UX educational sources
  rather than relying on the maintainer's judgment alone. Deliverable is a
  research and validation record, added to this PRD as section 12.5, that
  for each of the 14 concepts either confirms the concept's current
  definition, difficulty placement, and prerequisite chain against at least
  one credible external source, or revises it and records why. It also
  checks for any concept the source material treats as foundational that
  the current curriculum is missing, and for any current concept that the
  source material would place at a different difficulty level or module
  than section 12.1 currently does. The source list for this pass is fixed
  in section 12.5.1 rather than left open-ended, so the research has a
  defined scope and a defined stopping point. This milestone exists
  because writing fourteen concept pages against an unvalidated curriculum
  risks propagating the exact "learn by imitation, not by principle"
  problem Template Interface exists to solve, this time from the maintainer's
  own untested assumptions rather than a copied template. Complete as of
  this version; see section 12.5.2 through 12.5.4 for the findings, the
  per-concept record, and the ongoing (never re-closed) research intake
  process this milestone established for anything reviewed after M2.9
  itself.
- **M3**: fourteen concept pages, fourteen markdown mirrors, one populated
  `concepts-index.js`, and `education/INDEX.md`. Complete as of this
  version. Each concept page implements the interactive demo described in
  section 12.2 in vanilla JavaScript (a slider, a toggle, a live WCAG
  contrast calculator, a step-through checklist, and similar), cites the
  named-citation requirements logged in section 12.5.2 (Nielsen's
  heuristics, Fitts's Law, the NN/G microcopy and animation sources) by
  name where relevant, and links to its related concepts using real
  cross-page anchors now that every concept file exists.
- **M4**: full pass of section 12.4's acceptance criteria, plus the writing
  style sweep (section 6) and the responsive QA methodology (DESIGN.md
  section 8). Static link, JS-reference, and writing-style checks were
  clean, and the maintainer confirmed the live browser and
  responsive-breakpoint behavior directly. Complete as of this version.
- **M5**: five templates built, each meeting the folder contract in
  section 13.3 and using theme.css, base.css, and components.css by
  relative link, plus its own styles.css and script.js. Complete as of
  this version. The Small Business template's contact form intentionally
  does not submit anywhere; it intercepts its own submit event and shows
  a visible non-functional-demo notice, per section 18.
- **M6**: `templates-registry.js` populated with all five manifests,
  `templates/index.html` renders one showcase card per registry entry
  with a CSS and inline SVG generated preview keyed by template id, and
  every education concept page's "Used In Templates" section now links
  to its real, demonstrating templates instead of the Phase 2 placeholder
  note. Complete as of this version.
- **M7**: same verification as M4, applied to the five templates; the
  maintainer confirmed everything works correctly in an actual browser.
  Complete as of this version.
- **M8**: token value changes only, driven by the completed
  `color-and-contrast`, `typography`, and `accessibility-and-wcag-basics`
  concepts; no markup changes, per DESIGN.md section 10. Complete as of
  this version: a computed WCAG contrast audit (not an eyeballed one)
  found and fixed one real failure, `--color-text-tertiary` scoring
  below 4.5:1 against two of the three backgrounds it is actually used
  on. Full record, including two reviewed-but-not-changed findings (body
  line height, border non-text contrast), is in DESIGN.md section 10.1.
- **M10**: a broader presentation and marketing redesign than M8's
  token-only scope, applying the curriculum Template Interface teaches to
  Template Interface itself. Complete as of this version: root `index.html`
  rebuilt as a real landing page with a two-step Education-to-Templates
  narrative; a shared motion utility (`assets/js/motion-utils.js`, the
  `.fade-in-up` component) applied site-wide, both section overviews, all
  14 concept pages, and 4 of the 5 templates (Documentation Site
  deliberately excluded, since it has no scroll-reveal content and
  motion without a reason is itself a named `common-design-mistake`);
  and one real stale-copy bug found and fixed by the self-audit pass
  (`education/index.html` had claimed concept pages were still being
  written, after M3 had already shipped all 14). Full record in
  DESIGN.md section 11, including what was deliberately left as ongoing
  maintenance rather than redone from scratch.
- **M9**: fifteen additional templates built, per the list and acceptance
  criteria in section 13.5, taking the library from 5 to 20 entries using
  the same additive folder and registry contract from section 13.3, with
  no existing file modified to add them. Built after M10 rather than
  after M7 as originally planned, once M10's scope grew to include the
  template library's own presentation, so the 15 new templates went
  directly into the redesigned system instead of needing to be
  redesigned again afterward. `templates-registry.js` now holds all 20
  manifests, the showcase page's preview system has a distinct layout for
  each new template id, and all 14 concept pages' "Used In Templates"
  sections were updated to link the new templates that demonstrate them.
  One real writing-style violation, an `&mdash;` in a testimonial
  attribution, was caught by the project's own audit and fixed before
  this version shipped. Live browser verification of the 15 new
  templates is the one item still open.
- **M15** (done in v0.17.0): the site interface redesign in section 13.7, in
  three parts and in this order. The showcase gets filters, search, sort,
  a quick view dialog and previews drawn in each template's own palette.
  The root page gets a split hero with live previews and figures derived
  from the registries. Education gets search, an "on this page" column
  and previous and next links, in one shared layout change. The site
  stays dark: one more surface step, teal only for actions, location and
  focus, and neutral tags. Because every template links the shared
  stylesheets, the M14 checks are re-run on all 21 templates, not only on
  the redesigned pages.
- **M16** (done in v0.15.0): the rename to Template Interface in
  section 13.8. Every page title, the header wordmark, visible copy, the
  docs and template text that name the project change; the `WIREFRAME_*`
  script identifiers and dated history stay. The same pass rewrites the
  project's offline, not-hosted framing for a public site, including
  section 4's non-goal. Starts once the maintainer has registered
  `templateinterface.com`.
- **M17** (done in v0.15.0): template design notes in section 13.9. Every
  template gets a "How this template was designed" panel (brief, design
  process, why it suits the use case, lessons, and a closed "Recreate it
  with Claude Code" prompt with a copy button). Every prompt keeps the
  target site's existing branding and changes only layout and interface.
  Piloted on five templates, then added to the other sixteen. The design
  philosophy in section 13.9 applies to every template added later.
- **M18** (done in v0.15.0): dark and light mode on every template, in section
  13.10. One header button showing a sun emoji when dark and a moon
  emoji when light; every template opens dark; the choice is remembered
  across templates. Each template's current palette becomes its light
  mode and gets a designed dark palette with the same identity, checked
  for contrast in both. Rolled out a few templates at a time.
- **M19** (done in v0.16.0): the documentation audit from `docs/TODO.md`
  item 1. Runs the Documentation Prompt on this project, adds the
  missing `LICENSE.md`, `robots.txt` and `sitemap.xml`, and records a
  verification checklist.
- **M20** (planned, last, after M21): go live. `main` served as static files
  at `templateinterface.com`, every page still working from disk.
- **M21** (done in v0.18.0): the Brand Identity prompt, `docs/TODO.md` item 2.
  The prompt gains a `/brand/index.html` page presenting everything it
  produced in the format of a major consulting presentation. Built in
  the prompts project.

### Explicitly deferred items

- Additional curriculum modules beyond Module 07 (for example, data
  visualization or e-commerce specific UX patterns): deferred because the
  brief's required concept list is fully covered by Modules 01 through 07,
  and adding scope before finishing the defined scope would violate Tenet
  1's spirit.
- Templates beyond the twenty built in section 13.5 (M9): all twenty are
  now complete and registered; anything past twenty is genuinely
  deferred, with no scheduled milestone yet.
- Any build tooling, even purely local (a script that regenerates
  `INDEX.md` from `concepts-index.js`): deferred indefinitely unless it can
  be run optionally and never becomes required to open or use the site.


**D2 to D5. Horizontal overflow at narrow widths, four pages.** Found by
the first automated overflow sweep, all in the Education section, none
visible above 1024px except D2.

- **D2, `responsive-and-mobile-first-thinking.html`.** Overflowed at
  1024px, 768px, 414px, and 320px; at 414px it laid 590px of content into
  a 399px viewport. The page teaching mobile-first was the only page in
  the project that failed at every width below desktop.
- **D3, `templates/index.html` at 320px.** `.portfolio-grid` used
  `repeat(auto-fill, minmax(320px, 1fr))`. A bare 320px track floor cannot
  go below 320px, so on a 320px screen the grid was wider than the screen.
- **D4, `education/index.html` at 320px.** A table inside `.table-wrap`
  exceeded the viewport.
- **D5, `visual-hierarchy.html` and `interaction-states-and-feedback.html`
  at 320px.** Marginal, roughly 7px, from `.demo-container` padding.

*Cause.* Two root causes, not four. D2, D4, and D5 were all one bug:
`.content` is a flex item in the wiki layout and had no `min-width: 0`, so
its automatic minimum size was its content-based minimum. It therefore
refused to shrink below the widest thing inside it, and `.demo-stage` and
`.table-wrap` pushed the entire page sideways despite both already
declaring `overflow-x: auto` for precisely this case. D3 was independent:
a grid track floor that cannot collapse.

*Solution.* `min-width: 0` on `.content`, and
`minmax(min(320px, 100%), 1fr)` on `.portfolio-grid`.

*Status.* Fixed in v0.11.3. Verified by re-running the sweep across all 46
pages at both the five widths that found the defects and the seven widths
DESIGN.md section 8.1 documents: 0 overflow cases in 322 page-width
combinations. The two elements that should scroll internally now do:
`.table-wrap` reports a 333px scroll width inside a 257px box.

*Note.* DESIGN.md section 8.2 already described the flex `min-width: auto`
failure mode, with the correct fix, before any of this was written. The
methodology was right and the bug shipped anyway, because nothing measured
it. That is the argument for section 16's sweeps existing at all.

### Verification checklist

Each PRD and DESIGN section that describes code, and when it was last
checked against the files. "Not yet verified" means nobody has compared
it to the code since it was written.

| Section | Status |
|---|---|
| PRD 12 (Education contract) | Verified 2026-09-22 (v0.12.0 sweep) |
| PRD 13.6 (Templates contract) | Verified 2026-10-02 (v0.15.0) |
| PRD 13.9 (design notes) | Verified 2026-10-02 |
| PRD 13.10 (dark and light mode) | Verified 2026-10-04 against `theme-toggle.js` |
| PRD 13.11 (site bar) | Verified 2026-10-04 against `site-nav.css`: all 46 pages at 1280 and 375px |
| PRD 13.7 (site interface) | Verified 2026-10-04 (v0.17.0 sweep and driven checks) |
| PRD 16 (Runbook) | Verified 2026-10-02: the headless Edge sweep ran for v0.15.0 |
| PRD 17 (Technical requirements) | Checked 2026-10-04: the asset list differs (section 36) |
| PRD 18 (Security) | Not yet verified |
| PRD 23 (repository reference) | Verified 2026-10-04 for the top level only |
| DESIGN 2 and 3 (tokens) | Verified 2026-10-04: one stale value in section 3, fixed |
| DESIGN 4.11 (design notes panel) | Verified 2026-10-02 |
| DESIGN 8 (responsive QA) | Verified 2026-10-02 |
| DESIGN 13 (toggle and return bar) | Verified 2026-10-04 |
| DESIGN 12 and 14 (site interface) | Verified 2026-10-04 (v0.17.0) |
| PRD 41 (page metadata) | Not yet verified |
| DESIGN 17 (animation and motion) | Not yet verified |

### Future updates

Entries derived from `docs/TODO.md`. Both current items are already on
the roadmap: item 1 as M19 (done by this audit) and item 2 as M21, and
the maintainer emptied the file on 2026-10-04. New
ideas from that file are added here only after the maintainer agrees to
them (section 39).

## 15. Metrics

Template Interface is a free, non-commercial public site with no analytics
and no network requests of its own, so most conventional product metrics (acquisition
funnels, retention cohorts, growth rate) do not apply and are not tracked.
The metrics below are the honest substitutes: self-observed, manually
reviewed proxies for whether the project is doing its job.

- **North star metric**: number of curriculum concepts that are fully
  documented and pass every item in the Phase 1 acceptance criteria
  (section 12.4), out of the total concepts currently defined (14 as of
  this version).
- **Acquisition**: not applicable. There is no external audience to
  acquire; the maintainer is both builder and primary user.
- **Engagement**: informal, self-observed. Tracked qualitatively as "how
  often the maintainer actually opens and references a concept page while
  building something else," noted in the maintainer's own working notes,
  not instrumented in the site itself.
- **Retention**: not applicable, single user.
- **Performance**: page weight of each concept page's own CSS and JS
  (excluding shared theme, base, and component files loaded once per
  session), target under 20KB per concept page; combined shared
  `theme.css` + `base.css` + `components.css` weight, target under 40KB
  total, since there is no build step to minify these files automatically.
  Zero browser console errors on every page is a hard requirement, not a
  target.
- **Targets and cadence**: reviewed manually at the completion of each
  milestone in section 14, not continuously monitored, since instrumenting
  continuous monitoring would require a network call, which violates the
  offline constraint in section 9.
- **Measurement method**: manual checklist against section 12.4 and 13.4
  acceptance criteria, the responsive QA methodology in DESIGN.md section
  8, and the writing style sweep in section 6. No automated telemetry is
  built into the site itself.

## 16. Runbook

**Local setup.** See README.md's Installation and How to run locally
sections. In summary: copy the project folder to local disk, then double
click `index.html` in Chrome. No prerequisite beyond Chrome itself.

**Build.** None. There is no build command and no build output, since the
project runs directly from its source files.

**Deploy.** None. There is no staging or production environment. Moving the
project to a different machine means copying the folder; no reconfiguration
is needed since every path in the project is relative and no environment
variable exists.

**Rollback.** If a change introduces a regression, revert to the previous
commit in version control (`git log`, then `git revert` or `git checkout`
against the specific file or commit). If the project is not under version
control at a given point in time, keep a dated backup copy of the folder
before any non-trivial change; version control is the recommended default.

**Environment configs.** A single environment only: the local file system
where the project folder lives. There is no staging, production, or
per-environment configuration of any kind.

**Common errors.**

| Symptom | Likely cause | Fix |
|---|---|---|
| Blank page, missing styles | A relative path broke after a file was moved | Confirm the file's location matches the directory tree in README.md |
| Sidebar missing on a page | `nav-data.js` or `nav.js` not included, or included out of order | Confirm both `<script>` tags are present, with `nav-data.js` before `nav.js` |
| Console error referencing an undefined `WIREFRAME_*` global | Script load order is wrong, or a data file was renamed without updating its references | Check script tag order and confirm exact global names against section 12.3 and 13.3 |
| A template does not appear on the showcase page | Its manifest was never appended to `templates-registry.js` | Follow the two-step process in section 13.3 |
| An inline SVG icon does not render | Malformed SVG markup, often from an incomplete copy-paste | Re-copy the exact snippet from `assets/svg/icon-reference.md` |

**Monitoring.** None automated, since the offline constraint in section 9
rules out any telemetry that would need a network call. The manual
substitute is: open Chrome DevTools' console on every page touched by a
change and confirm zero errors, then run the responsive QA methodology in
DESIGN.md section 8 before considering that change complete.

**Verification sweep.** The manual check above does not scale to 45 pages,
and skipping it is how the `admin-dashboard` dead selector survived a
scripted contract audit: the file was well formed, the selector was
spelled correctly, and it still matched nothing. Structure can be checked
by reading; rendering cannot. It has to be rendered.

Chrome and Edge both run headless from the command line and both open
`file://` URLs, so the whole library can be swept without installing
anything. This is a verification aid invoked from outside the project, not
a dependency of it: nothing in the repository references it, and the
constraint in section 9 stands unchanged. The two flags that matter are
`--screenshot`, which writes a PNG that can be looked at, and
`--enable-logging=stderr`, which surfaces page console errors.

```
msedge --headless=new --disable-gpu --user-data-dir=<scratch>/prof   --no-first-run --disable-extensions --window-size=1400,1000   --enable-logging=stderr --v=0 --virtual-time-budget=2500   --screenshot=<scratch>/out.png "file:///<abs-path>/index.html"
```

Four details make the difference between a real check and a false pass:

- `--user-data-dir` pointed at a scratch profile, with
  `--disable-extensions`. Without it the default profile loads and its
  extensions write their own `CONSOLE` lines into the log, which buries
  the page's.
- Filter the log to `:CONSOLE:`, `Uncaught`, `SyntaxError`,
  `ReferenceError`, and `TypeError`, then drop lines containing
  `chrome-extension`. Everything else in a verbose Chromium log is browser
  noise, not the page.
- `--virtual-time-budget` in milliseconds, or the screenshot is taken
  before scripts have run.
- Sweep several widths, not one. Both defects fixed in v0.11.1 were
  invisible at 1400px; the `wiki-portal` overlap only appeared between
  761px and roughly 1080px.

What this covers is first paint and console health. It cannot press a key,
so it says nothing about focus, keyboard traversal, or any state a script
sets in response to input. That is the second tier, below.

**Interaction verification.** Chromium exposes the DevTools Protocol over
a websocket when launched with `--remote-debugging-port`, and that is
enough to dispatch real key and mouse events, read the DOM back, and
screenshot a page mid-interaction. Node is not needed for it; any language
with a websocket client will do. Three flags are required beyond the sweep
above:

- `--remote-debugging-port=<port>`, and a distinct port per run.
- `--remote-allow-origins=*`, or the websocket upgrade is rejected 403.
  Suppressing the `Origin` header on the client side works too.
- Kill stale browser processes between runs. A previous instance still
  holding the port will answer the handshake with its own flags, which
  produces a 403 that looks like the flag was never passed.

Two traps make an interaction test lie rather than fail:

- **Scroll the target into view before dispatching a mouse event.**
  Protocol mouse events take viewport coordinates, so a control below the
  fold is clicked at a point outside the window and nothing happens. The
  call still reports success. Four of this project's five demo forms
  appeared broken for exactly this reason before the harness was
  corrected; all five were fine.
- **Drive the real control, not a synthesised event.** Dispatching
  `new Event('submit')` bypasses native constraint validation, so it can
  pass where a real click is blocked, and it misses templates whose
  behavior hangs off a button rather than a form. Two templates here have
  no `<form>` at all.

**Overflow sweep.** The cheapest high-signal check of the three, and the
one that found the most. Set the viewport with
`Emulation.setDeviceMetricsOverride`, then read
`documentElement.scrollWidth > clientWidth`: true means the page is wider
than the screen. Run it across every page at every width in DESIGN.md
section 8.1. To find the cause rather than only the symptom, set a
candidate element's `width` to `min-content` and measure: the element
whose minimum exceeds the viewport is the one forcing the overflow, and
its nearest ancestor that still fits tells you where to apply the fix.
That technique located all four defects in v0.11.3 in a single pass, two
of which were one shared root cause rather than the four separate page
bugs they appeared to be.

What this tier still does not cover is hover, which has no reliable
protocol equivalent, and anything about how the page sounds to a screen
reader beyond checking that the attributes are present. Report the tiers
separately and never let a clean sweep of one be described as full
verification.

## 17. Technical requirements

**System architecture.** Fully static, client-only, no backend of any
kind. Three logical layers, all delivered as plain files opened directly by
the browser:

- **Presentation**: HTML pages plus CSS files (`theme.css`, `base.css`,
  `components.css`, `wiki-layout.css`, `portfolio-layout.css`, and from
  M15 `home.css` for the root page and `previews.css` for template
  previews).
- **Data**: plain JavaScript files that assign to global objects and
  nothing else, loaded via `<script src="...">`, never via `fetch` or
  modules: `nav-data.js`, `concepts-index.js`, `templates-registry.js`,
  `search-index.js` (generated, see below), and each template's own
  `manifest.js`.
- **Behavior**: `nav.js` (renders the sidebar from `nav-data.js`, and
  from M15 the Education top bar, search, contents and pager),
  `template-previews.js` (preview data and the drawing function),
  `demo-utils.js` (shared helpers for interactive concept demos),
  `prefs.js` (optional localStorage preferences), and each template's own
  `script.js`.

**Generated file.** `assets/js/search-index.js` is written by
`python tools/build-search-index.py` from the Education pages. Run it
after changing a lesson's title, headings or text, and commit the
result; the site never builds anything at load time.

**Tech stack.** See README.md's Tech stack table for the authoritative
list: HTML5, CSS3 with custom properties, ES2017+ JavaScript with no
transpilation, system font stack, inline SVG, zero frameworks, zero build
tooling.

**Folder structure.** See README.md's Directory tree for the full,
annotated layout. `README.md` stays at the project root only; `PRD.md`,
`DESIGN.md`, and `PATCHNOTES.md` live exclusively under `/docs/`.

**Data models.**

- **Nav data** (`nav-data.js`): `window.WIREFRAME_NAV`, an array of module
  objects, each shaped as `{ id, title, order, path, concepts: [{ id,
  title, path }] }`, in recommended sidebar order.
- **Concept index entry** (`concepts-index.js`): see the full shape in
  section 12.3.
- **Template manifest** (`manifest.js` and `templates-registry.js`): see
  the full shape in section 13.3.

**API design.** Not applicable; the site is browser-only with no backend.
The internal data flow is: a page loads its relevant data file(s) via
`<script src>`, then a behavior script reads the resulting global object
and renders DOM from it. For example, any Education page loads
`nav-data.js` then `nav.js`, which reads `window.WIREFRAME_NAV` and builds
the sidebar; the templates showcase page loads `templates-registry.js`
directly and iterates `window.WIREFRAME_TEMPLATES` to render cards.

**State management.** No framework and no central store. Page level state
lives in plain DOM and module-scoped JavaScript variables. The only state
that persists across sessions is the optional, non-essential preference
data in `prefs.js` (for example, sidebar collapsed state), which must
degrade gracefully to sensible defaults if `localStorage` is unavailable or
cleared, per the constraint in section 9.

**Third-party integrations.** None. Zero external services are called from
any page.

**Performance requirements.** See the budgets in section 15's Performance
metric: roughly 20KB of page-specific CSS and JS per concept page, roughly
40KB combined for the three shared stylesheets, and zero console errors as
a hard requirement on every page.

**Known technical debt.** None yet, since implementation has not started. *(Discrepancy, 2026-10-04: implementation is complete; the debt is listed in section 38.)*
The one accepted, permanent tradeoff is that the lack of a build step means
file size discipline is manual rather than automatic (no minification); this
is an intentional consequence of the offline, dependency-free constraint in
section 9, not an oversight to fix later.

## 18. Security

**Authentication model.** None. There are no accounts, no login, and no
sessions anywhere in the project.

**Authorization model.** None. There is a single implicit user (whoever
opens the file) and no roles or permission levels.

**Data storage.** The only data ever stored is optional, non-essential UI
preferences in `localStorage` (for example, sidebar collapsed state),
implemented in `prefs.js`. No personal data, form submission, or user
generated content is ever stored or transmitted. Any demo form in a
template (for example, the Small Business template's contact form) is
static markup only; it must not silently pretend to submit data anywhere,
and must show a visible note that it is a non-functional demo.

**Environment variables.** None. There is no server-side code, no API key,
and no external service credential anywhere in this project, so there is
nothing to configure and nothing to keep out of version control. This is
reconfirmed any time a new file is added: if a file ever appears to need a
secret or credential, that is itself a violation of the offline,
dependency-free constraint in section 9 and should be treated as a design
error, not solved with an environment variable.

**Third-party trust.** None. Zero third-party services receive any data,
since the site never makes a network request of any kind.

**Known attack surface.** Minimal, since there is no server and no network
access. The one realistic residual risk is a future interactive demo or
template input that echoes user-typed text back into the page (a
self-contained, local risk within the user's own browser tab, not a risk to
any other party). Mitigation: any code that reflects user input into the
DOM must use safe text assignment (`textContent`, `setAttribute` with
known-safe values) rather than building HTML strings by concatenation, and
must never use `innerHTML` with unsanitized input.

**Dependency policy.** Not applicable in the conventional sense, since the
project has zero third-party dependencies of any kind to monitor for
vulnerabilities. If this policy ever changes, any added dependency must be
vendored locally rather than loaded from a CDN (per section 9), with its
exact version pinned and recorded as a PATCHNOTES.md entry.

## 19. Press release

**Template Interface teaches the reasoning behind good web design, entirely
offline.**

A new personal reference site explains web design from first principles
and ships a growing library of ready-to-use templates, without a server,
an account, or an internet connection.

*Release notes, 2026-07-26.*

Template Interface is a self-contained website that teaches the concepts behind good
UI and UX design and includes a library of general purpose website
templates that put those concepts into practice. It opens directly in
Google Chrome from a local folder, with no installation and no network
access required, at any point, ever.

Most people learn web design by copying finished examples: a template here,
a cloned layout there, without ever learning why the original choice
worked. That approach breaks down the moment a project needs something the
copied example did not anticipate, leaving the builder with no principle to
fall back on.

Template Interface addresses this by teaching each concept, such as visual
hierarchy, spacing, color contrast, and accessibility, with an interactive
demo that shows the effect directly, at a pace the learner sets rather than
a forced linear course. Every concept is also structured so that an AI
coding assistant can look it up precisely, using a fixed, documented file
and anchor convention, so the lessons can inform sites built well beyond
Template Interface itself.

"I kept re-deriving the same design decisions from scratch on every project
until I finally wrote them down properly, in a place I would actually go
back to," said a hypothetical early user matching Template Interface's primary
audience. "Having the reasoning and a working demo in the same place, and
knowing my AI assistant can read the exact same reference, changed how I
work."

Anyone interested can open Template Interface today by copying the project folder
and double clicking `index.html` in Chrome. No sign-up, no download beyond
the files themselves, and no ongoing maintenance is required.

Template Interface is maintained as a personal, non-commercial educational project,
built and used by its own maintainer as both a learning tool and a working
reference for future website projects.

## 20. Frequently asked questions

**What is Template Interface?**
A free public website, at `templateinterface.com`, that teaches UI and UX
design concepts and provides a library of reusable website templates. It
is plain static files and also works opened from disk.

**Who is it for?**
The maintainer, as a personal design reference; AI coding assistants that
need a reliable place to look up a design concept; and anyone else who
wants to learn web design from first principles rather than by copying
examples.

**Do I need to install anything?**
No. Copy the project folder to disk and double click `index.html` in
Chrome.

**Does it need the internet?**
No, never, at any point, including the first time it is opened.

**What does it cost?**
Nothing. It is a personal, non-commercial project with no pricing tiers and
no paid features.

**Does it collect any data?**
No. It makes no network requests and stores nothing beyond optional,
non-essential UI preferences in the browser's local storage.

**What browser does it support?**
Google Chrome, current version. No other browser is verified against or
supported.

**Can I use it on mobile?**
The site is responsive down to a 375px wide viewport, but it is designed
and verified as a desktop-first Chrome, `file://` protocol experience; it
is not distributed as a mobile app.

**How is the curriculum organized?**
Into modules ordered beginner to advanced, each containing one or more
concepts. There is no forced order; the sidebar always shows a recommended
path, but any concept can be opened directly.

**Can I start on an advanced topic without reading the beginner modules
first?**
Yes. Every concept lists its prerequisites so you know what you might be
missing, but nothing blocks direct access.

**What are the starter templates?**
Landing Page, Portfolio Site, Blog and Article Site, Documentation Site,
and Small Business and Local Service Site. See section 13.2 for details on
each.

**Can I add my own template?**
Yes, by following the folder and registry contract in section 13.3. Any
template that satisfies the contract appears correctly on the showcase
page.

**How does this differ from a typical template marketplace?**
Templates here exist to demonstrate specific, named lessons from the
Education section rather than to be the primary product. Buying a template
elsewhere teaches nothing about why it works; Template Interface's templates are
paired with the exact concepts they demonstrate.

**Why no frameworks or build tools?**
So the site can be opened by double clicking a file, forever, on any
machine with Chrome installed, with zero setup and zero risk of a
dependency going stale or disappearing. See Tenet 2 and section 9.

**Why does a static site need an "AI queryability contract"?**
Because one of Template Interface's primary users is an AI coding assistant, not
just a human. A fixed heading, anchor, and index structure lets a model
find and cite a concept precisely instead of guessing at where content
lives or how it is formatted.

**What does Template Interface not do?**
It is not a CMS, not a page builder, not a hosted service, and does not
cover native app design, print design, or multi-language content. See
section 4.

**Is there a mobile app?**
No, and none is planned.

**Who supports this if something breaks?**
There is no support channel; this is a personal project maintained by a
single person. Issues are fixed by editing the local files directly.

**Will more concepts and templates be added later?**
Yes. Both the curriculum and the template library are explicitly designed
to grow; see section 8's Future feature list and section 14's deferred
items.

**Why build the Education section before any templates?**
Because templates without a finished teaching foundation would just be
more unexplained examples, which is the exact problem Template Interface exists to
solve. See Tenet 1.

**How is progress tracked without analytics?**
Manually, against the acceptance criteria in sections 12.4 and 13.4 and the
metrics in section 15, since instrumenting analytics would require a
network call that the offline constraint in section 9 rules out.

**What happens to the visual theme after Phase 1?**
It gets revisited, deliberately, using the site's own completed lessons on
color, typography, and accessibility as the audit checklist. See DESIGN.md
section 10 (the revisit happened in M8; DESIGN.md has no section 20).

## 21. Documentation and audit process

*(Discrepancy, 2026-10-04: `docs/TODO.md`,
`docs/TEMPLATE_DESIGN_REVIEW_PROMPT.md` and
`docs/reviews/template-design-review-findings.md` also exist, and the root
now has `LICENSE.md`. The rule below is kept as written; section 36
records the difference.)*

This project maintains exactly four markdown documents:
`README.md` at the project root, and `PRD.md`, `DESIGN.md`, and
`PATCHNOTES.md` under `/docs/`. No other markdown planning document is
created at the project root or scattered elsewhere in the tree; any new
documentation need is folded into one of these four files, or into a
concept's own markdown mirror under `/education/md-mirror/`, or into a
template's own `README.md` under `/templates/{template-slug}/`.

Three recurring audits keep this documentation and the eventual codebase
in sync. Each is triggered at defined checkpoints, not run ad hoc:

1. **Writing style sweep** (section 6). Run whenever any markdown or HTML
   content is added or edited, before that content is considered final.
   Searches independently for the literal em dash character, the
   `&mdash;` entity, and punctuation double dashes, while leaving CSS
   custom property syntax untouched. Any instance found is replaced using
   the methodology in section 6, chosen per sentence rather than a single
   default substitution.
2. **Responsive QA methodology** (DESIGN.md section 8). Run against every
   page or template once its markup and styles are believed complete, and
   again after any layout-affecting change to that page. Verified
   programmatically (`scrollWidth` versus `clientWidth`, measured
   `getBoundingClientRect()` values), not by eyeballing a screenshot,
   across every breakpoint listed in DESIGN.md section 8. Any fix that
   involves a real presentation choice, not just a CSS correctness issue
   with one obvious answer, is confirmed with the maintainer before being
   implemented, per Tenet 6.
3. **Documentation accuracy audit.** Run whenever the codebase changes in
   a way that could make README.md, PRD.md, or DESIGN.md inaccurate (a new
   concept, a new template, a changed folder contract, a changed design
   token). The audit crawls the current state of the project, compares it
   against each of the four documents, and updates whichever document has
   drifted. `PATCHNOTES.md` receives a new dated entry for every
   documentation change, describing what changed and why, using the
   Added, Changed, Fixed, Removed format defined in PATCHNOTES.md.

All three audits are treated as part of finishing a unit of work, not as
optional cleanup. A page, template, or documentation change is not
considered complete until the audits relevant to that change have run and
their findings have been resolved or explicitly deferred with a stated
reason.

---

## 22. Open items for future revisions

- The site's interface changed in M15 (section 13.7, v0.17.0): the
  layouts of the showcase, the root page and
  Education were rebuilt. The theme revisitation this item used to
  anticipate happened in M8; see DESIGN.md section 10.
- Modules 08 (Data Visualization) and 09 (E-commerce UX) were added in
  M23 (section 13.14). Further modules are not scoped.
- The Metrics section (section 15) was revisited for the public site in
  M16 and still tracks nothing automatically; revisit it again if the
  maintainer ever adds analytics, since its current
  metrics are deliberately scaled down to match that reality rather than
  a conventional multi-user product.


## 23. Repository reference (moved from README, 2026-10-04)

The audit's README rule keeps install steps, commands, environment
variables and version numbers out of the README, so these sections moved
here unchanged. Where they now contradict the project, section 36
records it; their text is kept as written.

### Live site

Not applicable. Template Interface is designed to run only from local static files
under the `file://` protocol and is never deployed to a server or public
URL. There is no live link by design; see Constraints in
[docs/PRD.md](docs/PRD.md).

### Tech stack

| Layer | Technology | Version |
|---|---|---|
| Markup | HTML | HTML5 (living standard) |
| Styling | CSS | CSS3, custom properties (CSS Variables Level 1) |
| Behavior | JavaScript | ES2017+ syntax, no transpilation |
| Fonts | System font stack | N/A, no font files shipped |
| Icons | Inline SVG | SVG 1.1 |
| Frameworks / libraries | None | N/A |
| Build tooling | None | N/A |
| Package manager | None | N/A |

No framework, build tool, package manager, or external service is used
anywhere in this project. This is a hard constraint, not a temporary
omission; see the Constraints section of [docs/PRD.md](docs/PRD.md).

### Prerequisites

- Google Chrome, any current version. Chrome is the only browser this
  project targets and verifies against.
- No Node.js, no package manager, no runtime of any kind is required.
- No internet connection is required at any point, including first run.

### Installation

There is no installation step. Cloning or copying the project folder to
local disk is the entire setup:

```
git clone <this-repository> wireframe
```

or simply copy the project folder to any location on disk. No further
command is run.

### How to run locally

1. Open the project folder on disk.
2. Double click [index.html](index.html) at the project root.
3. Chrome opens the file over `file://` and the site is fully functional,
   including navigation, interactive demos, and the template showcase.

There is no dev server and no default port, since nothing here is served
over HTTP. If a page fails to load a script or style correctly, confirm the
folder structure below has not been altered, since every path in the project
is relative.

### Environment variables

None. Template Interface has no environment variable of any kind, required or
optional, because it has no server, no build step, and no external service
to configure. This is confirmed and re-verified in the Security section of
[docs/PRD.md](docs/PRD.md).

### Build and deploy

None. There is no build step and no deploy target. The project runs
directly from source files exactly as they exist on disk. "Shipping" a
change means saving the edited file; there is no compile, bundle, minify, or
publish step at any point in this project's lifecycle.

### Directory tree

The tree below reflects the intended structure once implementation begins.
Nothing in this structure hardcodes the current concept count or template
count; both sections are designed to grow.

```
wireframe/
  README.md
  docs/
    PRD.md
    DESIGN.md
    PATCHNOTES.md
    TEMPLATE_DESIGN_REVIEW_PROMPT.md  Reusable prompt for a full design review of the template library
    reviews/
      template-design-review-findings.md  Evidence, scores and decisions from the v0.12.0 review
  index.html                          Site entry point, links into both sections

  assets/
    css/
      theme.css                       CSS custom properties only (design tokens)
      base.css                        Resets, base typography, layout primitives
      components.css                 Sidebar, cards, buttons, callouts, code blocks, etc.
      wiki-layout.css                 Layout rules for education article pages
      portfolio-layout.css            Layout rules for the template showcase grid
    js/
      nav-data.js                     window.WIREFRAME_NAV (single source of nav structure)
      nav.js                          Renders the sidebar from nav-data.js at runtime
      concepts-index.js               window.WIREFRAME_CONCEPTS (machine readable concept index)
      templates-registry.js           window.WIREFRAME_TEMPLATES (template registry, drives the showcase)
      templates-index.js              window.WIREFRAME_TEMPLATE_INDEX (machine readable composition index)
      demo-utils.js                   Shared helpers for interactive concept demos
      prefs.js                        Optional, non essential localStorage preferences
    svg/
      icon-reference.md               Inline SVG icon snippets and usage notes

  education/
    index.html                        Section 1 landing page (wiki style overview article)
    INDEX.md                          Human readable mirror of concepts-index.js
    01-foundations/
      index.html                       Module overview page
      what-is-ui-ux.html
      visual-hierarchy.html
    02-layout-and-structure/
      index.html
      layout-and-grid-systems.html
      spacing-and-rhythm.html
      responsive-and-mobile-first-thinking.html
    03-typography-and-color/
      index.html
      typography.html
      color-and-contrast.html
    04-accessibility/
      index.html
      accessibility-and-wcag-basics.html
    05-navigation-and-content/
      index.html
      navigation-and-information-architecture.html
      content-design-and-microcopy.html
    06-interaction-and-forms/
      index.html
      forms-and-inputs.html
      interaction-states-and-feedback.html
      motion.html
    07-critique/
      index.html
      common-design-mistakes.html
    md-mirror/
      01-foundations/
        what-is-ui-ux.md
        visual-hierarchy.md
      02-layout-and-structure/
        layout-and-grid-systems.md
        spacing-and-rhythm.md
        responsive-and-mobile-first-thinking.md
      03-typography-and-color/
        typography.md
        color-and-contrast.md
      04-accessibility/
        accessibility-and-wcag-basics.md
      05-navigation-and-content/
        navigation-and-information-architecture.md
        content-design-and-microcopy.md
      06-interaction-and-forms/
        forms-and-inputs.md
        interaction-states-and-feedback.md
        motion.md
      07-critique/
        common-design-mistakes.md

  templates/
    index.html                        Section 2 landing page (portfolio style showcase)
    INDEX.md                          Human readable mirror of templates-index.js
    TEMPLATE_CONTRACT.md              Folder, manifest, and README contract for any future template
    landing-page/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    portfolio-site/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    blog-article/
      index.html
      article.html
      manifest.js
      styles.css
      script.js
      README.md
    documentation-site/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    small-business/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    ecommerce-product/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    ecommerce-storefront/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    pricing-page/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    event-site/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    nonprofit-site/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    restaurant-site/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    real-estate-listing/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    course-landing/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    resume-site/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    community-forum/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    waitlist-signup/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    onboarding-flow/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    admin-dashboard/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    careers-page/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    help-center/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
    wiki-portal/
      index.html
      manifest.js
      styles.css
      script.js
      README.md
```

New templates are added by creating a new folder under `/templates/` that
follows the contract in `TEMPLATE_CONTRACT.md`, registering it in
`templates-registry.js`, adding a preview layout in
`templates/index.html`, and updating the two indexes
(`assets/js/templates-index.js` and `templates/INDEX.md`) so the library
map stays true. No page or script assumes a fixed number of templates. This structure and every file listed above are documented and
tracked; `README.md` stays at the project root only, and `PRD.md`,
`DESIGN.md`, and `PATCHNOTES.md` live exclusively under `/docs/`.


## 24. Conventions

Derived on 2026-10-04 from the files and `git log`.

- **Files.** Lowercase kebab-case folder and file names. Each template is
  one folder of five files: `index.html`, `styles.css`, `script.js`,
  `manifest.json`, `README.md`.
- **CSS.** Site pages read `--color-*`, `--space-*` and `--font-*` tokens
  from `theme.css`. Each template declares its own palette with a short
  prefix (`--am-` for Amaro, `--np-` for Northpass and so on). Shared
  components that must survive template rules double their class
  (`.site-nav.site-nav`).
- **JavaScript.** Plain ES2017 in an IIFE with `"use strict"` and `var`,
  no modules, so pages run under `file://`. Global data objects keep
  their `WIREFRAME_*` names after the rename.
- **Line endings.** Work files are CRLF on this machine through
  `core.autocrlf=true`; the repository stores LF.
- **Commits.** Imperative, sentence case, one line, no type prefix
  ("Add ...", "Finish ...", "Swap ..."), with the version in brackets when
  a release is cut. Claude-made commits end with a `Co-Authored-By` line.
- **Writing.** Section 6 governs all prose: plain words, no em dashes.

## 25. Browser testing

The audit default is Microsoft Edge, run headless, never Chrome. Edge is
at `C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`.
Section 16's sweeps already use it.

*Discrepancy:* sections 3, 10 and 20 and section 23's prerequisites name
Chrome as the only target browser. Both are Chromium, so results carry
over. Decided 2026-10-04: keep both. Chrome stays the stated target
browser and Edge is the browser the checks run in.

## 26. Verification environment

Checks run against the local files, opened over `file://` or a local
server, never against the production site. There is no production site
yet (M20).

## 27. Testing cadence

Before a major update ships: check the assumptions it relies on, then run
one browser test (section 16's sweep). Minor and docs-only updates need
no browser test. Do not test between individual edits.

This replaces section 21's trigger for responsive QA, "after any
layout-affecting change". The writing-style sweep (section 21, "whenever
any markdown or HTML content is added or edited") is a text check, not a
browser test, and stays as written.

## 28. Security addendum

Section 18 remains the security record. Added 2026-10-04: no secret,
token or credential goes in any tracked file, `docs/TODO.md` included.
The design-notes prompts mention the public address as plain text; no
page fetches anything over the network.

## 29. Repository hygiene

- `.gitignore` covers `Thumbs.db`, `desktop.ini`, `.DS_Store` and
  `.vscode/`.
- `.gitattributes` (added 2026-10-04) stores text as LF with
  `* text=auto eol=lf`; work copies on this machine are still CRLF through
  `core.autocrlf=true`.
- Canonical remote: the private `Azqato` repository on GitHub, default
  branch `main`.

**Disk use (standard, 2026-10-06).** The project folder is synced by
OneDrive, so throwaway files must not pile up inside it. On 2026-10-06,
5.4 GB of leftover headless browser profiles were removed from
`tools/checks/.out/` and `tools/color-standard/`.

- Browser profiles from checks go in the system temp folder, never in
  the project, and are deleted when the check ends. `tools/checks/cdp.py`
  does this for every script that uses it (the checks, the color audit and
  `tools/m24/`). Any new script that starts a browser uses `cdp.Browser`
  rather than its own profile folder.
- Screenshots and reports from checks go in `tools/checks/.out/`, which
  git ignores and which can be deleted at any time.
- Scratch scripts, one-off outputs and intermediate JSON stay outside the
  project (for example in a temp folder). Anything that must be kept is
  committed with a purpose; anything else is deleted when its task ends.
- Temporary working files in `docs/` (like the M24 scoring file) are
  removed once their results are recorded in the PRD.
- After a large task, check for ignored leftovers with
  `git status --short --ignored` and delete what is no longer needed.

## 30. Licensing

All rights reserved; see `LICENSE.md` at the root. `robots.txt` is left
fully open on purpose, so search engines can find the site; the licence,
not the crawler file, sets the terms of use.

## 31. Social sharing tags

Policy (changed 2026-10-22 to the Documentation prompt's default, at the
maintainer's request): every shareable page carries six tags:
`og:title`, `og:description`, `og:url`, `og:type`, `og:site_name` and
`twitter:card`.

- `og:url` is the absolute https URL of that page
  (`https://templateinterface.com/...`), never relative, never the site
  root, and unique across the site.
- `og:type` is `website` unless a page is genuinely an article;
  `og:site_name` is the same on every page.
- Budgets: `og:title` 60 characters (70 at most), `og:description` 150
  (200 at most), `og:site_name` 20. `og:title` does not repeat the site
  name.
- No share images: `twitter:card` is `summary`, and `og:image` is never
  added speculatively.
- Titles front-load the distinct part. Descriptions are complete
  sentences, read from the page, and reuse an accurate meta description.
- Excluded: 404 and error pages, mockups, work in progress, and anything
  not in `sitemap.xml` or marked noindex.
- Checks (read and report, counted by script): all six tags present;
  budgets met; every `og:url` absolute, https and unique; no `og:title`
  contains the `og:site_name`; `twitter:card` is `summary` where there is
  no image.

Previous rule, replaced: six tags with `twitter:title` instead of
`og:site_name`, titles up to 60 characters, descriptions up to 155. The
pages still follow it until milestone M25 updates them.

All 46 HTML pages carry the six tags as of 2026-10-04 (v0.16.1). Template
pages take their description from the registry, the root page from its
meta description, and other pages from their first paragraph.

## 32. Page titles

Policy: `<page> - <brand>`, at most 60 characters, the first 30 unique
across the site, and the homepage leads with the brand.

As of 2026-10-04 all 46 titles are 60 characters or fewer with unique
first 30 characters. `blog-article` and `event-site` were shortened in
v0.16.1. Template pages keep the suffix "Template Interface template".

## 33. Deprecation and removal

Removing a template means deleting its folder, its entry in
`templates-registry.js`, its entries in `templates-index.js` and
`templates/INDEX.md`, and any concept page link to it, then adding a
PATCHNOTES entry under **Removed**. Concepts follow the same pattern with
`nav-data.js`, `concepts-index.js` and the md-mirror. Script identifiers
are never renamed only for tidiness (section 13.8).

## 34. Metrics note

Section 15 is kept. Until M20 there is no traffic to measure. Once live,
the suggested north star is returning visitors who copy a template's
prompt. Uncertain: no analytics is planned.

## 35. Runbook additions

- Deploy (planned, M20): GitHub Pages or another static host serving
  `main`, with `templateinterface.com` as the custom domain. Rollback is
  reverting the commit on `main`.
- Browser binary for checks: the Edge path in section 25.

## 36. Documentation versus reality

Found by the audit on 2026-10-04. The documented text is kept where it
is; this table records what the files show.

| Where | Documented | Observed |
|---|---|---|
| Section 3 goal; tenet 2 | Runs in Chrome with zero network access, "double-click-to-open, forever" | Still opens from disk, but the project is now a public site (M16) |
| Section 9 | "Never hosted on a server or given a public URL" | M20 plans hosting at `templateinterface.com` |
| Sections 10 and 23 | Chrome is the only browser | Checks run in headless Edge (section 25) |
| Section 11 | Verified with a one-entry and an eight-entry registry | 64 templates are registered (M24) |
| Section 13.5 | Live verification of the 15 templates still open | The M9 row says verified |
| Section 13.8 | "Still to do: the going-live wording" | M16 is marked done |
| Section 14, D1 | Live confirmation outstanding | M11 says confirmed |
| Section 14, current phase | Five starter templates | 64 templates (21 before M24) |
| Section 14, build order | "M9 remains the one planned item left" | M9 is done |
| Section 15 | Single user, acquisition not applicable | A public site is planned |
| Sections 16 and 23 | Deploy: none; single environment; "Live site: not applicable ... by design" | M20 plans a deploy |
| Section 17 | No technical debt; architecture list | Omits `theme-toggle.js`, `design-notes.js`, `design-notes.css`, `site-nav.css` and the `template-theme` storage key |
| Section 18 | Never makes network requests | True of the code; the prompts contain the live address as text |
| Sections 19 and 20 | Offline forever, no internet ever, five starter templates, not hosted | As above |
| Section 21 | Exactly four markdown documents | Seven in `/docs` and the root, plus `LICENSE.md` |

## 37. Risks and open questions

Answered by the maintainer on 2026-10-04:

1. Browser: keep Chrome as the stated target, check in Edge (section 25).
2. `.gitattributes`: added (section 29).
3. D6: keep `wiki-portal`'s skip link (section 14).
4. Stale offline wording: rewritten as part of the go-live plan, right
   before public release (M20), not before.
5. Sharing tags and long titles: done in v0.16.1 (sections 31 and 32).
6. `docs/TODO.md`: both items are on the roadmap, so the file was
   emptied.

Open risk: the GitHub repository is private, so the design-notes
prompts' live links fail until M20.

## 38. Technical debt

- The Education search index is generated by hand with
  `tools/build-search-index.py` and can go stale if a lesson changes
  without a re-run. (The root page's counts, typed by hand before, are
  derived since M15.)
- Stale offline wording across the PRD (section 36).
- Closed in M23: the headless Edge checks live in `tools/checks/`; run
  `python tools/checks/run_all.py` (needs Edge and `websocket-client`).

## 39. Working practice

- Before every push: fetch, read `docs/TODO.md` on `origin/main`, and if
  it has new ideas, ask the maintainer whether to turn them into roadmap
  updates. Gather the ideas, interpret each, relate it to existing
  milestones, propose where it goes, and report. Never act on an idea
  without agreement, never move or merge the file, and keep its wording.
- After changing code a PRD or DESIGN section describes, update that
  section's row in the verification checklist (section 14).
- Push to `main` after each update.

## 40. Documentation audit record

The Documentation Prompt was run on 2026-10-04 (M19, v0.16.0): survey,
read every document, check them against the files, fix the gaps, report.
It added `LICENSE.md`, `robots.txt`, `sitemap.xml` and sections 23 to 40,
moved the README's technical sections here, and added DESIGN.md section
13. Rerun it before M20.

Rerun on 2026-10-05 as the last step of M23 (v0.23.0): the theme note
in section 22, the module and test suite items in sections 22 and 38,
the four new concept definitions (12.2), the site bar switch (13.11,
DESIGN 16), the README status table and the template contract were
brought up to date.

The press release (section 19) and FAQ (section 20) already exist and are
kept; their offline claims are listed in section 36.

## 41. Page metadata

Added 2026-10-22 by the Project Defaults pass. The project had no rule of
its own for the meta description or JSON-LD, so this is the default from
the Documentation prompt, recorded as policy only. No page was edited.

- Applies to the same pages as section 31, with the same exclusions.
- Meta description: 150 to 160 characters, complete sentences ending in a
  full stop, stating the page's purpose and main takeaway.
  `og:description` reuses it where it is accurate.
- One JSON-LD block per page, with the schema.org type that best fits
  (WebPage, Article, SoftwareApplication and so on), carrying `name`,
  `author`, `datePublished`, `dateModified`, a detailed section by section
  `description`, `keywords`, `about` and `mentions`, and `hasPart` for
  each major section.
- The metadata matches the visible content exactly; when a page's content
  changes, its metadata and `dateModified` change in the same commit.
- Important content is in the HTML as served, not only rendered by script.
- Where a page's full content also exists as plain text (such as the
  Education md-mirror), the head carries
  `<link rel="alternate" type="text/markdown" href="...">` with the
  absolute URL, the JSON-LD names it as an `encoding`, and the visible
  page links it. Each says in plain words that the file holds the page's
  complete content and that a model which cannot read the page should
  download and read it in full before summarising or acting on it.
- Every JSON-LD block is validated with a schema validator before
  publishing. When a page's head changes, the whole head is reviewed
  together.
- Checks (read and report only): meta description length and exactly one
  JSON-LD block per page, counted by script; each block parses and has
  the required fields; `dateModified` is not older than the file's last
  commit; every `hasPart` heading is on the page; pages with a plain-text
  source carry the alternate link and encoding with the reading
  instruction.

Status: adopted by the maintainer on 2026-10-22. Not yet verified. A
quick search found no JSON-LD block on the root page or on
`documentation-site`, so most pages likely do not meet this rule yet;
milestone M25 brings them in line.

---

## Brand Identity

Written by the Brand Identity prompt (prompts v1.110.0), run on
2026-10-04 as the M21 test. Nothing outside `brand/` and the two Brand
Identity sections is changed.

### Brand Brief

| Field | Value | Source |
|---|---|---|
| Brand name | Template Interface | README, PRD 13.8 |
| Core value | Understanding before imitation: the reason behind a design, then the working site | PRD 1, 3; root page headline |
| Audience | Self-directed learners without a design background, developers who learned by copying, and AI coding assistants | PRD 2 |
| Idea and mission | Learn why good web design works, then build with it: a lesson becomes a layout | Root page, PRD 3 |
| Industry | Design education and website template libraries | PRD 1, 4 |
| Colour constraints | Keep the site's dark canvas `#0d1117` and single teal accent `#00d4a0`, used only for actions, location and focus | theme.css, DESIGN 14.1 |
| Font constraints | The site uses the system font stack and loads no fonts (offline rule, PRD 5); a brand typeface may be used inside `brand/` only | PRD 5, 9 |
| Existing brand | A text wordmark in the system font, the dark and teal palette, and `favicon.png`, a gold picture frame around a landscape (the one raster file allowed, DESIGN 7) | DESIGN 7, theme.css |
| References | None (the default; not asked during this run) | |

### Competitive Analysis

From knowledge, not a web search. Eight brands in design education and
template libraries:

| Brand | Shapes | Colours | Type |
|---|---|---|---|
| Interaction Design Foundation | Rounded badge, initials | Blue and white | Geometric sans |
| Nielsen Norman Group | Text only, stacked | Black, red accent | Classic sans |
| Refactoring UI | Text only | Blue to indigo | Bold grotesque |
| Laws of UX | Text only | Black, white | Neo-grotesque |
| Figma Community | Stacked circles and rounded squares | Five-colour set | Custom geometric |
| Webflow Templates | Single angular letter | Blue | Geometric sans |
| ThemeForest (Envato) | Leaf mark | Green | Rounded sans |
| Tailwind UI | Wave or wind shapes | Cyan to sky gradient | Geometric sans |

Shared: rounded squares around an initial, blue or purple gradients,
geometric sans in lowercase, and pictograms of the work itself.
Clichés to avoid: cursor arrows, pen-tool curves with handles, a browser
window with three dots, overlapping translucent rectangles, purple to blue
gradients, code brackets, and generic image-placeholder icons.

Positioning: Template Interface stands out by showing the structure
behind a page, one plain shape for one idea, in a dark field with a single
accent, which is what its lessons teach, while the system type and
restraint keep it credible next to the reference sites it cites.

### Deliverables checklist

| Item | File | Status |
|---|---|---|
| Concepts A to E, E in five Primer colours | `brand/concepts/`, `brand/concepts/index.html` | Done |
| Horizontal and stacked lockups, symbol, wordmark (colour, reversed, black, white) | `brand/logo/` | Done |
| Single-colour print version | `brand/logo/symbol-single-color.svg` | Done |
| Favicon SVG with dark-mode variant, ICO, 16/32/48 PNG | `brand/logo/favicon.*` | Done |
| App icons 180/192/512/1024, maskable 192/512 | `brand/logo/app-icon-*` | Done |
| Clear space and minimum size rules | DESIGN.md Logo System | Done |
| Social images: link preview, profile, X header, LinkedIn banner | `brand/kit/*.png` | Done |
| Email signature logo | `brand/kit/email-signature-400x100.png` | Done |
| Tokens and contrast table | `brand/kit/tokens.css`, `tokens.json`; DESIGN.md Color Contrast | Done |
| Web manifest (not linked) | `brand/kit/site.webmanifest` | Done |
| Presentation and PDF | `brand/presentation.html`, `brand/brand-guidelines.pdf` (7 pages) | Done |
| Brand Design page, offline | `brand/brand-design.html` (ignored by git) | Done |
| Overview deck | `brand/index.html` | Done |

**Brand Design page.** The site is static and public with no way to
restrict a page, so the Brand Design page is the offline form:
`brand/brand-design.html`, opened by double-click, listed in
`.gitignore`, never committed or linked. Running Phase 7 of the Brand
Identity prompt again refreshes its file list.
