Contributing

The design system lives in the monk-business/design-system repository, a pnpm workspace:

Path	Contents
packages/tokens	DTCG sources (src/tokens), the Style Dictionary build and its tests
packages/brand	The logo generator (scripts/logos.mjs), PNG exports and fonts.css
packages/css	Component CSS, one file per component in src/
packages/astro	Astro components in src/, published as source
apps/docs	This site (Astro + Starlight)
docs/adr	Architecture decision records

Development

nvm use                 # Node 24
pnpm install
pnpm build              # tokens, brand, css (the astro package is source)
pnpm docs:dev           # this site at http://localhost:4321
pnpm test               # unit tests in every package
pnpm typecheck
pnpm lint               # Biome; pnpm format fixes formatting
pnpm --filter @monk-business/docs test:e2e   # Playwright: every page, axe

Versioning

The four packages are a fixed group in Changesets: they always share one version, and a release bumps all of them. Follow semantic versioning from the consumer’s point of view:

Change	Bump	Examples
Breaking	major	Remove or rename a token, CSS variable, class or prop; change a token value in a way that breaks contrast or layout; drop a theme selector
Additive	minor	New token, component, variant, prop or file; new output format
Fix	patch	Correct a value to match the approved design; fix markup or accessibility without changing the API; docs-only changes to packages

While the version is below 1.0, treat minor as breaking-capable but still call out every breaking change in the changeset.

Changesets workflow

1. Make the change on a branch.
2. Run pnpm changeset, pick the bump and write a summary for consumers: what changed and what they need to do.
3. Open a pull request. CI runs lint, build, typecheck, unit tests, the docs build and the end-to-end tests.
4. When the pull request is merged into main, CI runs again and the release workflow opens (or updates) a “Version Packages” pull request with the new version and the changelogs.
5. Merging that pull request publishes the packages to GitHub Packages, tags the release and creates GitHub releases.

This site deploys on every push to main once the checks pass, so documentation fixes go live without a package release.

Add or change a token

1. Edit the DTCG files in packages/tokens/src/tokens/: $value, $type and a $description that says where to use it. Reference other tokens with {color.teal.700}.
2. Themed tokens go in both themes/dark.json and themes/light.json; a test fails if one theme is missing a token.
3. New text and ground colors must pass the contrast tests (4.5:1 for text, 3:1 for graphics) in both themes; add the pair to test/tokens.test.mjs.
4. Run pnpm --filter @monk-business/tokens build and test. Review the CSS snapshot diff (test/__snapshots__) and update it with vitest -u only when the change is intended.
5. Never rename or remove an existing --mb-* variable in a minor release: the website depends on them.

Add a component

1. Write the styles in packages/css/src/<name>.css, inside @layer mb.components, using only --mb-* variables and mb- classes (BEM). Add the file to FILES in packages/css/scripts/build.mjs.
2. Write packages/astro/src/<Name>.astro with an exported Props interface, a JSDoc comment on every prop (the docs tables are generated from it) and no client JavaScript. Export it from src/index.ts.
3. Add tests for its markup in packages/astro/test/components.test.ts.
4. Add a demo in apps/docs/src/demos/ and a page in apps/docs/src/content/docs/components/ with usage rules, Astro and HTML snippets, and <PropsTable>.
5. Add the page to the sidebar in apps/docs/astro.config.mjs and to the end-to-end page list if it needs axe coverage.

Logos and brand files

The logo geometry in packages/brand/scripts/logos.mjs is approved: the tests compare every SVG byte by byte with the committed snapshots. Change it only with the owner’s approval, then update the snapshots in the same pull request and describe the change in the changeset.

Release process

Releases are automated with Changesets and GitHub Actions; nobody publishes from a laptop. To publish manually in an emergency, with a token that has write:packages:

pnpm build
pnpm changeset version
pnpm changeset publish