Skip to main content
JoshuaBriley.

Explore

Contact me

ToolsSelf-assessment

Design system scorecard.

Assess your shared UI across component consistency, accessibility, tokens, documentation, and handoff. Get a breakdown of strengths, gaps, and suggested priorities.

Start the assessment All tools
ASSESSMENT · 32 PROMPTS Keyboard access Yes Shared tokens Yes Component docs Partial PRIORITY Review documentation
  • About ten minutes
  • 32 questions
  • Shareable results

Assess your shared UI.

Choose No, Partial, or Yes for each prompt. Subject scores update as you go. Answer all 32 questions to see your report and suggested priorities.

Total score so far

0/64

Questions answered

0/32

Subject 01

Component consistency

Check whether shared patterns have consistent APIs, behavior, and migration paths.

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.

Subject 02

Accessibility

Review keyboard access, labels, focus, contrast, and feedback in the interfaces people use.

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.

Subject 03

Token architecture

Check how shared design decisions are named, maintained, and applied to components.

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.

Subject 04

Documentation

Review the examples and guidance an engineer needs to use the system independently.

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.

Subject 05

Handoff process

Look at how design and engineering keep shared patterns aligned through changes and releases.

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.

Your final report is below

Your assessment

Answer every question to see your report.

Overall grade

-

Final score

0/64

Complete every question to see your subject scores and suggested priorities.

Using this tool.

Use the results to start a review

The scorecard helps turn a broad concern about your design system into a more specific conversation. Complete it with someone who maintains the library and someone who uses it. Where your answers differ, look at a real component, a recent release, or a support request together.

The five subjects cover how components behave, how design decisions reach code, and how people find and maintain the system. A strong total can still hide a problem in one subject, so read the breakdown before choosing what to tackle.

Check the evidence behind an answer

This is a self-assessment. It does not inspect your repository, test accessibility, or measure adoption. The recommendations follow your answers, so treat them as prompts to investigate rather than proof of system quality.

Choose a specific gap and verify it in a product that uses the system. For example, if keyboard behavior is uncertain, test a complete workflow rather than an isolated component. If documentation scores poorly, watch an engineer try to use an unfamiliar component.

Share a snapshot

Your completed report is encoded in its URL. Save the link to revisit it, or share it with a teammate. Anyone with that link can read the results; no account is needed.

For an example of how an observed issue becomes a prioritized task, explore the sample audit findings.

Source: https://joshuabriley.com/tools/scorecard/