Margin design system · v1.2
One set of decisions, in Figma and in code.
Tokens live in JSON in the repo. A small script turns them into CSS variables, and the same names exist as Figma variables, so a change is made once. Brand modes let a partner's report use their colour and type without a single component changing.
Principles
What every decision is checked against.
Show the working
Every claim in a report can be traced to what Margin saw. Evidence is a component, not a footnote.
Never colour alone
Status always has a word and a shape as well as a colour. Text meets 4.5:1, edges and focus meet 3:1.
Quiet by default
Ink on paper, few borders, no shadows. Emphasis is earned by content, not decoration.
One source of truth
Tokens are written once in JSON. Figma and code both read the same names.
Tokens
Four layers, from raw value to component.
- 01PrimitivesRaw values with no meaning: a warm neutral ramp, four status ramps, spacing on a 4px grid, radius, type families.
color.neutral.900 - 02SemanticWhat a value is for, with light and dark modes: surface, text, border, focus, action, status.
text.primary → color.neutral.900 - 03BrandWhat can differ between brands: accent, display and body fonts, corner radius.
brand.accent → color.brand.northline - 04ComponentOnly where a component needs its own decision. Most components use semantic tokens directly.
Button primary → action.primary
Pipeline: tokens/*.json → scripts/build-tokens.mjs → src/styles/tokens.css (CSS variables and Tailwind utilities) and Figma variables with the same names and code syntax.
Colour
Semantic tokens. Contrast is measured live against the page, so it updates when you switch brand or theme.
Surface
surface.page
surface.raised
surface.sunken
surface.inverse
Text
text.primary
text.secondary
text.tertiary
Border and focus
border.subtle
border.default
border.input
focus.ring
Status
status.critical
status.warning
status.success
status.info
Brand
brand.accent
brand.accent-soft
Type
Eleven named styles replace twenty ad hoc sizes. Display sizes scale fluidly.
Display XL
type-display-xl
A second read.
Display L
type-display-l
A second read.
Display M
type-display-m
A second read.
Heading L
type-heading-l
Section titles
Heading M
type-heading-m
Finding titles
Body serif
type-body-serif
Editorial paragraphs
Body L
type-body-l
Intro copy
Body M
type-body-m
Default text
Body S
type-body-s
Hints and captions
Label
type-label
Eyebrows, tags, meta
Numeral
type-numeral
01 02 03 2026
Components
Button, Field, StatusTag and Evidence are mirrored in Figma with the same names and properties.
Button
variant · size · loading · arrowField, TextInput, TextArea
number · hint · error · optional · aside · variantA public page.
That doesn't look like a web address. Try example.com/pricing.
Audience, constraints, what you've tried.
StatusTag
tone · emphasisAccessibility severity
- High severityBlocks or seriously slows some people. Fix first.
- Medium severityMakes the task harder for some people.
- Low severityMinor friction or polish.
- Needs checkingCan't be confirmed from the capture. Test it.
Evidence strength
- Strong signalClear evidence on the page supports this.
- Worth verifyingLikely, but check it with data or users.
- Limited evidenceA hunch from what was visible. Treat as a question.
- MeasuredFrom an automated test or the phone-sized check, not a judgement.
Evidence
observationsThe newsletter sign-up asks for an email without saying what subscribers get.
Replaces raw reference codes like "(o10, i7)". Opens a note listing what Margin observed on the page.
ProgressSteps
steps · active · elapsedSecondsallbirds.co.uk
Auditing allbirds.co.uk
0:19 elapsed, usually about two minutes
Running the tests. Step 2 of 5.
Done: Opening the page
In a real browser, on desktop first, as a visitor would see it.
In progress: Running the tests
WCAG 2.2 accessibility tests, speed timings and real-visitor speed data.
Next: Checking it on a phone
Next: Reviewing the screenshots
Next: Ranking the fixes
Keep this tab open: the report opens here when it's ready. If a check can't run, the report says so.
MeasuredChecks
checks (report_json.automated_checks)Sample data from a test page with planted issues; speed figures are illustrative.
These were measured in a real browser, not judged. They catch some issues reliably and miss others, so they sit alongside the critique rather than replacing it.
Accessibility tests
axe-core 4.10.3 · WCAG 2.2 A and AA5 rules failed across 7 elements. 11 rules passed.
- High severity
Buttons with no name
1 element · WCAG 4.1.2 · How to fix Buttons with no name (opens in a new tab)
Where it happens
<button class="icon"></button>.icon:nth-child(4)
- High severity
Images with no alt text
1 element · WCAG 1.1.1 · How to fix Images with no alt text (opens in a new tab)
Where it happens
<img src="product.gif" width="50" height="50">img
- High severity
Text with too little contrast
1 element · WCAG 1.4.3 · How to fix Text with too little contrast (opens in a new tab)
Where it happens
<p class="low">Low contrast intro text</p>.low
- High severity
Tap targets too small
3 elements · WCAG 2.5.8 · How to fix Tap targets too small (opens in a new tab)
Where it happens
<a class="icon" href="#x"></a>a.icon
- Medium severity
Zoom blocked
1 element · WCAG 1.4.4 · How to fix Zoom blocked (opens in a new tab)
On a phone
390 by 844 screen- CheckMain action visible without scrolling"Add to bag" starts 1301px down, below the 844px first screen.
- CheckFirst screen not coveredFixed layers cover 38% of the first screen ("We use cookies Accept").
- CheckNo sideways scrollingThe page is 210px wider than the screen.
- CheckTap targets at least 24px4 of 5 controls are smaller (WCAG 2.5.8).
- CheckZoom allowedThe page stops people zooming in (WCAG 1.4.4).
- CheckText at least 12px1 text block is smaller, down to 10px.
The desktop page was resized to a 390 by 844 phone screen. Sites that serve different HTML to phones may differ.
Speed
Real visitors on mobile, whole site, last 28 daysLargest content shows
3.1s
Responds to taps
520ms
Layout stays still
0.04
Lab load: largest content at 2.4s, 140 requests, 4.1MB transferred (1.8MB of JavaScript).
Technical1 console error, 1 failed request
- 404 https://shop.example/missing.json
- boom
Toast
success · errorCard
variant: plain · sunken · feature · interactivePlain
variant="plain"
Sunken
variant="sunken"
Feature
variant="feature"
Interactive
variant="interactive"
Report patterns
How the components come together in the product.
At a glance
The central read, four counts that jump to their sections, and where to start.
Finding
Title, status tag, one paragraph, and the evidence behind it.
Brand mode
The same report in a partner's brand, for white-label delivery.
Governance
How the system changes without drifting.
01
Propose
Anyone can propose a token or component, with the problem it solves and where it's needed.
02
Review
Design and engineering check it against the principles, accessibility and existing parts.
03
Build
Built once in code and once in Figma, with matching names and properties.
04
Document
Added to this page with usage notes and states.
05
Release
Versioned with a changelog. Breaking changes get a deprecation period first.
Changelog
- v1.212 Nov 2026Measured checks: axe-core accessibility tests, phone-sized pass, lab and real-user speed, shown in reports and exports.
- v1.112 Nov 2026One report system for all three tools, exports (Markdown, CSV), print layout, app-wide dark mode.
- v1.012 Nov 2026First release: tokens, three brand modes, light and dark themes, core components, report patterns.