1. Purpose
To ensure every UI component is designed with all necessary variants and states, so that it is reusable, developer-friendly, and QA-complete.
2. Why This Matters
- Designers often design only the happy path (default button, single input state).
- Devs then guess what hover/disabled/error looks like → leads to inconsistency.
- Without robust variants, components cannot scale across products.
- Robust variants = less rework, consistent UX, smoother dev handoff.
3. Types of Variants & States
| Category | What to Include | Example | Notes |
| Style Variants | Different priority/role of component | Button → Primary, Secondary, Tertiary | Only 1 Primary per screen |
| Size Variants | Different sizes for contexts | Button → Small, Medium, Large | Follow spacing tokens (8px grid) |
| Platform Variants | Web, Mobile, Dashboard adaptations | Nav Bar → Desktop (top), Mobile (bottom) | Check against breakpoints (Doc 5.2) |
| State Variants | Interaction + feedback states | Default, Hover, Active, Disabled, Error, Success | Mandatory for all components |
| Content Variants | With/without icons, text length | Input → With icon, Without icon | Must test long text overflow |
| Accessibility Variants | Focus, keyboard, high-contrast modes | Checkbox → Focus outline visible | Must meet WCAG AA |
4. Step-by-Step Process for Designing Variants
Step 1 – Start with Base Component
- Create the simplest version first (default state).
- Apply tokens (Doc 4.1) → no hardcoded values.
Step 2 – Add Style Variants
- Identify business needs: which roles need Primary vs Secondary vs Tertiary.
- Keep visual weight aligned with UI Style Mapping (Doc 4.3).
Step 3 – Add State Variants
- Always include: Default, Hover, Active, Disabled, Error, Success.
- Add Empty, Loading, Permission states if data-driven.
Step 4 – Add Platform Variants
- Adapt for Desktop, Tablet, Mobile.
- Test responsiveness → grid alignment, reflow, tap target sizes.
Step 5 – Add Content Variants
- Icon Left, Icon Right, Text Only.
- Short text vs Long text overflow.
Step 6 – Validate Accessibility
- Focus outline visible for keyboard nav.
- Contrast ratio ≥ WCAG AA.
- Minimum tap size = 44px mobile.
5. Example – Button Component
- Style Variants: Primary (filled), Secondary (outlined), Tertiary (text).
- Size Variants: Small (28px), Medium (36px), Large (44px).
- State Variants: Default, Hover, Active, Disabled, Error, Success.
- Content Variants: With icon left, with icon right, text only.
- Platform Variants: Web (inline), Mobile (full-width).
- Accessibility Variants: Focus outline for keyboard, high-contrast mode.
6. Do’s & Don’ts
Do:
- Document every variant in Component Documentation Sheet (Doc 10.2).
- Keep variants inside one component set (Figma Variants).
- Annotate behaviors clearly for devs.
Don’t:
- Deliver only the default state.
- Create one-off styles outside system.
- Forget empty/loading/permission states for data-driven components.
7. Usage Notes
- Designers must not submit a component for approval until all variants are designed.
- Peer reviewers check using Component Consistency Checklist (Doc 4.7).
- Devs must receive visual + notes for every variant.