fecode-cli 1.1.2 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/README.md +101 -10
  2. package/dist/error-D4a-8BXd.js +56 -0
  3. package/dist/index.js +9770 -4513
  4. package/dist/node.browser-2EgZAKSy.js +46 -0
  5. package/dist/node.browser-B5Gur0wd.js +46 -0
  6. package/dist/node.browser-BSlAsiSV.js +46 -0
  7. package/dist/node.browser-BraUi2yf.js +9 -0
  8. package/dist/node.browser-CdVAMgSg.js +46 -0
  9. package/dist/src-CSWdjU4j.js +31870 -0
  10. package/dist/src-DY3OmBmT.js +33646 -0
  11. package/dist/src-DcYf8vsK.js +31880 -0
  12. package/dist/src-DkWmcv2Q.js +33647 -0
  13. package/package.json +5 -2
  14. package/skills/accessibility/SKILL.md +98 -98
  15. package/skills/css/SKILL.md +90 -90
  16. package/skills/frontend-debugging/SKILL.md +201 -201
  17. package/skills/frontend-design/SKILL.md +358 -358
  18. package/skills/frontend-performance/SKILL.md +89 -89
  19. package/skills/frontend-testing/SKILL.md +87 -87
  20. package/skills/nextjs/SKILL.md +75 -75
  21. package/skills/react/SKILL.md +213 -213
  22. package/skills/responsive-design/SKILL.md +190 -190
  23. package/skills/svelte/SKILL.md +86 -86
  24. package/skills/tailwind/SKILL.md +74 -74
  25. package/skills/ui-review/SKILL.md +245 -245
  26. package/skills/vue/SKILL.md +72 -72
  27. package/dist/App.d.ts +0 -33
  28. package/dist/App.js +0 -2224
  29. package/dist/approvalResolver.d.ts +0 -12
  30. package/dist/approvalResolver.js +0 -112
  31. package/dist/commands.d.ts +0 -11
  32. package/dist/commands.js +0 -33
  33. package/dist/index.d.ts +0 -3
  34. package/dist/ui/AppShell.d.ts +0 -14
  35. package/dist/ui/AppShell.js +0 -25
  36. package/dist/ui/ApprovalPrompt.d.ts +0 -31
  37. package/dist/ui/ApprovalPrompt.js +0 -55
  38. package/dist/ui/BlockedView.d.ts +0 -13
  39. package/dist/ui/BlockedView.js +0 -7
  40. package/dist/ui/CommandPalette.d.ts +0 -8
  41. package/dist/ui/CommandPalette.js +0 -18
  42. package/dist/ui/CurrentStepView.d.ts +0 -16
  43. package/dist/ui/CurrentStepView.js +0 -28
  44. package/dist/ui/DiagnosticsView.d.ts +0 -45
  45. package/dist/ui/DiagnosticsView.js +0 -23
  46. package/dist/ui/ExecutionTimeline.d.ts +0 -15
  47. package/dist/ui/ExecutionTimeline.js +0 -51
  48. package/dist/ui/ExecutionView.d.ts +0 -42
  49. package/dist/ui/ExecutionView.js +0 -20
  50. package/dist/ui/Header.d.ts +0 -15
  51. package/dist/ui/Header.js +0 -47
  52. package/dist/ui/HelpView.d.ts +0 -3
  53. package/dist/ui/HelpView.js +0 -35
  54. package/dist/ui/MessageBubble.d.ts +0 -9
  55. package/dist/ui/MessageBubble.js +0 -58
  56. package/dist/ui/PlanStep.d.ts +0 -16
  57. package/dist/ui/PlanStep.js +0 -71
  58. package/dist/ui/PlanView.d.ts +0 -26
  59. package/dist/ui/PlanView.js +0 -24
  60. package/dist/ui/ProgressBar.d.ts +0 -10
  61. package/dist/ui/ProgressBar.js +0 -14
  62. package/dist/ui/RecoveryView.d.ts +0 -20
  63. package/dist/ui/RecoveryView.js +0 -19
  64. package/dist/ui/ReplanView.d.ts +0 -16
  65. package/dist/ui/ReplanView.js +0 -21
  66. package/dist/ui/ResumeView.d.ts +0 -15
  67. package/dist/ui/ResumeView.js +0 -25
  68. package/dist/ui/RiskNotice.d.ts +0 -10
  69. package/dist/ui/RiskNotice.js +0 -21
  70. package/dist/ui/RunHistoryView.d.ts +0 -15
  71. package/dist/ui/RunHistoryView.js +0 -39
  72. package/dist/ui/StatusBar.d.ts +0 -16
  73. package/dist/ui/StatusBar.js +0 -104
  74. package/dist/ui/TaskInput.d.ts +0 -15
  75. package/dist/ui/TaskInput.js +0 -8
  76. package/dist/ui/ThinkingBlock.d.ts +0 -8
  77. package/dist/ui/ThinkingBlock.js +0 -13
  78. package/dist/ui/ThinkingIndicator.d.ts +0 -7
  79. package/dist/ui/ThinkingIndicator.js +0 -20
  80. package/dist/ui/TurnView.d.ts +0 -13
  81. package/dist/ui/TurnView.js +0 -11
  82. package/dist/ui/WorkspaceStatus.d.ts +0 -20
  83. package/dist/ui/WorkspaceStatus.js +0 -23
  84. package/dist/ui/index.d.ts +0 -26
  85. package/dist/ui/index.js +0 -26
@@ -1,358 +1,358 @@
1
- ---
2
- name: frontend-design
3
- description: Professional frontend design methodology for creating, modifying, and polishing user interfaces. Apply when creating new pages or components, redesigning existing interfaces, implementing UI from product requirements, improving visual quality, or working on responsive layout. This skill teaches design thinking, visual hierarchy, typography, color, spatial composition, interaction design, and how to avoid generic AI-generated UI in favor of deliberate, product-appropriate interfaces.
4
- category: frontend
5
- version: 2.0.0
6
- ---
7
-
8
- # Frontend Design
9
-
10
- ## When to use
11
- - Creating new UI pages, views, or components
12
- - Modifying or redesigning an existing interface
13
- - Implementing UI from a design brief or written requirements
14
- - Polishing visual quality of an existing interface
15
- - Responsive layout work
16
- - Improving interaction states or motion
17
-
18
- ## When not to use
19
- - Pure backend or API work with no UI surface
20
- - Database schema or server-side logic work
21
- - Writing tests unrelated to UI behavior
22
-
23
- ## Instructions
24
- - Make deliberate design choices appropriate to the product — never default to the nearest generic template.
25
- - Before writing any UI code, understand the product, its users, and the primary task the interface must accomplish.
26
- - When modifying an existing interface, preserve its design language unless explicitly asked to redesign it.
27
- - When creating new UI in an existing project, inspect and reuse existing design tokens, components, and conventions.
28
- - Design for the user's primary task first; everything else is supporting.
29
- - Every visual decision must earn its place — eliminate anything decorative without purpose.
30
-
31
- ## Design Thinking
32
-
33
- Before writing any UI code, reason through these questions:
34
-
35
- 1. **What is this interface?** A dashboard, a form, a detail page, a list view, a marketing page?
36
- 2. **Who uses it?** A consumer in a hurry, a professional doing analytical work, an administrator configuring a system?
37
- 3. **What is the primary task?** The single most important thing a user must be able to do efficiently.
38
- 4. **What information is most important?** Establish a hierarchy — not all elements deserve equal visual weight.
39
- 5. **What should the user notice first?** Design entry points deliberately.
40
- 6. **What visual personality fits the product?** Technical tools feel different from consumer apps, which feel different from luxury products.
41
- 7. **What existing design language must be preserved?** For existing projects, this question overrides all others.
42
-
43
- Design is a series of deliberate choices. Make those choices consciously rather than generating the first plausible layout.
44
-
45
- ## Existing Products vs New Interfaces
46
-
47
- ### Modifying an existing interface
48
-
49
- **The existing design system is the source of truth.**
50
-
51
- Before implementing anything:
52
- - Read existing components in the project
53
- - Identify design tokens (colors, spacing, radius, shadows, typography)
54
- - Understand existing layout patterns and grid conventions
55
- - Examine interaction patterns (hover, focus, active states)
56
- - Identify component naming conventions
57
-
58
- Then implement the change **within** that language. Do not introduce new color palettes, new radius conventions, or new spacing scales. Do not "improve" a product's aesthetic unless the user explicitly requests a redesign.
59
-
60
- Signs you are drifting from the existing system:
61
- - You are introducing a new color not present in existing components
62
- - You are using radius values unlike anything else in the project
63
- - Your component has a completely different spacing density than its neighbors
64
-
65
- ### Creating a new interface
66
-
67
- When the project is genuinely new or the user requests a redesign, establish a deliberate visual direction.
68
-
69
- Possible directions (choose what fits the product):
70
- - **Minimal** — whitespace-driven, restrained, high readability
71
- - **Editorial** — strong typographic hierarchy, expressive layouts
72
- - **Technical** — dense, information-rich, precise
73
- - **Utilitarian** — clarity and efficiency above expression
74
- - **Playful** — expressive color, rounded forms, energetic
75
- - **Luxury** — restrained, premium materials, deliberate pacing
76
- - **Industrial** — structured, mechanical, systematic
77
-
78
- Choose a direction. Then build everything within it consistently. Do not blend incompatible directions accidentally.
79
-
80
- ## Typography
81
-
82
- Typography is the primary instrument of visual hierarchy.
83
-
84
- **Hierarchy**
85
- - Establish a clear scale: display/heading/subheading/body/caption/label
86
- - Not every page needs every level — use what the content requires
87
- - Contrast between levels creates hierarchy; too-similar sizes create visual noise
88
-
89
- **Display and body roles**
90
- - Display type draws attention and communicates personality
91
- - Body type must be legible at length — optimize for readability over expression
92
- - Do not use display treatments for body-length content
93
-
94
- **Weight, leading, and tracking**
95
- - Use weight to differentiate hierarchy, not decoration
96
- - Line height for body text: 1.5–1.7 for comfortable reading
97
- - Line height for headings: 1.1–1.3 for tight, assertive display
98
- - Tight letter-spacing on large display type typically improves appearance
99
- - Loose letter-spacing on small caps/labels can improve legibility
100
-
101
- **Measure**
102
- - Body text reads best between 55–80 characters per line
103
- - Full-width body text on wide screens is almost always wrong — constrain it
104
-
105
- **Existing projects**
106
- - Use the project's established type scale, not a new one
107
- - If the project already uses Inter or Roboto, do not introduce a new typeface
108
- - If the project has no clear type system, establish one and be consistent
109
-
110
- ## Color
111
-
112
- **Semantics before aesthetics**
113
- Understand what colors mean in context before choosing them:
114
- - Primary: the interface's brand/action color
115
- - Secondary: supporting actions or alternative emphasis
116
- - Semantic: success, warning, error, info
117
- - Surface hierarchy: background → surface → elevated surface
118
- - On-colors: text/icons placed on each surface
119
-
120
- **Contrast**
121
- - Body text on backgrounds must meet WCAG AA contrast at minimum
122
- - Critical interactive elements must be distinguishable without color alone
123
-
124
- **Accent discipline**
125
- - Use accent colors for actions, not decoration
126
- - More than two or three accent colors in one interface is usually noise
127
-
128
- **Design tokens**
129
- - Prefer existing CSS variables or design tokens over arbitrary hex values
130
- - Introduce new tokens only when filling a genuine gap
131
-
132
- **Dark mode**
133
- - Surface hierarchy inverts in dark mode — darker isn't always correct
134
- - Avoid pure black surfaces; slightly elevated grays produce better depth
135
-
136
- ## Spatial Composition
137
-
138
- Space communicates relationships. It is not filler.
139
-
140
- **Proximity**: elements that belong together should be close; elements that are separate should breathe
141
- **Alignment**: consistent grid alignment creates calm; misalignment creates visual tension
142
- **Rhythm**: consistent vertical rhythm through spacing scales creates cohesion
143
- **Density**: match density to use case — dashboards can be dense, reading views need space
144
- **Grouping**: use space and visual weight before reaching for borders and dividers
145
-
146
- **Spacing scale**
147
- Use the project's spacing scale (or establish one: 4px base unit, multiples thereof). Avoid arbitrary pixel values that break rhythm.
148
-
149
- **Container width**
150
- - Reading content: constrain to ~65–75ch
151
- - Data-dense interfaces: allow wider containers
152
- - Full-bleed elements need intention — not everything should fill the viewport
153
-
154
- **Grid and flex**
155
- Use CSS Grid for two-dimensional layout; Flexbox for one-dimensional alignment. Do not reach for absolute positioning when flow-based layout is cleaner.
156
-
157
- ## Components
158
-
159
- **Inspect before building**
160
- Before creating a new component, search the codebase for:
161
- - Existing components that may already serve the purpose
162
- - Existing primitives (Button, Card, Input, Modal) that should be composed
163
- - Existing patterns for how similar UI is assembled
164
-
165
- **Composition over creation**
166
- Prefer composing existing primitives over building new ones from scratch. Every new primitive must be maintained.
167
-
168
- **Component size**
169
- - Components with more than three or four major responsibilities are usually too large
170
- - Extract sub-components when a section has independent visual logic
171
- - Do not extract purely for abstraction's sake when it adds no clarity
172
-
173
- **Avoid duplication**
174
- Do not create a `PrimaryButton` alongside an existing `Button` with a `variant="primary"` prop. Understand the existing component API first.
175
-
176
- ## Responsive Design
177
-
178
- Think about the interface's behavior at every width, not just at defined breakpoints.
179
-
180
- **Layout strategy**
181
- - Start from the most constrained layout the content requires
182
- - Define breakpoints where the layout naturally breaks, not at arbitrary device widths
183
- - Fluid layouts that adapt gracefully often require fewer breakpoints than rigid ones
184
-
185
- **Fluid width vs fixed columns**
186
- - Let containers grow to a max-width, then center
187
- - Avoid pixel-fixed widths on components that must live in fluid parents
188
- - Grid columns should collapse meaningfully at smaller sizes
189
-
190
- **Typography and spacing respond to viewport**
191
- - Headings that work at 1400px may be overwhelming on mobile — scale them
192
- - Spacing density can increase at wider viewports
193
- - Use relative units and clamp() for fluid typographic scaling
194
-
195
- **Navigation at small sizes**
196
- - Horizontal nav bars often cannot survive narrow viewports — plan mobile navigation early
197
- - Collapsed navigation patterns (hamburger, drawer, bottom bar) each have trade-offs; choose deliberately
198
-
199
- **Overflow**
200
- - Horizontal overflow is almost always a bug, not a design choice
201
- - Tables and data-dense elements need explicit overflow strategies on small screens
202
-
203
- **Between breakpoints**
204
- Test by resizing gradually, not just by snapping between sm/md/lg. Fix anything that breaks awkwardly in between.
205
-
206
- ## Interaction Design
207
-
208
- Every interactive element has multiple states. Design all of them.
209
-
210
- **Required states for interactive elements**
211
- - `hover` — shows the element is actionable
212
- - `focus-visible` — must be visibly distinct for keyboard users (do not remove outlines)
213
- - `active` / `pressed` — confirms the action is being triggered
214
- - `disabled` — communicates unavailability; reduce opacity or alter appearance
215
- - `loading` — prevents double submission and communicates progress
216
- - `error` — communicates failure clearly, without blame
217
- - `success` — confirms completion
218
-
219
- **Additional states as needed**
220
- - `selected` / `checked` / `on` for toggles and selections
221
- - `empty` — design empty states, not blank voids
222
- - `skeleton` / `loading placeholder` — prefer structural loading over spinners for content-heavy surfaces
223
-
224
- Hover is not the only interaction state. A button that looks identical when focused, hovered, and pressed is incomplete.
225
-
226
- ## Motion
227
-
228
- Motion should communicate, not decorate.
229
-
230
- **Purposeful transitions**
231
- - Transitions should reinforce spatial relationships (drawers slide, modals appear from their trigger, lists animate in sequence)
232
- - State changes benefit from transitions that indicate what changed and why
233
-
234
- **Duration and easing**
235
- - Most UI transitions: 150–300ms
236
- - Complex motion (modals, page transitions): 300–500ms
237
- - Ease-out for elements entering; ease-in for elements leaving; ease-in-out for state transitions
238
-
239
- **Reduced motion**
240
- - Always respect `prefers-reduced-motion`
241
- - Provide no-animation fallbacks; never disable reduced-motion support
242
-
243
- **What to avoid**
244
- - Animation that fires without user intent
245
- - Decorative animation that competes with content
246
- - Excessive bounce, spin, or particle effects in productivity interfaces
247
- - Animation that delays the user from completing their task
248
-
249
- ## Content as Design
250
-
251
- Content is not a placeholder. It is the interface.
252
-
253
- **Copy**
254
- - Labels, headings, and button text should be specific, not generic ("Save changes" not "Submit")
255
- - Error messages should explain what went wrong and what to do next
256
- - Empty states should explain the situation and offer a next action
257
-
258
- **Content length realism**
259
- - Design for realistic content — not just the 15-character happy-path name
260
- - Test with long names, long descriptions, many list items, empty lists
261
- - Define truncation behavior explicitly (ellipsis, clamping, expand)
262
-
263
- **Localization considerations**
264
- - Text expands significantly in many languages (German, Finnish); build layouts that tolerate it
265
- - Avoid fixed-width containers sized tightly to English text
266
-
267
- ## Basic Accessibility
268
-
269
- (The dedicated accessibility skill contains deeper guidance.)
270
-
271
- Minimum requirements regardless of design style:
272
- - Use semantic HTML elements for their intended purpose
273
- - All interactive elements must be keyboard-reachable and operable
274
- - Visible `:focus-visible` styles on all interactive elements — do not remove them
275
- - Text must meet WCAG AA contrast ratios on its background
276
- - Images must have meaningful alt text; decorative images use `alt=""`
277
- - UI actions must not depend solely on color to communicate state
278
- - Respect `prefers-reduced-motion` in all animations and transitions
279
-
280
- ## Avoiding Generic AI-Generated UI
281
-
282
- The most common failure mode of AI-generated frontend code is visual genericness. The interface looks assembled from an anonymous template rather than designed for a specific product.
283
-
284
- **Signs of generic AI UI to detect and correct**
285
- - Interchangeable card grids filling every surface regardless of content type
286
- - Hero sections with a centered headline, subtext, and two buttons — used when not appropriate
287
- - Excessive rounded corners applied uniformly regardless of brand personality
288
- - Purple/blue gradient text fills on headings with no product reason
289
- - Glassmorphism effects applied decoratively without contributing to hierarchy
290
- - Decorative blobs, particles, or abstract shapes placed behind content
291
- - Every section wrapped in a card, inside another card, inside another card
292
- - All text set in the same weight, creating a flat hierarchy
293
- - Gradients that exist because "gradients feel modern," not because they communicate anything
294
- - Bento grids populated with unrelated icons as substitutes for actual content
295
-
296
- **The principle**
297
- These are failure modes, not absolute prohibitions. Gradients, rounded corners, and cards are legitimate design tools. The failure is using them automatically, without a product reason.
298
-
299
- The corrective question: *Why does this specific product need this specific visual treatment?*
300
- If the answer is "because it looks good" without connection to the product — reconsider it.
301
-
302
- ## Design Workflow
303
-
304
- 1. **Understand the request** — What specifically is being created or changed? What outcome is the user trying to achieve?
305
- 2. **Inspect the existing project** — Read existing components, design tokens, colors, spacing, typography. For existing projects, this step determines most of what follows.
306
- 3. **Identify the primary task** — What must the user be able to do? Design around that.
307
- 4. **Determine visual direction** — For existing projects: maintain it. For new interfaces: choose deliberately.
308
- 5. **Establish structure** — Layout, information hierarchy, component breakdown.
309
- 6. **Implement structure** — Semantic HTML, layout, component composition.
310
- 7. **Implement visual styling** — Typography, color, spacing, depth.
311
- 8. **Implement responsive behavior** — Test from narrow to wide; fix what breaks between breakpoints.
312
- 9. **Implement interaction states** — All states for all interactive elements.
313
- 10. **Implement motion** — Where purposeful; none where not.
314
- 11. **Self-review** — Run the checklist below before considering the work complete.
315
- 12. **Verify** — Run project checks; review actual output.
316
-
317
- ## Self-Review Checklist
318
-
319
- Before considering UI work complete:
320
-
321
- - Does this interface feel specific to this product, or could it belong to any SaaS?
322
- - Does the visual hierarchy communicate the intended priority of information?
323
- - Is there anything decorative without purpose?
324
- - Are spacing and alignment consistent throughout?
325
- - Does the layout work at narrow and wide viewports, and between them?
326
- - Are all interactive states complete (hover, focus, active, disabled, loading, error)?
327
- - Does this preserve the existing design system, or does it introduce inconsistencies?
328
- - Does it feel like a coherent interface rather than a collection of independently styled components?
329
-
330
- ## Verification
331
-
332
- After implementing UI changes:
333
- - Inspect the actual rendered output or diff carefully
334
- - Run any existing visual or component tests in the project
335
- - Run the project's type and lint checks
336
- - Verify responsive behavior by considering the layout at multiple widths
337
- - Confirm interaction states are present by reviewing the implementation
338
-
339
- ## Examples
340
-
341
- ### Example: Dashboard primary action
342
-
343
- **Generic approach:**
344
- Create a dashboard with 12 metric cards in a responsive grid.
345
-
346
- **Better approach:**
347
- Identify the dashboard's primary decision. Design the layout hierarchy around that one thing. Surface the most actionable metric prominently. Use supporting data as secondary context. The number of cards follows from the content, not from filling a grid.
348
-
349
- ### Example: Modifying an existing component
350
-
351
- **Wrong approach:**
352
- The component uses gray-100 for its background. The AI decides to "improve" it with a subtle gradient and more rounded corners, introducing design system inconsistency.
353
-
354
- **Correct approach:**
355
- Read the existing Button, Card, and Input components first. Match their background, radius, shadow, and spacing conventions exactly. The new component is invisible relative to the design system — which is correct.
356
-
357
- ## References
358
- - Design System: Check project source for existing tokens and component conventions before writing new styles
1
+ ---
2
+ name: frontend-design
3
+ description: Professional frontend design methodology for creating, modifying, and polishing user interfaces. Apply when creating new pages or components, redesigning existing interfaces, implementing UI from product requirements, improving visual quality, or working on responsive layout. This skill teaches design thinking, visual hierarchy, typography, color, spatial composition, interaction design, and how to avoid generic AI-generated UI in favor of deliberate, product-appropriate interfaces.
4
+ category: frontend
5
+ version: 2.0.0
6
+ ---
7
+
8
+ # Frontend Design
9
+
10
+ ## When to use
11
+ - Creating new UI pages, views, or components
12
+ - Modifying or redesigning an existing interface
13
+ - Implementing UI from a design brief or written requirements
14
+ - Polishing visual quality of an existing interface
15
+ - Responsive layout work
16
+ - Improving interaction states or motion
17
+
18
+ ## When not to use
19
+ - Pure backend or API work with no UI surface
20
+ - Database schema or server-side logic work
21
+ - Writing tests unrelated to UI behavior
22
+
23
+ ## Instructions
24
+ - Make deliberate design choices appropriate to the product — never default to the nearest generic template.
25
+ - Before writing any UI code, understand the product, its users, and the primary task the interface must accomplish.
26
+ - When modifying an existing interface, preserve its design language unless explicitly asked to redesign it.
27
+ - When creating new UI in an existing project, inspect and reuse existing design tokens, components, and conventions.
28
+ - Design for the user's primary task first; everything else is supporting.
29
+ - Every visual decision must earn its place — eliminate anything decorative without purpose.
30
+
31
+ ## Design Thinking
32
+
33
+ Before writing any UI code, reason through these questions:
34
+
35
+ 1. **What is this interface?** A dashboard, a form, a detail page, a list view, a marketing page?
36
+ 2. **Who uses it?** A consumer in a hurry, a professional doing analytical work, an administrator configuring a system?
37
+ 3. **What is the primary task?** The single most important thing a user must be able to do efficiently.
38
+ 4. **What information is most important?** Establish a hierarchy — not all elements deserve equal visual weight.
39
+ 5. **What should the user notice first?** Design entry points deliberately.
40
+ 6. **What visual personality fits the product?** Technical tools feel different from consumer apps, which feel different from luxury products.
41
+ 7. **What existing design language must be preserved?** For existing projects, this question overrides all others.
42
+
43
+ Design is a series of deliberate choices. Make those choices consciously rather than generating the first plausible layout.
44
+
45
+ ## Existing Products vs New Interfaces
46
+
47
+ ### Modifying an existing interface
48
+
49
+ **The existing design system is the source of truth.**
50
+
51
+ Before implementing anything:
52
+ - Read existing components in the project
53
+ - Identify design tokens (colors, spacing, radius, shadows, typography)
54
+ - Understand existing layout patterns and grid conventions
55
+ - Examine interaction patterns (hover, focus, active states)
56
+ - Identify component naming conventions
57
+
58
+ Then implement the change **within** that language. Do not introduce new color palettes, new radius conventions, or new spacing scales. Do not "improve" a product's aesthetic unless the user explicitly requests a redesign.
59
+
60
+ Signs you are drifting from the existing system:
61
+ - You are introducing a new color not present in existing components
62
+ - You are using radius values unlike anything else in the project
63
+ - Your component has a completely different spacing density than its neighbors
64
+
65
+ ### Creating a new interface
66
+
67
+ When the project is genuinely new or the user requests a redesign, establish a deliberate visual direction.
68
+
69
+ Possible directions (choose what fits the product):
70
+ - **Minimal** — whitespace-driven, restrained, high readability
71
+ - **Editorial** — strong typographic hierarchy, expressive layouts
72
+ - **Technical** — dense, information-rich, precise
73
+ - **Utilitarian** — clarity and efficiency above expression
74
+ - **Playful** — expressive color, rounded forms, energetic
75
+ - **Luxury** — restrained, premium materials, deliberate pacing
76
+ - **Industrial** — structured, mechanical, systematic
77
+
78
+ Choose a direction. Then build everything within it consistently. Do not blend incompatible directions accidentally.
79
+
80
+ ## Typography
81
+
82
+ Typography is the primary instrument of visual hierarchy.
83
+
84
+ **Hierarchy**
85
+ - Establish a clear scale: display/heading/subheading/body/caption/label
86
+ - Not every page needs every level — use what the content requires
87
+ - Contrast between levels creates hierarchy; too-similar sizes create visual noise
88
+
89
+ **Display and body roles**
90
+ - Display type draws attention and communicates personality
91
+ - Body type must be legible at length — optimize for readability over expression
92
+ - Do not use display treatments for body-length content
93
+
94
+ **Weight, leading, and tracking**
95
+ - Use weight to differentiate hierarchy, not decoration
96
+ - Line height for body text: 1.5–1.7 for comfortable reading
97
+ - Line height for headings: 1.1–1.3 for tight, assertive display
98
+ - Tight letter-spacing on large display type typically improves appearance
99
+ - Loose letter-spacing on small caps/labels can improve legibility
100
+
101
+ **Measure**
102
+ - Body text reads best between 55–80 characters per line
103
+ - Full-width body text on wide screens is almost always wrong — constrain it
104
+
105
+ **Existing projects**
106
+ - Use the project's established type scale, not a new one
107
+ - If the project already uses Inter or Roboto, do not introduce a new typeface
108
+ - If the project has no clear type system, establish one and be consistent
109
+
110
+ ## Color
111
+
112
+ **Semantics before aesthetics**
113
+ Understand what colors mean in context before choosing them:
114
+ - Primary: the interface's brand/action color
115
+ - Secondary: supporting actions or alternative emphasis
116
+ - Semantic: success, warning, error, info
117
+ - Surface hierarchy: background → surface → elevated surface
118
+ - On-colors: text/icons placed on each surface
119
+
120
+ **Contrast**
121
+ - Body text on backgrounds must meet WCAG AA contrast at minimum
122
+ - Critical interactive elements must be distinguishable without color alone
123
+
124
+ **Accent discipline**
125
+ - Use accent colors for actions, not decoration
126
+ - More than two or three accent colors in one interface is usually noise
127
+
128
+ **Design tokens**
129
+ - Prefer existing CSS variables or design tokens over arbitrary hex values
130
+ - Introduce new tokens only when filling a genuine gap
131
+
132
+ **Dark mode**
133
+ - Surface hierarchy inverts in dark mode — darker isn't always correct
134
+ - Avoid pure black surfaces; slightly elevated grays produce better depth
135
+
136
+ ## Spatial Composition
137
+
138
+ Space communicates relationships. It is not filler.
139
+
140
+ **Proximity**: elements that belong together should be close; elements that are separate should breathe
141
+ **Alignment**: consistent grid alignment creates calm; misalignment creates visual tension
142
+ **Rhythm**: consistent vertical rhythm through spacing scales creates cohesion
143
+ **Density**: match density to use case — dashboards can be dense, reading views need space
144
+ **Grouping**: use space and visual weight before reaching for borders and dividers
145
+
146
+ **Spacing scale**
147
+ Use the project's spacing scale (or establish one: 4px base unit, multiples thereof). Avoid arbitrary pixel values that break rhythm.
148
+
149
+ **Container width**
150
+ - Reading content: constrain to ~65–75ch
151
+ - Data-dense interfaces: allow wider containers
152
+ - Full-bleed elements need intention — not everything should fill the viewport
153
+
154
+ **Grid and flex**
155
+ Use CSS Grid for two-dimensional layout; Flexbox for one-dimensional alignment. Do not reach for absolute positioning when flow-based layout is cleaner.
156
+
157
+ ## Components
158
+
159
+ **Inspect before building**
160
+ Before creating a new component, search the codebase for:
161
+ - Existing components that may already serve the purpose
162
+ - Existing primitives (Button, Card, Input, Modal) that should be composed
163
+ - Existing patterns for how similar UI is assembled
164
+
165
+ **Composition over creation**
166
+ Prefer composing existing primitives over building new ones from scratch. Every new primitive must be maintained.
167
+
168
+ **Component size**
169
+ - Components with more than three or four major responsibilities are usually too large
170
+ - Extract sub-components when a section has independent visual logic
171
+ - Do not extract purely for abstraction's sake when it adds no clarity
172
+
173
+ **Avoid duplication**
174
+ Do not create a `PrimaryButton` alongside an existing `Button` with a `variant="primary"` prop. Understand the existing component API first.
175
+
176
+ ## Responsive Design
177
+
178
+ Think about the interface's behavior at every width, not just at defined breakpoints.
179
+
180
+ **Layout strategy**
181
+ - Start from the most constrained layout the content requires
182
+ - Define breakpoints where the layout naturally breaks, not at arbitrary device widths
183
+ - Fluid layouts that adapt gracefully often require fewer breakpoints than rigid ones
184
+
185
+ **Fluid width vs fixed columns**
186
+ - Let containers grow to a max-width, then center
187
+ - Avoid pixel-fixed widths on components that must live in fluid parents
188
+ - Grid columns should collapse meaningfully at smaller sizes
189
+
190
+ **Typography and spacing respond to viewport**
191
+ - Headings that work at 1400px may be overwhelming on mobile — scale them
192
+ - Spacing density can increase at wider viewports
193
+ - Use relative units and clamp() for fluid typographic scaling
194
+
195
+ **Navigation at small sizes**
196
+ - Horizontal nav bars often cannot survive narrow viewports — plan mobile navigation early
197
+ - Collapsed navigation patterns (hamburger, drawer, bottom bar) each have trade-offs; choose deliberately
198
+
199
+ **Overflow**
200
+ - Horizontal overflow is almost always a bug, not a design choice
201
+ - Tables and data-dense elements need explicit overflow strategies on small screens
202
+
203
+ **Between breakpoints**
204
+ Test by resizing gradually, not just by snapping between sm/md/lg. Fix anything that breaks awkwardly in between.
205
+
206
+ ## Interaction Design
207
+
208
+ Every interactive element has multiple states. Design all of them.
209
+
210
+ **Required states for interactive elements**
211
+ - `hover` — shows the element is actionable
212
+ - `focus-visible` — must be visibly distinct for keyboard users (do not remove outlines)
213
+ - `active` / `pressed` — confirms the action is being triggered
214
+ - `disabled` — communicates unavailability; reduce opacity or alter appearance
215
+ - `loading` — prevents double submission and communicates progress
216
+ - `error` — communicates failure clearly, without blame
217
+ - `success` — confirms completion
218
+
219
+ **Additional states as needed**
220
+ - `selected` / `checked` / `on` for toggles and selections
221
+ - `empty` — design empty states, not blank voids
222
+ - `skeleton` / `loading placeholder` — prefer structural loading over spinners for content-heavy surfaces
223
+
224
+ Hover is not the only interaction state. A button that looks identical when focused, hovered, and pressed is incomplete.
225
+
226
+ ## Motion
227
+
228
+ Motion should communicate, not decorate.
229
+
230
+ **Purposeful transitions**
231
+ - Transitions should reinforce spatial relationships (drawers slide, modals appear from their trigger, lists animate in sequence)
232
+ - State changes benefit from transitions that indicate what changed and why
233
+
234
+ **Duration and easing**
235
+ - Most UI transitions: 150–300ms
236
+ - Complex motion (modals, page transitions): 300–500ms
237
+ - Ease-out for elements entering; ease-in for elements leaving; ease-in-out for state transitions
238
+
239
+ **Reduced motion**
240
+ - Always respect `prefers-reduced-motion`
241
+ - Provide no-animation fallbacks; never disable reduced-motion support
242
+
243
+ **What to avoid**
244
+ - Animation that fires without user intent
245
+ - Decorative animation that competes with content
246
+ - Excessive bounce, spin, or particle effects in productivity interfaces
247
+ - Animation that delays the user from completing their task
248
+
249
+ ## Content as Design
250
+
251
+ Content is not a placeholder. It is the interface.
252
+
253
+ **Copy**
254
+ - Labels, headings, and button text should be specific, not generic ("Save changes" not "Submit")
255
+ - Error messages should explain what went wrong and what to do next
256
+ - Empty states should explain the situation and offer a next action
257
+
258
+ **Content length realism**
259
+ - Design for realistic content — not just the 15-character happy-path name
260
+ - Test with long names, long descriptions, many list items, empty lists
261
+ - Define truncation behavior explicitly (ellipsis, clamping, expand)
262
+
263
+ **Localization considerations**
264
+ - Text expands significantly in many languages (German, Finnish); build layouts that tolerate it
265
+ - Avoid fixed-width containers sized tightly to English text
266
+
267
+ ## Basic Accessibility
268
+
269
+ (The dedicated accessibility skill contains deeper guidance.)
270
+
271
+ Minimum requirements regardless of design style:
272
+ - Use semantic HTML elements for their intended purpose
273
+ - All interactive elements must be keyboard-reachable and operable
274
+ - Visible `:focus-visible` styles on all interactive elements — do not remove them
275
+ - Text must meet WCAG AA contrast ratios on its background
276
+ - Images must have meaningful alt text; decorative images use `alt=""`
277
+ - UI actions must not depend solely on color to communicate state
278
+ - Respect `prefers-reduced-motion` in all animations and transitions
279
+
280
+ ## Avoiding Generic AI-Generated UI
281
+
282
+ The most common failure mode of AI-generated frontend code is visual genericness. The interface looks assembled from an anonymous template rather than designed for a specific product.
283
+
284
+ **Signs of generic AI UI to detect and correct**
285
+ - Interchangeable card grids filling every surface regardless of content type
286
+ - Hero sections with a centered headline, subtext, and two buttons — used when not appropriate
287
+ - Excessive rounded corners applied uniformly regardless of brand personality
288
+ - Purple/blue gradient text fills on headings with no product reason
289
+ - Glassmorphism effects applied decoratively without contributing to hierarchy
290
+ - Decorative blobs, particles, or abstract shapes placed behind content
291
+ - Every section wrapped in a card, inside another card, inside another card
292
+ - All text set in the same weight, creating a flat hierarchy
293
+ - Gradients that exist because "gradients feel modern," not because they communicate anything
294
+ - Bento grids populated with unrelated icons as substitutes for actual content
295
+
296
+ **The principle**
297
+ These are failure modes, not absolute prohibitions. Gradients, rounded corners, and cards are legitimate design tools. The failure is using them automatically, without a product reason.
298
+
299
+ The corrective question: *Why does this specific product need this specific visual treatment?*
300
+ If the answer is "because it looks good" without connection to the product — reconsider it.
301
+
302
+ ## Design Workflow
303
+
304
+ 1. **Understand the request** — What specifically is being created or changed? What outcome is the user trying to achieve?
305
+ 2. **Inspect the existing project** — Read existing components, design tokens, colors, spacing, typography. For existing projects, this step determines most of what follows.
306
+ 3. **Identify the primary task** — What must the user be able to do? Design around that.
307
+ 4. **Determine visual direction** — For existing projects: maintain it. For new interfaces: choose deliberately.
308
+ 5. **Establish structure** — Layout, information hierarchy, component breakdown.
309
+ 6. **Implement structure** — Semantic HTML, layout, component composition.
310
+ 7. **Implement visual styling** — Typography, color, spacing, depth.
311
+ 8. **Implement responsive behavior** — Test from narrow to wide; fix what breaks between breakpoints.
312
+ 9. **Implement interaction states** — All states for all interactive elements.
313
+ 10. **Implement motion** — Where purposeful; none where not.
314
+ 11. **Self-review** — Run the checklist below before considering the work complete.
315
+ 12. **Verify** — Run project checks; review actual output.
316
+
317
+ ## Self-Review Checklist
318
+
319
+ Before considering UI work complete:
320
+
321
+ - Does this interface feel specific to this product, or could it belong to any SaaS?
322
+ - Does the visual hierarchy communicate the intended priority of information?
323
+ - Is there anything decorative without purpose?
324
+ - Are spacing and alignment consistent throughout?
325
+ - Does the layout work at narrow and wide viewports, and between them?
326
+ - Are all interactive states complete (hover, focus, active, disabled, loading, error)?
327
+ - Does this preserve the existing design system, or does it introduce inconsistencies?
328
+ - Does it feel like a coherent interface rather than a collection of independently styled components?
329
+
330
+ ## Verification
331
+
332
+ After implementing UI changes:
333
+ - Inspect the actual rendered output or diff carefully
334
+ - Run any existing visual or component tests in the project
335
+ - Run the project's type and lint checks
336
+ - Verify responsive behavior by considering the layout at multiple widths
337
+ - Confirm interaction states are present by reviewing the implementation
338
+
339
+ ## Examples
340
+
341
+ ### Example: Dashboard primary action
342
+
343
+ **Generic approach:**
344
+ Create a dashboard with 12 metric cards in a responsive grid.
345
+
346
+ **Better approach:**
347
+ Identify the dashboard's primary decision. Design the layout hierarchy around that one thing. Surface the most actionable metric prominently. Use supporting data as secondary context. The number of cards follows from the content, not from filling a grid.
348
+
349
+ ### Example: Modifying an existing component
350
+
351
+ **Wrong approach:**
352
+ The component uses gray-100 for its background. The AI decides to "improve" it with a subtle gradient and more rounded corners, introducing design system inconsistency.
353
+
354
+ **Correct approach:**
355
+ Read the existing Button, Card, and Input components first. Match their background, radius, shadow, and spacing conventions exactly. The new component is invisible relative to the design system — which is correct.
356
+
357
+ ## References
358
+ - Design System: Check project source for existing tokens and component conventions before writing new styles