The ten-family design system

2026-09-21 · Case study

Every app in the portfolio inherits a design family. There are ten. An app does not get to pick colours; it gets to pick a family, and the family decides.

What a family fixes

Each family is six decisions, made once:

The ten are Ledger, Paper, Instrument, Arcade, Void, Field, Bench, Drill, Console and Inspector. The definitions live in families.json in the skill library, mirrored from the app-inventory sheet.

Why ten and not one

One system across twenty-odd apps produces twenty-odd apps that look like a template. Twenty free hands produce twenty apps with nothing in common. Ten families is the middle: enough that a single-purpose tool can feel like itself, few enough that I can hold the whole set in my head and audit it with a script.

The families are also functional, not decorative. Instrument is a split pane because the apps that use it take an input and produce an output. Console puts the result above the inputs because the result is what you came for. Paper has chrome in the corners and no toolbar because the artifact is a document. Picking a family is picking a layout argument, and the colours come along with it.

Governance, which is the actual system

The families themselves are the easy part. The part that keeps the portfolio coherent is the process around them:

1. The app-inventory sheet is canonical. Name, host, meta description, surface, status, family and build prompt all live in a row. Nothing gets renamed, rehosted or redescribed without the row changing first.
2. families.json and house-rules.md are mirrors of that sheet, synced by a command, not edited by hand.
3. A new app is scaffolded from its row. The family tokens, the footer, the store key, the favicons and the metadata are all wired before any product code is written.
4. /house-audit checks a repo against the rules deterministically. /design-audit checks that an app still matches the family its row claims.
5. A rule learned in one repo reaches the shared rules as a pull request, never as a direct push.

Two of those steps are worth naming precisely, because they are the ones people assume are more magical than they are:

The rules are dull on purpose: one footer line, one version scheme, one theme toggle shape, one storage key convention. Dull rules are the ones a script can check, and a rule a script can check is a rule that survives contact with a deadline.

What the system does not do

It does not stop an app from being ugly. A family fixes the palette and the layout; it says nothing about whether the thing you built inside it is worth using. The audits catch drift, not bad ideas.

It also did not, until recently, guarantee accessible text. Seven of the ten family palettes fail WCAG 2.2 AA on their own muted or accent colour, and the system had no way to notice. That is the subject of the next piece.

The evidence

The families, the house rules and the audit scripts are all in the calabrodesign repo under .claude/commands/skill-library/. The apps that use them are in the app-inventory sheet, with their family named in the row.