# 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.

From "Design systems", a free course by Venkat R. Murty: https://designervenkat.online/learn/design-systems/pr-templates

## 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.

- **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.

- **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?

A. Breaking change, because the Toast component has been edited
B. New component or feature, marked as non-breaking
C. Bug fix, because a success message was missing
D. Documentation update only, because no code paths changed

**Answer:** B. The new style adds something new and leaves existing Toasts working as before. That makes it a new feature that is non-breaking. The breaking option is wrong because nothing existing was changed in a way that stops products from working.

## 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?

A. Approve the change, because the boxes are ticked
B. Ask for the missing evidence and the design file update before reviewing further
C. Remove the checklist from the template so the mismatch stops happening
D. Merge the change and fix the design file later

**Answer:** B. The reviewer should ask for proof and the missing design update before going on. A ticked box without evidence is not a finished check. Approving or merging first would let the mismatch reach products.

## 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. **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. **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. **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. **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. **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. **Collect the questions:** Over a month, note every question a reviewer asks that the template did not answer. Also note every blank section.
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. **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. **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?

A. Screenshots only, because a Modal rename does not change how the Modal looks
B. Type of change set to breaking change, plus a summary that names the rename and says which products must update
C. A single checklist box saying tests pass, because tests show whether products still work
D. The linked ticket only, because the ticket will explain every side effect

**Answer:** B. A rename can stop existing products from working, so the type of change must say breaking. The summary tells the reviewer exactly what moved and what each team must update. Screenshots or a test tick alone would not reveal that a product still uses the old name, and a ticket link does not replace a clear statement in the request itself.

## 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 to Write an Effective GitHub Pull Request Template (Hypertext Dispatches)](https://tenthirtyam.org/dispatches/2026/04/04/how-to-write-an-effective-github-pull-request-template/)
- [Pull Request Template: Best Practices and an Example (pyor.review)](https://pyor.review/blog/pull-request-templates)
- [Comprehensive Checklist: GitHub PR Template (Graphite)](https://graphite.com/guides/comprehensive-checklist-github-pr-template)
- [Pull Request Template: Free Examples for GitHub, GitLab (gitmore.io)](https://gitmore.io/blog/pull-request-template)
- [Pull Request Template: 8 Examples for GitHub and GitLab (Screensnap)](https://www.screensnap.pro/blog/pull-request-template)
- [A GitHub Pull Request Template for Your Projects (Embedded Artistry)](https://embeddedartistry.com/blog/2017/08/04/a-github-pull-request-template-for-your-projects/)
- [Pull Request Best Practices: Code Review, Templates, and Merge Strategies (InventiveHQ)](https://inventivehq.com/blog/pull-request-best-practices-guide)
- [GitHub PR Template Examples and Setup Guide (Everhour)](https://everhour.com/blog/github-pr-template/)
- [Pull Request Best Practices: How to Create Great Pull Requests (Axolo)](https://axolo.co/blog/p/pull-request-best-practices-how-to-create-great-pull-requests)
- [Design System CONTRIBUTING guide (Swisspost design system, GitHub)](https://github.com/swisspost/design-system/blob/main/CONTRIBUTING.md)
- [Contribution criteria (NSW Digital Design System)](https://designsystem.nsw.gov.au/docs/content/contribute/contribution-criteria.html)
- [Feature pull request with author and reviewer checklists (GC Design System, GitHub PR 1073)](https://github.com/cds-snc/gcds-docs/pull/1073)
- [Design QA: process, checklist, and catching UI drift (Modeinspect)](https://modeinspect.com/design-qa/guide)
- [Design and user interface changes contributing guide (GitLab docs)](https://docs.gitlab.com/development/contributing/design)
