# How it is built

A static site, generated by a small Python build with no dependencies, served as plain files. No framework, no client-side rendering: every page is complete HTML before any script runs, and the one script on the site (the findings filter) only hides and shows rows that are already there.

## The files

| Path | What it is |
| --- | --- |
| `data/findings.json` | The register. The source of every finding page, list, filter and count |
| `data/exemplars.json` | What good looks like: things that work, each linked to the findings it answers |
| `data/principles.json` | The principles, each with a rule, a reason and a test |
| `data/taxonomy.json` | The problem, visibility and recommendation vocabularies findings are indexed by |
| `data/lab.json` | The design lab: vaults and read keys, directions, screenshots, decisions |
| `data/site.json` | Name, navigation, the products findings belong to (sites, platform, prototypes, browsers), the sibling sites |
| `data/versions.json` | The release history; the first entry is the current version |
| `content/**/*.md` | Hand-written pages, with `{{directives}}` the build fills from the data |
| `admin/build/build.py` | Builds every `.html`, its `.md` twin, `llms.txt`, `llms-full.txt`, `sitemap.xml` |
| `admin/build/md.py` | The markdown renderer (stdlib only) |
| `admin/build/gate.py` | The release gate |
| `assets/` | One stylesheet, one script, the icon |
| `lab/shots/` | Phone screenshots from the lab's vaults |
| `findings/img/` | Evidence screenshots attached to findings |

## Build and check

```
python3 admin/build/build.py     # write every generated file
python3 admin/build/gate.py      # must print GATE PASS
python3 -m http.server 8000      # then open http://localhost:8000/
```

## The gate

CI runs it on every push, and a release is the commit it passes on. It fails if:

- any generated file is stale (the build is re-run and compared byte for byte), or any `.html` in the tree is not generated;
- a finding is missing a field, uses an unknown product, area, problem, visibility, recommendation, kind, severity, status or principle, repeats an id, has a date that is not a date, or attaches an image that is missing or has no alt text;
- a principle, problem, visibility or recommendation has no finding that uses it;
- an internal link or `#anchor` on any page goes nowhere, or a page has no markdown twin;
- a colour is written anywhere but the token block at the top of `assets/site.css`;
- the version disagrees between `data/versions.json`, the pages, `llms.txt` and `index.md`;
- a lab screenshot named in `data/lab.json` is missing, or a credential that is not a published read key appears in a tracked file.

## Versions

The version is shown once, in the footer, and links to [what changed](/admin/versions.md).

Each release bumps the last number (v0.4.0 → v0.4.1), unless the project lead asks for a larger step. Every release gets an entry in `data/versions.json` naming what changed and the files it touched.