Maintaining the design system

For whoever edits and publishes this folder. Readers start at README.md; agents at AGENTS.md, the roadmap by job; people briefing agents at prompts.md.

Change the system

With an agent, paste this, in the design repo or anywhere the repo is checked out:

Change the Seeds of Renaissance design system: [what, and why; who decided it, if it's a rule].
Work in ~/src/life-itself/design/projects/sor-design-system. Follow the "Maintain"
route in its AGENTS.md and read only what it names.
Keep the guide, its route in AGENTS.md, its prompt in prompts.md and llms.txt
in step where the change touches them, and check the paths other repos read.
Show me the change before committing. Then tell me what you checked and what you guessed.

The common changes, and what each needs:

• Add a graphic. Check it isn't in the set already. The files in system/graphics/<set>/elements/, in the set's formats (woodcuts: SVG, with ids no other file in the set uses, since the gallery inlines them all); an entry in the set's elements.json, edited by hand in its own indentation (fields: system/graphics/README.md; the maker in source); a row in the set's README. Then python3 system/build/build-galleries.py && python3 system/build/build-reference.py, and check its gallery page. A new set also goes in FAMILIES in build-galleries.py.
• Change a token. In system/tokens.css only, keeping its role comment true. Find where the old value is written out (grep -rn '<old value>' --include=*.md --include=*.html --include=*.py . | grep -v archive/): guides that quote it, kits and examples that bake it in (rebuild those with their export.sh or build.py), guide.html (then rebuild the specimens). If components.src.css changed, run python3 system/build/build-css.py. The website takes the new value when its design pin is bumped.
• Record a decision. See Recording decisions: the answer in the planning repo, the rule as applied in the guide here, linked.
• Add or change a guide, kit or example. Change its route in AGENTS.md and its prompt in prompts.md (and the copy at the top of the guide) in the same commit; llms.txt if a page is added, renamed or moved.

Keep in step. Before committing: the builds run clean (see Publish); git status shows only what you meant to change; the guide, the route, the prompt and llms.txt agree. Generated files are never edited by hand: graphics/<set>.md, logos.md, the tables between <!-- … --> markers in graphics.md and reference.md, specimens/, components.css, site/. A published path that moves gets a redirect in the MOVED map in system/build/build-site.py. Paths other repos read (listed under "The roadmap and the prompts" below) don't move without telling that repo.

Test a route after changing it: give a fresh agent only its prompt, working from another repo or a scratch folder, and fix what it trips on.

Where it lives

• Source: life-itself/design, folder projects/sor-design-system/. The single home for SoR brand and design-system work.
• Published at https://design.seedsofrenaissance.org (Flowershow, from GitHub: branch design-system-site; custom domain via a DNS-only CNAME design → cname.vercel-dns.com in the seedsofrenaissance.org Cloudflare zone). The old address https://sor-design-system-rufuspollock.flowershow.me still works. Preview copy as a Claude artifact: https://claude.ai/artifact/MtNi8BxiybVhuXZCzwo6it.
• Tracking: beads design-34t.

How the site is put together

• Markdown pages hold the rules and the reasoning. Flowershow renders them with its own layout and the navbar from config.json. The sidebar is off. Each .md is also served raw at its .md URL, which is what agents read; llms.txt lists them in reading order.
• Library pages (graphics/<set>.md, logos.md, the cards in graphics.md) are generated by system/build/build-galleries.py: Flowershow pages with layout: plain, so they keep the navbar, with their own scoped CSS (.sg, the system tokens and faces) and a page script (scripts: in the frontmatter; inline <script> runs only on a full page load). No blank lines inside their HTML: Flowershow ends an HTML block at one.
• guide.html holds the visuals: the whole system rendered with the real CSS, one chapter per topic. It is the only place the visuals are edited.
• specimens/<chapter>.html are cut from guide.html by system/build/build-specimens.py and embedded at the top of the topic pages and on the home with an <iframe class="specimen">. A group inside a chapter with an id like <div id="examples-web"> also gets its own specimen (used on examples.md and youtube.md). Never edit them by hand. They hide each chapter's heading and "more" links, since the embedding page has its own.
• custom.css styles the specimen frames on Flowershow. Flowershow pages never load components.css (its generic class names would clash with the site theme); the system's CSS only runs inside the specimen frames, the guide and the examples.
• Navbar (config.json) follows the three ways in on the home page: Start here (BUILD), Make (one guide per format), Assets (logo, logo files, graphics, photography), Foundations (feel, voice, colour, type, layout, components, the guide), Brand and Examples. A page goes in the nav only once it is usable; the graphics galleries and the logo files are reached from graphics.md (the logo files also from Assets).
• The roadmap and the prompts. AGENTS.md routes agents by job (read, use, copy, ask, check); prompts.md holds the prompts people paste, each sending the agent to a route. llms.txt points to the roadmap first. When a guide, kit or example changes, change its route and its prompt in the same commit. Other repos read some paths directly (sor-website/scripts/sync-design.py copies system/tokens.css, components.css, graphics.js, sor.js, system/fonts/ and system/img/): moving one breaks that repo's next sync.
• Kit downloads are zipped from each kit's png/ by build-site.py (the KITS map), into the folders its README lists.
• Examples are standalone HTML pages under examples/<kind>/, one folder per kind (web, social, youtube, podcast, slides, print, diagrams), each kind with an index.html gallery where it has several. examples.md lists them all.

Pages state rules, not progress

Published pages say how things are now. No status tables, "Open"/"Next"/"To do" sections, 🚧, briefs or prompts for agent sessions, beads ids, or "(decided , )" on rules. Progress, open questions and session briefs go in beads (design-34t); the reasoning behind a rule goes in the decision record (see below), linked once at the foot of the page. A known constraint a maker must respect (unlicensed fonts, uncleared images) stays, as one plain sentence.

Specimen heights

A specimen lays out at a virtual 1000px width and scales to its frame, so its height is a fixed ratio of its width. Each <iframe> carries style="aspect-ratio:1000/H", where H is the specimen's height at 1000px plus about 10px. After changing a chapter in guide.html, re-measure: open any specimen locally, then in the browser console load each one into a 1000px-wide iframe and read document.body.scrollHeight. Update H wherever that specimen is embedded (grep -n 'specimens/<name>' *.md). Below 600px wide, frames fall back to a fixed height and scroll inside.

Recording decisions

(2026-10-12.) A decision is recorded in the planning repo's project issue tree (e.g. 2608 for the brand) as the question with a ✅ answer, who decided and the date. The design docs here (voice.md, colour.md, logo.md, etc.) hold the rule as applied, with a link back to the planning answer, and don't re-argue it. Write one decision to both in one go. There is no separate decision tree in this repo; decisions.md keeps only design-internal reasoning and history, and notes such as voice-notes.md keep the options considered.

The issue tree carries only the one-line answer. Longer discussion goes in a file next to the issue tree (e.g. projects/2608-seeds-of-renaissance-rebrand/YYYY-MM-DD-slug.md), linked from the answer. Existing design-side reasoning files such as voice-notes.md stay and are linked.

Publish

Merge to main. The workflow publish-design-system.yml runs on any push that touches projects/sor-design-system/, builds site/ and commits it on top of the design-system-site branch, which Flowershow publishes. Never force-push that branch: Flowershow syncs commit by commit and ignored the force-pushed builds of 13–15 October. Nobody needs fl or a Flowershow login. It can also be run by hand from the Actions tab. Check a run there if the site looks stale.

To build locally (for a preview, or to debug the workflow), from projects/sor-design-system:

python3 system/build/build-specimens.py && python3 system/build/build-galleries.py && python3 system/build/build-reference.py && python3 system/build/build-site.py

Keep the workflow's build steps in step with this list. The gallery builder makes thumbnails with ImageMagick (magick), or sips on macOS.

When the Wisdom paper is rebuilt, re-render the print example's page images with python3 examples/print/build.py (needs pdftoppm; check the page numbers in it first); it is not part of the site build.

build-site.py assembles site/ (gitignored): the docs, guide, specimens, graphics galleries, system code and images and examples. It leaves out moodboard/ and archive/: those are the working record and stay on GitHub, and links to archive/ from pages are rewritten to their GitHub addresses. It also rewrites .md links in HTML pages to Flowershow page URLs, and gives the guide and every example a small fixed link back to the site.

Code

Preview locally: run the static launch config (python http.server on 8790) from the repo root and open /projects/sor-design-system/. Markdown pages are not rendered locally; open the HTML pages and specimens directly.

Changing the look

Work out a change in HTML mockups first, then carry it into the format's own build. HTML is quick to iterate and review, and uses system/tokens.css directly; the builds (Typst for papers, build.py for diagrams) then follow the settled values.

• Make the mockup as a loose page, show it, decide. Then update the tokens and the guide, rebuild the real thing, and refresh its examples.
• When it's settled, move the mockup to archive/<format>-<what>-<yyyy-mm>.html as the record, fix its ../ paths and list it in archive/README.md. Examples show only finished work.
• Starting points: papers, archive/print-mockups-2026-10.html (A4 pages at 1:1, prints as a proof); diagrams, archive/diagrams-*-2026-10.html.

Where things came from

• The former life-itself/sor-brand repo, merged here 2026-10-05 with history and since folded in: decisions.md (the decision log; the plan it came with is archive/design-system-plan-2026-10.md), archive/logo-2026-10/logo-notes.md, moodboard/ (references and images, not published), archive/sor-brand-mockups/ (the mockups the system was extracted from: Direction E v7 and the four-page v2) and archive/sor-brand-STATUS.md.
• The old website design project (2026-sor-website, directions and moodboard, 2026-09): archive/website-2026-09/. Its brand substance and page copy now live here as brand.md and content/.
• type/: the two type selection rounds and research notes.
• Brand substance (who we are, offers, voice) stays in brand.md.

Shared by the SoR experiences and the website. The experiences carry their own working palette in common.md, not yet reconciled with this system.