Push Security · Design system case study

Push Security Design System

I audited 224 marketing pages and settled 672 competing values.

I used Claude Code to draft a decision for each inconsistency, and the design director and I made the calls. Then I built a Figma plugin that generates the library from one token file.

672 competing valuesAudit found27 decisionsFinal system717 tokensFinal system

Role
Lead UX/UI DesignerContract · AI workflow, Figma library
Timeline
About four weeksFrom audit to sign-off
Scope
Public marketing siteThe signed-in product was not included
Delivered
Figma library publishedUsed by designers, marketing and PMs

The problem

The site had drifted from its brand guide.

Push didn't have a true design system, so its marketing site had drifted into a lot of inconsistencies. I audited 224 of the site's 616 pages to measure them.

What the audit found

The site used 19 ways to set an H1.

It also used 120 distinct colors, and keyboard focus was invisible on 13 of 13 pages checked.

The 30-second read

01 · What I did

Every question got one written decision.

Each one gave its reason, and the design director and I made the calls. See each step

02 · What changed

Every value comes from one token file.

That file feeds the published library, the CSS, the 225-page guide and a version AI tools can read, so they all stay in step.

My role: Lead UX/UI Designer. Drawing the system in Figma by hand was far too slow, so I set a new method. I wrote the three tests and the decision record format, set up the adversarial AI review, and generated the library from one token file. I made 23 of the 38 logged sign-off calls, and the design director made 11, among them the primary orange, regular-weight headings and keeping pill buttons.

  • Design systems
  • Design tokens
  • Brand audit
  • Figma variables
  • Figma components
  • Figma plugin
  • Accessibility
  • Claude Code
  • AI-readable docs

Inside the Figma library

My plugin built this whole library from the token file in one run.

The Push design system library open in the Figma editor. Its 12 pages run from Cover and Start here through six Foundations pages, three Components pages and Templates. The Button component set has three variant properties, Variant with 5 values, Size with 4 and State with 6, plus Label, Leading icon, Leading glyph, Trailing icon and Trailing glyph properties. The selected instance is Primary, size 40, Default, 132 by 40, with its fill bound to a component variable. The library has 4 variable collections: Primitives, Semantic with Light and Dark modes, Component, and Breakpoint with Base, MD and LG modes. Each component set sits beside its spec, usage, do-not, accessibility, interaction and Figma notes.

The plugin turns the token file's 717 tokens into 685 variables plus text, paint and effect styles.

Guidance sits next to the variants. Every component set carries spec, usage, don'ts and accessibility notes, plus interaction notes where it has hover or click behavior.

The audit

I measured the live site before deciding anything.

Claude Code crawled the public marketing site, read computed styles in headless Chrome, including hover and focus states, and took a census of every stylesheet. Each value was labeled measured, official or inferred.

The audit's conclusion

The brand itself was fine.

The identity was sound and the official guide was clear, so nothing needed a rebrand.

It needs one decision per question, written down.

My audit summary
The three biggest problems the audit found

The audit rated 3 of its findings brand-breaking, 12 noticeable and 12 cosmetic. These are the 3 brand-breaking ones.

  1. The primary orange. Several near-identical oranges appeared side by side, while the brand guide names one.
  2. Two oranges on one screen. The header mark and the homepage hero mark were exported in different oranges, so both showed at once.
  3. One mark, many files. The //O mark lived in at least 7 files with different viewBoxes and 4 fill colors.

Each one became a decision record, settled with the three tests below.

Decisions

How each decision was made.

All 27 questions had competing answers, so I set three tests, always run in the same order, that AI could apply and people could check.

What does the brand guide say?

If it names a value, start there.

What does the site already use most?

Decides when the guide is silent.

Can everyone read it?

Can veto 1 and 2. A value that fails WCAG AA loses.

F-03 The guide's six accent colors, or the site's near misses?

Test 1, the brand guide:Answered here

The guide names six accents.

  • F89A2D
  • 05AFE6
  • C3DB65
  • FFB300
  • 6700BB
  • 0B657E
Test 2, what the site uses most:Not needed

The guide's six shipped 0 times. The site's CSS used near misses:

  • FF9D29, 10 uses
  • 02B0E6, 6 uses, and 0EB1E4, 8 uses
  • B1D57F, 9 uses
  • FFB64D, 7 uses
  • 724FFF, 2 uses
  • 017195, 6 uses
Test 3, can everyone read it:Passes, with limits

Four are too light for text on white (1.54 to 2.54:1), so they become fills with black labels. Violet and teal pass as text.

  • Aa amber, a fill
  • Aa azure, a fill
  • Aa lime, a fill
  • Aa gold, a fill
  • Aa9.15:1 violet, text
  • Aa6.61:1 teal, text
Answer

The guide's six, settled at test 1. Test 3 then set where each one may appear.

color.accent.{amber, azure, lime, gold, violet, teal}

F-08 What line height does 16px body text get?

Test 1, the brand guide:Silent, so pass on

The guide gives no line heights.

Typefaces
DM Sans, DM Mono
Weights
300, 400, 500, 700
Line heights
None
Test 2, what the site uses most:Answered here

16px body paragraphs on 21 measured pages:

24px×79
22.4px×31
26px×5

Not counted: 128 bold menu titles (not body text).

Test 3, can everyone read it:Passes

Nothing to veto. 24 ÷ 16 = 1.5, the line spacing WCAG AAA asks for.

Answer

24px, settled at test 2. One body line height, at every breakpoint.

type-body16px / 24px

F-10 Which green means success?

Test 1, the brand guide:Silent, so pass on

The guide has no status colors.

Primary
2 colors
Accents
6 colors
Status colors
None
Test 2, what the site uses most:Answered here

The most used success green in the site's CSS, and the old token file's success color:

Success6FBD61×6
Test 3, can everyone read it:Vetoes test 2
  • Success2.30:1White label fails even 3:1
  • Success6.66:1Wins on light grounds
  • Success6.98:1Stays for dark grounds
Answer

#33682A on light, #6FBD61 on dark, settled at test 3. The site's success green failed on light grounds.

color.success.basecolor.success.onDark

F-01 Which hex is Push orange?

Test 1, the brand guide:Answered here

The guide's orange, Pantone 172 C.

EE4323
Test 2, what the site uses most:Not needed

The site used both of these. The guide names one.

EE4323FF4824
Test 3, can everyone read it:Passes, with limits

Too light for small text on white, so marks and large text only, where 3:1 is enough.

EE43233.84:1After the sign-off,FF48243.38:1

  • Marks
  • Large text
Sign-off

The tests advise. The design director decides. The director chose #FF4824, the Figma library's existing orange. Every reference pointed at one token, so it changed once.

EE4323becameFF4824color.brand.orange.base
Regenerated:LogosFavicon setDeck marksEvery stated contrast ratio
See one full decision record (F-⁠26, keyboard focus)
  1. 1Brand guideIdentity comes first
  2. 2Most usedAlready in use and approved
  3. 3AccessibilityCan veto both
Decision F-26Behavior

What does keyboard focus look like, and on which elements?

Evidence
Book a demo

Focus outline 3px, style none. Nothing shows when the main button takes focus, on 13 of 13 pages that captured a focus state. Audit found

Competing values

38 entries on the site and in the old token file Audit found

Width1px2px3px5px Offset02px4px−1px−2px Methodoutlinebox-shadow ringinset ringborder swapbackground swap Color on white0EB1E4 2.49:1FEC573 1.56:1FFFFFF 1.00:16ACDDC 1.85:14EC5D6 2.04:102B0E6 at 60% 1.78:1

Test 3: a ring needs 3:1 against its ground, so every color above is out.

Answer

One ring, 2px at a 2px offset. One token name, a value per ground.

Book a demo017195 · 5.53:1 on white Book a demo72DDFE · 10.32:1 on gray-900 Book a demoBlack · 6.20:1 on orange
Why

Focus is a contrast guarantee, so it is declared once, where no component can forget or delete it. An outline follows the corner radius and survives forced-colors mode.

Token

focus.ring.width 2pxfocus.ring.offset 2pxcolor.border.focus.ring (Light, Dark)color.focus.ring.onBrand

Migration

Delete the 15 focus-suppression declarations and replace 26 scattered focus selectors with one global rule.

Retire

16 entries, starting with the measured 3px outline set to none.

One of the 27 decision records, condensed. Values shown are the signed-off v1 values.

Foundations

Each foundation is a rule with its math shown.

The audit found fractional line heights, seven section paddings and, on the homepage alone, five CTA heights.

Line boxes measured on the site, in px Audit found

19.222.425.227.231.236.028843.257.696.7296

The ladder: whole pixels on a 4px grid Final system

  1. Display80/8880 × 1.1 = 88
  2. H172/8072 × 10/9 = 80
  3. H248/6048 × 1.25 = 60
  4. H332/4032 × 1.25 = 40
  5. H424/3224 × 4/3 = 32
  6. Lead20/2820 × 1.4 = 28
  7. Body16/2416 × 1.5 = 24
  8. Small14/2014 × 10/7 = 20
  9. Caption12/1612 × 4/3 = 16
01 · Type

Line heights now land on whole pixels.

  • Leading was authored as percentages of sizes they don't divide, so browsers drew fractional line boxes.
  • Each one is a whole-pixel box on the 4px grid.
  • Headings are regular weight, the design director's call, so hierarchy comes from size.

Three modesEach heading style reads its size from the Breakpoint mode. H1 is 40/48 at Base and 72/80 at MD and LG. The Figma library has the same three modes, so a designer picks a mode and the sizes follow.

Fourteen steps, named by value Final system

0468101214162024324048648096128160
Old libraryspacing-4= 16pxv1space-16= 16px

Section padding at 1440 Audit found

485664808896144

Three densities, phone / tablet up Final system

Compact48 / 64Default64 / 96Feature96 / 128

(390 − 32 − 3 × 24) / 4 = 71.5(768 − 48 − 7 × 24) / 8 = 696 of 12 = 3 of 8 = 2 of 4

02 · Spacing

Spacing tokens are named for their values.

  • Every step is divisible by 4, and from 16 up by 8.
  • Index naming made the token called 4 mean 16px, in the CSS framework and in the old library. Now the name is the value.
  • Seven measured section paddings became three densities, and each page picks one.

ExceptionsThere are exactly two. Small type is 14px, and hairlines such as the focus ring are 2px.

CTA heights on the homepage alone, in px Audit found

3241435640

Four heights, each one a sum Final system

Book a demo4 + 24 + 4 = 32 Book a demo8 + 24 + 8 = 40 Book a demo12 + 24 + 12 = 48 Book a demo12 + 32 + 12 = 56
LoginA 32 control carries a 44 × 44 hit area Book a demoIcon in a fixed 24 slot, height holds at 40 Card 16, inset 8, child 8
03 · Controls

Controls come in four heights.

  • The row height is its own token, so a button keeps its height with or without an icon.
  • Below 44px a control carries an invisible 44 × 44 target, so there is no fifth height.
  • Actions are pills and fields keep a 4px corner. Keeping the pills was the design director's call.

Shape noteradius-full is 1000px, because 9999 is odd.

One gray ramp of 11 steps, by contrast on white Final system

1.0001.121001.412001.61300Divider2.474003.595004.95600Control border7.14700Body12.85800Heading16.06900Dark surface21.001000

The audit measured 55 grays and near-blacks. Each one maps to its nearest step. Audit found

One orange, a ladder of jobs Final system

  • FF4824The identity: marks, fills and large text. 3.38:1 on white.
  • E62600The CTA ground, with a white label at 4.52:1.
  • B81F00Text and errors on light grounds, 6.49:1.
  • FF775COrange on dark grounds, 6.15:1 on gray-900.
  • FFEEEBA tint for surfaces, never for text.
04 · Color

Every color has one job and a known contrast.

  • One identity color now has a ladder of jobs, where the site had a family of near-identical oranges.
  • One job takes exactly one value. The light control border is gray-600 alone, and the light divider is gray-300 alone.
  • The CTA gradient became one flat fill, so its label has one contrast ratio.

Why the CTA is darkerWhite on the identity orange is 3.38:1, too low for a button label, so the CTA fill is one step darker.

Tokens

I sorted the tokens into three tiers.

A new value needs a role and a reason before any component uses it.

Primitive250Final system

What a value is

  • color.brand.orange.darkE62600
  • color.brand.orange.baseFF4824
  • color.gray.90013232E
  • control.4040px

Semantic170Final system

What it is for, in Light and Dark

  • color.action.primary.defaultorange.dark
  • color.text.accentorange.base
  • color.logo.markorange.base
  • color.text.bodyLight Dark

Component297Final system

One part of one component

  • component.button.variant.primary.background.defaultaction.primary.default
  • asset.favicon.manifest.themeColororange.base
  • asset.appIcon.groundorange.base
  • component.button.size.control-40.heightcontrol.40

One name, three formatscolor.text.bodyJSON--color-text-bodyCSScolor/text/bodyFigma

Change one value

color.brand.orange.baseFF4824

12 tokens point at it directly, 6 semantic and 6 component Final system

  • push.tokens.json
  • push.tokens.css
  • text-styles.json
  • Figma variables, 4 collections
  • Guide, 225 pages
  • Deck
  • Logo files
  • Favicon set

3.38:1 on white, large text and marks only4.75:1 on gray-900

Two modes, one component

Semantic: LightBook a demoBook a demoWork emailyou@company.com
Semantic: DarkBook a demoBook a demoWork emailyou@company.com

Dark mode only swaps colors. The component stays the same.

Build and checks

How the system was built and checked.

Of the eight steps, two were human gates, my method and the sign-off.

Each step, and who did it

Claude Code and agentsPeople, a human gate

  1. 01CrawlClaude Code
    224of 616 sitemap pages fetched
  2. 02MeasureClaude Code, headless Chrome
    210distinct hex values in 14 CSS files16pages read with hover and focus40page captures at 1440 and 390 CaughtThree status icons matched on one prefix, so the green check overwrote the red X. Fetched again and matched on fill color.
  3. 03LogClaude Code
    27findings3brand-breaking
  4. 04DraftAgents, on my method and record format
    27decision records7domains672competing values resolved CaughtThe first type scale repeated the fractional bug. 68 × 1.1 = 74.8.
  5. 05ChallengeAdversarial AI reviews, three lenses
    42reviews554objections151of them blocking
  6. 06Sign offPeople
    38logged calls23mine11the design director4raised by Claude
  7. 07GenerateClaude Code, from one token file
    1token fileCSSText styles225-page guideDeckFigma plugin that builds the library
  8. 08CheckScripts
    8automated token checks0problems in each
The hardest problem

Figma couldn't draw everything the CSS could.

Figma has no outline offset, so the one focus ring became three effect styles, one per ground. A Figma variable needs a value in every mode, so roles that existed only per theme in CSS needed tokens. Code's breakpoints had to collapse into three Figma modes.

Claude flagged four gaps like these while building the library and proposed a fix for each, for sign-off.

How I used AI
  • Measuring. Claude Code ran the audit, from the crawl to the stylesheet census.
  • Arguing. Agents drafted each decision on my method, adversarial reviews argued with every draft, and a script checked every contrast ratio.
  • Generating. I built the Figma plugin with Claude Code, and agents reviewed every generated output.
Checking the AI

Where the AI got it wrong, and how it was caught.

Claude was fast, but some of its drafts were wrong. I caught some at sign-off, and the agent reviews I set up caught others. Here is one of each.

What I caught

Calls I made at sign-off that overruled or corrected the AI.

  1. My call

    Squeezing a nav that didn't fit
    What the AI did
    The drafted nav rule showed the full nav from 768px. When review agents found “Book a demo” clipped to “Book a demc”, they proposed squeezing the gaps or scaling the row.
    What happened
    I changed the rule. If the row doesn't fit, use the menu. The row needs 1094px, so the full nav now starts at 1280.

What my checks caught

Blocking objections from agents in the adversarial review I designed.

  1. Agent review

    A rule every browser ignores
    What the AI did
    The breakpoint draft said to write every query as @media (min-width: var(--bp-*)). Browsers ignore var() there, without an error.
    What happened
    Reviewer agents blocked it, because it would have silently switched off the whole responsive system. Breakpoints ship as fixed values, like 48rem.
Four more things the AI got wrong

What I caught

Calls I made at sign-off that overruled or corrected the AI.

  1. My call

    A “None” that looked broken
    What the AI did
    Claude paired a filled circle with “None” in the comparison table. By its own note, “the pairing was ours.”
    What happened
    To me it read as a missing icon, so I asked for a real glyph. “None” now shows a minus.
  2. My call

    Details that drifted from the site
    What the AI did
    The drafted interactions didn't match the live site. They had a filled orange play button where the site has a ring, and 200ms nav hovers.
    What happened
    I matched them to the site, with a white ring that draws in orange on hover and 300ms for the nav.

What my checks caught

Blocking objections from agents in the adversarial review I designed.

  1. Agent review

    A banner measured as body text
    What the AI did
    The body text draft measured the first paragraph on 33 of 40 page templates. That was the purple promo banner, so the draft said every paragraph on the site would grow about 7%.
    What happened
    Reviewer agents blocked it. The site's most common real body style was already 16/24, so there was no site-wide 7% reflow.
  2. Agent review

    Ratios that missed whole pixels
    What the AI did
    The first type foundation published rounded ratios, so 24 × 1.3333 gave 31.9992, not 32.
    What happened
    Reviewer agents flagged it as blocking. Line heights ship as whole pixels, and the ratios are written as exact fractions like 4/3.

Results

The live site next to the new system.

Many values on the site were near duplicates of a value the system kept.

Drag to compare all six boxes.
Headings

19H1 treatments across the siteAudit found

1H1 style, 72/80, regular weightFinal system

Color

120distinct colors in the stylesheetsAudit found

36colors in one paletteFinal system

Neutrals

55grays and near-blacksAudit found

11steps in one gray rampFinal system

Keyboard focus

13of 13 pages checked, focus invisibleAudit found

1focus ring, declared onceFinal system

Contrast

6color pairs below AAAudit found

0contrast failures in token checksFinal system

Buttons

2competing button systemsAudit found

1button system, 6 variantsFinal system

Final system717tokens250 primitive · 170 semantic · 297 component19text styles34components11templates8automated token checks, all at 0

Where it landed

Each audience got a version it could use.

The AI-readable version was the tokens with a description on every one, plus the guide, a CLAUDE.md system doc and a Claude skill.

Designers

The published library.

Variables with Light and Dark modes, three breakpoint modes, 19 text styles and component sets with variants and properties.

Marketing and PMs

An AI-readable version.

It let them explore the system or draft on-brand assets in their own AI tools.

Engineering

The token JSON and CSS.

Generated from the same file as the Figma library, so code and design share the same values.

  1. Audit224 pages of the marketing site
  2. Library34 components and 11 templates
  3. Sign-offWith the design director
  4. Handed offMy final delivery, where it stands now
Handoff
  • The working Figma design system
  • The brand guideline and documentation
  • A Claude package for anyone bringing the system into Claude mocks or concepts
  • An interactive brand guideline with the documentation built in
Push Studio
A proof of concept I scoped and built to give marketers a curated slice of the system, so they could make on-brand social and email assets quickly without stepping off brand. The full system, Claude package included, was for anyone exploring rough concepts, building slides or preparing a design request.
See the Push Studio case study

Looking back

What held up

Running the same three tests every time worked.

Every record started from the same three tests in the same order, and when a record departed from them, it said why. That let the AI reviews and the sign-off check the reasoning as well as the result.

What I would change

The cross-check should have blocked the next step.

A cross-area check crashed early and never reran, so 6 conflicting picks reached the design director. Next time the check would block the next step until it passes.

One contrast gap I would close

The system allows orange labels from H4 up, and its token checks hold them to 3:1. On phones, though, H4 is 20px at medium weight, just under WCAG's large text size, so there it falls short of AA. A larger phone H4 or the darker text orange would close it.

Every number on this page comes from the project's audit, token file, review files and sign-off log. Audit numbers describe the public marketing site as measured during the audit, and system numbers describe what v1 defines. Agents are automated AI reviewers. The AI chat under Where it landed is an example of the AI-readable version. It was not a shipped tool.

Design system · Push Security

Thanks for reading.

In about four weeks I took Push Security from a site audit to a signed-off design system and a published Figma library.