Skip to content
FoundryFoundry — home
Search

Community

Contributing

Stable

Adding to the catalogue should mean adding a file and a record. If it means editing a page, the architecture has a bug.

Updated in v1.0.0

Adding a component

  1. Write the implementation in src/components/ui/. It may import tokens, other primitives and icons — nothing else.
  2. Write a demo in src/components/demos/<slug>.tsx with a default export. The demo must show every state the component claims, because it is the preview.
  3. Add a record to src/lib/catalogue/components.ts with makeItem('component', …).
  4. Run npm run registry. The source and preview maps regenerate; nothing else changes.

The detail page, search index, filters, related-content links and sitemap all pick the item up automatically. There are 45 components and exactly one detail page renderer.

Adding a section

Same shape, one directory deeper: src/components/blocks/sections/<group>/<slug>.tsx, then a record in src/lib/catalogue/sections.ts. The registry id is derived from the path, and a test asserts that the derivation in the catalogue helper and the one in the build script agree.

Keep copy in src/content/. A section file should be a layout decision and nothing else.

Adding a starter

Append a record to src/lib/starters/index.ts: a brand, a palette, and a route table where each route names the catalogue blocks it composes. No files under app/ change — one dynamic route already serves every starter.

If a route needs a screen no block covers, add it once to src/components/starter-kit/pages.tsx so the next starter can reuse it.

Adding a category

Add it to the family definition in src/lib/catalogue/families.ts. It appears in the catalogue filters, the search grouping and the footer immediately. A test asserts every declared category has at least one item, so an empty filter chip cannot ship.

One rule about variants

A variant is valid only when it represents a real decision. If two entries differ only in padding, they are one entry and a density token. One hundred excellent components beat three hundred nearly identical ones.

What the tests enforce

  • Unique ids and slugs, and a valid category for every item
  • Every related item resolves — no dangling recommendations
  • Every declared source file exists in the generated registry
  • The displayed source matches the file on disk, byte for byte
  • Every registered preview is used by exactly one catalogue record
  • Counts derived from the catalogue match the catalogue
  • No unfinished-work markers, debug logging, secrets or development URLs in shipped source

Before opening a change

Run npm run verify. It formats, lints, type-checks, tests and builds in that order. Every one of them must pass — weakening a test to make it pass is the one thing this project will not accept.

Read Composition first if you are unsure which level your addition belongs to.