1# States and Variants
2 
3Component state definitions and variant patterns.
4 
5## Interactive States
6 
7### State Definitions
8 
9| State | Trigger | Visual Change |
10|-------|---------|---------------|
11| default | None | Base appearance |
12| hover | Mouse over | Slight color shift |
13| focus | Tab/click | Focus ring |
14| active | Mouse down | Darkest color |
15| disabled | disabled attr | Reduced opacity |
16| loading | Async action | Spinner + opacity |
17 
18### State Priority
19 
20When multiple states apply, priority (highest to lowest):
21 
221. disabled
232. loading
243. active
254. focus
265. hover
276. default
28 
29### State Transitions
30 
31```css
32/* Standard transition for interactive elements */
33.interactive {
34  transition-property: color, background-color, border-color, box-shadow;
35  transition-duration: var(--duration-fast);
36  transition-timing-function: ease-in-out;
37}
38```
39 
40| Transition | Duration | Easing |
41|------------|----------|--------|
42| Color changes | 150ms | ease-in-out |
43| Background | 150ms | ease-in-out |
44| Transform | 200ms | ease-out |
45| Opacity | 150ms | ease |
46| Shadow | 200ms | ease-out |
47 
48## Focus States
49 
50### Focus Ring Spec
51 
52```css
53/* Standard focus ring */
54.focusable:focus-visible {
55  outline: none;
56  box-shadow: 0 0 0 var(--ring-offset) var(--color-background),
57              0 0 0 calc(var(--ring-offset) + var(--ring-width)) var(--ring-color);
58}
59```
60 
61| Property | Value |
62|----------|-------|
63| Ring width | 2px |
64| Ring offset | 2px |
65| Ring color | primary (blue-500) |
66| Offset color | background |
67 
68### Focus Within
69 
70```css
71/* Container focus when child is focused */
72.container:focus-within {
73  border-color: var(--color-ring);
74}
75```
76 
77## Disabled States
78 
79### Visual Treatment
80 
81```css
82.disabled {
83  opacity: var(--opacity-disabled); /* 0.5 */
84  pointer-events: none;
85  cursor: not-allowed;
86}
87```
88 
89| Property | Disabled Value |
90|----------|----------------|
91| Opacity | 50% |
92| Pointer events | none |
93| Cursor | not-allowed |
94| Background | muted |
95| Color | muted-foreground |
96 
97### Accessibility
98 
99- Use `aria-disabled="true"` for semantic disabled
100- Use `disabled` attribute for form elements
101- Maintain sufficient contrast (3:1 minimum)
102 
103## Loading States
104 
105### Spinner Placement
106 
107| Component | Spinner Position |
108|-----------|------------------|
109| Button | Replace icon or center |
110| Input | Trailing position |
111| Card | Center overlay |
112| Page | Center of viewport |
113 
114### Loading Treatment
115 
116```css
117.loading {
118  position: relative;
119  pointer-events: none;
120}
121 
122.loading::after {
123  content: '';
124  /* spinner styles */
125}
126 
127.loading > * {
128  opacity: 0.7;
129}
130```
131 
132## Error States
133 
134### Visual Indicators
135 
136```css
137.error {
138  border-color: var(--color-error);
139  color: var(--color-error);
140}
141 
142.error:focus-visible {
143  box-shadow: 0 0 0 2px var(--color-background),
144              0 0 0 4px var(--color-error);
145}
146```
147 
148| Element | Error Treatment |
149|---------|-----------------|
150| Input border | red-500 |
151| Input focus ring | red/20% |
152| Helper text | red-600 |
153| Icon | red-500 |
154 
155### Error Messages
156 
157- Position below input
158- Use error color
159- Include icon for accessibility
160- Clear on valid input
161 
162## Variant Patterns
163 
164### Color Variants
165 
166```css
167/* Pattern for color variants */
168.component {
169  --component-bg: var(--color-primary);
170  --component-fg: var(--color-primary-foreground);
171  background: var(--component-bg);
172  color: var(--component-fg);
173}
174 
175.component.secondary {
176  --component-bg: var(--color-secondary);
177  --component-fg: var(--color-secondary-foreground);
178}
179 
180.component.destructive {
181  --component-bg: var(--color-destructive);
182  --component-fg: var(--color-destructive-foreground);
183}
184```
185 
186### Size Variants
187 
188```css
189/* Pattern for size variants */
190.component {
191  --component-height: 40px;
192  --component-padding: var(--space-4);
193  --component-font: var(--font-size-sm);
194}
195 
196.component.sm {
197  --component-height: 32px;
198  --component-padding: var(--space-3);
199  --component-font: var(--font-size-xs);
200}
201 
202.component.lg {
203  --component-height: 48px;
204  --component-padding: var(--space-6);
205  --component-font: var(--font-size-base);
206}
207```
208 
209## Accessibility Requirements
210 
211### Color Contrast
212 
213| Element | Minimum Ratio |
214|---------|---------------|
215| Normal text | 4.5:1 |
216| Large text (18px+) | 3:1 |
217| UI components | 3:1 |
218| Focus indicator | 3:1 |
219 
220### State Indicators
221 
222- Never rely on color alone
223- Use icons, text, or patterns
224- Ensure focus is visible
225- Provide loading announcements
226 
227### ARIA States
228 
229```html
230<!-- Disabled -->
231<button disabled aria-disabled="true">Submit</button>
232 
233<!-- Loading -->
234<button aria-busy="true" aria-describedby="loading-text">
235  <span id="loading-text" class="sr-only">Loading...</span>
236</button>
237 
238<!-- Error -->
239<input aria-invalid="true" aria-describedby="error-msg">
240<span id="error-msg" role="alert">Error message</span>
241```
242