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.

PR Templates: The Pre-Filled Form That Makes Every Design System Change Easy to Review

Learn what a pull request template asks for, how its checklist protects quality, and how to keep the template short enough that people really fill it in.

In short

A pull request template is a pre-filled form that asks for the details and checklist a reviewer needs, kept short enough that people really fill it in.

13 min readFree

What you will learn

In a design system, many people change shared parts such as buttons, dropdowns, and modals. Each change is proposed in a request that reviewers read before it is accepted. This lesson explains the pre-filled form that shapes those requests, called a PR template. You will learn what the form asks for, how its checklist protects the quality bar, how a real fix uses it, and how to keep the template useful over time.

Key words

Design system
A shared set of parts, rules, and guidance that teams use to build consistent products.
Pull request (PR)
A formal request to add a proposed change to a shared project. Reviewers read it before the change is accepted.
Template
A ready-made starting text. Its blank prompts are filled in by the person who uses it.
Maintainer
The person or small team that looks after a shared project and decides what gets accepted.
Reviewer
A person who reads a proposed change and checks it before it is accepted.
Quality bar
The minimum standard every change must meet before it is accepted.

What is a PR template?

A PR template is a pre-filled form. When someone opens a pull request, the form appears in the description box with headings and prompts already in place. The author types their answers under each heading. Many code platforms, including GitHub, support this. The template is usually saved as a text file in the project, so every new request starts from the same shape.

The purpose is simple. Reviewers need to know what changed, why it changed, and what was checked. When every request answers those questions in the same order, a reviewer can scan it in seconds. Without a template, one author writes a long paragraph, another writes one line, and a third forgets to say whether an existing product will be affected. The reviewer then has to ask questions before they can even start.

A template does not decide whether a change is good. It only makes sure the information needed for a decision is present. A design system team uses it to be fair too. Every contributor, new or experienced, is asked the same questions, so no one is judged on how well they guessed what the team wanted.

Tip

Think of a PR template as a checklist for the author, not a test for the reviewer. Its job is to help the author explain their change so the reviewer does not have to guess.

What does the template contain?

Most design system templates share the same core parts. The exact wording and the sections change from team to team, and sources differ on which parts matter most. Each one answers a question a reviewer will ask.

  • Summary of the change

    A short description of what is different after the change. One to three plain sentences is enough. For example, the button now has a visible focus ring. Some teams also ask for the reason, so the reviewer knows the problem being solved.

  • Linked ticket

    A link to the task or issue that asked for the change. The ticket holds the background, such as who reported the problem. The template only needs the link, so the reviewer can open the full story if they want it.

  • Type of change

    A set of tick boxes that says what kind of change this is. Typical choices are a new feature, a bug fix, a breaking change, or a documentation update. This one choice tells the reviewer how careful to be and who else may need to look.

  • Screenshots or before and after visuals

    Pictures of the part before the change and after it. For a design system, this is often the fastest way to show a visual change. Reviewers can compare the two images without reading a single line of description.

  • Short checklist

    A few tick boxes the author confirms before asking for review. These boxes point to the quality bar, which is explained in the next section. Keep the list short, because a long list is often ticked without being read.

Some templates also ask how the change was tested, or which products are affected. These are useful, but they should be added only if the team reads them. Start with the five parts above, and add more only when reviewers keep asking the same question.

Key words

Before and after visuals
Two pictures of the same part, one from before the change and one from after, placed side by side or one under the other.
Breaking change
A change that makes existing products stop working as they did, so teams must update their own work to keep it running.
Non-breaking change
A change that keeps existing products working as before, so no one has to update their work.

Type of change: new component, fix, or breaking change

The type of change tick box is the part of the template that does the most work for a reviewer. A common set of choices is a bug fix, a new feature, and a breaking change. Some teams add refactoring, which means the code or design is reorganized without changing how it looks or behaves, and documentation updates. The author chooses one or more options, and unused options are removed so the form stays clean.

  • New component or feature

    Adds something that did not exist before. It is usually non-breaking, because no current product depended on it. The reviewer still checks that it follows the rules and names of the system.

  • Fix

    Corrects something that was wrong, such as a button that cannot be reached by keyboard. A fix is usually non-breaking if it keeps the same names, options, and sizes that products already use.

  • Breaking change

    Changes something that existing products rely on. A renamed option or a removed part is a common example. These changes need the most care, a clear explanation, and a plan for teams to update.

Quick check

A contributor adds a brand-new Toast style for success messages. No product uses it yet, and every existing Toast looks and behaves exactly as before. Which type of change should they tick?

What are the checklist and the quality bar?

The checklist is where the template connects to the quality bar. Each tick box stands for a standard the whole system has agreed to meet. When the author ticks a box, they are saying that the standard was checked for this change. A reviewer then knows where to look first, and can trust that the basics are already done.

  • Docs are updated

    The written guidance for the part matches the new behavior. If a button now has a new state, the page that describes its states must show it too. If no guidance changed, the author should say so.

  • Accessibility was checked

    Some teams write their accessibility checks into the design system guide, so the checklist simply points there.

  • Tests pass

    Any automatic checks set up for the project have run and passed.

  • Design files match the code

    The design file that designers use shows the same thing that the built part does. If they drift apart, the next designer who copies the part will get the wrong result.

A single unchecked accessibility problem in a shared button can reach every screen that uses that button at once, so the checklist prevents that kind of spread.

Tip

Keep checklist items as questions the author can answer yes or no, such as 'Did I check keyboard access?' Vague items like 'Looks good' give reviewers nothing to rely on.

How do you check the checklist honestly?

A ticked box is only useful if the work behind it was really done. Templates can be filled in quickly without any real check. Reviewers should look for evidence: a screenshot, a test result, or a link to the updated guide. If the evidence is missing, the review is not finished, even if every box is ticked.

Quick check

A contributor changes the colour of a Badge. They tick 'Tests pass' and 'Accessibility checked', but the screenshot section is empty and the design file has not been updated. What should the reviewer do first?

Worked example: fixing the focus ring on a Button

Here is a realistic case, described as a walk-through. A contributor works on a company design system. Its Button has a focus ring, which is the outline that shows which control is active when someone moves through the page with the Tab key. The ring is too faint to see on the company's light background. The contributor fixes it and opens a pull request. The template guides every step.

  1. 1

    Link the ticket

    The contributor pastes the link to the bug report that described the faint focus ring. The reviewer can now read the original problem and see who asked for it.

  2. 2

    Write the summary

    In two short sentences, the contributor says that the focus ring on the Button is now stronger and easier to see. They say that nothing else about the Button has changed.

  3. 3

    Choose the type of change

    The contributor ticks Fix and marks the change as non-breaking. The names, sizes, and options of the Button stay the same, so existing products need no update.

  4. 4

    Attach before and after screenshots

    They add two images of the same Button in the same state, one from before the fix and one from after. The reviewer can compare the ring at a glance.

  5. 5

    Tick the checklist

    The contributor presses Tab through a sample page and confirms the ring is clear. They tick 'Keyboard focus verified'. They also confirm that the guide for the Button already describes focus correctly, so no docs change is needed.

When the reviewer opens the pull request, every question is already answered. They know the problem, the type of change, what it looks like, and what was checked. Their review can focus on whether the new ring is strong enough and whether it matches the design file. The template did not do the reviewing, but it made the review quick and fair.

How do you write and maintain a good template?

A template is a living tool. A team writes it once, then improves it as people use it. The goal is a form that people actually complete. A long, unread form is worse than no form, because it teaches people to click past every heading. The four habits below keep a template useful.

  • Keep it short

    Ask only for information that changes a review decision. Many experienced teams cap a template at a small number of prompts, because each extra prompt makes the form feel more like paperwork.

  • Use clear prompts

    Each heading should be a question or a plain instruction. 'What changed and why?' works better than 'Description'. Add a one-line hint only where people often get stuck.

  • Adapt it for each change type

    A visual change needs screenshots. A breaking change needs a note about which products must update. A documentation-only change does not need a testing section. Some teams keep one template per change type, so the right form appears for the right request.

  • Revise from reviewer feedback

    Reviewers are the best judges of whether the form helps. When they keep asking the same question, add a prompt. When a prompt is always skipped or always blank, remove it or rewrite it.

  1. 1

    Collect the questions

    Over a month, note every question a reviewer asks that the template did not answer. Also note every blank section.

  2. 2

    Propose one small change

    Change one thing at a time, such as adding a prompt about affected products. Small edits are easy to judge.

  3. 3

    Trial it

    Use the new version for a set period, then compare. Did reviews get faster, and did authors fill in more sections? If not, go back to the old version.

  4. 4

    Keep what works

    Keep the change only if it made reviews clearer. Then share the updated form so every contributor sees the same version.

Tip

Treat the template like the design system itself. Propose changes to it, test them, and keep only what improves the work. A template that nobody fills in is a broken tool, even if it looks complete.

Putting it together: the renamed Modal prop

Now consider the problem that a good template prevents. A teammate opens a pull request that renames one option on the Modal component. The option controls whether the Modal can be closed with the Escape key. They leave the template blank. The reviewer cannot tell whether existing products will break, because the renamed option may still be used in them. The review stalls until someone answers questions that the template should have asked.

Quick check

The renamed Modal option is the only problem here. Which template parts would have prevented the confusion, and why?

Summary

A PR template is a pre-filled form that shapes every proposed design system change. Its core parts are a summary, a linked ticket, a type of change, before and after visuals, and a short checklist. The checklist links the template to the quality bar: docs, accessibility, tests, and design files. A good template stays short, uses clear prompts, adapts to each change type, and changes when reviewers say what is missing. When these parts work together, reviewers can judge a change quickly and fairly, and every product that depends on the system stays safer.

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.