Design System Scorecard

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

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

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

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

No one-off components solve the same problem as an existing shared component in a different way.

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

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

All form inputs have visible, programmatically associated labels.

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

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

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

Images, icons, and decorative elements have appropriate alt text or are hidden from assistive technology.

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

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

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

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

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

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

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

No component redefines a token value instead of referencing it.

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

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

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

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

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

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

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

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

New components follow a documented process from design to code.

Developers do not regularly rebuild components that already exist in the library.

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

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