Naming things after what they do

A component called Card will be used for everything that is rectangular. A component called ProjectSummary will be used for project summaries. This is the entire finding, and I have watched teams spend a quarter arriving at it.

Shape names invite misuse

When a name describes a shape, the only question a developer can ask is whether the thing they are building is that shape. It usually is. So the card accumulates variants: a card with an image, a card without padding, a card that is actually a table row. Six months later nobody can change the card, because changing it changes eleven screens that have nothing to do with each other.

When a name describes a job, the question becomes whether the thing they are building does that job. That question has a real answer, and the answer is often no, which is how you find out you need a second component before you have wrecked the first one.

The same applies to tokens

I no longer ship a token called grey-200. I ship line, and it happens to be a grey. The difference shows up on the day the palette changes: line survives, because hairlines still exist, while grey-200 has to be found in ninety places and reasoned about individually. A token named after its value is a value with extra steps.

Where it breaks down

Purpose names get silly at the bottom of the stack. There is no honest job-name for the third step of a neutral ramp, and inventing one — surface-tertiary-alt — is worse than admitting you are describing a shade. The rule I use: name by job until the name stops being obvious, then stop.

An easy test

Read the name to someone who has not seen the design. If they can tell you where it appears, the name is describing a job. If they ask which one, it is describing a shape, and you have not finished naming it.