Components
Reusable interface elements with a defined structure, behavior, and appearance.
Well-designed components help teams reduce duplication, maintain consistency, and build interfaces faster without sacrificing flexibility.
Reusing the same component across an interface also makes maintenance easier. Instead of updating multiple separate implementations, teams can update the shared component and apply the change consistently wherever it is used.
Design and Code
A component in a design tool and a component in code are two implementations of the same design system concept.
Designers may use a component in Figma, while developers use its implementation in a component library. Both should follow the same design decisions.
This includes the component’s variants, states, properties, behavior, and design tokens.
The goal is not to make the design file and the code identical. The goal is to keep their design contract aligned.
Component Variants and States
Components adapt to different design contexts and runtime interactions through variants and states.
Variants (Configuration)
Variants allow a single component to support related use cases without creating a separate component for every visual difference. They define the component’s static role, size, and hierarchy.
States (Interaction)
States reflect real-time feedback: interactive components must explicitly define how they respond to user actions, navigation, and system events.
Common variant dimensions include:
Type / Intent
Primary, Secondary, Destructive / Danger
Size
Small, Medium, Large
Appearance
Solid, Outline, Ghost
States must follow a consistent design approach across all components in the system. For example, a button and a text field should not use fundamentally different focus treatments without a clear reason.
Common states include:
Default
Hover
Focus
Active
Disabled
Loading
Selected
Error
Success
Component Properties
Properties define the configurable aspects of a component.
Properties should be limited to options that represent legitimate use cases. For example, a button may expose properties such as label, variant, size, and disabled state.
Too many properties can make a component difficult to understand and maintain.
The goal is not to make a component infinitely configurable. The goal is to make it flexible enough to cover its intended use cases while remaining predictable.
Composite Components
Composite Components are larger interface elements created by combining multiple smaller components. They focus on composition: how smaller, reusable components work together.
The individual components remain reusable, while the combined component defines how they are structured and related to each other.
This allows teams to build more complex interface elements from a smaller set of well-defined components without unnecessarily expanding the component library.
Accessibility
A component should define the accessibility requirements necessary for its intended use.
Accessibility should not be treated as an additional layer applied after the component has been designed.
A reusable component is only truly reusable when it can be used accessibly across the products that depend on it.
Depending on the component, this may include:
Semantic HTML Keyboard interaction Focus behavior Focus visibility Accessible names Screen reader behavior Color contrast Error identification Touch target size Reduced-motion behavior
Responsive Components
Components should behave predictably across different screen sizes and contexts.
Responsive behavior may involve:
- Changes in size
- Changes in spacing
- Content wrapping
- Stacking
- Hiding or revealing secondary content
- Changes in interaction patterns
Not every component needs a separate mobile and desktop version.
Whenever possible, define rules for how the component adapts instead of creating independent versions.
Component Naming
Component names should describe what the component is or does, not how it looks.
Prefer names based on purpose
Button,
TextField,
Select,
Dialog,
Tooltip
Avoid names based on visual properties
BlueButton,
RoundedInput,
LargeBox
A component may change its color, size, or shape over time. Its name should remain meaningful even when its visual appearance changes.
Consistent naming also makes components easier to find and understand in design tools, codebases, and documentation.
When Not to Create a Component
Not every repeated element needs to become a component. Creating components too early can make a design system harder to maintain.
Before turning an element into a shared component, make sure that:
- The pattern appears repeatedly.
- Its behavior is consistent.
- Its structure is well understood.
- It has clear boundaries.
- Reuse provides meaningful value.
- Standardization improves the user or development experience.
A one-off element may be better left as part of a page or pattern until its need for reuse becomes clear.
The goal of a component library is not to contain everything. It is to provide the right building blocks.