Implementing the design system: workflow explorations

Draft for discussion. June 2026. Shamsi Brinn.

The goal of arXiv's design system is an accessibility-led semantic structure contract. It lives in git, ships as versioned code, is enforced through automated and maintainable tests, and improves as developers use it and bump against its weaknesses.

We can't reach it in one step. The big lift is first making arXiv's markup semantically sound across all repos. It is not only necessary for the design system, but is also the primary pillar of accessibility. Below are three stages that I think are realistic based on arXiv's resources.

Now

Manual reference

Point your agent at the design system repo and manually verify alignment.

Designer edits by hand Design system repo Versioned package Build Manual testing Production

Description

  • The design system repo as a valid, if less formally structured, reference
  • Works on any stack, any agent, today

Benefits

  • Usable today for low-risk or urgent applications (opt-in, transitional header and footer, internal tools, what next?)

Still missing

  • Output drifts (no versioned package)
  • Token-intensive: prose corpus, agent reads all of it each time
  • Verification is manual, no formal tests written yet, easy to miss things

Contract status: none. The design system is re-interpreted from scratch each time, so nothing holds the repos to it.

Next (transitional)

Versioned package + manual testing

Convert at least one repo to semantic markup and apply the design system'sversioned package. Start building out automated testing but mostly human review (designer is still a bottleneck).

Designer reviews PRs Design system repo Versioned package Build Manual testing Production

Description

  • A versioned, framework-agnostic package: DTCG tokens.json, CSS custom properties
  • An agent-readable spec that is structured to reduce token load
  • Manual testing and human review — some automated checks

Benefits

  • Fidelity increases as semantic HTML and design system stabilize
  • Reduced token load from more structured design system content
  • The shared semantic vocabulary is emerging

Requires first

  • Stabilize the token + naming foundation
  • Structure the design-system content

Contract status: emerging. The shared design vocabulary can be applied to restructured repos, and manual review makes it begin to be a semantic structure contract. However, the consuming markup will probably still be in flux and human oversight is needed.

Later

Versioned package + automated testing

All repos converted, build out robust automated tests/linting in CI. Stabilize contribution loop for continuous improvement of the design system.

PR + governance Design system repo Versioned package Build Automated testing Production

Description

  • Everything in Next, plus…
  • Automated conformance: linting + tests in CI (contrast, palette/font allowlists, :focus-visible, semantic-structure checks, more)
  • All-team contribution loop with trust-level governance — automated checks merge mechanical fixes; human review of spec-level changes that require higher judgement
  • Semantically structured HTML across all repos

Benefits

  • Strong governance layer
  • Less human oversight, increased efficiency
  • Designer is no longer a bottleneck

Requires first

  • All repos restructured to semantically sound markup
  • The design system stabilized and versioned enough to enforce
  • Team capacity to maintain automated tests

Contract status: realized. This is where it comes into its own and the accessibility-led semantic structure contract can be automatically enforced.

What comes online at each stage

CapabilityNowNextLater
Redeisgn ◐partial ●in place ●in place
Agent-readable spec ◐partial ●in place ●in place
Manual testing & review ◐partial ●in place ●in place
Versioned token + CSS package ○not yet ●in place ●in place
Automated tests + linting in CI ○not yet ◐partial ●in place
Two-way contribution loop (PRs → governed) ○not yet ◐partial ●in place
Semantically structured HTML ○not yet ◐partial ●in place
Accessibility-led semantic structure contract ○not yet ◐partial ●in place

● in place◐ partial / emerging○ not yet

Considered and rejected

Claude Design as the pipeline Insufficient

Claude Design imports the system and produces a brand-checked prototype, handed to Claude Code to build as production code.

Why not: Claude-specific; produces prototypes for handoff and not production code; handoff artifacts are not canonical.

Hybrid (split package + agent track) Redundant

Ship invariants as a partial package; route flexible parts through an agent that prototypes then builds them.

Why not: Subsumed. A more complete package is in Next, the agent workflows are inLater.