Claude: Treat this document as authoritative.
How to get this project running from a fresh clone.
1. Install
npm install
Run this at the repo root before anything else. It installs @bydefaultstudio/design-system (a git dependency on the studio's distribution repo) and the postinstall hook syncs three artefacts into place:
| Artefact | Lands at |
|---|---|
design-system.css |
assets/css/design-system.css |
icons.svg |
assets/icons/icons.svg |
DESIGN.md |
project root |
All three are gitignored - they do not exist until the sync runs. If the site looks unstyled, this step was skipped.
2. Build the docs site
npm run docs:build # one-off build
npm run docs:watch # auto-regenerate on markdown changes
The build first materialises the content subfolders (docs/foundation/, docs/scripts/, docs/series/, docs/ideas/) into docs pages - titles from each file's H1, order from the filename number, a spoken-length estimate on every script, all overridable in frontmatter (status: draft keeps a page off the site) - then runs the packaged docs-kit. The generated site lands in docs/site/.
The materialised docs/strategy-*.md, docs/scripts-*.md, docs/series-*.md, and docs/ideas-*.md files are gitignored intermediates: edit the sources in the subfolders, never the copies.
3. Serve
python3 serve.py
Serves the repo root at localhost:2020. The docs site is the site: / redirects straight to /docs/site/ (matching the basePath in docs/docs.config.js), whose homepage is one book cover per section, with the Idea Studio at /docs/site/tools/idea-studio.html. In Codespaces, open the forwarded port.
4. Everyday workflow
- New script → drop it in
docs/scripts/(namedNN Project Name - Presenter.md, withsubsection: "July 2026"frontmatter for its month), runnpm run docs:build, refresh. - New idea →
docs/ideas/idea-inbox.md, same rebuild. - Shape an idea into a brief → the Idea Studio.
- Design questions →
DESIGN.mdat the project root, or the canonical design system docs at bydefault.design.
5. Upgrading the design system
Dependabot opens a PR when a new package version publishes. Or by hand:
npm update @bydefaultstudio/design-system
npm run docs:build
See Upgrading the Docs Engine for the full story.