---
title: "max.system, max.zeichen and max.lab — Maximilian Dahl"
description: "Product design case study by Maximilian Dahl: a design system of his own with four token layers, 131 custom marks, component contracts, guards and a documentation platform, built with Claude Code, Codex and Orca under the same rules."
url: https://max.does.systems/en/work/max-system/
lang: en
---

Product design case study · Design systems · Own system · Own 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.

Read the case · RJump to results

Role in the project · End to end · Design, architecture, code and documentation

Tools · Astro, React, Tailwind 4 · Radix Colors and shadcn; built with Claude Code, Codex and Orca

Scope · Three parts · max.system, max.zeichen and max.lab

Status · 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 · and 2 more states

As of September 2026

**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 contract · Manifest with source hashes

1. Problem
   One path per value
   Four token layers. No colour and no spacing lives outside them.

2. Intervention
   The system says no
   Guards fail the build when something bypasses the system.

3. 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 end**Design, architecture, code and documentation

Tools**Astro, React, Tailwind 4**Radix Colors and shadcn; built with Claude Code, Codex and Orca

Scope**Three parts**max.system, max.zeichen and max.lab

02 · Why a system of my own

## 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, building**Job 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, changing**Job 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 agent**Job 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 work**Job 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.

Written from the requirements I set for the system.

Context

The decision

Instead of documenting rules and hoping for discipline, I built the system so there is no other path. Anything that doesn't come from the tokens fails a test. The cost: every new idea first needs a name and a role. In return, the site stays coherent after hundreds of changes.

03 · Four token layers

## 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.

Four layers

1. Primitives
   Radix scales, spacing, radii, type, motion. Only token files may touch them.

2. Semantics
   88 roles; dark mode only swaps the scales.

3. shadcn bridge
   18 names that point only to semantics.

4. Tailwind
   Our own colours, radii, shadows and type, nothing else.

From utility to colour value · Live on this site

max.does.systems · max.system · Live · original · original · Runs on the real system of this site: the same tokens, components and rules.[Docs](https://max.does.systems/en/design-system/foundations/)

Pick a role and follow the chain, light and dark side by side.

Context

The decision

Radii and shadows are named after their role, not a number: tag, control, card, sheet; lift, object, island. The cost: anyone new learns the names first. In return, making every radius one step rounder was a single change.

04 · max.zeichen

## 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 · Live on this site

max.does.systems · max.system · Live · original · original · Runs on the real system of this site: the same tokens, components and rules.[Docs](https://max.does.systems/en/design-system/zeichen/)

Search, filter, change size: every size is drawn, not scaled.

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.

Context

The decision

I didn’t adapt a library, I drew my own. The cost: every new UI mark is made by hand, in all six sizes. In return, the site has one hand, from the smallest icon to the hero motif.

05 · Contracts and workbench

## 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 · Live on this site

max.does.systems · max.system · Live · original · original · Runs on the real system of this site: the same tokens, components and rules.[Docs](https://max.does.systems/en/design-system/library/)

Pick a component: job, reuse, limits, real usages and the component itself.

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.

06 · Guards

## The system says no

So every build runs guards that raise hard errors.

What gets rejected

1. Hard-coded values
   Hex, rgb, oklch, px and rem literals outside the token files.

2. Foreign palettes
   Tailwind colours, off-scale values, primitives inside components.

3. Foreign marks
   Icon imports that don't come from max.zeichen.

4. 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.

07 · Human and agent

## 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.

Pattern: a chapter’s decision · from this case

Sample

Context

The decision

Rules live as files in the repository, not in a prompt. Prompts vanish with the session. Files stay, can be checked and apply to every tool. So every rule an agent needs to know lives in the repository, and every important rule also has a test. The cost: a rule has to be precise enough for a test to check it.

1. Marker · Glyph and kind of note, so the decision stands out from the running text

2. Title · Names the decision as a statement

3. Reason and cost · 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.

**How an agent reads it`patterns/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.

One route for human and agent

1. Own branch
   Every change starts away from the live site

2. Contract
   New components need a registry entry, or the check fails

3. Guards and tests
   Run on every build and fail hard

4. Preview
   Every state can be checked as a preview before it goes live

5. 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.

My part

Design, architecture, code and documentation are mine. I built it with Claude Code, Codex and Orca; the decisions and the sign-off are mine, and a different model reviewed the workbench independently.

08 · max.lab

## 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 · Live in the lab

max.lab · Compass · Live · rebuilt · rebuilt · Rewritten for this site, not the original code. Where a detail is approximated, the docs say so.[Docs](https://max.does.systems/lab/#/compass/komponenten/button?lang=en)

Switch on “Measure” and the inspector shows every value with its token.

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](https://max.does.systems/en/work/camelot/)

09 · Outcome

## What came of it

1. One path per value
   Four layers, 88 roles; hard-coded values fail the build
   No colour and no spacing outside the tokens

2. One hand
   131 marks from one source, foreign icon imports blocked
   Own marks instead of third-party icon sets

3. Knowledge in the system
   Over 300 component files with a contract, a manifest with source hashes
   Every component explains itself

4. Human and agent
   Agent contract and skills in the repository, no server or key
   The same rules in every tool

5. Show earlier systems
   max.lab with an inspector, embedded in the cases
   Compass and Camelot live, not as screenshots

6. What is still open · open
   not measured
   Measure speed and quality

10 · Looking back

## 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

1. 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.

2. 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.

3. 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

1. The guards first
   I would write the checks before the first components. Every rule that came later brought clean-up work with it.

2. 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.

3. 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.
> 
> Maximilian Dahl

fin (for now)

**Case notes · How to read this case.**

Evidence · The max.systems, max.zeichen and max.lab repositories, their commits, contracts and tests. Figures from the manifest of 1 November 2026.

AI · Built with Claude Code, Codex and Orca. Decisions, design and sign-off are mine; a different model reviewed the workbench independently.

Last updated · As of 1 November 2026
