@dedesfr/prompter 0.8.9 → 0.8.10
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.
- package/CHANGELOG.md +8 -0
- package/dist/cli/index.js +1 -1
- package/dist/cli/index.js.map +1 -1
- package/package.json +1 -1
- package/skills/ui-ux-pro-v2/SKILL.md +344 -0
- package/skills/ui-ux-pro-v2/assets/design-spec-template.md +173 -0
- package/skills/ui-ux-pro-v2/references/component-patterns.md +255 -0
- package/skills/ui-ux-pro-v2/references/design-principles.md +167 -0
- package/src/cli/index.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
# CHANGELOG
|
|
2
2
|
|
|
3
|
+
## [0.8.10] - 2026-04-22
|
|
4
|
+
|
|
5
|
+
### ✨ Added
|
|
6
|
+
- **ui-ux-pro-v2 Skill**: Added a new senior-level design workflow focused on implementation-ready UI decisions
|
|
7
|
+
- Introduces a low-fi to high-fi preview flow using disposable HTML + Tailwind mocks in `.preview/`
|
|
8
|
+
- Adds a design spec template plus component and design-principles references for handoff quality
|
|
9
|
+
- Emphasizes recommendation-driven guidance and more opinionated design decisions
|
|
10
|
+
|
|
3
11
|
## [0.8.9] - 2026-04-14
|
|
4
12
|
|
|
5
13
|
### ✨ Added
|
package/dist/cli/index.js
CHANGED
|
@@ -16,7 +16,7 @@ const program = new Command();
|
|
|
16
16
|
program
|
|
17
17
|
.name('prompter')
|
|
18
18
|
.description('Enhance prompts directly in your AI coding workflow')
|
|
19
|
-
.version('0.8.
|
|
19
|
+
.version('0.8.10');
|
|
20
20
|
program
|
|
21
21
|
.command('init')
|
|
22
22
|
.description('Initialize Prompter in your project')
|
package/dist/cli/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,KAAK,CAAC;AACtB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACF,IAAI,CAAC,UAAU,CAAC;KAChB,WAAW,CAAC,qDAAqD,CAAC;KAClE,OAAO,CAAC,
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -0,0 +1,344 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ui-ux-pro-v2
|
|
3
|
+
description: Design and revise UI/UX like a senior designer. Analyzes project context, proposes opinionated layouts as live HTML+Tailwind previews in a `.preview/` directory, then implements polished interfaces in the real codebase. Use for new pages, redesigns, component design, or design audits.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# UI UX Pro v2
|
|
7
|
+
|
|
8
|
+
Act as a senior UI/UX designer. Make opinionated design decisions based on project context. Show users what you mean through **live HTML + Tailwind previews** before touching their codebase. When presenting options, always lead with a recommendation.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Core Principles
|
|
13
|
+
|
|
14
|
+
1. **Decide, don't ask** — Analyze the project and make the best design choice. Let the user react to something concrete.
|
|
15
|
+
2. **Preview before you build** — Every proposal is a real, openable HTML file. No abstract descriptions, no code dumped into the real codebase until direction is approved.
|
|
16
|
+
3. **Low-fi, then high-fi** — Two-pass rule. Confirm layout in grayscale first, then polish with real tokens. This prevents users fixating on color before structure is right.
|
|
17
|
+
4. **Recommend, don't menu** — Variations are fine (up to 3), but always mark one as recommended with a clear reason.
|
|
18
|
+
5. **Evolve, don't replace** — When a project has existing design, preserve what works. Introduce changes incrementally.
|
|
19
|
+
6. **The mock is disposable** — Previews live in `.preview/` and are not the implementation. Always tell the user this.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Step 0: Read Project Context
|
|
24
|
+
|
|
25
|
+
Before designing, silently gather context (do not ask the user for this):
|
|
26
|
+
|
|
27
|
+
1. Read `AGENTS.md` and `CLAUDE.md` at the project root for tech stack and conventions
|
|
28
|
+
2. Detect the CSS system:
|
|
29
|
+
- **Tailwind** (look for `tailwind.config.*`, `@tailwind` directives)
|
|
30
|
+
- **Component library** (shadcn, Radix, Material, Chakra, Mantine, etc.)
|
|
31
|
+
- **Vanilla CSS / CSS modules / CSS-in-JS**
|
|
32
|
+
3. Scan for design tokens: CSS variables, theme files, color palettes, font stacks
|
|
33
|
+
4. Note the frontend framework (React, Vue, Svelte, Next, Laravel Blade, etc.)
|
|
34
|
+
|
|
35
|
+
This context drives your design decisions. Do not ask the user to confirm what you can read from the codebase.
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Step 1: Quick Discovery (3 Questions Max)
|
|
40
|
+
|
|
41
|
+
Ask only what you cannot determine from the codebase.
|
|
42
|
+
|
|
43
|
+
### For new designs:
|
|
44
|
+
1. **What is this for?** — Page/feature, audience, goal
|
|
45
|
+
2. **Any references?** — Sites or apps they like the feel of (optional)
|
|
46
|
+
|
|
47
|
+
### For redesigns:
|
|
48
|
+
1. **What feels wrong?** — Specific pain points
|
|
49
|
+
2. **What should stay?** — Elements to preserve
|
|
50
|
+
|
|
51
|
+
### For audits:
|
|
52
|
+
1. **Which pages/components?** — Scope of review
|
|
53
|
+
|
|
54
|
+
### Do NOT ask:
|
|
55
|
+
- "Which design direction resonates?" — You pick based on context
|
|
56
|
+
- "What color scheme do you prefer?" — Derive from brand or propose one
|
|
57
|
+
- Multiple-choice aesthetic menus — These overwhelm non-designers
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## Step 2: Build the Preview (REQUIRED)
|
|
62
|
+
|
|
63
|
+
Every design proposal MUST be a real HTML file the user can open in a browser.
|
|
64
|
+
|
|
65
|
+
### Preview Directory
|
|
66
|
+
|
|
67
|
+
Create previews in `.preview/` at the project root:
|
|
68
|
+
|
|
69
|
+
```
|
|
70
|
+
.preview/
|
|
71
|
+
├── index.html # Main preview (or variations hub)
|
|
72
|
+
├── hero-lowfi.html # Low-fi pass
|
|
73
|
+
├── hero-v1.html # High-fi variation 1 (recommended)
|
|
74
|
+
├── hero-v2.html # High-fi variation 2
|
|
75
|
+
└── hero-v3.html # High-fi variation 3 (optional)
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
**Rules for `.preview/`:**
|
|
79
|
+
- Do NOT auto-delete. The user keeps these as reference.
|
|
80
|
+
- Add `.preview/` to `.gitignore` if not already ignored (ask first if repo tracks it).
|
|
81
|
+
- Each file must be standalone and openable with `file://` or a simple static server.
|
|
82
|
+
|
|
83
|
+
### Stack Decision — Which CSS to Use in the Mock
|
|
84
|
+
|
|
85
|
+
**Always use plain Tailwind via CDN in the preview, even if the project uses shadcn/Radix/Material.**
|
|
86
|
+
|
|
87
|
+
Reasoning:
|
|
88
|
+
- **Efficiency** — no build step, no dependency wiring, instant preview
|
|
89
|
+
- **Isolation** — the mock stays disposable; not entangled with the real design system
|
|
90
|
+
- **Portability** — user can open the file without running their dev server
|
|
91
|
+
|
|
92
|
+
Exceptions:
|
|
93
|
+
- If the project uses **custom CSS variables or brand tokens**, inline them in a `<style>` block in the mock so colors/fonts match
|
|
94
|
+
- If the project has **no CSS system at all**, still use Tailwind CDN — it's the fastest way to produce a quality mock
|
|
95
|
+
|
|
96
|
+
The real implementation (Step 4) uses the project's actual design system (shadcn components, Material, etc.). The mock uses plain Tailwind. Keep this separation clear.
|
|
97
|
+
|
|
98
|
+
### Preview HTML Template
|
|
99
|
+
|
|
100
|
+
```html
|
|
101
|
+
<!doctype html>
|
|
102
|
+
<html lang="en">
|
|
103
|
+
<head>
|
|
104
|
+
<meta charset="utf-8" />
|
|
105
|
+
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
106
|
+
<title>Preview — [Feature Name]</title>
|
|
107
|
+
<script src="https://cdn.tailwindcss.com"></script>
|
|
108
|
+
<style>
|
|
109
|
+
/* Inline project brand tokens here if they exist */
|
|
110
|
+
:root {
|
|
111
|
+
--brand: #0ea5e9;
|
|
112
|
+
--brand-fg: #ffffff;
|
|
113
|
+
}
|
|
114
|
+
body { font-family: ui-sans-serif, system-ui, sans-serif; }
|
|
115
|
+
</style>
|
|
116
|
+
</head>
|
|
117
|
+
<body class="bg-gray-50 text-gray-900">
|
|
118
|
+
<!-- Section: Header -->
|
|
119
|
+
<header class="...">...</header>
|
|
120
|
+
|
|
121
|
+
<!-- Section: Hero -->
|
|
122
|
+
<section class="...">...</section>
|
|
123
|
+
|
|
124
|
+
<!-- Section: Features -->
|
|
125
|
+
<section class="...">...</section>
|
|
126
|
+
|
|
127
|
+
<!-- Section: Footer -->
|
|
128
|
+
<footer class="...">...</footer>
|
|
129
|
+
</body>
|
|
130
|
+
</html>
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### Section Comments Are Required
|
|
134
|
+
|
|
135
|
+
Every major block gets an HTML comment: `<!-- Section: Hero -->`. This preserves the "point and move" feedback pattern — users can say "move the Hero below Features" without knowing HTML.
|
|
136
|
+
|
|
137
|
+
### Two-Pass Rule (Low-fi → High-fi)
|
|
138
|
+
|
|
139
|
+
**Pass 1: Low-fi** (grayscale, structural)
|
|
140
|
+
- No brand colors, only grays and neutrals
|
|
141
|
+
- System font only
|
|
142
|
+
- No shadows, gradients, or decorative effects
|
|
143
|
+
- Focus: layout, hierarchy, spacing, content flow
|
|
144
|
+
- File: `<feature>-lowfi.html`
|
|
145
|
+
|
|
146
|
+
Present this first. Confirm the bones are right.
|
|
147
|
+
|
|
148
|
+
**Pass 2: High-fi** (polish)
|
|
149
|
+
- Apply brand colors, typography, shadows, borders
|
|
150
|
+
- Add interaction states (hover, focus)
|
|
151
|
+
- Add responsive breakpoints
|
|
152
|
+
- File: `<feature>-v1.html` (+ optional `-v2.html`, `-v3.html` for variations)
|
|
153
|
+
|
|
154
|
+
Move to Pass 2 only after the user confirms the low-fi structure.
|
|
155
|
+
|
|
156
|
+
### Variations (Optional, Max 3)
|
|
157
|
+
|
|
158
|
+
When the design direction is genuinely ambiguous, produce up to **3 variations** in the high-fi pass. Each in its own file. Create a `variations.html` hub that iframes or links to all three side-by-side for comparison:
|
|
159
|
+
|
|
160
|
+
```html
|
|
161
|
+
<!-- variations.html -->
|
|
162
|
+
<div class="grid grid-cols-1 lg:grid-cols-3 gap-4 p-4">
|
|
163
|
+
<div>
|
|
164
|
+
<h3 class="font-semibold mb-2">V1 — Minimal ⭐ Recommended</h3>
|
|
165
|
+
<iframe src="./hero-v1.html" class="w-full h-[600px] border rounded"></iframe>
|
|
166
|
+
<p class="text-sm text-gray-600 mt-2">Best because [reason].</p>
|
|
167
|
+
</div>
|
|
168
|
+
<div>
|
|
169
|
+
<h3 class="font-semibold mb-2">V2 — Bold</h3>
|
|
170
|
+
<iframe src="./hero-v2.html" class="w-full h-[600px] border rounded"></iframe>
|
|
171
|
+
<p class="text-sm text-gray-600 mt-2">Better if [scenario].</p>
|
|
172
|
+
</div>
|
|
173
|
+
<div>
|
|
174
|
+
<h3 class="font-semibold mb-2">V3 — Editorial</h3>
|
|
175
|
+
<iframe src="./hero-v3.html" class="w-full h-[600px] border rounded"></iframe>
|
|
176
|
+
<p class="text-sm text-gray-600 mt-2">Better if [scenario].</p>
|
|
177
|
+
</div>
|
|
178
|
+
</div>
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Always mark one as **Recommended** with a one-line reason.
|
|
182
|
+
|
|
183
|
+
### Delegating to `frontend-design` Skill
|
|
184
|
+
|
|
185
|
+
If a `frontend-design` skill (or similar HTML/Tailwind generation skill) is available in the current session, delegate the actual mock construction to it — pass your layout decisions and content, let it produce the markup. If not available, build the markup inline. Either way, you own the layout decisions, the stack rules above, and the section-comment convention.
|
|
186
|
+
|
|
187
|
+
### Presenting the Proposal
|
|
188
|
+
|
|
189
|
+
Structure your message as:
|
|
190
|
+
|
|
191
|
+
```
|
|
192
|
+
## Design Proposal: [Feature Name]
|
|
193
|
+
|
|
194
|
+
**Approach:** [1-2 sentences on direction and why]
|
|
195
|
+
|
|
196
|
+
**Preview:** `.preview/<feature>-lowfi.html` (open in browser)
|
|
197
|
+
|
|
198
|
+
### Key Decisions
|
|
199
|
+
- [Decision]: [rationale]
|
|
200
|
+
- [Decision]: [rationale]
|
|
201
|
+
|
|
202
|
+
This is a throwaway mock — once you approve the direction I'll build
|
|
203
|
+
it properly in your codebase using [shadcn / Material / your design system].
|
|
204
|
+
|
|
205
|
+
Does the layout work? I can adjust any section before moving to high-fi.
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
## Step 3: Mock vs. Edit — Decision Tree
|
|
211
|
+
|
|
212
|
+
Not every request needs a standalone mock. Decide up front:
|
|
213
|
+
|
|
214
|
+
### Mock first (build in `.preview/`)
|
|
215
|
+
- New page or feature from scratch
|
|
216
|
+
- Major redesign of an existing page
|
|
217
|
+
- Multiple directions are plausible and you want the user to see them
|
|
218
|
+
- User is non-technical and needs to see before they can react
|
|
219
|
+
|
|
220
|
+
### Edit real code directly
|
|
221
|
+
- Small tweaks to an existing component (color, spacing, copy)
|
|
222
|
+
- Fixing a specific usability bug the user pointed at
|
|
223
|
+
- Adding a single element to an already-approved layout
|
|
224
|
+
- User is a developer who asked for a specific change
|
|
225
|
+
|
|
226
|
+
### When in doubt — mock it
|
|
227
|
+
The cost of a disposable HTML file is low. The cost of the user rejecting a real-code change and you having to undo it is higher.
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## Step 4: Design Analysis (For Existing Projects)
|
|
232
|
+
|
|
233
|
+
When auditing existing code, analyze yourself and present findings organized by impact.
|
|
234
|
+
|
|
235
|
+
### What to Evaluate
|
|
236
|
+
1. **Visual hierarchy** — Is important content visually dominant?
|
|
237
|
+
2. **Consistency** — Are spacing, colors, components systematic?
|
|
238
|
+
3. **Usability** — Contrast (WCAG AA minimum), touch targets (44px+), form labels, affordances
|
|
239
|
+
4. **Responsiveness** — Does it work across breakpoints?
|
|
240
|
+
5. **Interaction quality** — Transitions, loading/error/empty states
|
|
241
|
+
6. **Dark mode** — If the project supports it, does this feature work in both themes?
|
|
242
|
+
|
|
243
|
+
### Present Findings with Before/After Previews
|
|
244
|
+
|
|
245
|
+
For each high-impact issue, produce a **before/after preview** in `.preview/audit/`:
|
|
246
|
+
|
|
247
|
+
```
|
|
248
|
+
.preview/audit/
|
|
249
|
+
├── nav-before.html
|
|
250
|
+
├── nav-after.html
|
|
251
|
+
└── index.html # Side-by-side comparison
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
Don't just list problems — show the fix in HTML the user can open.
|
|
255
|
+
|
|
256
|
+
---
|
|
257
|
+
|
|
258
|
+
## Step 5: Implementation (Real Codebase)
|
|
259
|
+
|
|
260
|
+
Once the preview is approved, implement in the project's actual stack.
|
|
261
|
+
|
|
262
|
+
### Order of Implementation
|
|
263
|
+
1. **Layout structure and spacing** — Get the bones right first
|
|
264
|
+
2. **Typography and color** — Apply the visual language
|
|
265
|
+
3. **Component details** — Buttons, forms, cards (use the project's design system — shadcn, Material, etc.)
|
|
266
|
+
4. **Interaction states** — Hover, focus, loading, error, empty
|
|
267
|
+
5. **Responsive adaptations** — Mobile/tablet breakpoints
|
|
268
|
+
6. **Dark mode** — If the project supports theming, verify both modes
|
|
269
|
+
|
|
270
|
+
After each chunk, check in: "Layout is done — moving to typography next, or want to adjust anything?"
|
|
271
|
+
|
|
272
|
+
### Browser Verification
|
|
273
|
+
|
|
274
|
+
For UI changes, start the dev server and verify in a browser before reporting the task complete. Test the golden path and at least one edge case. If you cannot run the dev server, say so explicitly — do not claim the work is done based on a successful build or passing type check.
|
|
275
|
+
|
|
276
|
+
### Implementation Rules
|
|
277
|
+
|
|
278
|
+
Follow the anti-pattern catalog in [design-principles.md](references/design-principles.md):
|
|
279
|
+
- No gratuitous gradients, glassmorphism, or trend effects without purpose
|
|
280
|
+
- Intentional border-radius (not 9999px on everything)
|
|
281
|
+
- Typography does 80% of the work
|
|
282
|
+
- Color used sparingly: 1-2 primaries, 1 accent, rest neutrals
|
|
283
|
+
- Faster transitions (150-200ms) for small elements, slower (300-400ms) for layout
|
|
284
|
+
- Whitespace creates hierarchy
|
|
285
|
+
|
|
286
|
+
### Adapting Existing Design
|
|
287
|
+
- Preserve brand colors, fonts, recognizable patterns
|
|
288
|
+
- Use existing CSS variables and design tokens
|
|
289
|
+
- Introduce changes gradually
|
|
290
|
+
- Flag when a user request conflicts with their design system; recommend the best path
|
|
291
|
+
|
|
292
|
+
---
|
|
293
|
+
|
|
294
|
+
## Step 6: Iteration
|
|
295
|
+
|
|
296
|
+
### Responding to Feedback
|
|
297
|
+
- **"I like it but..."** — Targeted adjustment in the preview, preserve what works
|
|
298
|
+
- **"It's not what I imagined"** — Revise the preview before recoding
|
|
299
|
+
- **"Can you try..."** — Update the preview, re-open
|
|
300
|
+
- **"Perfect!"** — Move from preview to real implementation
|
|
301
|
+
|
|
302
|
+
### When the User is Unsure
|
|
303
|
+
1. Make the decision yourself based on best practices
|
|
304
|
+
2. Explain your reasoning in plain language
|
|
305
|
+
3. Build the preview
|
|
306
|
+
4. Say: "This is what I'd recommend. If something feels off once you see it, tell me and I'll adjust."
|
|
307
|
+
|
|
308
|
+
---
|
|
309
|
+
|
|
310
|
+
## Handling Options — The Recommendation Rule
|
|
311
|
+
|
|
312
|
+
**Every time you present a choice, you MUST include a recommendation.**
|
|
313
|
+
|
|
314
|
+
For HTML previews with variations, render all variations but mark one as recommended in the hub file and in your message. Never present more than 3 variations at once.
|
|
315
|
+
|
|
316
|
+
---
|
|
317
|
+
|
|
318
|
+
## Skill Level Adaptation
|
|
319
|
+
|
|
320
|
+
Infer from how the user communicates. Never ask.
|
|
321
|
+
|
|
322
|
+
- **Non-designer**: Make all decisions, explain plainly, previews are essential, give complete code. Skip jargon.
|
|
323
|
+
- **Some design sense**: Focus on trade-offs, provide code with brief rationale.
|
|
324
|
+
- **Designer/developer**: Be concise, engage as a peer, previews can be lighter.
|
|
325
|
+
|
|
326
|
+
---
|
|
327
|
+
|
|
328
|
+
## Edge Cases
|
|
329
|
+
|
|
330
|
+
- **No existing design**: Derive from project type and stack. Propose a cohesive starting point.
|
|
331
|
+
- **Screenshot input**: Analyze visually, recreate as an HTML preview to confirm understanding before implementing.
|
|
332
|
+
- **Design system conflict**: Flag it, recommend extending the system vs. one-off, explain trade-off.
|
|
333
|
+
- **Accessibility**: Always meet WCAG AA. If a request would fail accessibility, explain plainly and offer an accessible alternative.
|
|
334
|
+
- **Performance**: Flag heavy animations, large images, complex CSS; suggest alternatives.
|
|
335
|
+
- **Dark mode**: If the project supports theming, every preview should include a dark-mode variant (toggle or separate file).
|
|
336
|
+
- **No browser access**: If you can't run the dev server to verify, say so — don't claim success from a passing build alone.
|
|
337
|
+
|
|
338
|
+
---
|
|
339
|
+
|
|
340
|
+
## Resources
|
|
341
|
+
|
|
342
|
+
- **Design principles**: [design-principles.md](references/design-principles.md) — Anti-AI-look patterns and visual quality checklist
|
|
343
|
+
- **Component patterns**: [component-patterns.md](references/component-patterns.md) — Component states, sizing, and interaction patterns
|
|
344
|
+
- **Design spec template**: [design-spec-template.md](assets/design-spec-template.md) — Structured output template for design handoff
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# Design Specification — [Project / Feature Name]
|
|
2
|
+
|
|
3
|
+
> Generated on [date] | Direction: [chosen direction name]
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Overview
|
|
8
|
+
|
|
9
|
+
**Target:** [page / component / feature description]
|
|
10
|
+
**Framework:** [React / Vue / Svelte / etc.]
|
|
11
|
+
**CSS Approach:** [Tailwind / CSS Modules / styled-components / vanilla CSS]
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Design Tokens
|
|
16
|
+
|
|
17
|
+
### Colors
|
|
18
|
+
|
|
19
|
+
| Token | Value | Use |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| `--color-primary` | | Primary actions, brand accent |
|
|
22
|
+
| `--color-primary-hover` | | Primary hover state |
|
|
23
|
+
| `--color-secondary` | | Secondary actions, supporting |
|
|
24
|
+
| `--color-background` | | Page background |
|
|
25
|
+
| `--color-surface` | | Card/panel backgrounds |
|
|
26
|
+
| `--color-text` | | Body text |
|
|
27
|
+
| `--color-text-muted` | | Secondary text, captions |
|
|
28
|
+
| `--color-border` | | Borders, dividers |
|
|
29
|
+
| `--color-success` | | Success states |
|
|
30
|
+
| `--color-warning` | | Warning states |
|
|
31
|
+
| `--color-error` | | Error states |
|
|
32
|
+
|
|
33
|
+
### Typography
|
|
34
|
+
|
|
35
|
+
| Token | Value | Use |
|
|
36
|
+
|---|---|---|
|
|
37
|
+
| `--font-family-body` | | Body text, UI elements |
|
|
38
|
+
| `--font-family-heading` | | Headings (if different from body) |
|
|
39
|
+
| `--font-family-mono` | | Code, technical data |
|
|
40
|
+
| `--text-xs` | 12px / 1.5 | Captions, badges |
|
|
41
|
+
| `--text-sm` | 14px / 1.5 | Secondary text, labels |
|
|
42
|
+
| `--text-base` | 16px / 1.6 | Body text |
|
|
43
|
+
| `--text-lg` | 18px / 1.5 | Subheadings, emphasis |
|
|
44
|
+
| `--text-xl` | 20px / 1.4 | Section headings |
|
|
45
|
+
| `--text-2xl` | 24px / 1.3 | Page headings |
|
|
46
|
+
| `--text-3xl` | 32px / 1.2 | Display, hero |
|
|
47
|
+
| `--text-4xl` | 48px / 1.1 | Large display |
|
|
48
|
+
|
|
49
|
+
### Spacing
|
|
50
|
+
|
|
51
|
+
Base unit: `[4px / 8px]`
|
|
52
|
+
|
|
53
|
+
| Token | Value | Use |
|
|
54
|
+
|---|---|---|
|
|
55
|
+
| `--space-1` | 4px | Tight gaps, inline spacing |
|
|
56
|
+
| `--space-2` | 8px | Component internal padding |
|
|
57
|
+
| `--space-3` | 12px | Compact element gaps |
|
|
58
|
+
| `--space-4` | 16px | Standard element spacing |
|
|
59
|
+
| `--space-6` | 24px | Section internal padding |
|
|
60
|
+
| `--space-8` | 32px | Section gaps |
|
|
61
|
+
| `--space-12` | 48px | Major section separation |
|
|
62
|
+
| `--space-16` | 64px | Page-level spacing |
|
|
63
|
+
|
|
64
|
+
### Borders & Radii
|
|
65
|
+
|
|
66
|
+
| Token | Value | Use |
|
|
67
|
+
|---|---|---|
|
|
68
|
+
| `--border-width` | | Default border width |
|
|
69
|
+
| `--border-color` | | Default border color |
|
|
70
|
+
| `--radius-sm` | | Buttons, inputs, small elements |
|
|
71
|
+
| `--radius-md` | | Cards, panels |
|
|
72
|
+
| `--radius-lg` | | Modals, large containers |
|
|
73
|
+
| `--radius-full` | | Avatars, pills |
|
|
74
|
+
|
|
75
|
+
### Shadows
|
|
76
|
+
|
|
77
|
+
| Token | Value | Use |
|
|
78
|
+
|---|---|---|
|
|
79
|
+
| `--shadow-sm` | | Subtle depth (cards) |
|
|
80
|
+
| `--shadow-md` | | Moderate elevation (dropdowns) |
|
|
81
|
+
| `--shadow-lg` | | High elevation (modals, popovers) |
|
|
82
|
+
|
|
83
|
+
### Transitions
|
|
84
|
+
|
|
85
|
+
| Token | Value | Use |
|
|
86
|
+
|---|---|---|
|
|
87
|
+
| `--transition-fast` | 150ms ease | Hover states, small elements |
|
|
88
|
+
| `--transition-base` | 200ms ease | Standard transitions |
|
|
89
|
+
| `--transition-slow` | 300ms ease-in-out | Layout changes, modals |
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## Layout
|
|
94
|
+
|
|
95
|
+
### Page Structure
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
[Describe or diagram the overall page layout]
|
|
99
|
+
[Include breakpoint behavior]
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Grid / Container
|
|
103
|
+
|
|
104
|
+
- Max width: [value]
|
|
105
|
+
- Columns: [count at each breakpoint]
|
|
106
|
+
- Gutter: [value]
|
|
107
|
+
- Margin: [value at each breakpoint]
|
|
108
|
+
|
|
109
|
+
### Breakpoints
|
|
110
|
+
|
|
111
|
+
| Name | Min Width | Layout Changes |
|
|
112
|
+
|---|---|---|
|
|
113
|
+
| Mobile | 0px | [describe] |
|
|
114
|
+
| Tablet | 768px | [describe] |
|
|
115
|
+
| Desktop | 1024px | [describe] |
|
|
116
|
+
| Wide | 1280px | [describe] |
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Components
|
|
121
|
+
|
|
122
|
+
### [Component Name]
|
|
123
|
+
|
|
124
|
+
**Purpose:** [what the component does]
|
|
125
|
+
|
|
126
|
+
**Variants:**
|
|
127
|
+
- [variant 1]: [description]
|
|
128
|
+
- [variant 2]: [description]
|
|
129
|
+
|
|
130
|
+
**States:**
|
|
131
|
+
| State | Visual Treatment |
|
|
132
|
+
|---|---|
|
|
133
|
+
| Default | |
|
|
134
|
+
| Hover | |
|
|
135
|
+
| Focus | |
|
|
136
|
+
| Active | |
|
|
137
|
+
| Disabled | |
|
|
138
|
+
| Loading | |
|
|
139
|
+
| Error | |
|
|
140
|
+
|
|
141
|
+
**Specs:**
|
|
142
|
+
- Height: [value by size]
|
|
143
|
+
- Padding: [values]
|
|
144
|
+
- Font: [size, weight]
|
|
145
|
+
- Border radius: [value]
|
|
146
|
+
- Colors: [token references]
|
|
147
|
+
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
## Interaction Patterns
|
|
151
|
+
|
|
152
|
+
### [Interaction Name]
|
|
153
|
+
|
|
154
|
+
**Trigger:** [click / hover / scroll / load]
|
|
155
|
+
**Behavior:** [describe the interaction]
|
|
156
|
+
**Duration:** [transition timing]
|
|
157
|
+
**Easing:** [easing function]
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## Accessibility Notes
|
|
162
|
+
|
|
163
|
+
- [ ] All contrast ratios meet WCAG AA
|
|
164
|
+
- [ ] Focus indicators are visible and styled
|
|
165
|
+
- [ ] Interactive elements have accessible labels
|
|
166
|
+
- [ ] Heading hierarchy is logical
|
|
167
|
+
- [ ] Motion respects `prefers-reduced-motion`
|
|
168
|
+
|
|
169
|
+
---
|
|
170
|
+
|
|
171
|
+
## Implementation Notes
|
|
172
|
+
|
|
173
|
+
[Any technical notes, caveats, or implementation-specific guidance]
|
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
# Component Patterns — UI Interaction Best Practices
|
|
2
|
+
|
|
3
|
+
Reference for designing common UI components with proper states, accessibility, and interaction patterns. Load when designing or reviewing specific components.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Buttons
|
|
8
|
+
|
|
9
|
+
### Hierarchy
|
|
10
|
+
|
|
11
|
+
Every interface needs a clear button hierarchy:
|
|
12
|
+
|
|
13
|
+
| Level | Name | Use Case | Visual Treatment |
|
|
14
|
+
|---|---|---|---|
|
|
15
|
+
| 1 | Primary | Main action per section/page | Filled, brand color, high contrast |
|
|
16
|
+
| 2 | Secondary | Supporting actions | Outlined or muted fill |
|
|
17
|
+
| 3 | Tertiary / Ghost | Low-priority actions, cancel | Text-only or very subtle background |
|
|
18
|
+
| 4 | Destructive | Delete, remove, irreversible | Red/danger color, confirm pattern |
|
|
19
|
+
| 5 | Icon-only | Compact actions (close, menu, edit) | Icon with tooltip, adequate touch target |
|
|
20
|
+
|
|
21
|
+
### Required States
|
|
22
|
+
|
|
23
|
+
Every button must handle:
|
|
24
|
+
- **Default** — Resting state
|
|
25
|
+
- **Hover** — Subtle background/shadow change (desktop)
|
|
26
|
+
- **Focus** — Visible ring/outline for keyboard users (2px offset, contrasting color)
|
|
27
|
+
- **Active/Pressed** — Slightly darker, subtle depression
|
|
28
|
+
- **Disabled** — Reduced opacity (0.5-0.6), no pointer events, `aria-disabled`
|
|
29
|
+
- **Loading** — Spinner or dots replacing text, button disabled during action
|
|
30
|
+
|
|
31
|
+
### Sizing
|
|
32
|
+
|
|
33
|
+
| Size | Height | Padding (x) | Font Size | Use Case |
|
|
34
|
+
|---|---|---|---|---|
|
|
35
|
+
| sm | 32px | 12px | 13-14px | Dense UI, table actions, tag actions |
|
|
36
|
+
| md | 40px | 16px | 14-15px | Standard forms, toolbars |
|
|
37
|
+
| lg | 48px | 24px | 16px | Hero CTAs, mobile-first interfaces |
|
|
38
|
+
|
|
39
|
+
### Accessibility
|
|
40
|
+
- Minimum touch target: 44×44px (even if visual size is smaller, pad the clickable area)
|
|
41
|
+
- Always include accessible label (text content or `aria-label` for icon buttons)
|
|
42
|
+
- Don't rely on color alone — icons or text should reinforce meaning
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## Forms
|
|
47
|
+
|
|
48
|
+
### Input Fields
|
|
49
|
+
|
|
50
|
+
**Required states:**
|
|
51
|
+
- Default — Clear border, label above
|
|
52
|
+
- Focus — Highlighted border (brand color), optional subtle shadow
|
|
53
|
+
- Filled — Same as default but with content
|
|
54
|
+
- Error — Red/danger border, error message below, `aria-invalid="true"`
|
|
55
|
+
- Disabled — Muted background, reduced opacity
|
|
56
|
+
- Read-only — No border/minimal border, text appears as content
|
|
57
|
+
|
|
58
|
+
**Layout rules:**
|
|
59
|
+
- Label above input (not beside, not as placeholder)
|
|
60
|
+
- Placeholder text is supplementary, never the only label
|
|
61
|
+
- Error messages appear below the input, in context
|
|
62
|
+
- Help text appears below label or below input, not as tooltip
|
|
63
|
+
- Group related fields (name + email, street + city + state)
|
|
64
|
+
|
|
65
|
+
**Sizing:**
|
|
66
|
+
|
|
67
|
+
| Size | Height | Font Size | Use Case |
|
|
68
|
+
|---|---|---|---|
|
|
69
|
+
| sm | 32px | 13-14px | Dense forms, admin panels |
|
|
70
|
+
| md | 40px | 14-15px | Standard forms |
|
|
71
|
+
| lg | 48px | 16px | Landing pages, mobile |
|
|
72
|
+
|
|
73
|
+
### Select / Dropdown
|
|
74
|
+
|
|
75
|
+
- Show current selection in the trigger
|
|
76
|
+
- Keyboard navigation: arrow keys, type-ahead, Enter to select, Escape to close
|
|
77
|
+
- Long lists: include search/filter
|
|
78
|
+
- Multi-select: use checkboxes inside dropdown, show count or tags in trigger
|
|
79
|
+
|
|
80
|
+
### Checkbox & Radio
|
|
81
|
+
|
|
82
|
+
- Minimum 44×44px touch target (including label)
|
|
83
|
+
- Label always to the right of the indicator
|
|
84
|
+
- Checkbox: independent selections (multi-select)
|
|
85
|
+
- Radio: mutually exclusive within a group
|
|
86
|
+
- Indeterminate checkbox state for "select all" with partial selection
|
|
87
|
+
|
|
88
|
+
### Form Validation
|
|
89
|
+
|
|
90
|
+
- **Inline validation**: Validate on blur (not on every keystroke)
|
|
91
|
+
- **Submit validation**: Validate all fields, focus the first error, scroll if needed
|
|
92
|
+
- **Error messaging**: Specific ("Email must include @") not generic ("Invalid input")
|
|
93
|
+
- **Success feedback**: Brief confirmation, then move on — don't celebrate trivial actions
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Cards
|
|
98
|
+
|
|
99
|
+
### When to Use
|
|
100
|
+
- Displaying a collection of items with mixed content (image + text + actions)
|
|
101
|
+
- Content that can be browsed and compared
|
|
102
|
+
- NOT for single content blocks or sequential content (use sections instead)
|
|
103
|
+
|
|
104
|
+
### Anatomy
|
|
105
|
+
1. **Media area** (optional) — Image, video, or illustration at top or left
|
|
106
|
+
2. **Header** — Title, subtitle, metadata
|
|
107
|
+
3. **Body** — Description or summary content
|
|
108
|
+
4. **Footer** (optional) — Actions, tags, or secondary metadata
|
|
109
|
+
|
|
110
|
+
### Interaction Patterns
|
|
111
|
+
- **Clickable card**: Entire card is a link, hover shows elevation change
|
|
112
|
+
- **Card with actions**: Card is not clickable, specific buttons/links inside are
|
|
113
|
+
- **Never both**: Don't make the whole card clickable AND have buttons inside it
|
|
114
|
+
|
|
115
|
+
### States
|
|
116
|
+
- Default, Hover (if clickable), Selected (in a selection context), Loading (skeleton)
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Navigation
|
|
121
|
+
|
|
122
|
+
### Top Navigation (Navbar)
|
|
123
|
+
|
|
124
|
+
- Logo/brand on the left
|
|
125
|
+
- Primary nav items horizontally centered or right-aligned
|
|
126
|
+
- Active page indicator: bold text, underline, or background highlight
|
|
127
|
+
- Mobile: hamburger menu (3 lines) → slide-out or full-screen overlay
|
|
128
|
+
- Sticky/fixed: include subtle shadow or border when scrolled
|
|
129
|
+
- Max 5-7 primary items; overflow into "More" dropdown
|
|
130
|
+
|
|
131
|
+
### Sidebar Navigation
|
|
132
|
+
|
|
133
|
+
- Collapsible for more content space
|
|
134
|
+
- Active item: filled background with brand color, or left border accent
|
|
135
|
+
- Group items with section headers
|
|
136
|
+
- Icons + labels in expanded state, icons-only in collapsed state with tooltips
|
|
137
|
+
- Scroll independently from main content
|
|
138
|
+
|
|
139
|
+
### Breadcrumbs
|
|
140
|
+
|
|
141
|
+
- Show current location in hierarchy
|
|
142
|
+
- Each segment is a link except the current page
|
|
143
|
+
- Separator: `/` or `>` or chevron icon
|
|
144
|
+
- Truncate long paths: show first, `...`, last 2 segments
|
|
145
|
+
|
|
146
|
+
### Tabs
|
|
147
|
+
|
|
148
|
+
- Horizontal for 2-5 options, vertical for 5+ or when labels are long
|
|
149
|
+
- Active tab: bold/colored text + bottom border (horizontal) or left border (vertical)
|
|
150
|
+
- Tab content switches without page reload
|
|
151
|
+
- Keyboard: arrow keys to switch, Tab to enter content area
|
|
152
|
+
- Don't nest tabs within tabs
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## Modals & Dialogs
|
|
157
|
+
|
|
158
|
+
### When to Use
|
|
159
|
+
- Confirming destructive actions
|
|
160
|
+
- Short forms that don't warrant a new page (login, quick edit)
|
|
161
|
+
- Displaying focused content that blocks the main flow
|
|
162
|
+
|
|
163
|
+
### When NOT to Use
|
|
164
|
+
- Displaying information that could be inline
|
|
165
|
+
- Long forms or multi-step flows (use a page instead)
|
|
166
|
+
- Welcome messages or tutorials (use onboarding flows)
|
|
167
|
+
|
|
168
|
+
### Anatomy
|
|
169
|
+
- **Overlay/backdrop**: Semi-transparent dark (rgba(0,0,0,0.4-0.6))
|
|
170
|
+
- **Container**: Centered, max-width 480-640px, adequate padding (24-32px)
|
|
171
|
+
- **Header**: Title + close button (X) in top-right
|
|
172
|
+
- **Body**: Content area, scrollable if content overflows
|
|
173
|
+
- **Footer**: Action buttons (primary right, cancel left)
|
|
174
|
+
|
|
175
|
+
### Interaction
|
|
176
|
+
- Escape key closes the modal
|
|
177
|
+
- Clicking backdrop closes (for non-critical modals) or doesn't (for confirmations)
|
|
178
|
+
- Focus trapped inside modal (Tab cycles through modal elements only)
|
|
179
|
+
- Return focus to trigger element on close
|
|
180
|
+
- Prevent body scroll while modal is open
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
## Tables
|
|
185
|
+
|
|
186
|
+
### Best Practices
|
|
187
|
+
- Align text left, numbers right
|
|
188
|
+
- Header row: bold, subtle background, sticky on scroll
|
|
189
|
+
- Zebra striping OR subtle horizontal borders (not both)
|
|
190
|
+
- Minimum row height: 48px for touch, 36px for dense desktop
|
|
191
|
+
- Sortable columns: show sort indicator (arrow up/down)
|
|
192
|
+
- Pagination or virtual scroll for large datasets
|
|
193
|
+
|
|
194
|
+
### Responsive
|
|
195
|
+
- Priority columns stay visible, secondary columns hide on mobile
|
|
196
|
+
- Alternative: card-based layout on mobile instead of table
|
|
197
|
+
- Horizontal scroll as a last resort (wrap in a scroll container with shadow indicators)
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## Feedback & Status
|
|
202
|
+
|
|
203
|
+
### Toast / Snackbar
|
|
204
|
+
- Brief messages (1-2 lines), auto-dismiss after 4-6 seconds
|
|
205
|
+
- Position: bottom-center or top-right
|
|
206
|
+
- Types: success (green), error (red), warning (amber), info (blue/neutral)
|
|
207
|
+
- Include dismiss action and optional undo for destructive actions
|
|
208
|
+
- Stack new toasts, don't replace existing ones
|
|
209
|
+
|
|
210
|
+
### Empty States
|
|
211
|
+
- Illustration or icon (purposeful, not decorative)
|
|
212
|
+
- Clear headline: what this area is for
|
|
213
|
+
- Description: why it's empty
|
|
214
|
+
- CTA: how to populate it
|
|
215
|
+
- Don't just show a blank white space
|
|
216
|
+
|
|
217
|
+
### Loading States
|
|
218
|
+
- **Skeleton screens** (preferred): Gray placeholder shapes matching content layout
|
|
219
|
+
- **Spinner**: Only for short, indeterminate waits (< 3 seconds expected)
|
|
220
|
+
- **Progress bar**: For determinate operations with known duration
|
|
221
|
+
- **Inline loading**: Button spinner, input loading indicator
|
|
222
|
+
|
|
223
|
+
### Error States
|
|
224
|
+
- Page-level: Friendly message + illustration, retry button, link to support
|
|
225
|
+
- Inline: Red border, error text below the field, `aria-invalid`
|
|
226
|
+
- Network: "Something went wrong" with retry, not a technical error dump
|
|
227
|
+
- 404: Helpful redirect suggestions, search, home link
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## Accessibility Essentials
|
|
232
|
+
|
|
233
|
+
### Color & Contrast
|
|
234
|
+
- Body text: 4.5:1 contrast ratio minimum (WCAG AA)
|
|
235
|
+
- Large text (18px+ or 14px+ bold): 3:1 minimum
|
|
236
|
+
- Interactive elements: 3:1 against adjacent colors
|
|
237
|
+
- Don't use color as the only indicator — pair with icons, text, or patterns
|
|
238
|
+
|
|
239
|
+
### Keyboard Navigation
|
|
240
|
+
- All interactive elements focusable via Tab
|
|
241
|
+
- Visible focus indicator (not just browser default — design a custom one)
|
|
242
|
+
- Logical tab order matching visual layout
|
|
243
|
+
- Escape closes overlays, Enter activates buttons/links
|
|
244
|
+
|
|
245
|
+
### Screen Readers
|
|
246
|
+
- Meaningful alt text for informational images
|
|
247
|
+
- Empty alt (`alt=""`) for decorative images
|
|
248
|
+
- Proper heading hierarchy (h1 → h2 → h3, no skipping)
|
|
249
|
+
- ARIA labels for icon-only buttons and complex widgets
|
|
250
|
+
- Live regions for dynamic content updates (toast notifications, form errors)
|
|
251
|
+
|
|
252
|
+
### Motion
|
|
253
|
+
- Respect `prefers-reduced-motion` — disable or simplify animations
|
|
254
|
+
- No auto-playing video or audio without user control
|
|
255
|
+
- Avoid rapid flashing (3 flashes per second max)
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
# Design Principles — Anti-AI Aesthetic & Authentic Design Craft
|
|
2
|
+
|
|
3
|
+
Reference for producing designs that feel human-crafted, intentional, and unique. Load this when implementing designs or reviewing design quality.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Anti-AI-Look Patterns
|
|
8
|
+
|
|
9
|
+
AI-generated designs share recognizable traits. Avoid these to produce authentic work.
|
|
10
|
+
|
|
11
|
+
### Layout Anti-Patterns
|
|
12
|
+
|
|
13
|
+
| AI Trap | Why It Feels Generic | Do Instead |
|
|
14
|
+
|---|---|---|
|
|
15
|
+
| Perfect 3-column symmetry for everything | Real content isn't symmetric | Vary column widths, use 2-col or asymmetric grids |
|
|
16
|
+
| Every section is full-width hero + centered text | Repetitive rhythm, no visual variety | Mix layout types: sidebar, offset, editorial, split |
|
|
17
|
+
| Giant hero with headline + subtitle + CTA on every page | Cookie-cutter template feel | Match the hero to content importance — some pages don't need one |
|
|
18
|
+
| Everything centered on the page | Monotonous visual flow | Use left-aligned text with intentional center/right accents |
|
|
19
|
+
| Equal spacing everywhere | Flat, robotic rhythm | Vary spacing to create grouping and breathing room |
|
|
20
|
+
| Card grids with identical card sizes | Catalog/stock feel | Vary card sizes, feature one, use masonry or editorial layouts |
|
|
21
|
+
|
|
22
|
+
### Color Anti-Patterns
|
|
23
|
+
|
|
24
|
+
| AI Trap | Why It Feels Generic | Do Instead |
|
|
25
|
+
|---|---|---|
|
|
26
|
+
| Blue-to-purple gradient as primary | Overused AI default | Choose a palette rooted in the brand or project's personality |
|
|
27
|
+
| Neon accent on dark background | "Tech startup template" look | Use muted, sophisticated accents — or bold ones with restraint |
|
|
28
|
+
| Using 6+ colors with equal prominence | Visual noise, no hierarchy | 1-2 primary colors, 1 accent, rest neutrals |
|
|
29
|
+
| Gradient backgrounds on every section | Decorative without purpose | Use solid colors; reserve gradients for specific emphasis |
|
|
30
|
+
| Pure black (#000) text on pure white (#fff) | Harsh contrast, screen glare | Use near-black (#1a1a1a–#2d2d2d) on off-white (#f8f8f8–#fafafa) |
|
|
31
|
+
| Colored shadows (purple/blue box-shadows) | Trendy but rarely appropriate | Neutral shadows unless the brand specifically calls for it |
|
|
32
|
+
|
|
33
|
+
### Typography Anti-Patterns
|
|
34
|
+
|
|
35
|
+
| AI Trap | Why It Feels Generic | Do Instead |
|
|
36
|
+
|---|---|---|
|
|
37
|
+
| Using Inter/Poppins/Montserrat for everything | Ubiquitous AI defaults | Consider the project's personality — serif for editorial, geometric sans for tech, humanist for approachable |
|
|
38
|
+
| Only 2 sizes: heading and body | Flat hierarchy | Use a proper type scale (e.g., 12/14/16/20/24/32/48) |
|
|
39
|
+
| All text in the same weight | No emphasis, everything competes | Use 2-3 weights (regular, medium, bold) with clear purpose |
|
|
40
|
+
| ALL CAPS EVERYWHERE | Aggressive, hard to read | Reserve caps for small labels, buttons, or overlines |
|
|
41
|
+
| Giant display text with no supporting content | Empty visual calories | Size should match content importance |
|
|
42
|
+
|
|
43
|
+
### Component Anti-Patterns
|
|
44
|
+
|
|
45
|
+
| AI Trap | Why It Feels Generic | Do Instead |
|
|
46
|
+
|---|---|---|
|
|
47
|
+
| border-radius: 9999px on everything | Bubbly, toy-like | Choose 1-2 radius values that match the design's tone (4-8px for sharp, 12-16px for soft) |
|
|
48
|
+
| Glassmorphism / frosted glass everywhere | Trend over function | Use glass effects sparingly where depth communication is needed |
|
|
49
|
+
| Drop shadows on everything | Visual heaviness, everything "floats" | Shadow only elements that conceptually need elevation (modals, dropdowns, cards on hover) |
|
|
50
|
+
| Outlined icon + outlined button + outlined card | Everything is a border, nothing has weight | Mix filled and outlined treatments for hierarchy |
|
|
51
|
+
| Decorative blob SVGs or wave dividers | Instant AI template identifier | Use geometric shapes with purpose, or no decoration at all |
|
|
52
|
+
| Stock illustration people with purple skin | Unmistakable AI/startup template | Use photography, custom illustration, or no illustration |
|
|
53
|
+
|
|
54
|
+
### Interaction Anti-Patterns
|
|
55
|
+
|
|
56
|
+
| AI Trap | Why It Feels Generic | Do Instead |
|
|
57
|
+
|---|---|---|
|
|
58
|
+
| Everything has a hover scale(1.05) | Bouncy, distracting | Reserve scale for interactive cards; use color/shadow changes for most hover states |
|
|
59
|
+
| 0.3s ease on everything | Sluggish, indiscriminate | Use faster transitions (150-200ms) for small elements, slower (300-400ms) for layout changes |
|
|
60
|
+
| Fade-in-up on scroll for every element | Scroll-jacking, animation fatigue | Animate only key content on first appearance; let secondary content be static |
|
|
61
|
+
| Loading spinners as the only loading state | No context about what's loading | Use skeleton screens, progressive content reveal, or inline loading indicators |
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Authentic Design Principles
|
|
66
|
+
|
|
67
|
+
### 1. Content-First Hierarchy
|
|
68
|
+
|
|
69
|
+
Design serves content, not the other way around.
|
|
70
|
+
|
|
71
|
+
- Read the actual content before choosing layout
|
|
72
|
+
- Size elements proportional to their importance
|
|
73
|
+
- Use whitespace to group related content and separate sections
|
|
74
|
+
- Ask: "What should the user see first, second, third?"
|
|
75
|
+
|
|
76
|
+
### 2. Intentional Contrast
|
|
77
|
+
|
|
78
|
+
Every visual difference should communicate something.
|
|
79
|
+
|
|
80
|
+
- **Size contrast** — Headings vs. body, featured vs. standard items
|
|
81
|
+
- **Weight contrast** — Bold labels vs. regular values, strong CTAs vs. subtle links
|
|
82
|
+
- **Color contrast** — Primary actions vs. secondary, active states vs. default
|
|
83
|
+
- **Space contrast** — Tight groups of related items, generous gaps between sections
|
|
84
|
+
- **Density contrast** — Dense data areas vs. breathing hero/summary areas
|
|
85
|
+
|
|
86
|
+
### 3. Systematic but Not Robotic
|
|
87
|
+
|
|
88
|
+
Use systems (type scale, spacing scale, color tokens) but break them intentionally.
|
|
89
|
+
|
|
90
|
+
- Establish a base grid (4px or 8px) but don't snap everything mechanically
|
|
91
|
+
- Use your type scale but occasionally break it for display/hero moments
|
|
92
|
+
- Maintain consistent component patterns but allow contextual variations
|
|
93
|
+
|
|
94
|
+
### 4. Typography Does the Heavy Lifting
|
|
95
|
+
|
|
96
|
+
Most visual hierarchy comes from type, not decoration.
|
|
97
|
+
|
|
98
|
+
- Establish a clear scale: body → subhead → section head → page title → display
|
|
99
|
+
- Use weight and size together: a 14px bold label and a 16px regular body text create clear hierarchy without needing different colors
|
|
100
|
+
- Line-height matters: tighter for headings (1.1-1.3), looser for body (1.5-1.7)
|
|
101
|
+
- Letter-spacing: slightly positive for small caps/labels, zero or negative for large display text
|
|
102
|
+
|
|
103
|
+
### 5. Color as Communication
|
|
104
|
+
|
|
105
|
+
Color should mean something, not just decorate.
|
|
106
|
+
|
|
107
|
+
- **Brand color** — Primary actions, key elements, brand identity
|
|
108
|
+
- **Semantic color** — Success (green), warning (amber), error (red), info (blue)
|
|
109
|
+
- **Neutral palette** — Background, text, borders, dividers (this is 80% of your palette)
|
|
110
|
+
- **Accent** — Sparingly, to draw attention to one thing
|
|
111
|
+
|
|
112
|
+
### 6. Space Creates Meaning
|
|
113
|
+
|
|
114
|
+
Proximity and spacing communicate relationships.
|
|
115
|
+
|
|
116
|
+
- Items close together = related
|
|
117
|
+
- Items far apart = separate concepts
|
|
118
|
+
- Consistent internal padding = belonging to the same container
|
|
119
|
+
- Asymmetric margins = visual rhythm and movement
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## Design Quality Checklist
|
|
124
|
+
|
|
125
|
+
Use this to evaluate designs before presenting to the user:
|
|
126
|
+
|
|
127
|
+
### Visual Hierarchy
|
|
128
|
+
- [ ] The most important element is visually dominant
|
|
129
|
+
- [ ] There is a clear reading order (F-pattern or Z-pattern where appropriate)
|
|
130
|
+
- [ ] Headings form a logical scale (not random sizes)
|
|
131
|
+
- [ ] CTAs are visually distinct from surrounding content
|
|
132
|
+
|
|
133
|
+
### Typography
|
|
134
|
+
- [ ] Body text is 16px+ for readability
|
|
135
|
+
- [ ] Line length is 45-75 characters for body text
|
|
136
|
+
- [ ] Heading/body font pairing is intentional
|
|
137
|
+
- [ ] No more than 3 font weights in active use
|
|
138
|
+
|
|
139
|
+
### Color
|
|
140
|
+
- [ ] Palette has 2 or fewer primary/accent colors
|
|
141
|
+
- [ ] Text:background contrast meets WCAG AA (4.5:1 for body, 3:1 for large text)
|
|
142
|
+
- [ ] Color is not the only indicator of state (icons, text, or shape also signal)
|
|
143
|
+
- [ ] Neutral palette has enough range (light bg, medium borders, dark text)
|
|
144
|
+
|
|
145
|
+
### Spacing & Layout
|
|
146
|
+
- [ ] Spacing follows a consistent scale (4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px)
|
|
147
|
+
- [ ] Related elements are grouped with tighter spacing
|
|
148
|
+
- [ ] Sections have comfortable breathing room
|
|
149
|
+
- [ ] Layout works at mobile, tablet, and desktop widths
|
|
150
|
+
|
|
151
|
+
### Components
|
|
152
|
+
- [ ] Interactive elements have visible hover/focus states
|
|
153
|
+
- [ ] Buttons have clear hierarchy (primary, secondary, tertiary/ghost)
|
|
154
|
+
- [ ] Form inputs have labels, placeholders are not used as labels
|
|
155
|
+
- [ ] Empty states, loading states, and error states are designed
|
|
156
|
+
|
|
157
|
+
### Interaction
|
|
158
|
+
- [ ] Transitions are fast (150-200ms) and purposeful
|
|
159
|
+
- [ ] Hover states indicate interactivity without being distracting
|
|
160
|
+
- [ ] Focus indicators are visible for keyboard navigation
|
|
161
|
+
- [ ] Animations don't block user interaction
|
|
162
|
+
|
|
163
|
+
### Authenticity
|
|
164
|
+
- [ ] Design doesn't match common template/AI patterns listed above
|
|
165
|
+
- [ ] Layout has visual variety (not repeating the same section format)
|
|
166
|
+
- [ ] Decoration (if any) serves a purpose
|
|
167
|
+
- [ ] The design reflects the project's unique personality
|