Design system

MatDS

The system behind mveiga.com, open for anyone to take. Every value on these pages is read live from the stylesheet the site ships, so the documentation can't drift from what you see.

I kept this closed and only ever showed it in interviews. That seems like a waste. design.md is the whole framework in one file, written to be handed to an AI assistant: drop it next to your CLAUDE.md or .cursorrules and point at it. Tokens, type scale, contrast rules, and the failure modes nobody warns you about, including the one that breaks design systems quietly.

Take it, change the values, delete what you don't need. No attribution required.

download design.md ask me about it

What's inside

How it was built An AI writes the code. A person makes the calls, and most of them came out of the conversation. Process · Rules · Tools · What a person catches Foundations Colour, type, space, motion and glass. Every value is a token, and every token earned its place. Colour · Typography · Space and radius · Motion · Glass · Icons · All tokens Components The pieces the site is made of, and why each one works the way it does. Navbar · Buttons and pill · Cards and rows · Case study · Video and audio · Contact assistant Accessibility AA as a floor, measured on the real backdrop, and the failures that were found. Contrast · Sizes · Focus · Motion · Screen readers Decisions What changed, why, and the number that proved it. The case, in order. June to September 2026

Five playgrounds

Five pages let you play with the real thing, with the same maths the site runs:

  • Contrast: pick a text colour, a background and an opacity, and see whether it passes.
  • Navbar: slide a photo under the capsule and watch it decide when to change.
  • Width: drag a screen from 320 to 2560 pixels and watch the type and its air grow together.
  • Glass: drag a panel over a photo and change its tint, blur and saturation.
  • Motion: change the curve, the speed and the way a photo enters.

Principles

  1. Decide once, write it down. Every value that appears twice is a token. Every rule you had to explain twice belongs in the file.
  2. Contrast is a floor, not a review step. 4.5:1 for normal text, 3:1 from 24px, measured on the backdrop the text really sits on.
  3. Nothing waits at half strength. Interface text sits at full contrast. State is carried by colour, weight or position, never by dimming whatever is not active.
  4. Fewer names. Two tokens the eye can't tell apart are one token with a naming problem. Below ΔE 2, nobody can separate two colours side by side.
  5. Reversible by default. Every effect behind a single class or flag, so it can be pulled without collateral damage.

Built with an AI

The code on this site is written by an AI. The ideas, the criteria and the calls are mine, and most of them came out of the conversation: I bring the problem, it argues back, we measure, I decide. How that works, and what each side catches and misses, is in How it was built.