Cosa Nostra
Self-initiated · Design Systems
A design system documented all the way down to who gets to change it.
A complete design system in the Apple register — 34 documented components, three token layers, both themes drawn, and a governance section that says who gets to change it.
Twenty-four numbered sections carry it from colour and grid through to versioning. The library ships as specified components with props, states and dark mode rather than as a swatch sheet.
A design system in the Apple register: soft surfaces and high-contrast display type, with one very loud red. It runs to twenty-four sections, from colour and grid through to governance, and the library ships as documented components with props, states, dark mode and a changelog.
The library
- Components: 34 (at v1.0)
- Sections: 24 (foundations + library)
- Token layers: 3 (primitive → semantic → component)
- Themes: 2 (light and dark, both drawn)
The problem with pretty systems
Most personal design systems stop at a colour ramp and a button. They look finished in a portfolio thumbnail and fall apart the moment two people need to disagree about a radius.
This one was built to survive that argument. Every section answers a question a second designer would actually ask: which red, at what size, on which surface, and who gets to change it. The look is Apple-adjacent, all generous radii and quiet greys, but most of the work went into the rulebook underneath.
How it is organised
Twenty-four numbered sections, split in two. Foundations first, then the library that has to obey them.
Foundations: Colour, Type, Metrics, Grid, Icons, Motion, House rules, Voice, Accessibility, Tokens, Density, Governance
Library: Buttons, Controls, Surfaces, Navigation, Feedback, Overlays, Data, States, Component spec, Extended library, Charts, Dark mode, Case uses
The house rules
One spread, printed red, that overrides everything else in the document. It is the part I would hand to someone on their first day.
The rules are deliberately blunt. The accent is for one thing per screen. Grey is for structure and nothing else. Radius follows the touch target rather than my taste. And if a component needs a paragraph explaining when to use it, it is not ready for the library yet.
Colour
A neutral field and a single accent. The dark theme lightens that accent so it survives on a dark surface instead of vibrating against it.
- Accent · dark theme #FF5A41: Lightened from the light-theme red
- Surface 01 · dark #000000: Base
- Surface 02 · dark #1C1C1E: Raised
- Surface 03 · dark #2C2C2E: Overlay
Tokens
Three layers, and traffic only flows one way. A component never reaches past its own layer, which is why switching to the dark theme means swapping tokens instead of redrawing anything.
Primitive holds raw values. Semantic holds intent. The component layer holds the contract a button actually consumes, and the whole thing ships as CSS custom properties and JSON.
Token output
| Layer | Example | Consumed by |
|---|
| Primitive | red-50 · grey-900 · space-4 | Semantic layer only |
| Semantic | accent · surface-raised · text-secondary | Component layer, themes |
| Component | button-bg · button-radius · field-border | Components in the library |
Emitted as CSS custom properties and JSON from the same source.
Component spec
Every component carries the same four-part spec, modelled on the button: an anatomy diagram with numbered parts, a props table giving each prop a type and a default, behaviour notes covering keyboard and loading states, and a short "use it when / reach for something else" pair.
That last pair does most of the work, and it is the part people skip. Anyone can publish a component. Telling someone when to leave it alone is the harder half.
Button props
The shape every other component spec follows.
| Prop | Type | Default |
|---|
| variant | primary | secondary | ghost | destructive | primary |
| size | sm | md | lg | md |
| icon | leading | trailing | none | none |
| loading | boolean | false |
| disabled | boolean | false |
| fullWidth | boolean | false |
Extended library
The components past the obvious ones. These are the ones that usually get skipped, and the ones a real screen ends up asking for.
- Date picker
- Accordion
- File upload
- Autocomplete
- Multi-select
- Rating
- Skeleton
- Avatar group
- Command palette
- Vertical tabs
- Code block
Charts
Rules instead of a chart library, so the constraints hold whatever ends up drawing them.
- Series order. Fixed, so the same category keeps the same colour across every chart
- Series limit. Four. Past that the chart is answering more than one question
- Axis. Bars baseline at zero, and units always labelled
- Legend. Omitted when a direct label will fit
Voice
Write-this / not-that pairs, with the number and date formats pinned so two writers produce the same thing.
| Write this | Not that | Why |
|---|
| Delete project | Are you sure? | Say what the button does |
| 3 items selected | 3 Items Selected | Sentence case everywhere except proper nouns |
| 1,240 t/h | 1240 t/h | Thousands separated, unit always present |
| 12 Mar 2026 | 03/12/26 | Unambiguous across locales |
| Save | Submit | Use the word the reader would use |
Accessibility
The ratios below are computed from the tokens at render time instead of typed in, so the table cannot drift away from the palette it describes. White on the accent fails at body size and is documented as large-and-above. Accent on the overlay surface clears AA by 0.01, which is close enough to be worth watching. The light-theme pairs are missing until that accent is recorded.
- Accent on black: #FF5A41 on #000000
- Accent on raised surface: #FF5A41 on #1C1C1E
- Accent on overlay surface: #FF5A41 on #2C2C2E
- White on accent: #FFFFFF on #FF5A41
- Black on accent: #000000 on #FF5A41
Past contrast, the rules are a visible focus ring on every interactive element, a 44×44 minimum touch target, and no state signalled by colour alone.
Density
One system, two densities. Comfortable is the default. Compact is there for tables and dashboards dense enough to need it.
| Comfortable | Compact |
|---|
| Row height | 48px | 32px |
| Control height | 40px | 32px |
| Cell padding | 16px | 8px |
| Type scale | Base | Base − 1 step |
Table, dialog and sidebar each carry their own responsive behaviour across both densities.
Governance
Almost nobody writes this section, and skipping it is how libraries rot.
- Changelog. Every token and component change recorded with author, date and state
- Versioning. Semantic. Renaming a token is a breaking change, adding a variant is not
- Contribution. A component arrives with its spec, its states and its dark theme, or it waits outside
Open the Figma library
Design System, Tokens, Accessibility, Governance