Back to README

Checklist

The change workflow. The implementation stays small on purpose — plain HTML pages, one stylesheet, one chrome module, one page script — so agents edit exactly what ships. Walk the list before every commit.

Making changes

  1. 1. Find the ownerChange a token, symbol, or shared class before overriding an individual instance.
  2. 2. Add semanticsUse a real section, heading, link, or button before styling it.
  3. 3. Test both sizesCheck wide desktop and a narrow phone. Nothing should require horizontal scrolling.
  4. 4. Test both modesConfirm contrast in light and dark system themes.
  5. 5. Keep navigation trueNew destinations must update the dock, active state, and browser history together — and pick the right dock: main tabs go in TABS, docs pages go in DOCS_TABS.
  6. 6. Keep the agent editions truePage content ships with its matching .md file updated in the same commit — agents read those, not the HTML. The worker serves them on Accept: text/markdown; see worker.js.
  7. 7. Verify the agent surfaceAfter deploys that touch pages, worker.js, or llms.txt, run ./verify-agent.sh — it checks markdown negotiation, the raw-HTML H1, real 404s, and the markdown 404 body.
  8. 8. Run the unit testsnpm test runs the pill-slide tests in tests/ — zero dependencies, they load the real site.js/chrome.js against DOM fakes and assert the cross-file contract.
  9. 9. Document the systemNew shared components get a registry entry under the Components tab (what it is, when to use it, markup, tokens). Decisions with dead ends get an essay under the Dock tab — write it while the context is fresh, because it evaporates. New colors go in the token list first, never as one-off hex.
index.html              → home (profile, now, colophon, contact)
resume/index.html     → resume
ai/index.html         → AI blog
docs/index.html       → README (this portal's index)
docs/components/index.html → component bench
docs/checklist/index.html  → this checklist
docs/dock/index.html  → dock deep dive
styles.css            → tokens, components, view transitions
chrome.js             → <site-header>, <site-nav> + icon sprite
site.js               → tab SPA, copy button, labs

assets/
├── herman.jpg
└── lottie/

Interface rules

Distilled from Vercel's Web Interface Guidelines — the ones this site follows. Check new work against them, not the whole list.

  • Explicit transitions only.Never transition: all — list the properties (usually transform, opacity). Never animate layout properties (width, height, top); keep motion on the compositor.
  • Typography is typeset.Curly quotes (“ ”) and the … character in prose; ... only inside code. Non-breaking spaces glue units and names (10 MB).
  • Keyboard gets everywhere.Every page has a skip link and a hierarchical heading order. Icon-only buttons carry an aria-label; the copy button announces via aria-live.
  • Hit targets ≥ 44px on mobile.If the visual target is smaller, expand the hit area — never the other way around.
  • Images declare dimensions.width and height on every <img> so nothing shifts as assets load.