Design Systems · Labs · 4 min read
Run a contribution review
A guided lab: take one contribution through triage and review. Read a request, decide if it's useful and unique, review the built work against a published checklist, and write a decision the contributor can act on. About two hours, alone or with two colleagues playing the roles.
The review is where a design system either earns contributors or loses them. A vague "not quite there" sends someone back to their product team with nothing to show for two sprints. A clear checklist, with findings that say exactly what to change, turns the same review into a release with their name on it. You'll run both stages of one review, with a real or invented request.
What you'll do:
- Read a contribution request and triage it
- Decide between accept, merge, park and decline
- Review the built contribution against a checklist
- Write a decision the contributor can act on
You'll need: a contribution request (a real one from your team, or the Harbour example below), the GOV.UK contribution criteria open in a tab, a document to write in, and if you can, two colleagues to play the contributor and a product reviewer. About two hours.
1. Read the request
Proposal: Quantity stepperOpened by Inês, staff console team · 4 March
- The need
- People set how many passengers, cars or bikes are on a booking. Today they type a number, or tap a custom + and −.
- Evidence
- Booking app: passenger picker on the search screen. Staff console: party size at check-in, vehicles at the ramp. In 5 check-in sessions, 3 staff typed "2" into the field and got "12".
- Who else needs it
- Both products, three screens. The cafe pre-order flow (planned) would be a fourth.
- Is it in Harbour?
- No.
TextFieldwithtype="number"is the closest; it has no buttons and no min or max shown. - What exists already
- Two versions in product code (screenshots attached), one with 28 px buttons, one with raw hex
#2A6FC9. - What I can give
- Design and research time for two sprints. Our engineer, Tomás, can pair on the code.
- Status
- Accepted for development useful and unique, triaged 11 March
If you don't have a real request, use this one. Before deciding anything, check that the request answers four questions. If one is missing, ask for it before triage, not after:
- What's the need, in the user's terms?
- What's the evidence: where does it show up, how often, what goes wrong?
- Who else needs it: is it more than one team or product?
- Is it already in the system, or close?
2. Triage: useful and unique
This is GOV.UK's proposal stage: useful means there's evidence that many teams or services would use it; unique means it doesn't replicate something already in the system. Pick one of four outcomes and write one line of reason:
| Outcome | When | Example line |
|---|---|---|
| Accept | Useful and unique | "Accepted: both products need it, nothing in Harbour does it." |
| Merge | Useful, but an existing component nearly does it | "Merged into TextField: we'll add a stepper variant." |
| Park | Unique, but only one team needs it now | "Parked: build it in the console's product layer; we'll look again when a second team asks." |
| Decline | Not useful, or already covered | "Declined: Notice with tone="warning" does this. Here's an example." |
The quantity stepper is useful (two products, three screens, a real error in research) and unique (TextField has no buttons and no visible limits), so it's accepted. Agree on a pairing: who from the system team works with the contributor, and when the review will be.
3. Review the built work
| Check | Question | Finding | Result |
|---|---|---|---|
| Usable | Tested with people who will use it? | 4 sessions with port staff, 3 with app users. Nobody got "12" again. | Pass |
| Consistent | Uses Harbour tokens and components? | Buttons are Button secondary sm. One raw #2A6FC9 left in the focus style. | Fix |
| Versatile | Works in both products and both densities? | Comfortable and compact both checked; works in dark mode. | Pass |
| Keyboard | Follows the APG spinbutton pattern? | Up and Down work. Home and End don't jump to min and max yet. | Fix |
| Screen reader | Name, value and limits announced? | "Adults, 2, spin button". The + and − are hidden from the accessibility tree, the field does the work. | Pass |
| Target size | At least 24 × 24 px (WCAG 2.5.8)? | 32 px in compact, 44 px in comfortable. | Pass |
| Docs | Doc page, Figma component and Storybook story? | Figma and story done; doc page missing "When not to use". | Fix |
At the publishing stage GOV.UK checks three things: usable (tested in research, including with people with disabilities), consistent (reuses existing styles and components) and versatile (works in a range of services). Add the checks your system needs. A review template:
## Review: <component>, <date>
Reviewers: <system team>, <product reviewer>
| Check | Question | Finding | Result |
|---------------|-----------------------------------------------------|---------|--------|
| Usable | Tested with people who will use it, incl. disabled? | | |
| Consistent | Only tokens and existing components? | | |
| Versatile | Every product, mode and density it's meant for? | | |
| Keyboard | Follows the APG pattern for its role? | | |
| Screen reader | Name, role, value announced? | | |
| Target size | At least 24 × 24 px (WCAG 2.5.8)? | | |
| Docs | Doc page, Figma component, story? | | |
Decision: accept / accept with changes / not yet
Changes: <numbered, each one specific>
Release: <version>
For the stepper, the keyboard row uses the APG spinbutton pattern: Up and Down change the value, Home and End go to the minimum and maximum if they're set, and focus stays in the field (WAI-ARIA APG, Spinbutton). Test it with a keyboard, not by reading the code.
4. Write the decision
Write it so the contributor can act without a meeting:
Accept with three changes, release in 3.7.0.
- Replace
#2A6FC9in the focus style withcolor.action.primary.- Home and End should set the minimum and maximum (APG spinbutton).
- Add "When not to use" to the doc page: for more than 10 items, use
TextField. Thanks, Inês and Tomás. Your names go in the changelog.
Each change is one thing, checkable, with the reason or the source. "Polish the focus state" isn't a change; it's a reason to schedule another review.
5. Release and close the loop
- The system team merges, versions and publishes the Figma library and the package together (see Versioning and releases).
- The changelog line names the contributors.
- The doc page links the research.
- The original request is closed with a link to the release, so the next person searching finds it.
- Note how long it took from request to release. Over time, that number tells you if your process is working.
6. Check your work
Reflection questions: If you played the contributor, which line of the decision helped most? What would make a product team want to contribute again?
Related
Contribution models · Accessible components · Component docs people use · Versioning and releases · Design critique in practice