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.

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.

12 min readFree

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.

Key words

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.

Key words

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

Key words

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

    Add the scope

    The change belongs to the Button component, so the scope is button. Put it in brackets after the type.

  4. 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. 5

    Add the reason

    Finish the line with the reason: 'to meet WCAG AA'.

  6. 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?

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?

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

    Choose one format

    Pick a pattern, such as Conventional Commits, and decide which types and scopes your team will use.

  2. 2

    Write examples

    Add good and bad examples from your own components. Examples teach faster than long rules.

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

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.