Design Systems & Component
Libraries
A practical guide to building and maintaining a scalable design system
Table of Contents
1. What a Design System Actually Solves
2. Design Tokens
3. Core Component Inventory
4. Component Anatomy & States
5. Variants vs Properties
6. Naming Conventions
7. Documentation Practices
8. Governance & Contribution Workflow
9. Working Across Light & Dark Themes
10. Design System Health Checklist
1. What a Design System Actually Solves
A design system is not just a shared color palette — it's the set of tokens, components, and rules
that let a team ship consistent interfaces faster, with less debate over small decisions each time.
The clearest signal a project needs a design system is repetition: the same button, card, or spacing
decision being remade slightly differently across screens. Left unaddressed, this compounds into
inconsistency that is expensive to unwind later, especially across a large screen count.
2. Design Tokens
2.1 What to Tokenize
• Color — primary, secondary, neutral, and semantic (success, warning, error, info) colors.
• Typography — font family, size scale, line-height, and weight.
• Spacing — a consistent scale (commonly based on 4px or 8px increments).
• Radius — corner rounding values used across buttons, cards, and inputs.
• Shadow/elevation — a small set of defined elevation levels rather than arbitrary shadow values.
2.2 Why Tokens Beat Hardcoded Values
A hardcoded hex value has to be found and replaced everywhere it was used if the brand color
changes. A token reference updates everywhere it's used the moment the token's value changes —
this is the difference between a one-line update and a multi-hour hunt across every screen.
3. Core Component Inventory
A reasonably complete component library typically includes:
• Buttons (primary, secondary, tertiary/ghost, destructive, icon-only)
• Form inputs (text field, select, checkbox, radio, toggle, date picker)
• Navigation (tab bar, top nav, breadcrumbs, pagination)
• Feedback (toast, banner, modal, tooltip, badge)
• Data display (cards, tables, lists, avatars, tags/chips)
• Layout (containers, dividers, grids)
Build the inventory by auditing existing screens first — most teams already have most of these
components in some form; the design system work is standardizing and consolidating them, not
inventing from zero.
4. Component Anatomy & States
Every interactive component should be designed across its full state set, not just the default
appearance:
• Default
• Hover (for pointer-based interfaces)
• Focus (keyboard navigation)
• Active/pressed
• Disabled
• Loading
• Error
Missing states are the most common source of inconsistency once a component is used by multiple
people on a team — someone eventually needs the disabled or error variant and improvises one
that doesn't match the original design intent.
5. Variants vs Properties
In component-building tools, it helps to separate two kinds of change:
5.1 Variants
Distinct visual treatments of the same component — e.g. primary vs secondary button. Each variant
is really a different design, sharing structure but not always styling.
5.2 Properties
Configurable aspects within a single variant — e.g. whether a button shows an icon, its size
(small/medium/large), or whether it's in a loading state. Properties let one component definition flex
to many contexts without duplicating the underlying design.
6. Naming Conventions
Consistent naming prevents confusion as a library grows past a handful of components.
• Use a clear hierarchy: category/component/variant (e.g. Button/Primary/Large).
• Avoid color names in component names (e.g. "Blue Button") since the underlying color may
change with rebranding — name by role instead (e.g. "Primary Button").
• Keep token names describing purpose, not raw value (e.g. "color-error" not "color-red").
7. Documentation Practices
A component without documented usage rules gets used inconsistently no matter how well it's built.
• Document when to use a component versus a close alternative (e.g. modal vs full-screen
page).
• Include do/don't examples for common misuse patterns.
• Note accessibility requirements per component (minimum touch target, required labels).
• Keep documentation next to the component itself rather than in a separate, easily-forgotten
document.
8. Governance & Contribution Workflow
As more people contribute to a shared library, a lightweight review process prevents drift:
• Define who can approve new components or changes to existing ones.
• Require a stated reason before adding a new variant — often an existing variant with a different
property value already solves the need.
• Periodically audit the library for orphaned or duplicate components that crept in outside the
process.
9. Working Across Light & Dark Themes
When a design system needs to support both themes, define tokens as semantic references rather
than raw values, so each theme simply maps the same token names to different underlying colors.
• Test contrast ratios independently in each theme — colors that pass in light theme may fail in
dark theme.
• Avoid hardcoding "white" or "black" directly in components; use a background/surface token so
theme switching doesn't require touching individual components.
• When converting an existing dark-theme product to also support light theme (or vice versa),
audit for any hardcoded values first — these are the most common source of visual bugs during
the conversion.
10. Design System Health Checklist
• Every color, spacing, and type value in new screens traces back to a token, not a one-off value.
• Every interactive component has its full state set designed (default through error).
• Naming conventions are consistent and documented across the whole library.
• There's a defined process for proposing and approving new components or variants.
• The library has been audited recently for duplicate or orphaned components.
• Light/dark theme (if both are supported) have both been contrast-checked independently.