Skip to main content
Joshua Briley.
Back to blog
Design Systems 10 min read

Grade your design system like a report card

Ten minutes, five subjects, thirty-two questions. An honest snapshot of where your design system shines and where it is quietly burning your team out.

Most teams know their design system has problems. What they usually lack is a way to say where, and how bad, without turning it into a six-week audit first. This is that shortcut: a structured self-assessment across the five subjects a healthy system is actually graded on, scored as you go.

It covers the same five dimensions I use when I review a real system: component consistency, accessibility, token architecture, documentation, and the handoff process. Answer thirty-two short prompts and a written report tells you what to tackle first, and what to leave alone.

Take the assessment

For each prompt, pick No, Partial, or Yes. Nobody is grading you, so answer honestly: a flattering score helps no one. Subject grades appear live and the running total tracks as you go. Finish every row and a full report appears with where you stand and where to start.

Total score so far

0/64

Questions answered

0/32

01 · Component consistency
-

Component consistency

Are the pieces of your UI actually the same pieces, or are there six buttons wearing the same trench coat?

01. Similar UI patterns (buttons, inputs, modals) are built as shared components, not duplicated across the codebase.

02. Component APIs (props, slots, events) follow a consistent naming convention across the library.

03. Visual decisions (spacing, color, border radius) reference tokens, not hardcoded values inside components.

04. Components render consistently across the browsers and viewports your product supports.

05. One-off components that duplicate an existing shared component don’t exist in the codebase.

06. Deprecated components have a documented migration path and are not mixed with current components in production.

02 · Accessibility
-

Accessibility

Not a feature, not a checklist. The subject that tells you whether your system is architecture or wallpaper.

01. Every interactive component (buttons, links, form controls) is fully operable with a keyboard alone.

02. All form inputs have visible, programmatically associated labels.

03. Focusable elements have a clearly visible focus indicator that meets WCAG 2.1 AA contrast requirements.

04. Color is never used as the only means of conveying information (errors, statuses, required fields).

05. Components that control visibility (modals, drawers, tooltips) trap focus correctly and return focus on close.

06. Informative images and icons have descriptive alt text, and purely decorative elements are hidden from assistive technology.

07. Text and interactive elements meet WCAG 2.1 AA contrast ratios (4.5:1 for text, 3:1 for UI components).

08. Dynamic content updates (alerts, notifications, loading states) are announced to screen readers.

03 · Token architecture
-

Token architecture

The quiet plumbing underneath everything. Good tokens make redesigns a rename, not a rewrite.

01. Tokens are defined in a single source of truth (design tool, JSON file, or equivalent) and synced to code.

02. Token names follow a consistent, predictable pattern (for example: category/property/variant) with no abbreviations or ambiguity.

03. Semantic tokens (for example: color.text.primary) reference primitive tokens (for example: color.gray.900), not raw values.

04. Token names describe intent, not value. For example, color.brand-primary rather than color.blue.

05. Tokens cover every design decision that varies across themes, modes, or brands.

06. Every component references tokens rather than redefining their values.

04 · Documentation
-

Documentation

The delivery, not the afterthought. If it isn’t documented, it doesn’t really exist for the next engineer.

01. Every component has a working example showing its most common use case.

02. Props, slots, and events are documented with types and plain-language descriptions.

03. Components with common misuse patterns or non-obvious behavior have explicit do/don’t guidance.

04. Documentation is updated as part of the development workflow, not added retroactively.

05. A getting-started guide lets a new developer install and use the library without asking anyone for help.

06. Keyboard interactions, ARIA attributes, and screen reader behavior are documented per component.

05 · Handoff process
-

Handoff process

The seam between design and code. When it’s working, nobody talks about it. When it isn’t, nobody talks about anything else.

01. Design files use components from the shared library, not custom one-offs that don’t exist in code.

02. Designers and developers use the same token names to describe design decisions.

03. New components follow a documented process from design to code.

04. Developers don’t rebuild components that already exist in the library.

05. A clear owner (team or individual) is responsible for maintaining and evolving the design system.

06. The design system has a versioning and changelog process so consumers know what changed between releases.

Scroll for your final report →

Teacher's report

Keep going. Answer every question to unlock your report.

Overall grade

-

Final score

0/64

Pick a choice for every question and a personalized writeup will appear here with the two things I'd prioritize first.

What the score is really measuring

The five subjects are not arbitrary. Component consistency is what users feel and what reviewers argue about. Accessibility is the floor the whole thing stands on. Token architecture decides whether a change lands once or thirty times. Documentation determines whether anyone but you can use the system. And the handoff process is what keeps all of the above from quietly rotting the month after launch.

A low grade in one subject is not a crisis. A low grade you did not know about is. The point of a snapshot is to turn a vague unease into a specific, rankable list you can bring to a planning conversation.

This scorecard is also a work sample

It is built the way I build production work: accessible radio groups, live scoring, no frameworks under the hood, the same tokens as the rest of this site. Tab through it; the keyboard path is real. If the snapshot surfaces something worth fixing properly, a full design system audit replaces the self-assessment with specifics, ranked by severity and paired with the order to fix them in.

Share

Written by

Joshua Briley

Design- and front-end-focused product engineer with 20 years in production UI. The interface is where I bring the most value (design-grade, accessible front-end), backed by capable full-stack development in Rails and TypeScript.

Keep reading / next