CSS & design systems

01The idea: decisions, not values

Think of a design system as the rulebook of a brand. A raw value like #0f62fe means nothing; a token like --color-accent tells you what it is for. Tokens usually come in two layers. Primitive tokens describe the palette (--blue-600, --gray-100). Semantic tokens describe purpose (--color-accent, --color-surface, --color-text-muted) and point at primitives. Components only use semantic tokens. That one rule is what makes theming and redesigns cheap: you change what --color-surface points to, and every card, modal and input follows. Tokens cover more than colour: spacing, font sizes, line heights, radii, shadows, z-index layers, durations and easings all belong in the same file.

1:root {
2  /* primitives */
3  --gray-50: #f7f7f8;
4  --gray-900: #16161a;
5  --blue-600: #2952e3;
6 
7  /* semantic: components use only these */
8  --color-bg: var(--gray-50);
9  --color-text: var(--gray-900);
10  --color-accent: var(--blue-600);
11  --radius-md: 0.5rem;
12  --duration-fast: 150ms;
13}

02Spacing and type scales

A scale is a short, fixed list of allowed sizes. Instead of 13px here and 15px there, you pick steps like 4, 8, 12, 16, 24, 32, 48, 64 for spacing, and a modular ratio (for example 1.2 or 1.25) for font sizes. Fewer options means faster decisions and visible rhythm. Fluid type uses clamp() so headings grow smoothly between a minimum and maximum without breakpoints: clamp(2rem, 1.2rem + 3vw, 3.5rem). Use rem for font sizes so the user's browser font setting is respected, and keep line-height unitless (1.5 for body, 1.1 to 1.2 for large headings).

• Spacing: a 4px or 8px base grid, named --space-1 to --space-10.
• Type: 6 to 8 steps are enough for most products.
• Fluid: clamp(min, preferred, max) for headings and section padding.
• Never let a component invent a size that is not on the scale.

03Theming: light, dark and brands

Because components read semantic tokens, a theme is just a different set of values for the same names. Dark mode can follow the operating system with prefers-color-scheme, or a user choice stored in a data-theme attribute on the html element. Modern CSS also has the light-dark() function, which picks one of two values based on the color-scheme property, so many tokens can be written once. For white-label products, each brand is another token set loaded on the root. Set the theme attribute on the server or in a tiny inline script before paint, otherwise users see a flash of the wrong theme.

1:root {
2  color-scheme: light dark;
3  --color-bg: light-dark(#ffffff, #121214);
4  --color-text: light-dark(#16161a, #ececf1);
5}
6 
7/* explicit user choice wins over the OS setting */
8[data-theme="dark"] { color-scheme: dark; }
9[data-theme="light"] { color-scheme: light; }

04CSS Modules vs styled-components vs Tailwind

All three can build a good design system; they differ in where styles live and what runs at runtime. CSS Modules are plain CSS files with locally scoped class names, compiled at build time, with zero runtime cost and full support in React Server Components. styled-components is CSS-in-JS: styles live in the component and can react to props, but styles are generated in the browser and rely on React context, so in the Next.js App Router they need client components and a style registry for SSR. The project has been in maintenance mode since 2025 and is not a good default for new RSC projects. Tailwind is utility-first: you compose classes like px-4 text-sm in the markup. Version 4 defines tokens in CSS with @theme, generates only the classes you use, and works perfectly with server components.

• CSS Modules: real CSS, zero runtime, RSC-safe; you name things yourself.
• styled-components: dynamic props and co-location; runtime cost, client-only in RSC.
• Tailwind: very fast to build, tiny CSS output, RSC-safe; long class lists need discipline.
• Zero-runtime CSS-in-JS (vanilla-extract, Panda, StyleX) sits in between.

05Component libraries

Your token file is the foundation; the component library is the house built on it. Start with the boring, high-traffic pieces: Button, Input, Select, Checkbox, Modal, Toast, Card, Stack and Grid layout primitives. Each component should have a small, typed API (variant, size, disabled) instead of accepting arbitrary styles, so the system stays consistent. For complex interactive widgets (dialogs, menus, comboboxes), build on headless, accessible primitives such as Radix, React Aria or Ark UI rather than writing focus traps and keyboard handling yourself. Document each component with real examples, and version shared packages with semantic versioning so a breaking change in a button does not surprise ten consuming apps.

1// Button/index.tsx - a small, closed API
2import s from "./style.module.css";
3 
4type Props = {
5  variant?: "primary" | "ghost";
6  size?: "sm" | "md";
7} & React.ButtonHTMLAttributes<HTMLButtonElement>;
8 
9export function Button({ variant = "primary", size = "md", className, ...rest }: Props) {
10  const cls = [s.button, s[variant], s[size], className].filter(Boolean).join(" ");
11  return <button className={cls} {...rest} />;
12}

06Responsive strategy and container queries

Pick one breakpoint list, store it in one place, and use it everywhere. Whether you go mobile-first (min-width) or desktop-first (max-width) matters less than being consistent. Media queries answer the question 'how wide is the screen?'. Container queries answer the better question for components: 'how wide is the box I am in?'. A product card can switch from stacked to horizontal when its container is wide enough, whether it sits in a sidebar or a full-width grid. Container queries and the cqi unit are supported in all modern browsers. Use intrinsic layouts too: grid with repeat(auto-fill, minmax(16rem, 1fr)) often removes the need for breakpoints entirely.

1.cardWrap {
2  container-type: inline-size;
3}
4 
5.card {
6  display: grid;
7  gap: var(--space-3);
8}
9 
10@container (min-width: 28rem) {
11  .card { grid-template-columns: 10rem 1fr; }
12}

07Production tips

Guard the system with tooling, not memory. Stylelint can forbid raw hex colours and px values outside the token file. Cascade layers (@layer reset, tokens, components, utilities) make specificity predictable so you never need !important. Keep tokens additive: renaming or deleting a token is a breaking change, so introduce the new one, migrate, then remove the old. Test components at your real breakpoints and with long translated strings, because German, Russian or Armenian text breaks layouts that look fine in English. Finally, check contrast for every text and background token pair in both themes.

• Lint rule: no hex, no px outside tokens.
• Use @layer instead of !important.
• Add tokens first, migrate, then delete.
• Test with the longest locale and at every breakpoint.

08Cascade layers: an architecture for specificity

Cascade layers (@layer) decide which group of styles wins before specificity is even compared. You declare the order once, for example reset, vendor, tokens, base, components, utilities, and any rule in a later layer beats any rule in an earlier one, however specific its selector is. That ends the arms race of longer selectors and !important. Three details trip people up. Styles outside any layer beat all layered styles, so CSS you do not control should be imported into a low layer with @import url(...) layer(vendor), otherwise it silently wins. !important reverses the order: an important declaration in an early layer beats an important one in a later layer, which lets a reset protect accessibility rules. And the order is fixed the first time a layer name appears, so declare the full list at the very top of the entry stylesheet, before any import.

1@layer reset, vendor, tokens, base, components, utilities;
2 
3@import url("datepicker.css") layer(vendor);
4 
5@layer components {
6  .button { background: var(--color-accent); }
7  .card .button.primary { background: var(--color-accent-strong); }
8}
9 
10@layer utilities {
11  /* wins over both rules above, despite lower specificity */
12  .bg-surface { background: var(--color-surface); }
13}

09Colour you can compute: OKLCH, color-mix() and relative colours

Hex and HSL are poor at building scales. Two HSL colours with the same lightness value can look very different in brightness, so generated tints fail contrast unpredictably. OKLCH describes colour as perceived lightness, chroma (colourfulness) and hue, so stepping lightness from 0.95 down to 0.25 gives an even-looking scale and makes contrast easier to reason about. Modern CSS can also derive colours in the browser. color-mix(in oklch, var(--brand), black 15%) makes a hover shade from any brand colour, and relative colour syntax, oklch(from var(--brand) l c h), lets you change one channel and keep the rest. All of this works in current versions of the major browsers. The practical win is white-labelling: a tenant supplies one or two brand colours, and the system computes hover, pressed, subtle background and border states. Computed colours are a starting point, not a guarantee, so still test every text and background pair against WCAG contrast.

1:root {
2  --brand: oklch(0.58 0.17 255);
3 
4  --color-accent: var(--brand);
5  --color-accent-hover: color-mix(in oklch, var(--brand), black 15%);
6  --color-accent-subtle: oklch(from var(--brand) 0.95 calc(c * 0.3) h);
7  --color-accent-border: oklch(from var(--brand) calc(l + 0.15) c h);
8  --color-on-accent: oklch(0.99 0 0);
9}
10 
11[data-brand="b"] {
12  --brand: oklch(0.62 0.19 25); /* the only value a new brand changes */
13}

10Tokens as a pipeline, not a file

In one app, a single tokens.css file is enough. Across several web apps, a native mobile app and a design tool, tokens become a product with consumers. The source of truth is then a JSON file in the W3C Design Tokens Community Group (DTCG) format, which published its first stable version, 2025.10, and is understood by Figma plugins and build tools. A transformer such as Style Dictionary turns that source into CSS custom properties, a typed TypeScript object for autocompletion, and Swift or Kotlin constants for mobile. Treat the package like any public API: semantic versioning, a changelog, and deprecations that keep an old name as an alias for one major version while a lint rule warns about it. Run screenshot tests (for example Storybook with a visual diff service) on every token change, because one value can move hundreds of components at once.

1{
2  "color": {
3    "blue-600": {
4      "$type": "color",
5      "$value": { "colorSpace": "srgb", "components": [0.145, 0.388, 0.922], "hex": "#2563eb" }
6    },
7    "accent": { "$type": "color", "$value": "{color.blue-600}" }
8  },
9  "space": {
10    "4": { "$type": "dimension", "$value": { "value": 1, "unit": "rem" } }
11  }
12}

11Runtime cost of CSS at scale

CSS performance rarely matters until a page has thousands of elements; then a few things cost real time. Style recalculation: changing a custom property on :root, for example on theme switch, invalidates styles for every element that inherits it. Once per click is fine; animating a root variable every frame is not, so scope animated variables to the element that uses them. Register animated variables with @property and inherits: false, which gives them a real type, makes them interpolate smoothly and stops the change from cascading through the tree. Unused CSS: a global stylesheet only grows, so prefer per-component CSS (CSS Modules, or Tailwind, which generates only the classes it finds) and check the DevTools Coverage panel. Off-screen work: content-visibility: auto with contain-intrinsic-size lets the browser skip layout and paint for long sections below the fold. Selector matching is rarely the bottleneck; measure with the Performance panel's selector stats before rewriting selectors.

1@property --progress {
2  syntax: "<percentage>";
3  inherits: false;
4  initial-value: 0%;
5}
6 
7.meter {
8  background: linear-gradient(90deg, var(--color-accent) var(--progress), transparent 0);
9  transition: --progress 300ms ease-out;
10}
11 
12.long-section {
13  content-visibility: auto;
14  contain-intrinsic-size: auto 800px;
15}