9 days ago•

Write a design system contribution guide that invites participation without lowering the bar

Views

11.6K

Copies

3.0K

Likes

927

Comments

Copy rate

26.0%

Prompt

You are the lead of a design system team at a [company_stage] company with [team_size] product designers and [eng_size] engineers. Write a contribution guide that makes it easy for contributors to participate while keeping the bar high.

Cover:

1. **Philosophy** — why contribution matters and what "good contribution" means here
2. **Types of Contributions** — token edits, new component proposals, accessibility fixes, documentation improvements, bug reports
3. **Before You Start** — prerequisites, where to check for existing work, how to avoid duplicate efforts
4. **The Proposal Stage** — what to include in a proposal, with a concrete template
5. **The Review Stage** — who reviews, criteria, typical turnaround, what rejection feels like
6. **The Build Stage** — code standards, accessibility requirements, visual regression tests, design tokens
7. **The Ship Stage** — documentation expectations, changelog conventions, office hours for adopters
8. **How to Disagree Well** — escalation paths, when to write a tech-spec-style ADR, when to let it go

Tone: warm, direct, confident. Treat contributors as capable colleagues, not strangers who need hand-holding.

Customise this prompt

Fill in 3 variables to personalise this prompt

Company Stage

Team Size

Eng Size

Preview

You are the lead of a design system team at a [company_stage] company with [team_size] product designers and [eng_size] engineers. Write a contribution guide that makes it easy for contributors to participate while keeping the bar high. Cover: 1. **Philosophy** — why contribution matters and what "good contribution" means here 2. **Types of Contributions** — token edits, new component proposals, accessibility fixes, documentation improvements, bug reports 3. **Before You Start** — prerequisites, where to check for existing work, how to avoid duplicate efforts 4. **The Proposal Stage** — what to include in a proposal, with a concrete template 5. **The Review Stage** — who reviews, criteria, typical turnaround, what rejection feels like 6. **The Build Stage** — code standards, accessibility requirements, visual regression tests, design tokens 7. **The Ship Stage** — documentation expectations, changelog conventions, office hours for adopters 8. **How to Disagree Well** — escalation paths, when to write a tech-spec-style ADR, when to let it go Tone: warm, direct, confident. Treat contributors as capable colleagues, not strangers who need hand-holding.

Example output

# Contributing to Atlas Design System ## Philosophy A design system is only alive if it's being used, challenged, and shaped by the people it serves. Every contribution — a fixed contrast ratio, a new component, a better-worded doc — is what keeps Atlas from becoming a museum. "Good contribution" here means three things: it solves a real problem you encountered in real product work, it generalizes beyond that single problem, and it takes future maintainers seriously. ## Types of Contributions - **Token edits.** Color, spacing, type, and motion token changes. Small in code, large in downstream impact. - **New component proposals.** A pattern you've built twice and would rather build zero more times. - **Accessibility fixes.** Always high priority. You do not need permission to file these. - **Documentation improvements.** Clarifying a usage section, adding a do/don't, fixing a broken example. - **Bug reports.** The fastest path to a fix is a tight reproduction and a screenshot. ## Before You Start Check the `#atlas-announce` channel and the open Proposals column on our project board. Search the repo for your idea — we've often taken a swing at it and learned something worth reading. If your work is likely to take more than a day, write a proposal first; we'd rather catch a misalignment early than rework a PR late. When in doubt, drop a message in `#atlas-hallway` — the team lives there. ## The Proposal Stage Use the proposal template: ``` **What problem are we solving?** One paragraph. Cite at least two places where you've seen this problem in product. **Proposed solution** Sketch, Figma link, or rough code. Real examples beat abstract descriptions. **Alternatives considered** At least two. Explain why this one wins. **Open questions** Things you're genuinely unsure about. ``` Proposals go in the repo's `proposals/` folder as a markdown file, or as a GitHub issue using the Proposal template. Either is fine. ## The Review Stage Proposals are reviewed twice a week by the Atlas core (three designers, two engineers). Turnaround: under five business days, usually faster. We review against four criteria: real problem, generalizes well, accessible by default, consistent with the rest of the system. If a proposal is rejected, you get a written explanation — never a shrug. Rejection here is a teaching moment, not a door closing. Most rejected proposals become a different, better proposal within two weeks. ## The Build Stage Code standards live in `CONTRIBUTING.md`. In short: TypeScript strict, tested against our accessibility test suite, visual regression tested via Chromatic, documented inline with JSDoc, and token-driven — no hardcoded hex values, no hardcoded pixel values outside of the token system. Every new component ships with a Storybook story covering at minimum default, hover, focus-visible, disabled, and error states. Motion must respect `prefers-reduced-motion`. ## The Ship Stage A contribution isn't shipped until it's discoverable. Every merged change requires a changelog entry following our conventional commits format, updated documentation with a usage example, and a short note in the next Atlas newsletter. For any component that affects existing product surfaces, join the next Atlas office hours (every Thursday, 3pm) to answer adopter questions live. ## How to Disagree Well Strong opinions are welcome — we'd rather know you disagree than discover a grudge in code review. If a disagreement persists past one round of conversation, write a short ADR (Architecture Decision Record) in `docs/adr/` laying out the tradeoffs; the Atlas lead makes the final call and documents the reasoning. If the lead is wrong, the system will show it within a quarter, and the ADR gives us the receipts to revisit cleanly. Sometimes the right move is to let it go for now and file it in `future-revisits.md` — good systems evolve, and shipped is better than perfect.

Prompt

Customise this prompt

Example output

Related prompts