# Commit Guidelines: Write Clear, Small Commit Messages for Your Design System

> Learn how a design system team writes commit messages that are easy to read, search, and trace, and why that helps everyone who uses the system.

**In short:** Commit guidelines help a design system team write commit messages that are easy to read, search and trace, which helps everyone who uses the system.

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

## What you will learn

Every time a team saves a change to a design system, it writes a short note about that change. This lesson teaches the rules a design system team follows when it writes those notes. The rules are called commit guidelines. They make every change easy to read, search, and trace, whether the change touched code or design files.

By the end, you will know how to write a clear summary line, when to add a body, how a shared format helps, why each change should be small, and how these notes feed the system's changelog.

- **Commit:** One saved change in the history of a project. Each commit records what changed.
- **Commit message:** The short note written with a commit. It tells readers what the change does and, often, why it was made.
- **Design system:** A shared set of parts, rules, and guidance that a team uses to build product screens in the same way.
- **Consumer:** A person or product team that uses the design system's parts in their own work.
- **Changelog:** A list of changes to a system, written in order, so people can see what changed over time.

## Why do commit messages matter?

A design system keeps a long history. Each commit is one entry in that history. A good message makes each entry useful. A weak message, such as one that only says the work is done, leaves readers guessing. Later, someone may need to know why a value changed. The message is often the only clue they have.

Commit messages are read by more than one kind of person. Each reader needs something different from the same note.

- **Reviewers:** A teammate reads the message before they read the change. A clear message helps them judge the work faster.
- **Your future self:** Months later, you may need to remember why a choice was made. The message should explain the reason, not only the steps.
- **Tools:** Software can read a well-formed history and build lists and summaries from it. Messages that follow a shared pattern are easier for tools to use.

## What are the parts of a good commit message?

A commit message has up to three parts. The first line is the subject line. It is a short summary. A blank line comes next. After that, an optional body can explain the change in more detail. Footers, which are short notes at the very end, can link to related work.

- **Subject line:** A one-line summary of what the change does. Keep it short, ideally under about 50 characters, which is the common guide for this line.
- **Body:** Optional. Use it when the summary cannot give enough context. It explains why the change was needed and any side effects.
- **Footers:** Optional. They usually point to a related issue, a related discussion, or another commit that the change depends on.

Some changes are small enough that a subject line is all they need. Do not write a long body just to fill space.

### How do you write the summary line?

The summary line is the part people read most. Most history tools show it first, so it must stand on its own.

- **Subject line:** The first line of a commit message. It is the short title for the change.
- **Imperative mood:** The command-style form of a verb, such as Add, Fix, or Remove. It tells the reader what the change does, like an order.

1. **Name the effect:** Describe what the change does to the system, not what you did to get there. The reader cares about the result.
2. **Start with a verb in the imperative:** Write 'Fix' or 'Increase', not 'Fixed' or 'Increases'. Git itself uses this form when it writes its own messages, so your history will match.
3. **Run the sentence test:** Read the line after the words 'If applied, this commit will'. If the sentence makes sense, the summary is clear.
4. **Keep it short and plain:** Aim for under about 50 characters. Leave off the final full stop. Use plain words that a new team member would understand.

### Why use the body to explain why?

Good commit messages focus on why a change was made. The code or the design file already shows how it was changed. A reader can compare the old and new versions to see the details.

Compare two messages for the same change. 'Change label color' only says what was touched. 'Make disabled labels easier to read on light backgrounds' gives the reason. The second message is the one that helps someone later.

> **Tip:** Ask yourself: if someone reads only this message, will they know why the change matters? If not, add a short body with the reason.

## What is the Conventional Commits format?

A team needs one shared pattern so that every message looks the same. Conventional Commits is a lightweight set of rules for writing commit messages. It adds a short label, called a type, before the summary.

- **Conventional Commits:** A public set of rules for writing commit messages in a standard pattern, with a type, an optional scope, and a description.
- **Type:** A short label at the start of the message that names the kind of change, such as feat for a new feature or fix for a bug fix.
- **Scope:** An optional label in brackets after the type. It names the part of the system the change touches.

The pattern is a type, an optional scope in brackets, a colon, a space, and then the description. The optional body and footers follow after blank lines.

- **feat:** Use it when the change adds a new feature. For a design system, this could be a new state on a button.
- **fix:** Use it when the change repairs a bug or a wrong behavior.
- **docs:** Use it for changes to documentation, such as 'docs: update ref docs'.

Conventional Commits also allows other types, such as refactor, style, and chore. Each one is a label for a kind of change. The main point is that your team uses the same labels every time.

> **Tip:** Write your chosen types and examples into a short guide that every contributor can read. Use the same language as the rest of your history, so the log stays consistent.

### Choose a scope for a design system

The scope tells the reader where to look. In a design system, a good scope is often the name of one component, such as button or tooltip. A shared area, such as icons or color, can also work as a scope. The specification describes a scope as a short noun that names a section of the codebase. In a design system, the same idea applies to a section of the shared library.

Keep one scope for each change. If a change touches two parts, it may be two commits, each with its own scope.

## Worked example: rewrite a vague Button commit

Imagine a design system team that has a Button component. Its shared button comes in several states, such as default, hover, and disabled. A teammate changed the color of disabled button text so it reads more clearly. They saved the work with the message 'fixed stuff'. A reviewer or a future reader cannot tell what changed or why. Here is how to rewrite it.

1. **Find the real change:** The change made disabled button text easier to read against the light background. Write down what changed in plain words before you type the message.
2. **Pick the type:** The change repairs a problem, so the type is fix. The specification says fix is the type for a bug fix.
3. **Add the scope:** The change belongs to the Button component, so the scope is button. Put it in brackets after the type.
4. **Describe the effect in the imperative:** Write the result as a command: 'increase disabled text contrast'. Contrast means how clearly text stands out from its background.
5. **Add the reason:** Finish the line with the reason: 'to meet WCAG AA'.
6. **Check the final line:** The result is 'fix(button): increase disabled text contrast to meet WCAG AA'. It has the type, the component, the effect, and the reason in one line. It is about 60 characters, a little over the 50-character guide. That guide is a goal, not a hard limit, so this is acceptable.

If the team wants more context, it can add a body. The body could say that disabled labels were hard to read on light backgrounds and that this change fixes that for everyone who uses the component.

> **Tip:** Before you save a commit, read the message as if you had never seen the change. If the message still makes sense, it is ready.

## Keep each commit small and focused

The message is only half the job. The other half is the size of the commit. Each commit should hold one change. A commit with one change can be reviewed, reverted, or understood on its own. A commit with five unrelated changes cannot be untangled easily.

Experienced teams often describe this as making atomic commits. An atomic commit is one that does exactly one thing. If you need to undo one part of your work later, a small commit lets you do that without losing the other parts.

**Quick check:** A teammate commits 'updates' after changing the Tooltip's arrow position, fixing its color, and renaming a prop, all at once. How should they have split and written these commits so the history is clear for the people who use the system?

A. Keep one commit named 'updates' and add a long body that lists all three changes.
B. Make three commits. Each one has a type and the tooltip scope, such as fix(tooltip) for the arrow and for the color, and a separate commit that describes the prop rename, all in the imperative.
C. Make one commit named 'fix(tooltip): many changes' so the history stays short.
D. Make three commits, all titled 'updates', so they stay grouped together.

**Answer:** B. Each commit then holds one change, and each message says what it does in the imperative with a type and a scope. Someone who uses the Tooltip can see that the prop was renamed, find the change fast, and revert one fix without undoing the others.

### Signs a commit is too big

- **The message needs 'and':** If the summary has the word 'and' in it, the commit probably holds two changes. Split it into two commits.
- **You cannot sum it up briefly:** If you cannot describe the purpose in a short line, the commit likely holds too much, or the goal was not clear before you started.
- **It mixes types:** A commit that adds a new feature and fixes a bug at the same time is hard to classify. Give each kind of change its own commit.

The habit of committing often helps. Small steps are easier to check and easier to undo.

## Why consistent messages matter for a design system

A design system has many consumers. Product teams import its parts, and each team needs to know what changed. Consistent messages support three goals.

- **Searchable history:** Clear types and scopes let people filter the history. They can look for every fix to the button, for example, instead of reading every line.
- **Clear notes for consumers:** A message that describes the effect on a component helps consumers decide whether to update. It tells them what they will see differently.
- **Automatic changelogs:** Tools can turn a consistent history into release notes, grouped by type. The team still needs to check and polish the result.

### How messages feed changelogs and release notes

Conventional Commits gives tools a clear signal.

The output is only as good as the input. If the messages say 'fix thing' or 'update stuff', the automatic changelog repeats those vague words. Automation can only pass along what people wrote.

A design changelog is a different document from the raw commit history. A raw history is a record made by the system. A design changelog is curated, written in plain language, and explains the intent behind each change. Automation helps build the draft, but a person should still review it before it reaches consumers.

> **Tip:** Never publish commit messages to users without reading them first. Use them as raw material, then rewrite the notes in plain language for the people who will read them.

**Quick check:** A design team's tool builds release notes from commit messages. A designer adds a new archive icon to the shared set. Which commit message will the tool and the readers handle best?

A. misc updates to icons
B. feat(icon): add archive icon to the shared set
C. Added new icon
D. icon stuff

**Answer:** B. The feat type marks a new feature, so the tool places it under new features. The scope shows which part changed, and the imperative line says what the change does. The other options are vague, or they use the past tense, which does not match the team's style.

## Common mistakes to avoid

- **Vague words:** Messages like 'fixed stuff' or 'updates' tell the reader nothing. Name the part of the system and the effect instead.
- **Too much in one commit:** A big mixed commit is hard to review and hard to undo. Split the work by change, and give each change its own short message.
- **Describing only the steps:** A message that lists what you did, not why it matters, leaves out the useful part. Lead with the effect, and add the reason in the body.

Watch for one more habit. Some people write in the past tense, such as 'Fixed the badge'. The team's style is the imperative, such as 'fix(badge): ...'. Consistent style makes the log easier to scan.

## Agree on the rules as a team

Commit guidelines only work when everyone follows them. A team should agree on the rules before the first commit, and then keep them up to date.

1. **Choose one format:** Pick a pattern, such as Conventional Commits, and decide which types and scopes your team will use.
2. **Write examples:** Add good and bad examples from your own components. Examples teach faster than long rules.
3. **Check messages in review:** Reviewers read the message as part of the review. If it is vague, ask the author to rewrite it before the change is accepted.
4. **Keep the language consistent:** Write every message in the same language as the rest of the history, so readers can search the whole record.

> **Tip:** Put the agreed rules in a short contribution guide, so new team members and outside contributors can read them on day one.

## Sources

- [Conventional Commits 1.0.0 (official specification)](https://www.conventionalcommits.org/en/v1.0.0/)
- [How to Write a Git Commit Message, by Chris Beams](https://cbea.ms/git-commit/)
- [Git Commit Message: The Rules, Examples, and Conventions (DataCamp)](https://www.datacamp.com/tutorial/git-commit-message)
- [How to Write Good Commit Messages: A Practical Git Guide (freeCodeCamp)](https://www.freecodecamp.org/news/writing-good-commit-messages-a-practical-guide/)
- [The art of writing meaningful Git commit messages (thoughtbot)](https://thoughtbot.com/blog/the-art-of-writing-meaningful-git-commit-messages)
- [Commit message guidelines (GitHub gist)](https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53)
- [Conventional Commits cheat sheet (Kapeli)](https://kapeli.com/cheat_sheets/Conventional_Commits.docset/Contents/Resources/Documents/index)
- [Best Practices for Git Commit Message (Baeldung)](https://www.baeldung.com/ops/git-commit-messages)
- [Commit Message Guideline, Developer Handbook (Stakater)](https://developerhandbook.stakater.com/git/commit-message-guidelines.html)
- [Best Practices to Make a Good Commit (DEV Community)](https://dev.to/wallacefreitas/best-practices-to-make-a-good-commit-writing-clean-effective-commit-messages-5eg9)
- [How to Create a Design System Changelog (UXPin)](https://www.uxpin.com/studio/blog/how-to-create-a-design-system-changelog/)
- [Design Changelog for Design Systems: Practical Template (Pinhub)](https://blog.usepinhub.com/blog/design-changelog)
- [How Engineering and Product Teams Can Automate Their Product Changelog Generation (Doc Holiday)](https://doc.holiday/blog/automate-product-changelog-generation)
- [Automating Your Changelog: Tools, Tips, and Best Practices (Changelogy)](https://www.changelogy.com/blog/changelog-automation-best-practices)
