Documenting and governing a system: the component page, versions, contributions

Design system documentation says when and how to use each component. Governance is the rules for change: statuses, versions, deprecation and contributions.

A system that can’t be used doesn’t exist

A good button can be made in an hour. For others to use it takes another day: to describe when to take it and how. Without a description a person either asks the author or makes a button of their own. A design system lives exactly as long as its documentation is clear.

The second half of the lesson is about what happens after launch. A system doesn’t end at its release: changes have to be made to it, and the people who use it must have guarantees. These are agreed in advance, and it is called the governance of a system.

The component page

Open the button page of GOV.UK from the sources. It is a model, and it shows what a good description is made of.

• A name and a live example. You see the component at once, not a retelling.
• When to use. One or two phrases about the purpose: to start an application or to save what was entered.
• How it works. Rules for use: the label, the alignment, ways to include it in markup.
• Variants. GOV.UK’s button has several: default, start, secondary, warning, inverse (for dark backgrounds), disabled, and a button group. Each has its own example and code.
• Wording. A rule for labels: write button text in sentence case and describe the action (“Save and continue”, not “OK”).
• Research. A short note with evidence: for example, that, in GOV.UK’s testing, green start buttons got more clicks.
• Changes. A history of versions and a link to help improve the page.

The principles it stands on:

1. Answer the person’s question at the moment of work. “Which button should I use for this?”, “Can I use a secondary one here?”
2. Show, don’t only tell. A live example and code that can be copied.
3. Write “when not to use”. It is the most valuable part: it prevents bad decisions.
4. Keep the documentation next to the code. In one repository, in Markdown, and then it is changed along with the component. Big systems have a showcase tool for this: Storybook shows every component in all its states and works as living documentation.

Check yourself: which part of a component page is the most valuable?

“When not to use”: it prevents bad decisions. And next to it a live example and the states.

Status and life cycle

Not everything in a system is equally reliable. So every part can have a status.

• Experimental. Tried in one place, and the rules may change. In GOV.UK this status is called “trial”: the part is released to gather feedback, and it becomes stable after six months if no negative feedback arrives. Carbon has a separate space for such work, Carbon Labs (for now only for IBM staff).
• Stable. Accepted into the system and maintained.
• Deprecated. Marked: it will soon be removed, and the replacement is named.

A new part is not added simply because someone wanted it. GOV.UK checks proposals against published contribution criteria (a proposal must be useful and unique), and in Carbon a new component has to go through a development lifecycle and a checklist (all categories of requirements must be completed before a part counts as done). A simple rule for a small project: make something a component of the system the third time you need it. Earlier is too early: you don’t yet know how the cases will differ.

Versions: an honest agreement

If a system changes, the people who have built on it must understand what awaits them. For this, versions are numbered by the rule of SemVer (semantic versioning): three numbers with points, major.minor.patch.

• Patch (1.4.2 to 1.4.3): a fix, the contract doesn’t change.
• Minor (1.4.2 to 1.5.0): something new was added, and the old keeps working.
• Major (1.4.2 to 2.0.0): a change after which something of the people’s breaks.

The difficulty is that a break is not only a change of code. Renamed a token? Major. Removed a component? Major. Made the default button larger? Also major: layouts fitted to the old size will shift. Play with the diagram: apply the changes and watch how the number moves.

Version 1.4.2 (major.minor.patch, starting from 1.4.2)

Rename the token color.accent to color.brandChange a token’s value: the accent a little darkerAdd a “Tooltip” componentFix: the focus on a button was not visible in the dark themeRemove the deprecated “Carousel” componentMake the default button largerFix a typo in a component’s description Start again

Every change is written in the changelog: the date, the version, what changed and what the user must fix. A good changelog is read before updating. GOV.UK’s button page has a “Recent changes” section and a link to the history of versions, and the GOV.UK Frontend project has a CHANGELOG file.

How a part is removed

You can’t delete a part in one day: you would break other people’s pages. The right order is called deprecation:

1. Mark the part deprecated in the documentation and in the code.
2. Name what replaces it, and write how to move over.
3. Record it in the changelog.
4. Keep it for a few versions.
5. Remove it in the next major version.

Check yourself: why can’t you just delete a component you no longer need?

Those who built pages on it would be left with a break and no warning. So it is first marked deprecated and kept for a few versions.

Who contributes, and how

Many people use a system, and proposals come from everywhere. It must be decided in advance how they are accepted. GOV.UK describes how its community can take part: propose a component or a pattern, share research, give feedback through GitHub discussions; the system’s team checks everything against the contribution criteria. There is also a list of upcoming components, a roadmap, a Slack channel for people in government and monthly community calls. Carbon says “anyone can contribute” code, design or documentation; new components go through the lifecycle and the checklist, enhancements are taken from a backlog, and bugs are fixed by an issue and a pull request.

For your project the simplest will do: one owner (you), a changelog and a deprecation rule, which you will write below.

Practice

Write a reference page for your project’s main-action button: when to use it and when not to, variants, states, wording, accessibility, a code example, a status and version, a changelog and a deprecation rule. It is a page you can show to anyone who will work on your site, an AI builder from the part on AI included: the clearer your rules are described, the better it keeps them.

What was wrong with 2014

In 2014 the documentation for styles was often kept in a separate wiki or a PDF, and it fell behind the code. A system had no versions at all: the site was updated “as a whole”, and nobody knew what exactly had changed. The habit of keeping a changelog and numbering versions by SemVer came to design from software development, and it is what tells a living system from a one-off piece of work.