05
1 min read
Naming & structure
You called it brandColor2. Then btnBg. Then theRoundness. The third engineer has no idea which one to use.
A name has to encode the tier. color.primitive.blue.600 is a fact. color.semantic.primary is a decision. component.button.bg is a place. If you have to explain the name, rename it.
Same button on both sides. Only the names change — and whether you can read the tier.
Learn more
brandColor2?
btnBg?
theRoundness?
Learn more
color.primitive.blue.600primitive
color.semantic.primarysemantic
component.button.bgcomponent
btnBg tells you nothing about the tier. component.button.bg does. CSS writes the dots as hyphens. The next engineer can find it without asking you.
:root {
/* Dots in the system, hyphens in CSS: category.tier.role */
--radius-md: 8px;
--color-primitive-blue-600: #2563eb;
--color-semantic-primary: var(--color-primitive-blue-600);
--component-button-bg: var(--color-semantic-primary);
--component-button-radius: var(--radius-md);
}:root {
/* Dots in the system, hyphens in CSS: category.tier.role */
--radius-md: 8px;
--color-primitive-blue-600: #2563eb;
--color-semantic-primary: var(--color-primitive-blue-600);
--component-button-bg: var(--color-semantic-primary);
--component-button-radius: var(--radius-md);
}