No raw hex: why every colour goes through one door

There is a moment on every ageing project where someone asks "can we just make the blue a bit darker?" and the honest answer is "define which blue, in how many files." That moment is avoidable. You avoid it by deciding, early, that no colour, space, or type size is allowed to be written as a raw value anywhere in the app.

In this studio that is a hard rule: no raw hex in the application code. Every colour is a token.

A token is just a named value with a job

Strip away the jargon and a design token is a variable with intent. Instead of #00e5ff scattered across forty components, there is one --color-electric-blue, defined once, referenced everywhere. The hex literal lives in exactly one place — the tokens file — and nothing else is allowed to know the actual number.

The payoff is not tidiness for its own sake. It is leverage. "Make the blue darker" becomes a one-line change in one file, and the whole site moves together, in step, with no stragglers. Themes, dark surfaces, a rebrand — all become edits to the source of truth instead of archaeology across the codebase.

The rule has teeth or it has nothing

A convention everyone agrees with and quietly ignores is worse than no convention, because it lies about consistency. So this one is enforced, not hoped for: raw hex in application code is flagged and blocked, the same as any other defect. Literals are only legal in the token definitions themselves.

There is exactly one principled exception, and it proves the rule. The social share-card images are generated by a renderer that cannot read CSS variables — it paints to a raw image, so it genuinely needs the literal values. That exception is written down, explained, and contained. Everywhere a browser does the painting, the variable wins.

Semantic names beat decorative ones

The other half of the discipline is what you name things. A class called blueBox ages badly the day the box turns pink. A class called container never does. So names describe the structural role, not the current appearance — surface, border, eyebrow, not darkPanel, thinGreyLine, smallCaps. The same goes for type: I would rather reach for a semantic type class that means "display heading" than hand-set a font size and lose track of why.

It feels pedantic right up until the redesign, when it is the difference between an afternoon and a fortnight.

Why this matters to you, not just to me

If you have ever been quoted a frightening number for a "small" visual change, this is usually why: the previous build hard-coded its values, so nothing can move without everything being hunted down by hand. A site built on tokens stays cheap to change for years — which is the whole point of owning it.

That maintainability is something I build in from the first commit on every website project, because it is what makes a site a long-term asset instead of a slow liability. If you are weighing up a build or a redesign and want it to stay easy to live with, book a free intro call.