Creating a meaningful & tasteful style-guide for your web projects in 2025

Here’s my corner of the internet where I get to think out loud, explore ideas, and share what I’m learning along the way. I write about whatever I’m curious about — design, development, motion, tools, creativity, and sometimes life outside of work too.

I write to provide value, but also because teaching and documenting is one of the best ways to learn. So while you take something away from these pieces, I’m growing through them as well.

A style-guide isn’t a deliverable. It’s a decision you stop re-making.

— someone wise, probably

What is WF Cloud

Here’s the shape of the idea. A style-guide earns its keep when it removes decisions from your day — not when it sits in Figma looking organized. The things worth systematizing first:

• Color — one source of truth, themed with custom properties
• Type roles — a handful of named voices, not thirty sizes
• Spacing scale — one controlled list; every gap picks from it
• Surfaces — cards, controls, and code share the same few recipes

And the order I’d actually build them in:

1. Tokens (color, scale, radius, easing)
2. Type roles on top of the tokens
3. Components that only consume the roles
4. Pages that only compose the components

Why it matters

Everything on this site derives from a single scale. When a component needs a gap, it asks the scale; when the scale changes, everything follows. Here’s the kind of utility that keeps positioning honest:

function getPositions() {
  const section = document.querySelector('[data-section="hero"]');
  const pos1 = document.querySelector('[data-pos="1"]');
  const pos2 = document.querySelector('[data-pos="2"]');
  const pos3 = document.querySelector('[data-pos="3"]');

  const rectSection = section.getBoundingClientRect();

  return [pos1, pos2, pos3].map((el) => {
    const r = el.getBoundingClientRect();
    return {
      x: r.left - rectSection.left + r.width / 2,
      y: r.top - rectSection.top + r.height / 2,
      width: r.width,
      height: r.height,
    };
  });
}

The Math.min() constraints prevent the control points from extending too far on extremely large screens. Small guards like that are what let a system breathe across viewports without babysitting.

Feat. dev notices

Motion belongs in the guide too — a reel says more than a spec page:

And when the reference lives elsewhere, it should stay lightweight until you actually press play:

Best practices

A quick reference I keep coming back to:

Getting started

Two shots from the same system — different content, same recipe:

Start smaller than feels serious: tokens first, then one component that only consumes them. The guide grows by subtraction — every one-off you delete is a rule the system just learned.

Closing thoughts

The goal is simple: help you think differently, build better, and keep creating cool things on the web and beyond.

I’m very honored to write this piece and share it with you all on the internet.