Contribute
How work enters the library: design first, then plan, implement, review, and release — every component graduates through explicit lifecycle stages.
Contribution cycle
Every change follows the same seven-step path from idea to published package.
Design
Brainstorming skill produces an approved spec. No code without a preceding design.
Plan
Writing-plans skill breaks the spec into bite-sized tasks.
Implement
Build with TDD where applicable — code plus tests.
Pull request
Review plus CI: lint, test, a11y, visual, and bundle size.
Changeset
Declare the version bump level.
Merge
Changesets bot opens a Release PR.
Release
Published to GitHub Packages.
Component lifecycle stages
Where a component lives and how stable its API is, signalled by a stage annotation.
| Stage | Annotation | Export location | Use when |
|---|---|---|---|
| experimental | @experimental | @idinstudio/ui/experimental | Design exploration, not yet validated. |
| alpha | @alpha | main export (doc-hidden) | Early production use; API may change in a minor. |
| beta | @beta | main export | API frozen; behaviour may still adjust. |
| stable | — | main export | Production-ready; API locked. |
Stage progression
Each promotion has an explicit gate and a Changeset noting the change.
Typed, has at least one test, design reviewed.
Full test coverage, a11y contract complete, stories cover all variants, used in at least one consumer.
In production at least 4 weeks in a consumer, zero high-severity bugs, Chromatic baseline approved.
Replacement exists, codemod written, deprecated across 2 minor versions before removal.
Every component ships seven files
Co-located in one folder. A missing file fails CI. Scaffold them with the create-component CLI.
{name}.tsx — implementation{name}.stories.tsx — all variants × severities × sizes{name}.test.tsx — unit tests (Vitest + RTL){name}.a11y.test.tsx — axe-core tests{name}.a11y.md — accessibility contract, written first{name}.figma.ts — Figma Code Connect mappingindex.ts — barrel re-export