Design and implement a contribution workflow that lets dozens of engineers contribute high-quality components while maintaining system coherence and accessibility standards.
Design and implement a contribution workflow that lets dozens of engineers contribute high-quality components while maintaining system coherence and accessibility standards.
A well-structured PR template is the first line of quality enforcement. It captures intent, surfaces impact, and guides reviewers. Essential sections: type of change (bug fix, new component, token update, breaking change), description (what changed and why), component checklist (TypeScript strict, Storybook story added, WCAG AA verified, visual diff attached, changelog entry), screenshots (before/after or Chromatic link), and related issues or RFCs. Make the template unfillable in a hurry — if a contributor skips the accessibility checkbox, CI fails with a clear message pointing to the a11y guide. Store the template at .github/PULL_REQUEST_TEMPLATE.md.
1# Pull Request
2
3## Summary
4Replace this with a concise description of the change.
5
6## Type of Change
7- [ ] Bug fix (patch)
8- [ ] New feature/variant (minor)
9- [ ] Breaking change (major)
10- [ ] Token update
11
12## Checklist
13- [ ] TypeScript compiles with 0 errors: pnpm type-check
14- [ ] New or updated Storybook stories added
15- [ ] WCAG 2.1 AA verified (axe-core + manual keyboard test)
16- [ ] Visual diff attached (Chromatic link or before/after screenshots)
17- [ ] changeset entry added: pnpm changeset
18- [ ] Documentation updated in Storybook MDX
19
20## Related Issues / RFC
21Closes #Automate every check that does not require human judgment. A production CI pipeline for a design system runs type checking with tsc --noEmit in strict mode, ESLint with eslint-plugin-jsx-a11y and eslint-plugin-storybook, unit tests with Vitest at 90% or higher coverage for utilities, visual regression with Playwright screenshots diffed against main or Chromatic for Storybook, and bundle size verification with Bundlewatch or Size-limit that fails if any package grows more than 5KB gzip without approval. Each check runs as a separate GitHub Actions job so failures are pinpointed rather than buried in a monolithic log.
1# .github/workflows/ci.yml
2jobs:
3 typecheck:
4 runs-on: ubuntu-latest
5 steps:
6 - uses: actions/checkout@v4
7 - run: pnpm install --frozen-lockfile
8 - run: pnpm type-check
9
10 a11y-audit:
11 runs-on: ubuntu-latest
12 steps:
13 - uses: actions/checkout@v4
14 - run: pnpm install --frozen-lockfile
15 - run: pnpm storybook:build
16 - run: pnpm test:a11y # axe-playwright on built Storybook
17
18 bundle-size:
19 runs-on: ubuntu-latest
20 steps:
21 - uses: actions/checkout@v4
22 - run: pnpm build
23 - run: npx bundlewatch --config bundlewatch.config.jsonEngineering review alone misses design and accessibility issues. A three-stage review process catches all dimensions at the right cost. Stage 1 — Automated: CI must be green before human review is requested. Stage 2 — Engineering review: a core team member evaluates API design, TypeScript generics, test coverage, and performance impact. Stage 3 — Design and A11y review: one designer validates visual fidelity against the Figma spec, and an accessibility reviewer runs NVDA and VoiceOver on the Storybook story. Encode this as branch protection rules requiring 2 approvals, with one from the @design-system/a11y-reviewers team. Use GitHub CODEOWNERS to auto-assign reviewers based on changed files: token changes route to @design-system/token-owners, component changes to @design-system/core.
Manual changelog maintenance breaks down at scale. Changesets (@changesets/cli) solves this with intent-driven version bumps. Contributors run pnpm changeset to declare whether their change is a patch, minor, or major and write a human-readable summary. On merge to main, the Changesets GitHub Action opens a Version packages PR that bumps all affected package versions and aggregates changelog entries. On merge of that PR, packages are published to npm automatically. This decouples changelog authorship from release timing.
1# Contributor workflow
2# 1. After writing code, run:
3pnpm changeset
4# Prompts: which packages changed? patch/minor/major? human summary?
5# Creates .changeset/random-adjective-noun.md
6
7# 2. Commit the changeset file
8git add .changeset
9git commit -m 'chore: add changeset for Button focus fix'
10
11# 3. Open PR — Changesets bot comments with version preview
12# 4. On merge: GitHub Action opens 'Version packages' PR automatically
13# 5. On merge of version PR: packages publish to npm registryNew contributors should be productive within 30 minutes. Achieve this with a CONTRIBUTING.md containing a 5-step quickstart: clone the repo, run pnpm install, run pnpm dev to start Storybook, run pnpm test:watch to start Vitest in watch mode, then open the first issue labeled good-first-issue. Provide a dev container at .devcontainer/devcontainer.json so Node, pnpm, and Playwright versions are pinned and consistent. Add a component scaffold generator so running pnpm generate:component Button creates the component file, TypeScript types, Storybook stories, and a Vitest test with correct imports. Record a 10-minute First Contribution video and link it prominently from CONTRIBUTING.md. Track onboarding success by measuring time from first commit to first merged PR — target under 3 working days.
Add a .github/PULL_REQUEST_TEMPLATE.md to your design system with the full checklist. Set up Changesets and wire it to your GitHub Actions release workflow this sprint.
Your progress is saved in this browser, on this device only.