Building Design Systems from Scratch: A Small Team Survival Guide

Every design system guide assumes resources we do not have. A dedicated team. Quarterly reviews with stakeholders. Interactive documentation. That is a system for Salesforce. We need one for a two-person consultancy shipping every six weeks.

We start every project with a Design Token Document -- a TypeScript file defining every visual decision. Colors, spacing, typography, radii, shadows, breakpoints. Takes two hours, saves dozens over the project lifetime.

Colors use semantic names, not generic ones. No "blue-500." We have "primary," "primary-hover," "destructive," "muted," "border." A developer never guesses which blue to use. Spacing follows a 4px base scale: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64. No other values allowed. Typography is named styles: heading-xl through caption, each specifying size, line-height, weight, and letter-spacing.

From tokens, we build a restricted Tailwind config. Default Tailwind values outside our tokens are unavailable. A developer cannot use bg-blue-500 because it does not exist. They must use bg-primary. This is automatic enforcement.

Components build atomically: primitives first (Button, Input, Badge), then composites (Card, FormField, Dialog), then patterns (PageHeader, DataTable, EmptyState). Each component accepts only defined variants. Button has four: primary, secondary, destructive, ghost. No "custom" variant.

We maintain the library as a local package in each project's monorepo, not a published npm package. We tried shared publishing and ended up with three projects on incompatible versions. Now each project starts from a template and diverges independently.

Documentation is minimal and co-located -- comment blocks in each component file. No Storybook. For two developers who built the components, inline docs are faster to write and reference.

Total investment: two hours for tokens, four hours for the base component set, thirty minutes per new component ongoing. About 15 percent of the first week, saving roughly 20 percent of total development time by eliminating ad hoc visual decisions.