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.

Brand
Theme

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.

  1. 01PrimitivesRaw values with no meaning: a warm neutral ramp, four status ramps, spacing on a 4px grid, radius, type families.color.neutral.900
  2. 02SemanticWhat a value is for, with light and dark modes: surface, text, border, focus, action, status.text.primary → color.neutral.900
  3. 03BrandWhat can differ between brands: accent, display and body fonts, corner radius.brand.accent → color.brand.northline
  4. 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

Aa

text.primary

Aa

text.secondary

Aa

text.tertiary

Border and focus

border.subtle

border.default

border.input

focus.ring

Status

Aa

status.critical

Aa

status.warning

Aa

status.success

Aa

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 · arrow

Field, TextInput, TextArea

number · hint · error · optional · aside · variant
01

A public page.

01

Audience, constraints, what you've tried.

0 / 4000

StatusTag

tone · emphasis
CriticalWarningSuccessInfoNeutralOutline

Accessibility 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

observations

The 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 · elapsedSeconds

allbirds.co.uk

Auditing allbirds.co.uk

0:19 elapsed, usually about two minutes

Running the tests. Step 2 of 5.

  1. Done: Opening the page

    In a real browser, on desktop first, as a visitor would see it.

  2. In progress: Running the tests

    WCAG 2.2 accessibility tests, speed timings and real-visitor speed data.

  3. Next: Checking it on a phone

  4. Next: Reviewing the screenshots

  5. Next: Ranking the fixes

The screenshots appear here as soon as they're taken.
Opening the page in a real browser.

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 AA

5 rules failed across 7 elements. 11 rules passed.

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 days

Largest content shows

3.1s

Needs improvementLCP: good under 2.5s

Responds to taps

520ms

PoorINP: good under 200ms

Layout stays still

0.04

GoodCLS: good under 0.1

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 · error

Card

variant: plain · sunken · feature · interactive

Plain

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.

  1. 01

    Propose

    Anyone can propose a token or component, with the problem it solves and where it's needed.

  2. 02

    Review

    Design and engineering check it against the principles, accessibility and existing parts.

  3. 03

    Build

    Built once in code and once in Figma, with matching names and properties.

  4. 04

    Document

    Added to this page with usage notes and states.

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