Shipfolder demo. All sample content on this page is fictional.

Shipfolder

The text of AGENTS.md from the Shipfolder 1.1.0 download.

AGENTS.md

Instructions for coding agents, and for people, who edit this kit. Read this before you change anything.

What this is

A static website kit: six HTML pages, two CSS files, one optional JavaScript file. No build step, no package manager, no framework. Do not add any of these unless the owner of the site asks for them.

File map

PathWhat it holds
index.html, docs.html, changelog.html, blog.html, blog-post.html, 404.htmlThe pages. Each one contains its own copy of the header and footer.
css/theme.cssEvery design token: type, spacing, radius, layout, shadow, motion, the three colour presets and the light and dark colours.
css/components.cssLayout and components. Reads tokens only. No raw colour values.
js/main.jsTheme toggle (localStorage key shipfolder-theme), copy buttons, mobile docs menu. Budget: 5,120 bytes.
assets/favicon.svg, blog-cover.svg.
qa/qa.pyThe QA checks. Python 3 standard library only.
README.md, CUSTOMISING.md, FAQ.mdHuman documentation. CUSTOMISING.md has step-by-step recipes.

Rules

  1. Run python3 qa/qa.py after every change. It must end with SUMMARY: 10/10 checks passed -> PASS (exit code 0). If a check fails, fix the cause; do not weaken the check. If the site owner deliberately adds real external links or self-hosted fonts, follow README "The QA script" and CUSTOMISING §3 to adjust the script.
  2. Keep the header and footer in sync. Edit them in index.html first, then paste the identical markup into the other five pages. Only aria-current="page" may differ. The shared-chrome check fails on any other difference.
  3. Colours live in css/theme.css only. Add or change a colour there, as a --color-* token, never as a raw value in components.css. The dark-mode block exists twice (inside @media (prefers-color-scheme: dark) and as :root[data-theme="dark"]); change both identically.
  4. Presets are set with data-preset on <html> (indigo, teal, ember). A new preset needs a block in theme.css and an entry in PRESETS in qa/qa.py.
  5. Load nothing from other hosts. No CDN scripts or styles, no web-font services, no analytics, no embeds. Put every file the page needs in the folder.
  6. Keep the page structure accessible. One <h1> per page, no skipped heading levels, alt on every image, a label on every control, the skip link as the first focusable element.
  7. Keep JavaScript optional. Pages must work without it. The theme toggle and copy buttons start hidden or absent and are added by main.js.
  8. Every page needs a unique <title>, a meta description, lang, charset and viewport. New pages are found by qa.py automatically (every *.html in the kit folder).
  9. Inside <code>, escape <, > and &.
  10. Content honesty. The sample pages describe a fictional product ("Example API" from "Example Co"). Replace placeholder copy with the owner's real content. Do not invent testimonials, customer names or logos, user counts or performance numbers.

Common tasks

  • Change brand colours: CUSTOMISING §2.
  • Add a docs page, blog post or changelog entry: CUSTOMISING §7.
  • Change the logo or product name: CUSTOMISING §4.
  • Deploy: README "Deploy" (fix the paths in 404.html if the host serves it at nested URLs).