I shipped a component foundation from scratch: layout primitives, theme, color palette, interactive documentation. Eight months later, other teams are extending it, and other developers have written its tests.
What matters to me is that others use it without me. Here are the choices that helped.
A semantic palette, not a list of colors. A component doesn't say "use this green", it says "use the action color". Changing the theme then happens in one place.
A typed palette. If roles are typed, you can't use a role that doesn't exist: the editor refuses it before you even run the app.
// generic example const palette = { text: { primary: "#1a1c1b", muted: "#5a5f5c" }, action: { default: "#0b7a5b" }, } as const; type TextTone = keyof typeof palette.text; // "primary" | "muted" Contrast fixed in the palette itself. Light grey text on a white background looks nice and is unreadable. Fix the contrast once, in the palette, and it's fixed everywhere. For body text, the target is a ratio of 4.5 to 1.
Interactive documentation. A component you can't try without running the application won't get reused. The documentation shows each component in each of its states, and doubles as a visual check.
What I aim for with a foundation: a developer on another team can use it without asking me anything.
Amine Affif, full-stack developer in Paris. amineaffif.com
