What a design token is #
Your website uses the same values in hundreds of places: the same text colour, the same gap between two sections, the same rounding on the corners. A design token is one of those values with a name. It sits in one central place, and every other place asks for that name.
The benefit shows up the first time you change something. If you want a different accent colour, you change one value and every button, every link and every active state follows. Without tokens the same job is a search through every file, and you reliably miss three places.
That is why every template follows the same rule: colour values, corner radii and spacing live in the tokens, not in individual pages. A colour you write straight into a page works there immediately and stays behind at the next change. Those stray values usually surface months later, often in dark mode.
Your template ships these groups of tokens above all.
- Surfaces. The page background, cards, boxes and set-apart bands.
- Text. Usually three levels: strong for headings, normal for body text, quiet for side information.
- Lines. Dividers, card borders and form field borders.
- Accent. Your one signal colour, together with its variants for hover and light surfaces.
- Shape. The corner radii and the spacing ladder between sections.
- Type. The family and the size steps.
Looks are changed through tokens. Write a colour straight into a page and you have created a place that gets forgotten at the next brand change.
Show me every design token in this project as an overview: file, name, value and what the token is for. Tell me as well whether there is a dark version and where it sits. Change nothing, just list it.
Where the tokens live #
There are two kinds of template, and this is exactly where they differ. One look inside your project folder tells you which one you have. What else lives where is covered in the chapter Inside your template.
Template with a folder called src
The tokens sit in the token block at the very top of src/styles/global.css. Below it, in the same file, comes a second block for dark mode. It gives the same names different values.
Template without a folder called src
The tokens sit in the :root block of assets/css/style.css, also in the upper part of the file. There is no build step here, so your change is visible as soon as you reload.
- src/styles/global.css · tokens in a template with a build step
- assets/css/style.css · tokens in a static template
- styleguide.html · the same system to look at
Both files are built the same way. The values sit at the top, the building blocks that use them sit below. You work in the upper part. Everything further down is the machinery, and it runs best when you leave it alone.
| Role | Typical names | What depends on it |
|---|---|---|
| Base surface | page, bg, cream | The background of every page. The largest surface, and therefore the strongest single change to the overall look. |
| Raised surfaces | card, paper, surface | Cards, boxes, form fields and anything meant to lift off the background. |
| Text | ink, fg, muted | Headings, body text and side text, usually in three levels of the same colour. |
| Lines | border, line | Dividers between sections, card borders and the borders of input fields. |
| Accent | accent, blue, terra | Buttons, links, active states and focus rings. The colour visitors remember as your brand. |
| Radii | radius, radius-card | How rounded cards, buttons, images and input fields are at the corners. |
| Spacing | space, gap | The gap between sections and the air inside cards. |
If you find a colour code like #c46f4d in a page file, it is almost always a leftover. Have it replaced with the matching token, otherwise that one spot keeps the old colour at the next change.
Changing the colour #
Every template comes with exactly one accent. It is the colour of the buttons, the links and the active states, and it is the part of your website visitors remember. Changing it is the single most common design request.
The change runs through the token, not through the places where the colour appears. The difference is not convenience, it is completeness. Through the token you also catch the states you never see while clicking around, such as the focus ring for keyboard users or the highlight behind selected text.
An accent is rarely a single value. Usually it is a small family: the base tone, a darker version for hover, a very light tone for surfaces and sometimes a brightened tone that still glows on dark bands. You set that family together, otherwise the hover state no longer matches the base tone after the change.
Change the project's accent colour to [enter your colour here]. Change the complete accent family in the tokens, meaning the base tone, the hover tone, the light surface and the tone for dark surfaces, and the matching values in the dark version as well. Then tell me which places outside the tokens you brought along, such as the favicon, the browser bar colour and text selection. Finally check the contrast values in both versions.
A few places carry the colour outside the stylesheet. They do not stand out at first glance and they look wrong as soon as somebody takes a closer look.
- The favicon. The small image in the browser tab is its own file and often carries the accent.
- The browser bar colour. On a phone the bar above the page takes on a colour. That value sits in the page head, not in the stylesheet.
- Text selection. Whatever a visitor selects with the mouse is highlighted in the accent colour.
- Decorative graphics. Patterns, gradients and moving backgrounds sometimes take their colour from a script rather than the stylesheet.
- The sharing preview image. Anyone sending your link through a messenger sees an image that may still show the old colour.
The wish for a second signal colour comes up almost every time, and it breaks the design almost every time. Two accents cancel each other out, because the eye can no longer tell which is the most important button on the page. If you want more variety, take it from surfaces, sizes and spacing. A split that holds up: about 60 per cent calm base surface, 30 per cent raised surfaces, at most 10 per cent accent.
Check contrast instead of guessing #
A colour can look good on your screen and still be unreadable: on an older laptop, in daylight outdoors, or for eyes that perceive contrast less strongly. There are fixed numbers for this, and they are the reason some colour wishes get nudged slightly during implementation.
The values come from the accessibility guidelines and count as a floor, not as a target.
- Body text: at least 4.5 to 1 against its surface.
- Large text from about 24 pixels, bold from about 19 pixels: at least 3 to 1.
- Interface elements: borders of buttons and fields, icons and focus rings at least 3 to 1 against the neighbouring colour.
Guessing does not work here. Mid tones are especially deceptive. Orange, yellow green and turquoise look strong and still fail as a text colour. Let your AI do the maths instead of debating the impression.
Check the contrast values after my colour change. Calculate the value for every important pair: body text on the base surface, body text on cards, side text on all surfaces, button labels on the accent, the accent as a link colour in text, and light text on dark bands. Check this in the light and in the dark version and name every value below the threshold with a concrete fix.
If a tone fails, it gets pushed lighter or darker until it passes. It keeps its role. Some templates solve this more elegantly and carry two versions of the same brand colour: a strong one for surfaces and a darkened one for text. Both ways are clean, what matters is that the text stays readable.
An error in a form must not be red only, a link must not be coloured only. Both need text, an icon or an underline as well. Anyone who informs through colour alone loses every visitor who cannot tell the colours apart.
Light and dark, both versions #
Many templates ship both versions. A switch in the header moves between them, the browser remembers the choice, and on a first visit the device setting decides.
Technically the dark version is a second token block in the same file. It gives the same names different values. That is exactly why dark mode works at all: the building blocks still ask for the text colour, they simply get a different answer.
Dark is not an inversion of light. Pure white on pure black flickers while you read, and an accent colour that looks rich on white often sinks into a dark background. That is why the dark version has its own deliberately chosen values.
For you that turns into a habit: every colour change gets looked at in both versions, not in one. The most common mistake is an accent that sits well in light and stays too dark in dark mode.
If something looks wrong in dark mode, the cause is a token value and not the individual card. Correct the value in the dark block. An exception rule for one card solves the problem for today and creates two new ones for the next change.
Changing the typeface #
One typeface family is enough for most websites. Differences come from weight, size and letter spacing, not from a second family. Some templates deliberately use two, one for headings and one for body text. Anything beyond that looks restless and costs extra loading time.
The second point weighs more than taste. Fonts live in your project and load from your own address, never from someone else's server. If you embed a font through an outside service, every visitor's browser sends their IP address there before anyone has agreed to it. A regional court in Munich awarded damages in one such case in 2022, and a wave of warning letters followed. How that applies to your site is a question for your own legal advice. Fonts stored locally never raise it.
Local is faster on top of that. Browsers now keep their cache separate per website. An outside service saves you nothing any more and instead costs another connection before the first letter appears.
What loading time costs
Every weight is a file of its own. Four weights in regular and italic are eight files. Take only the weights you actually use, use the WOFF2 format only, and preload at most one or two. The rest can follow as long as the page stays readable in the meantime.
What the licence requires
Not every typeface may be embedded as a webfont. Typefaces under the SIL Open Font License are free for commercial use as well and are therefore the simplest route. Purchased typefaces need an explicit webfont licence, often billed by page views. Copying a font file from your own computer is not a licence.
Change the project's typeface to [name of the typeface]. Take only the weights we really need, put them in the project locally as WOFF2 and embed them where the current typeface is embedded. No embedding through an outside server. Then tell me the licence of the typeface, the total size of the files and every place where the old typeface name was still standing.
Body text from 16 pixels on a phone, line height at least one and a half times the type size, line length around 50 to 75 characters. A typeface that cannot take those values is a typeface for headings, not for text.
Spacing and corners #
Spacing is the part of design with the strongest effect and the least conscious attention. In your template it comes as a ladder: a manageable number of fixed steps that repeat everywhere.
A ladder beats free values because free values multiply. First it is 20 pixels, then 22 because it looked tight in one spot, then 18 somewhere else. After ten changes the page has thirty different gaps, looks restless, and nobody can say why. With a ladder every decision offers only two options: one step up or one step down.
The same holds for corners on a smaller scale. Usually there are two values, one for cards and large surfaces and one for small elements. If you want the design softer, you change those values, not the individual card. The other route ends with buttons that have three different corners on three pages.
I want cards and buttons to look less rounded and the sections to get a little more air. Change both through the radius and spacing tokens, not on individual building blocks. Show me first which tokens exist, what values they have and which elements depend on each of them.
If a page feels cramped, the reason is rarely the content and usually the gap between sections. Go one step up the ladder instead of inventing a new value in between.
The styleguide in your browser #
Almost every template carries a file called styleguide.html in its main folder. It shows your design system in one view: the colour world in both versions, the type sizes, the buttons, cards and typical sections, all rendered with your website's real stylesheet.
It needs no build step. You open it in your browser and see the state of your system on one page. After a token change this is the fastest check there is. Instead of clicking through five pages and hoping, you see all the building blocks side by side.
The second purpose is communication. If you work with a designer, an agency or a colleague, send them this file. It is a complete briefing on your system and answers most questions before they come up.
This file does not belong on the server. It is an internal reference and serves no purpose for visitors. Exclude it when you upload, along with the explanation files, the knowledge folder and the skills. In some templates it already sits outside the folder that gets published, and then it takes care of itself.
In some templates the values in the styleguide are copied from the tokens by hand. If you change something there, bring the styleguide along. Otherwise your reference drifts away from your website, and then nobody trusts either of them.
Swapping logo and favicon #
Depending on the template, the logo sits as its own image file in the image folder, or it sits as a graphic directly in the page code. The second case is more common than people expect, and it has a consequence that surprises many.
If the wordmark sits as a graphic in the code, it is made of lines and curves rather than letters. A search for the old company name walks straight past it and reports zero hits, even though the name is clearly visible on every page. The same goes for names and numbers baked into an image. Ask your AI explicitly to search graphics as well, not only text.
The favicon is the small image in the browser tab and in bookmarks. It sits as its own file among the public files of your project and often carries the accent colour. If you change the colour, change it too, otherwise the old brand stays on exactly that spot.
Then there is the preview image that appears when somebody shares your link in a messenger or a social network. In many templates this is a picture of the invented persona as delivered. It belongs replaced before you go live, more on that in the chapter Going live.
Swap the logo for my file [path to the file]. Find every place the current logo appears first, explicitly including the places where it sits as a graphic in the code rather than as an image file. Think of the favicon, the sharing preview image and the single-colour version for dark surfaces. List every changed place at the end.
One in full colour, one single-colour version for dark surfaces and a reduced mark for small sizes. Always keep some clear space around it, and never stretch the logo sideways to fill a gap.
The version number in a static template #
So that your website loads quickly, the browser stores the style file on the first visit and uses the stored version afterwards without asking again. In static templates this storage time is set deliberately long, in places a full year.
That is good for loading time and becomes a problem the moment you change the file. This is why every reference carries a version number, and that number is your job.
If you change assets/css/style.css or any other style or script file, raise the version number in the reference. style.css?v=12 becomes style.css?v=13, on every page that includes the file. Skip this and you see your change after a hard reload while visitors with a stored version keep seeing the old website for weeks. It looks like a mistake in your work, and it is not one.
Templates with a build step handle this for you. There every generated file gets a name with a checksum that changes along with the content. The browser treats the new file as a different file and loads it.
I have changed a style file. Raise the version number in the reference, on every page that includes the file. Then tell me how many files you touched and whether the old number is left anywhere.
What to leave alone #
Not everything that can be changed should be changed. These three areas are thought through in the template, and touching them costs more than it gives.
The motion system
Reveals on scroll, transitions and subtle effects run through one central system and a handful of markers in the code. That system checks in one place whether a visitor has asked their operating system for reduced motion, and then it stays still. Anyone building their own animations alongside it usually bypasses that consideration without noticing. More motion rarely makes a website better anyway, it quickly feels restless and slows reading down. Use the markers that are there instead of introducing new effects.
The grid widths
How wide the content runs, where it wraps and how many columns a section has is tuned across three device sizes. Widening one of them looks generous at a desk and creates a bar on a phone that can be pushed sideways. That is one of the few mistakes visitors notice immediately.
Restyling single components
A card that should look different from all the other cards is almost always the start of a system falling apart. After five such exceptions there is no system left, only a collection of special cases, and every token change reaches half of it. If one place really should be different, the better question is whether it becomes a new, named building block that then exists everywhere.
The same restraint applies to the type size ladder and the line heights. They are tuned to each other, and a single changed value has an effect in three other places you are not looking at while you change it.
The check after every change #
Design changes are quick to make and show their side effects where you were not looking. This round takes ten minutes and catches almost everything.
- The change sits in the tokens, not in individual pages
- Light and dark version have both been looked at
- Contrast values for the important pairs are calculated and clear the threshold
- Buttons checked at rest, on hover and with keyboard focus
- Form fields, error messages and hints still look right
- Checked at 390, 768 and 1440 pixels wide
- Nothing can be pushed sideways on a phone
- Favicon, browser bar colour and preview image carry the new colour
- The styleguide shows the same state as the website
- In a static template the version number has been raised
I have changed the design. Run the check: contrast values in both versions, buttons in every state including keyboard focus, form fields and error messages, sideways overflow at 390, 768 and 1440 pixels wide, and whether an old colour value is still sitting directly in a page. Give me a list sorted by urgency.
Once colour, type and spacing sit right, the frame is finished, and the rest is decided by what goes inside it. How to prepare your pages so people and AI assistants find you is covered in the chapter SEO and visibility.