This is for the designer who is the only designer on a team of engineers.

Ten small checks for design work, and what each one caught.

Ten checks73 rounds of changesVersion 1.1.0

A week

The checks were working. Nobody was reading them.

I had checks running on my design work. I thought they were doing their job.

They were. Two real problems had been sitting in the results for weeks: a link the same color as the page behind it, and fonts that had been wrong since a redesign.

Nobody looked, because the results were always noisy. A real problem looked exactly like the forty small ones I had decided to live with.

So I tested the checks themselves. Given nothing to look at, eight of them still answered “all clear”.

Then I fixed that. A check now shows only what you just changed, and “I could not look” is a different answer from “nothing is wrong”.

Ten skills

A design system is the shared set of buttons, colors and type a product gets built from. These ten keep it honest. Each starts with something that went wrong.

Nine of the ten are not public yet, so there is nothing to click. The line at the bottom of each card is what you say out loud to try it.

01ds-init

You open a project, run the checks, and every one says nothing. You cannot tell whether the project is fine or the checks are broken.

The project has the files the checks need, so silence means something.

Its own first version said three files were missing from a project that had all three. It had guessed where they should be instead of looking.

Try: “set this project up

02ds-start

You are about to build a filter. You looked around for ten minutes and you are fairly sure there is not one already.

Now you know, because the search is written down with what it found.

Last time it ran it found seven things already built that did the job. Nothing new got made.

Try: “start work on a filter

03bill-of-materials

A page is done. Someone asks how much of it came from the design system, and you shrug.

You can list every piece on the page and say where it came from.

It gives you counts, never a percentage. “41 reused, 6 built from scratch” tells you what to do next. “87%” does not.

Try: “what is this page made of

04atomic-composition

Two people build two buttons on two days. Side by side they do not match, and neither one is wrong.

Same parts, same sizes, same behavior. They fit together.

Its check reads five of the twelve rules and says so. The other seven need a real page on a screen.

Try: “does this button follow the system

05component-contract

You hand engineering a design with a button style that was never in the system. It gets built. It ships. Nothing looks broken.

One short file says what that button can be, and design and code both follow it.

When it cannot check something, it says so instead of saying it passed.

Try: “write down what this button promises

06design-contract

The page looks wrong. You read the code and the code is right.

You find out which promise got broken, and you have the proof.

Its whole point: broken design still looks like design. Nothing crashes, so nobody reports it.

Try: “check this page against the system

07design-token-vitals

A button shows a color nobody picked, and dark mode only works on half the screen.

You get a grade for the colors and sizes, and a list of what could not be checked.

Given no files at all, it used to answer “all clear”. Now “I had nothing to look at” is its own answer.

Try: “grade the colors in this project

08design-dna

You made one thing you loved. Ask for the same style again and you get close, then a bit off, then generic.

The look is written down, so you can make it again. Poster, deck, page.

It rebuilds your original from the notes and compares the two. On this site it caught three misses: a rounded tag that should have been square, an underline in the wrong color, and a caption that was not there.

Try: “write down this style so I can reuse it

09design-motion-principles

A hover effect felt fine on its own. Three components later it is a tic.

Every bit of movement has a reason you can say out loud.

Three of its six checks look for repetition rather than mistakes. One bounce is a choice. The same bounce three times is a habit.

Try: “review the animation here

10design-engineer

An engineer explains why something is hard. You nod. You did not follow a word of it.

You get the same thing in the words you already use.

It is the only one with no automatic check, and the reason why is written down next to it.

Try: “explain this in design terms

One job, start to finish

The request

Someone says: we need a way to filter the demos by category. Nothing else. No page named, no design attached.

This site already has 127 pieces built, more than anyone keeps in their head. That is the whole reason the looking comes before the building.

  1. ds-start asks three questions. Which part of the site is this? Is anything half-finished in the way? And does it already exist?
  2. bill-of-materials lists the pieces it will need and where each one comes from, before anyone builds anything.
  3. Most work stops here. The cheapest piece is the one already built. The expensive mistake is a second one nobody knew was a second one.
  4. If something really does have to be made, atomic-composition says how to put it together and component-contract writes down what it promises, so a change later has something to argue with.
  5. design-contract and design-token-vitals ask whether those promises are being kept everywhere else.
  6. design-motion-principles asks whether it moves well. A machine can settle half of that. The other half is whether you can say what the movement is for.
  7. Then a person decides whether it is any good. No machine answers that one, and none is coming.

Three rules, and the mistakes behind them

Each one came from a mistake. A rule with no story behind it is a preference, and preferences do not survive being inconvenient.

The mistake

  • I wrote “nothing uses this file” and moved it

One search found three things using it. Moving it would have broken all three.

The rule

  • Before you say something is unused, run the search and show what it found.

A wrong “unused” deletes something that matters. A wrong “used” costs you one search.

The mistake

  • A new check found 89 problems in a file that had none

The check read correctly on paper. Pointed at a file I already knew was right, it found 89 things to complain about.

The rule

  • Try a new check on something you know is good, before you trust it.

A check that cries wolf gets switched off, and then it catches nothing at all.

The mistake

  • A result came back with one warning and I almost let it go

I had written down what I expected first: 58 and 0. It came back 58 and 1. That 1 was real. The summary next to it said everything had passed.

The rule

  • Write down the number you expect before you run it again.

One warning looks like nothing. With a number to compare it to, it looks like what it is.

The checks, run on this page

Six checks, run on this page before it went up. These are the answers they actually gave. The last one took no reading at all, and that is the row worth reading.

colors and sizes typed by handWhere a name for the value already exists. One file read, none found.pass
names that point at nothingClean across the whole site. Pointed at this one folder it finds two, because the names live a level up. Look in too small a box and things seem missing that are not.attention
pieces match what they promiseThree promises checked against the built code. Three kept.pass
size is one setting, not fourThree checked. One passed, two could not be read, and that counts as open rather than fine.attention
only what this page addedCompared against the site as it was before this page. Two files changed, nothing new.pass
the running tally of old problemsNo reading taken. It could not find the thing it runs, so it stopped and said so, instead of reporting all clear over nothing. That is this whole page, happening to this page.blocked
3.5sto run the five that ranTwo runs on my laptop, 3.22s and 3.46s. The slower one is the number here, because that is the one to plan around.
49pieces reused, against 2 writtenThe two are a heading size and a lead-paragraph size, both already on the scale and neither one used before. Everything else on this page already existed.
2things only a person can checkWhether this reads plainly, and whether it looks right in light and dark. Both were done by eye, and saying so is the point.

One small ask

Pick one component you shipped this week. Run one skill on it.

If nothing useful comes back you have lost five minutes and you can stop. That is the whole ask. Not a new way of working. One piece of one screen.

One of the ten is public and needs nobody’s permission.

design-token-vitalsGitHubGrades the named colors and sizes a project is built from, says what it could not prove, and puts the fixes in order. 648 tests across 29 files.The rest of the work