| name | f0-component-promotion |
| description | Use when promoting an F0 component from experimental/ to stable (Phases 4–5 of the lifecycle). Owned by Foundations team. For building a new component, use f0-component-contribution. |
F0 Component Promotion (Phases 4–5)
This skill guides Foundations team members through validating that an experimental component meets the maturity criteria and promoting it to stable. The full contract is in packages/react/docs/definition-of-done.mdx Phases 4–5.
Who can run this skill: members of @factorialco/foundations. Other contributors can request promotion in #f0-support, but only Foundations executes the move.
Phase 4 — Validate real-world adoption
The component owner (or a Foundations engineer) starts a promotion request in #f0-support and proves all DoD criteria are met.
4.1 — Demand axis
Run a cross-repo search across the factorialco GitHub org. Use GitHub code search (not local rg):
org:factorialco "F0MyComponent" -repo:factorialco/f0
Required: ≥3 distinct product teams import or use the component in production code (not tests, not docs, not examples).
Document the findings in the #f0-support promotion thread with links.
Also check: no "would you remove this?" or "this should be deprecated" feedback in the last 30 days (search the component name in #f0-support).
4.2 — Maturity axis
Verify all four:
-
No breaking changes for ≥60 days. Run:
git log --since="60 days ago" --oneline -- packages/react/src/experimental/<Category>/F0Name/
Inspect any commits touching types.ts, prop signatures, or default values.
-
Zero open critical or high-severity bugs. Search #f0-support (and any bug tracker) for the component name; check severity.
-
f0-quality-gate passes including extended subagent reviews. Load and run f0-quality-gate with full subagent suite (a11y, design tokens, dark mode).
-
Owner declares API stable in the #f0-support promotion thread (explicit message).
4.3 — Foundations re-confirmation
A Foundations team member explicitly approves promotion in the #f0-support promotion thread. There is no auto-promotion.
If any axis fails, the promotion is deferred with a documented explanation in the thread.
Phase 5 — Execute promotion
5.1 — Decide the destination zone
| If the component is… | Move to… |
|---|
| A primitive (Button, Input) | src/components/ |
| A composition (Page header) | src/patterns/ |
| A vertical bundle | src/kits/ |
| A layout primitive | src/layout/ |
| A hook | src/hooks/ |
For Domain specific components in src/sds/<area>/, promotion stays inside the domain folder and ownership stays with the domain team — only the story tag changes (experimental → stable). Foundations does not take ownership of Domain specific components.
5.2 — Run the migration skill
Load f0-experimental-component-migration and follow it end-to-end. It handles file moves, import updates, removing the experimentalComponent() wrapper, and ensuring exports.ts is correct.
5.3 — Update the story
-
Change tag from experimental to stable:
tags: ["autodocs", "stable"]
-
Story title stays the same (no rename).
5.4 — Update MDX docs to Good tier
Load factorial-f0-component-documentation. Required for stable: Good tier minimum (Gold encouraged).
5.5 — Update CODEOWNERS
Transfer ownership to Foundations. Add a line to CODEOWNERS:
packages/react/src/components/F0Name/ @factorialco/foundations
(Or update an existing wildcard line if one already covers the destination.)
5.6 — Run quality gate again
Load f0-quality-gate and run the full workflow on the promoted component.
5.7 — Open the promotion PR
Load f0-pr.
PR title: feat(F0Name): promote to stable
The promotion is not a breaking change for consumers — the public import path doesn't change and the API was already stable de facto during Phase 4. So we use plain feat: (which the release pipeline interprets as a MINOR bump) without the ! marker. Using feat!: would trigger an unintended MAJOR version bump in Conventional Commits / semantic-release. PR body:
- Link the
#f0-support promotion thread.
- Document Phase 4 evidence (≥3 teams, 60-day window, quality gate output).
- Confirm Foundations approval.
5.8 — Announce
After merge:
- Post in
#f0-support Slack with a short changelog entry.
- Confirm the component appears with
Stable badge in the Component Status table on next nightly regeneration.
Response time
An F0 designer + Foundations engineer respond to promotion requests based on team availability and as quickly as possible — we don't commit to a fixed SLA today, as it depends on team size and current focus. For urgent or blocking cases, ping #f0-support in Slack.
Common pitfalls
- Promoting on time alone — there is no time minimum; only the demand + maturity axes matter.
- Skipping cross-repo search — local
rg only checks the design-system repo, which has zero product consumers. Always use GitHub code search across factorialco.
- Forgetting
CODEOWNERS — the original team will keep getting bug pings.
- Forgetting to remove
experimentalComponent() wrapper — consumers will see the warning forever.
- Updating story title — keep
"Components/F0Name", do not rename.
