Product design case study · Design systems · Own systemOwn system · max.systems · October 2026
A design system you can't work around
For my portfolio I didn't take a template, I built a system: four token layers, 131 custom marks, a contract for every component and guards that reject any hard-coded colour. Humans and AI agents work under the same rules, and max.lab makes my earlier systems explorable, live.
- Role in the project
- End to endDesign, architecture, code and documentation
- Tools
- Astro, React, Tailwind 4Radix Colors and shadcn; built with Claude Code, Codex and Orca
- Scope
- Three partsmax.system, max.zeichen and max.lab
- Status
- and 2 more states
Live+2
As of September 2026
Live
Has carried this website since October 2026
Checked
Guards and around 300 tests on every build
Open
Effect not measured
Live+2
As of September 2026
Live
Has carried this website since October 2026
Checked
Guards and around 300 tests on every build
Open
Effect not measured
I didn’t write rules for my portfolio. I built a system no change can get around, whether it comes from me or from an agent.
max.system, max.zeichen and max.lab
At a glance
88 roles
in four token layers; fixed values fail the build
131
glyphs from one source, foreign icon imports blocked
300+
component files with a contract
300+component files with a contractManifest with source hashes
Problem
One path per value
Four token layers. No colour and no spacing lives outside them.
Intervention
The system says no
Guards fail the build when something bypasses the system.
Outcome
For human and agent
The same files and tests apply to me and to every AI tool. max.lab makes earlier systems explorable.
- Role in the project
- End to endDesign, architecture, code and documentation
- Tools
- Astro, React, Tailwind 4Radix Colors and shadcn; built with Claude Code, Codex and Orca
- Scope
- Three partsmax.system, max.zeichen and max.lab
A portfolio about design systems has to be one
I build my portfolio with AI agents. They're fast, but they like to improvise: a hex value here, a foreign icon there, a spacing that exists nowhere else. After a few weeks the site would have looked like the codebases I've cleaned up in every job I've had.
The system has four jobs to do, depending on who is building, changing or checking:
Me, buildingJob story
- When
- I build a new page or case,
- I want
- to draw only on the system’s tokens, marks and components,
- so
- the site stays coherent after hundreds of changes.
Me, changingJob story
- When
- I change a component,
- I want
- to see first which pages and parts use it,
- so
- nothing breaks unnoticed somewhere else.
An AI agentJob story
- When
- I get a task in the repository,
- I want
- to read rules, components and limits from files instead of guessing,
- so
- my change passes the guards.
Whoever reviews my workJob story
- When
- I assess a design system that can’t be published,
- I want
- to touch it live and trace it back to the token,
- so
- I see more than a screenshot.
Every colour has exactly one path
The values come from five Radix scales, light and dark. Above them sit 88 semantic roles such as surface, text, line, brand, success and warning. A thin bridge translates them for shadcn, and only the top layer makes them usable in Tailwind. I removed Tailwind's default palettes: whatever isn't in the system doesn't exist.
Primitives
Radix scales, spacing, radii, type, motion. Only token files may touch them.
Semantics
88 roles; dark mode only swaps the scales.
shadcn bridge
18 names that point only to semantics.
Tailwind
Our own colours, radii, shadows and type, nothing else.
From utility to colour value
Marks of my own instead of an icon library
Third-party icon sets bring their own stroke weight and attitude. So I drew max.zeichen: 64 UI marks in outline and filled, each in six true sizes on a 32-unit grid, plus illustrations, hero motifs and 48 flow motifs in seven palettes. The geometry lives as source code; a build turns it into SVGs, sprites, React components and custom elements.
131 marks, searchable
The website only receives released files, with checksums and a locked version. Edits happen in the source only. An import from lucide-react fails the build.
Knowledge belongs in contracts, not in heads
Every component has a contract: its job, entry point, limits and how it is reused, directly, through a parent or as a reference only. A generated manifest holds source hashes, and a usage scan shows where a component is really used. A command line answers the same questions for humans and agents.
A contract, live
What the system knows is in the manifest: over a hundred curated contracts, more than 300 component files, over 500 scanned source files. It also states what the system doesn't know: an import doesn't prove that something actually renders.
The system says no
So every build runs guards that raise hard errors.
Hard-coded values
Hex, rgb, oklch, px and rem literals outside the token files.
Foreign palettes
Tailwind colours, off-scale values, primitives inside components.
Foreign marks
Icon imports that don't come from max.zeichen.
Drift
A stale manifest, demos without a component, files without a contract.
Around 300 tests and a browser matrix across German and English, three widths and both themes hold it together. In the lab, a dedicated guard makes sure original code from former employers can never be published.
Accessibility
Every change has to meet the same bar: keyboard, visible focus, contrast, reduced motion and no horizontal scrolling at 320 pixels. Checks run in both themes at 1440, 390 and 320 pixels, and colour is never the only information. Browser scripts measure WCAG contrast, at least 4.5:1 for text and 3:1 for icons, on selected pages. This does not yet run automatically in every build; a checker like axe is still missing.
Learning
Rules nobody checks are suggestions. A system only holds once the build can say no.
The same rules for human and agent
Whether it's Claude, Codex or ChatGPT, they all read the same files. An agent contract describes tokens, components and limits; skills of my own guide case copy, stories and variant labs. No server, no key, just the repository.
This site has patterns too, and the most important one is the decision: every chapter names one, with its cost. Its rules live in the repository’s case playbook, the same one the agents read. Here is the pattern, shown on this chapter’s own decision.
Sample
- MarkerGlyph and kind of note, so the decision stands out from the running text
- TitleNames the decision as a statement
- Reason and costWhy it was decided this way, and what it cost
Rules
- Do:One decision per chapter, with its cost.
- Do:Headings as statements.
- Do:Only what portfolio.os can back up.
- Don’t:Claiming impact that wasn’t measured.
How an agent reads itpatterns/decision.md
---
pattern: decision
source: docs/case-playbook.md
---
## Anatomy
1. Marker [mark] — Glyph and kind of note, so the decision stands out from the running text
2. Title [title] — Names the decision as a statement
3. Reason and cost [body] — Why it was decided this way, and what it cost
## Rules
- DO: One decision per chapter, with its cost.
- DO: Headings as statements.
- DO: Only what portfolio.os can back up.
- DON’T: Claiming impact that wasn’t measured.The rules are shortened from the case playbook.
Own branch
Every change starts away from the live site
Contract
New components need a registry entry, or the check fails
Guards and tests
Run on every build and fail hard
Preview
Every state can be checked as a preview before it goes live
Release
Only I release, as one merge
Clean-up has a route too. A usage report reads the source code and classifies every component: in early November 2026, 202 of 321 were reachable from a public page, 107 only from docs or previews. Nothing is deleted automatically; every candidate is reviewed one by one.
Systems you can touch
My earlier systems belong to my former employers. To show them anyway, I built max.lab: a documentation platform where Compass and Camelot run as rebuilds, measured from the rendered original and written from scratch. An inspector traces every spacing and colour back to the token that produces it.
Compass button with inspector
The lab is a system in its own right: one shared component contract for both systems, an embed protocol for height and theme, and a public build that only contains rebuilds.
See also:Camelot Design System
What came of it
One path per value
Four layers, 88 roles; hard-coded values fail the build
No colour and no spacing outside the tokens
One hand
131 marks from one source, foreign icon imports blocked
Own marks instead of third-party icon sets
Knowledge in the system
Over 300 component files with a contract, a manifest with source hashes
Every component explains itself
Human and agent
Agent contract and skills in the repository, no server or key
The same rules in every tool
Show earlier systems
max.lab with an inspector, embedded in the cases
Compass and Camelot live, not as screenshots
What is still openopen
not measured
Measure speed and quality
What I learned and would do differently today
Caveats
max.system carries one website, built by one person with agents; how it scales across several teams is untested. What is documented is scope, contracts and checks, not how much faster I build with it; the lab shows Compass and Camelot as rebuilds. As of 1 November 2026.
Learnings
Coverage isn't a goal
I don't delete a variant study just to make a metric look better. An open list is a to-do list, not a list of failures.
Same values, different roles
I don't merge two tokens with the same value if they do different jobs. Otherwise the first change breaks both.
Name the debt
A type token still carries the name of a former typeface but has long pointed to another. That sits openly in the code until it's renamed properly.
What I would do differently today
The guards first
I would write the checks before the first components. Every rule that came later brought clean-up work with it.
Names by job, from the start
A type token still carries the name of a former typeface. Had I named every role by its job from the start, that debt wouldn’t exist.
Record a baseline
I should have noted how long a new page took before the system. As it is, the gain in speed stays an estimate.
A design system doesn’t prove itself in its documentation but in what it rejects.
fin (for now)