Building Blocks, Not Pages

Build the same card three times across three pages and you have already lost. The drift is invisible at first — a slightly different radius on one, a tighter gap on another — and then one day every screen looks a little off and nobody can explain why. The page is the wrong unit of work. The component is the right one.

Compose, do not reinvent

The rule is simple enough to say and hard to follow: if a component exists, use it. A settings page is a Tabs plus a Card plus some form controls. A dashboard is a Sidebar plus a Card plus a Chart plus a Table. The moment you reach for a styled div to do something a component already does, you have started a second system. It will diverge from the first.

<Button variant="outline" size="sm">Cancel</Button>

Variants are a vocabulary. They let a designer and an engineer point at the same word and mean the same thing. A custom class is a sentence only one person can parse, and that person is usually on vacation when something breaks.

The cost of "just this once"

Every "just this once" becomes a precedent. The one-off bg-blue-500 becomes the brand color for a feature nobody owns. The hardcoded space-y-4 becomes the gap every new screen inherits without thinking.

A few habits prevent most of it:

• Use semantic tokens (bg-background, text-muted-foreground), never raw colors.
• Use gap-* with flex or grid, never space-y-* with block flow.
• Use size-* for equal dimensions, never w-* h-* pairs.

These are not aesthetic preferences. They are the difference between a system that scales and a pile of files that share a folder.

What you get back

When components are the unit, velocity stops being a function of how fast you can type and becomes a function of how well you can compose. A new page is an arrangement of things that already exist. A redesign is a change to a few tokens, not a rewrite of a hundred files. A bug fix in one place fixes it everywhere.

Build blocks, not pages, and the pages take care of themselves.