Marcus Andrey Study
Ler em português Library

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. TextField with type="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
A filled-in contribution request. It brings the need and the evidence, not a finished design, so the triage can still say "use what exists" without wasting anyone's work.Example: Marcus Andrey, CC BY 4.0. People and products are fictional.

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:

  1. What's the need, in the user's terms?
  2. What's the evidence: where does it show up, how often, what goes wrong?
  3. Who else needs it: is it more than one team or product?
  4. 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

CheckQuestionFindingResult
UsableTested with people who will use it?4 sessions with port staff, 3 with app users. Nobody got "12" again.Pass
ConsistentUses Harbour tokens and components?Buttons are Button secondary sm. One raw #2A6FC9 left in the focus style.Fix
VersatileWorks in both products and both densities?Comfortable and compact both checked; works in dark mode.Pass
KeyboardFollows the APG spinbutton pattern?Up and Down work. Home and End don't jump to min and max yet.Fix
Screen readerName, value and limits announced?"Adults, 2, spin button". The + and − are hidden from the accessibility tree, the field does the work.Pass
Target sizeAt least 24 × 24 px (WCAG 2.5.8)?32 px in compact, 44 px in comfortable.Pass
DocsDoc page, Figma component and Storybook story?Figma and story done; doc page missing "When not to use".Fix
The review of the same proposal, eight weeks later. Decision: accept with three changes, ship in 3.7.0. Every "Fix" names exactly what to change, so the contributor isn't left guessing what "not quite there" means.Example: Marcus Andrey, CC BY 4.0. Criteria: GOV.UK Design System (usable, consistent, versatile), WAI-ARIA APG spinbutton pattern, WCAG 2.2 SC 2.5.8.

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.

  1. Replace #2A6FC9 in the focus style with color.action.primary.
  2. Home and End should set the minimum and maximum (APG spinbutton).
  3. 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

  1. The system team merges, versions and publishes the Figma library and the package together (see Versioning and releases).
  2. The changelog line names the contributors.
  3. The doc page links the research.
  4. The original request is closed with a link to the release, so the next person searching finds it.
  5. 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?

Contribution models · Accessible components · Component docs people use · Versioning and releases · Design critique in practice

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close