esc
  • WorkflowsPages
  • Case studiesPages
  • Machine Learning FoundationsLearn
  • AI EngineeringLearn
  • AI Guardrails & Red TeamingLearn
  • UI/UXLearn
  • Design SystemsLearn
  • Production System DesignLearn
  • Book a callContact
  • Download ResumeContact
Let’s talk

I’ll build the agent for it.

Contribution Guidelines: How Anyone Proposes and Ships a Design System Change

The written rules that show anyone, inside or outside the core team, how to propose, build, and submit a design system change so it is reviewed and accepted smoothly.

In short

Contribution guidelines are the written rules that show anyone, inside or outside the core team, how to propose, build and submit a design system change.

13 min readFree

What you will learn

A design system is a shared set of parts and rules that many teams use to build products. The core team usually keeps it up. Sooner or later, though, someone outside that team wants to add a part, fix a bug, or improve the written guidance. Contribution guidelines are the written rules that tell that person how to do it. In this lesson you will learn why these rules matter, what a good guide holds, how a change moves from idea to merge, and how to keep the guide useful over time.

Key words

Contribution
Any finished piece of work that someone makes for a design system and that others can then reuse. It can be a fix, a new part, or better writing.
Contribution guidelines
The written rules that say how to propose, build, and submit a change so that it is accepted.
Core team
The small group that looks after the design system day to day.
Maintainer
A person who looks after part of the system and decides whether changes are accepted.
Proposal
A short written plan for a change. It says what problem the change solves and why it is needed.
Review
A check by the maintainers, using agreed criteria, before a change is accepted.
Merge
The moment an accepted change becomes part of the official system.
Code of conduct
A written promise about how people should treat each other when they work together.

Why does a design system need contribution guidelines?

No single group can judge every need or draw every part. <cite index="23-3">Central system team members cannot make all the decisions, design everything, and code everything.</cite> A good system therefore becomes a shared effort. One writer calls this <cite index="23-4">a federated community, opening the door to contributions far and wide.</cite> A community like that needs rules, or the help arrives in too many shapes to use.

  • Lower the barrier

    Newcomers need a clear way in. <cite index="17-3">Lowering barriers for others to contribute is treated as crucial, even while the central team keeps its expertise.</cite>

  • Keep quality high

    <cite index="1-1">GOV.UK says its contents must be of high quality and meet user needs, so every component and pattern must meet a set of criteria.</cite>

  • Less back-and-forth

    One system practitioner with more than ten years of experience says a first draft is almost never ready to merge. <cite index="16-6">A contribution has rarely been complete enough to merge straight away.</cite> Clear rules set the bar before the work starts, so fewer rounds of revision are needed.

Tip

Write the guide for the newest designer you can imagine. If that person can follow it alone, most reviewer questions will be answered before anyone has to ask them.

What counts as a contribution?

Before anyone follows a process, they need to know what counts. Under one common view, a contribution is any finished work from outside the core team that the system releases so others can reuse it. That work can be code, a design, a piece of writing, or a design file. <cite index="11-3">Each one is a measurable, tangible change that moves the system forward.</cite> A good guide names the main types it accepts.

  • Bug fix

    When a broken shared part gets repaired and accepted, the person who fixed it has contributed. <cite index="11-6">Merging a code fix for a defect is a contribution.</cite>

  • New component

    Designing a fresh interface part, or a new variant of one already in the system, is a major kind of design work. <cite index="19-9">Examples include leading the design of a new UI component or a new variation for an existing component.</cite>

  • Documentation

    Improving the written guidance for a part that already exists also counts. <cite index="19-10">Examples include expanding or editing documentation for existing UI components.</cite>

Tip

Name every kind of contribution in your guide, including design files and writing. If a designer sees only code examples, they may assume their work is not wanted.

What is the path from idea to merge?

Most good guides describe a clear path: start with the problem, check what already exists, write a proposal, research and build, ask for review, and merge. Each stage catches weak work early, before it wastes the time of both the contributor and the maintainers.

Why start with the problem and not the fix?

Good contributions begin with a clear need. Teams often jump straight to a solution, such as 'we need a new card layout', before they name the user problem behind it. <cite index="18-7">Teams often skip the underlying user problem and go straight to a proposed design.</cite> A guide should push contributors to name the problem first. A useful question is whether the problem is a one-off exception or something other products will meet too. <cite index="18-14">If a change is too specific to one product and cannot be generalized, the flowchart recommends building it locally rather than adding it to the central system.</cite>

Why check what already exists?

GOV.UK's criteria check two things. The first is whether a proposal copies something that already exists in the system. The second is whether it reuses shared styles and parts where that makes sense. <cite index="1-2">A proposal must not replicate something already in the Design System.</cite> <cite index="1-4">It should reuse existing styles and components where relevant.</cite> If the need cannot be met by what is already there, the next question is whether an existing part could be stretched safely to fit. <cite index="18-11">Consider whether an existing one could be safely extended.</cite>

Seven steps from idea to merge

  1. 1

    Raise the idea

    Share the problem with the team before you start building. Many teams use a shared chat channel for this, so others can help early. <cite index="15-8">Post the problem you are solving in the team's channel before you start work.</cite>

  2. 2

    Check the existing system

    Try the current parts first and note exactly where they fall short. This shows the maintainers that you looked before you asked for something new.

  3. 3

    Write a proposal

    For a new component or a large change, write a short proposal before you bring it to the wider community. <cite index="18-1">A proposal should state the gap it fills.</cite> It should also list the options you ruled out, the parts it might affect, and how it meets accessibility standards.

  4. 4

    Research and build

    <cite index="7-8">Ideas discussed in public may not have been tested.</cite> Before review, show with evidence that people can use the idea. Test it with the people who will use it, and keep notes.

  5. 5

    Ask for review

    Tell the maintainers that your work is ready. <cite index="4-8">The team uses its criteria to review the contribution.</cite>

  6. 6

    Discuss and revise

    Maintainers may ask for changes before the work goes live. <cite index="4-10,4-11">They invite you to meet and discuss the decision, and if they recommend changes, they help you make them.</cite>

  7. 7

    Final checks and merge

    The last stage covers final checks of the design, content, code, and guidance. Only then does the change become part of the system.

Who reviews, and how far the review goes

Not every change needs the same level of review. One public design system guide ties the route to the size of the impact. <cite index="15-11,15-12">Medium impact goes to the community channel, and high impact is raised with the system leaders.</cite> The community helps check fit, such as where a part belongs and whether it overlaps with something existing. It does not decide the design quality or whether the work can be built. <cite index="15-15">The community does not assess feasibility, which is the contributor's team's call, or design quality, which happens in design review.</cite>

Quality criteria a guide should set

A guide should describe what a finished contribution looks like. Four areas come up again and again in the sources. Each one protects the people who will reuse the work.

  • Design specs

    A builder needs enough detail to use the design without guessing. <cite index="12-10">That means naming the parts of the component, its design tokens (named design decisions such as colors or spacing), its states, its options, and how it behaves at different screen widths.</cite>

  • Accessibility

    Accessibility means that a part works for people with a wide range of abilities and situations. <cite index="12-5">Accessibility features should be added if they are missing.</cite>

  • Documentation

    A complete contribution includes written guidance. <cite index="12-3">That guidance includes examples of how to use the component and how not to use it.</cite> Good documentation saves reviewers from answering the same question again and again.

Tip

Documentation does not have to be perfect on the first try. Offer a template that contributors can copy, plus a short editorial guide. That lowers the effort needed to start.

Code of conduct and respect

A code of conduct sets out how people should treat one another. Open communities often give this job an owner. One governance guide notes that <cite index="28-3">a very active contributor community might form subcommittees that each take ownership of an issue area, such as community conduct.</cite>

Your guide should say what respectful behavior looks like, how to raise a concern, and who answers it. Write your own text rather than copying someone else's. Keep it short and clear. Respect also comes from framing. GOV.UK describes contribution as a spirit of collaboration. <cite index="6-7">Contributors should work in a collaborative spirit, because the design system is the product of a whole community.</cite> It also notes that <cite index="7-12">views in public discussions belong to individuals, not to the design system team.</cite>

Worked example: adding a missing error-message pattern

This walk-through is a teaching case. The designer and the error-message gap are invented, but each step follows the public GOV.UK process. Imagine a designer who finds that the system has no clear pattern for a common error on a form.

  1. 1

    Raise the idea

    GOV.UK invites people to say where its guidance is confusing or unclear. <cite index="6-1">You can raise this in the backlog discussions, on the cross-government chat, or by contacting the team.</cite> The designer posts the gap in the public discussion.

  2. 2

    Check for overlap

    The designer checks that no existing pattern already covers this case. The criteria say a proposal must not repeat something already in the system. <cite index="1-2">It does not replicate something already in the Design System.</cite>

  3. 3

    Share research evidence

    The designer runs user research on the error case and adds the findings to the discussion. <cite index="7-9,7-10">Research is needed to check that an idea works for a service. Findings go back into the relevant discussion.</cite>

  4. 4

    Meet the team

    The designer contacts the GOV.UK Design System team. <cite index="4-4">A team member arranges a kick-off meeting after the first contact.</cite> Together they plan the design, content, code, and guidance needed.

  5. 5

    Involve the community

    The designer brings in other people working on government services. <cite index="4-6">Involve people from the government design community in any work you're doing.</cite>

  6. 6

    Review by the team

    When the work is ready, the designer says so. <cite index="4-9">To arrange a review, tell the Design System team your contribution is ready.</cite> The team checks the work against its criteria and invites a meeting to discuss the decision.

  7. 7

    Pattern added

    If the team asks for changes, it helps make them. <cite index="4-12">This includes final checks or updates to the design, content, code, and guidance.</cite> When the pattern is published, <cite index="7-4">the team includes details of how and when it was tested in user research.</cite>

The guide did its job at each stage. It told the designer where to start, what evidence counted, who to contact, and what the review would check. Without those rules, the designer would have had to guess at each step, and the team would have had to explain them again and again.

How to write and maintain guidelines people use

A guide is only useful if people read it and follow it. Four habits help. Each one is drawn from how public design system teams describe their own work.

Use plain words and a short checklist

Write for people who are new to the system. <cite index="3-4">The GOV.UK Design System is for everyone, not just experts.</cite> The GOV.UK team also cuts any content that has no clear point or action for the reader. Keep each page focused on one job.

  • Is it needed?

    Does the proposal solve a real problem that more than one product might have?

  • Is it documented?

    Are the usage notes, the do and don't examples, and the design states written down?

  • Is it checked?

    Has someone confirmed the design works for users and meets accessibility needs?

Give first-timers a start-here path

Newcomers should not have to search for the first step. GOV.UK offers <cite index="7-3">introductory guides that help you get set up.</cite> It also places links at the end of each page under a 'Help improve this page' heading, so readers can see how to contribute from where they are. Put one clearly named start-here page at the top of your guide. It should link to the first three steps only, so a newcomer is never lost.

Name owners for each decision

A rule with no owner is hard to change and easy to ignore. GOV.UK asks a contributor to <cite index="4-5">identify a contact to work with in the Design System team.</cite> That person is the first point of help. Larger groups sometimes split ownership by area, as the subcommittee example above shows. Write down who owns each kind of decision, such as accepting a new component, approving a documentation change, or handling a conduct concern.

Update the guide from contributor feedback

A guide is never finished. The GOV.UK team says its internal playbook describes <cite index="9-5">the way things are done now, but that will change from time to time.</cite> Feedback is the main source of change. <cite index="3-1">Suggestions for improving guidance for a component or pattern can be shared with the team.</cite> Regular check-ins also help. <cite index="4-5">During a contribution, the team arranges a weekly catch-up to see how the work is going and whether support is needed.</cite>

Tip

Every quarter, list the questions reviewers answered most often. Turn the three most common answers into new lines in the guide. Then test the guide by asking a designer outside the team to follow it alone.

Test yourself

Try these two scenarios. Each one needs the ideas from this lesson to answer.

Quick check

A designer at your company built a custom date picker for one product. They want it in the shared design system but do not know where to start. Which part of the guidelines should they find first?

Quick check

The guide says nothing about whether a part must be useful to more than one product. The date picker works only in one product's booking flow. What is the most likely result?

Sources

How is this lesson?

Last updated on 17 November 2026

Learn with me

Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.