@cliangdev/conductor 0.41.1 → 0.42.1

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 (44) hide show
  1. package/assets/claude/agents/conductor-coder.md +278 -7
  2. package/assets/claude/agents/{conductor-content-art-director.md → conductor-marketing-art-director.md} +2 -2
  3. package/assets/claude/agents/{conductor-content-creative-director.md → conductor-marketing-creative-director.md} +12 -8
  4. package/assets/claude/agents/{conductor-content-ideator.md → conductor-marketing-ideator.md} +11 -5
  5. package/assets/claude/agents/{conductor-content-scriptwriter.md → conductor-marketing-scriptwriter.md} +19 -6
  6. package/assets/claude/agents/{conductor-content-strategist.md → conductor-marketing-strategist.md} +2 -2
  7. package/assets/claude/commands/conductor/implement.md +1 -1
  8. package/assets/claude/commands/conductor/marketing.md +26 -0
  9. package/assets/claude/skills/conductor-marketing-create/SKILL.md +87 -0
  10. package/assets/claude/skills/{conductor-creative → conductor-marketing-create}/references/brand-kit-setup.md +2 -3
  11. package/assets/claude/skills/{conductor-content-studio → conductor-marketing-create}/references/design-critique.md +0 -1
  12. package/assets/claude/skills/{conductor-creative/SKILL.md → conductor-marketing-create/references/direct.md} +50 -60
  13. package/assets/claude/skills/{conductor-creative → conductor-marketing-create}/references/hooks.md +13 -9
  14. package/assets/claude/skills/{conductor-content-studio → conductor-marketing-create}/references/idea-template.md +2 -2
  15. package/assets/claude/skills/{conductor-creative → conductor-marketing-create}/references/layout-guide.md +0 -1
  16. package/assets/claude/skills/{conductor-creative → conductor-marketing-create}/references/realism-check.md +0 -1
  17. package/assets/claude/skills/{conductor-content-studio → conductor-marketing-create}/references/rubric.md +15 -6
  18. package/assets/claude/skills/{conductor-content-studio → conductor-marketing-create}/references/script-template.md +4 -2
  19. package/assets/claude/skills/{conductor-creative → conductor-marketing-create}/references/slideshow-formats.md +12 -9
  20. package/assets/claude/skills/{conductor-content-studio/SKILL.md → conductor-marketing-create/references/team-run.md} +33 -37
  21. package/assets/claude/skills/conductor-marketing-create/references/voice.md +120 -0
  22. package/assets/claude/skills/{conductor-publisher → conductor-marketing-publish}/SKILL.md +5 -5
  23. package/assets/claude/skills/{conductor-marketing-analyst → conductor-marketing-report}/SKILL.md +11 -4
  24. package/assets/cli-manifest.json +17 -37
  25. package/dist/lib/plugin-assets.d.ts.map +1 -1
  26. package/dist/lib/plugin-assets.js +98 -42
  27. package/dist/lib/plugin-assets.js.map +1 -1
  28. package/package.json +1 -1
  29. package/assets/claude/commands/conductor/content.md +0 -66
  30. package/assets/claude/commands/conductor/creative.md +0 -108
  31. package/assets/claude/commands/conductor/marketing-report.md +0 -38
  32. package/assets/claude/skills/conductor-coder/SKILL.md +0 -282
  33. package/assets/claude/skills/conductor-content-studio/references/layout-guide.md +0 -73
  34. package/assets/claude/skills/conductor-content-studio/references/realism-check.md +0 -95
  35. package/assets/claude/skills/conductor-content-studio/references/slideshow-formats.md +0 -135
  36. package/assets/claude/skills/conductor-creative/references/design-critique.md +0 -52
  37. package/assets/claude/skills/conductor-ux-ui-design/SKILL.md +0 -346
  38. package/assets/claude/skills/conductor-ux-ui-design/references/design-tokens.md +0 -359
  39. /package/assets/claude/skills/{conductor-content-studio → conductor-marketing-create}/references/capabilities.md +0 -0
  40. /package/assets/claude/skills/{conductor-content-studio → conductor-marketing-create}/references/compliance-checklist.md +0 -0
  41. /package/assets/claude/skills/{conductor-content-studio → conductor-marketing-create}/references/platform-specs.md +0 -0
  42. /package/assets/claude/skills/{conductor-content-studio → conductor-marketing-create}/references/publish-pack-template.md +0 -0
  43. /package/assets/claude/skills/{conductor-content-studio → conductor-marketing-create}/references/shotlist-template.md +0 -0
  44. /package/assets/claude/skills/{conductor-marketing-analyst → conductor-marketing-report}/references/html-layout.md +0 -0
@@ -1,135 +0,0 @@
1
- <!-- Keep identical to the copy in the other creative skill (conductor-creative / conductor-content-studio references/slideshow-formats.md). Skills install independently and cannot reference each other. -->
2
- # Slideshow formats
3
-
4
- For organic posts: a native-looking photo slideshow (TikTok photo post, Instagram carousel) that
5
- promotes an app or product by being worth watching first. Build it with `compose_slideshow`, then
6
- post it as a CAROUSEL Creative. Ads use the brand layouts (STILL) instead; this is not the ad path.
7
-
8
- Branding is light: no logo, badge or offer on the slides. The product appears as the payoff, not the
9
- opener.
10
-
11
- ## Post anatomy
12
-
13
- Aim for 5 to 7 slides. Each slide has one job.
14
-
15
- 1. **Slide 1, the hook.** A human tension or a result people want to keep. Never a feature, the
16
- product name or a price.
17
- 2. **Middle slides, the value.** The part people save or send: the list, the plan, the fix, the story
18
- beat. Saves and sends carry a post beyond followers.
19
- 3. **Slide N-1, the payoff.** The product in use on a real screenshot (a `screen` slide, optionally
20
- with `callouts`) plus one plain mention, such as "I keep mine in <App>".
21
- 4. **Last slide, the ask.** A save or follow ask: "Save this. Link in bio."
22
-
23
- ## Slide types
24
-
25
- Every slide takes `type` (default `photo`), an optional background (`bg` path, `bgColor`, `blur`,
26
- `grade`, `grain`, `dim`) and `texts`. Each text is `{t, y, fs, style}`; the first text of a slide
27
- needs `y`, and later texts without `y` stack under the previous one.
28
-
29
- | Type | For | Key fields | Use when |
30
- |---|---|---|---|
31
- | `photo` | A full-bleed photo with text on it | `bg`, `pos`, `grade`, `grain`, `dim`, `texts` | The default hook, list or story slide |
32
- | `screen` | A real app screenshot in a phone frame | `shot`, `phoneY`, `pw`, `cropH`, `callouts [{x, y, label}]`, `bg`, `blur`, `texts` | The payoff slide (N-1); callouts point at what to notice |
33
- | `notes` | A Notes-app page | `title`, `date`, `items` (strings or `{t, done, strike}`), `paras` | A plan, checklist or "what I do now" |
34
- | `messages` | A chat thread | `bubbles [{from: "me"|"them", t}]` | Doubt or conflict: what someone said to you |
35
- | `grid` | A wall of small photos | `cols`, `gridTop`, `photos [{src, x, badge, cap, restore}]` | "Everything you saved and never used"; one tile `restore`d for the close |
36
- | `stack` | Photos stacked in a column | `photos [{src, label}]` | A before/after with `label`s ("Before", "After") or a short comparison |
37
- | `tier` | A tier list | `rows [{k, c, items}]`, `ts` | Ranking, "what's worth it and what isn't" |
38
- | `week` | A week planner | `days [{d, t, img, icon, fog}]` | A routine or plan across days |
39
- | `receipt` | A till receipt | `head`, `sections [{h, items}]`, `count` | A tally or breakdown; `count` must be a real figure |
40
- | `placard` | A museum-style label over a photo | `bg`, `ex`, `title`, `y`, `lines [{k, v}]` | A deadpan, collectible-feeling item card |
41
-
42
- Text `style`: `box` (white rounded box, TikTok's own text look), `dark` (dark box), `stroke` (white
43
- text, black outline), `sub` (smaller subline).
44
-
45
- ### Example spec
46
-
47
- A five-slide "stop doing X" post. Paths are relative to the spec file or absolute.
48
-
49
- ```json
50
- {
51
- "id": "stop-over-saving",
52
- "slides": [
53
- {"type": "photo", "bg": "photos/desk.jpg", "grade": true, "grain": true,
54
- "texts": [{"t": "Stop saving things you will never open.", "y": 30, "fs": 76}]},
55
- {"type": "messages",
56
- "bubbles": [{"from": "them", "t": "did you ever look at that thing you saved?"},
57
- {"from": "me", "t": "define look"}],
58
- "texts": [{"t": "Be honest.", "y": 20}]},
59
- {"type": "notes", "title": "What I do now", "date": "Today",
60
- "items": ["Save one thing", {"t": "Open it within a day", "done": true}, "Delete the rest"]},
61
- {"type": "screen", "shot": "shots/home.png", "phoneY": 40, "pw": 600,
62
- "callouts": [{"x": 50, "y": 30, "label": "one tap"}],
63
- "texts": [{"t": "I keep mine in <App>.", "y": 18}]},
64
- {"type": "photo", "bg": "photos/desk.jpg", "dim": true,
65
- "texts": [{"t": "Save this.", "y": 32, "fs": 80}, {"t": "Link in bio.", "style": "sub"}]}
66
- ]
67
- }
68
- ```
69
-
70
- ## Hook archetypes
71
-
72
- Pick one per post and name it in the idea. Change one thing per post so results are comparable.
73
-
74
- | Archetype | Slide 1 | Slides |
75
- |---|---|---|
76
- | Saved-but-never-used guilt | "Camera-roll graveyard." | `grid` (one tile `restore`d at the end), `photo`, `screen`, ask |
77
- | Doubt or conflict | What someone said to you (needs a true story) | `messages`, `photo`, `notes`, `screen`, ask |
78
- | Stop doing X | "Stop doing X." | `photo` with the reason per slide, `screen`, ask |
79
- | Numbered list | "5 things worth saving" | `photo` per item, `screen` last, ask |
80
- | Tier list | "Ranking everything I tried" | `tier`, `photo` close-ups, `screen`, ask |
81
- | Notes-app plan | "My plan for the week" | `notes`, `week`, `screen`, ask |
82
- | POV | "POV: you finally did it" | `photo` (hands or a real scene), `screen`, `photo`, ask |
83
- | Before / after | "Week 1 vs week 4" | `stack` with `label`s, `photo`, `screen`, ask |
84
-
85
- ## Text rules
86
-
87
- - Native box text (`box`) or white text with a black stroke (`stroke`); centred, bold, sans.
88
- - At most 8 words a line and 3 lines a box.
89
- - Keep text between about y 16 and y 75 (percent of the 9:16 frame). That survives the 4:5 Instagram
90
- cut and the platform UI (top bar, bottom caption, right button column).
91
- - The first text of every slide needs `y`.
92
- - Read the composer's `checks`; an `error` severity blocks the preview.
93
-
94
- ## Resolution
95
-
96
- Slides are 1080x1920 (and 1080x1350 for Instagram). Never upscale a background photo: the full-bleed
97
- scale is `max(1080/w, 1920/h)` for a photo of w x h (use `max(1080/w, 1350/h)` for the 4:5 cut). A 1200x1200
98
- photo full-bleed at 9:16 uses 675x1200 source pixels, a 1.6x upscale. Check every `bg` and
99
- `photos[].src` before composing and refuse a full-bleed use above 1.0x. The fixes are: generate at
100
- the largest size in that aspect (`aspect: "9:16"`), use a different photo, or use a slide type that
101
- shows the photo framed at or below native size (such as `grid` or `stack`).
102
-
103
- ## Honesty and brand
104
-
105
- - No logo, badge or offer on the slides. The offer, if any, goes in the caption.
106
- - No invented numbers or claims. A placeholder count (a receipt `count`, "312 saved") must be
107
- replaced with a real figure, or the line rewritten without one.
108
- - Real screenshots only for `screen` slides; never mock up the product.
109
- - A generated photo needs the platform's AI label turned on. Turn on the platform's branded-content
110
- or "your brand" setting for a brand's own promotional post.
111
- - A conflict or testimonial story must be true, and anyone shown or quoted must be real and agree.
112
-
113
- ## Getting the download
114
-
115
- Captions on TikTok and Instagram cannot hold clickable links, so do not rely on one:
116
-
117
- - Name the app in the caption and on slide N-1, so it can be searched ("search <App> in the App
118
- Store").
119
- - Pin a comment that says where to find it.
120
- - Keep the link in the profile bio.
121
- - Repost the post to Instagram Stories with a link sticker.
122
-
123
- ## Flow
124
-
125
- 1. Write the spec (`slideshow-spec.json`); call `compose_slideshow({specPath})`.
126
- 2. If `passed` is false, fix every `error` check and compose again. Warnings are advisory.
127
- 3. `preview_creative_draft({kind: "CAROUSEL", slidePaths, caption, slideAltText})` using the
128
- returned `slidePaths` (`9x16` for TikTok, `4x5` for Instagram). Look at the contact sheet and show
129
- it.
130
- With music (`audio: {source: "track", trackId}`, a library track from
131
- `list_creative_media({kind: "AUDIO"})`; a new file is uploaded there first with its source and
132
- licence), the preview also renders the slideshow video and returns `slideshowVideoPath`: watch it
133
- with the person. No platform accepts a chosen track on photos, so a destination sends the video
134
- (`carouselAs: "video"`) or the silent photos.
135
- 4. Only after the person approves, `commit_creative_draft`.
@@ -1,52 +0,0 @@
1
- <!-- Keep identical to the copy in the other creative skill (conductor-creative / conductor-content-studio references/design-critique.md). Skills install independently and cannot reference each other. -->
2
- # Design critique
3
-
4
- Passing checks does not make an ad good. `checks` and `passed` cover text spill, safe zones, contrast
5
- and fonts. This critique covers craft, and it runs before the person sees a draft.
6
-
7
- Look at the preview image at phone size. Vision models miss small typography details, so don't
8
- claim to have judged kerning or hairline spacing; judge what is visible at a glance.
9
-
10
- ## Which criteria apply
11
-
12
- Stills, ads and brand-layout creatives use the six criteria below. An organic slideshow (a
13
- `compose_slideshow` CAROUSEL) uses the five slideshow criteria further down instead, because it is
14
- meant to look native, not like an ad.
15
-
16
- ## Score each criterion 1 to 5 (stills and ads)
17
-
18
- Score each one on its own, against the description, not against another draft.
19
-
20
- 1. **Thumb-stop**: would it stop a scroll? One clear focal point and a hook you get in a second.
21
- 2. **Headline size and position**: readable at thumbnail size, not crammed into a corner or a thin strip.
22
- 3. **Empty space**: no dead slab or empty panel. Space that is there on purpose is fine; a leftover band is not.
23
- 4. **Photo and copy together**: copy is not on the subject's face, and the photo carries the concept rather than decorating it.
24
- 5. **Product shown**: the product, or the result it gives, is visible. A stock pose or an empty scene scores 1 or 2.
25
- 6. **Not a banner ad**: it does not read as logo + badge + tagline stacked on a picture.
26
-
27
- ## Act on the scores
28
-
29
- - Any criterion below 3: fix it (copy, layout, `focalOverride`, `typeOverrides`, the photo) and
30
- render again. At most two fix rounds.
31
- - Still below 3 after that: show the best version with one honest line on what is weak.
32
- - Comparing variants: score each on its own first. Use a side-by-side comparison only to break a
33
- tie, and judge it in both orders (first vs. second, then second vs. first); if the order changes
34
- the winner, call it a tie. Pairwise judging favours whichever is shown first.
35
-
36
- ## Show the scores
37
-
38
- One compact line next to the preview, for example:
39
- `Craft: thumb-stop 4, headline 4, space 3, photo+copy 4, product 3, not-banner 4. Weakest: product is implied, not shown.`
40
-
41
- ## Slideshow criteria (organic slideshows)
42
-
43
- Look at the contact sheet: slide 1 at full size, then the slides in order. Score each 1 to 5.
44
-
45
- 1. **Slide 1 stops the scroll**: a human tension or a result people want, in a line a stranger gets in a second. A feature, the app name or a price scores 1 or 2.
46
- 2. **Each slide earns the next swipe**: every slide has one job and a reason to go on; no filler slide, no slide that repeats the last.
47
- 3. **People would save or send it**: the middle slides hold something to keep or to send to a named person.
48
- 4. **The app is the payoff, not the opener**: it appears on slide N-1 on a real screenshot with one plain mention, never on slide 1 and never as a logo, badge or offer.
49
- 5. **Native look**: text boxes and photos feel like a person's post. Banner-ad signs (a logo lockup, a badge, a tagline stack, a call-to-action button) score 1 or 2.
50
-
51
- Act on the scores as below. Show them in one line, for example:
52
- `Slideshow: scroll-stop 4, next-swipe 3, save/send 4, app-as-payoff 4, native 5. Weakest: slide 3 repeats slide 2.`
@@ -1,346 +0,0 @@
1
- ---
2
- name: conductor-ux-ui-design
3
- description: Expert UX/UI design guidance for creating simple, user-focused experiences with clean, cohesive interfaces. Use when designing or reviewing UI components, layouts, navigation, forms, or any user-facing interface. Applies human-centered design principles and explicitly avoids AI slop patterns (generic, over-designed, feature-bloated interfaces). Triggers on UI implementation, design decisions, component creation, or layout work.
4
- user-invocable: false
5
- ---
6
-
7
- # UX/UI Design Skill
8
-
9
- Design guidance for creating interfaces that are simple for users and visually clean—not generic AI slop.
10
-
11
- ## Core Philosophy
12
-
13
- **UX**: Remove friction. Every interaction should feel effortless.
14
- **UI**: Less is more. Every element earns its place.
15
-
16
- ---
17
-
18
- ## UX Principles
19
-
20
- ### 1. Reduce Cognitive Load
21
-
22
- Users form opinions in 50ms. Simplify ruthlessly.
23
-
24
- - **One primary action per screen** — Secondary actions stay subtle
25
- - **Progressive disclosure** — Show basics upfront, reveal complexity on demand
26
- - **Predictable patterns** — Consistency reduces learning curve
27
-
28
- ```
29
- ❌ Dashboard with 12 cards, 5 CTAs, sidebar, and floating action button
30
- ✅ Dashboard with 3 key metrics, one primary action, minimal navigation
31
- ```
32
-
33
- ### 2. Design for Intent, Not Features
34
-
35
- Start with user goals, not feature lists.
36
-
37
- | User Intent | Good Design | Bad Design |
38
- |-------------|-------------|------------|
39
- | "Find a product" | Search bar prominent, filters accessible | Feature tour modal on load |
40
- | "Complete checkout" | Linear flow, minimal fields | Upsells interrupting every step |
41
- | "Check status" | Status visible immediately | Requires 3 clicks to find |
42
-
43
- ### 3. Respect User Time
44
-
45
- - **Minimize steps** — Combine related actions
46
- - **Smart defaults** — Pre-fill what you can infer
47
- - **Instant feedback** — Show loading states, confirm actions immediately
48
- - **Remember state** — Don't make users repeat themselves
49
-
50
- ### 4. Error Prevention Over Error Messages
51
-
52
- Design to prevent errors, not just handle them.
53
-
54
- ```
55
- ❌ "Invalid email format" after submit
56
- ✅ Real-time validation as user types
57
-
58
- ❌ Delete button with no confirmation
59
- ✅ Undo within 5 seconds, or confirmation for destructive actions
60
- ```
61
-
62
- ---
63
-
64
- ## UI Principles
65
-
66
- ### 1. Visual Hierarchy
67
-
68
- Guide attention through deliberate contrast.
69
-
70
- **Size**: Larger = more important
71
- **Color**: Accent colors for actions, muted for secondary
72
- **Space**: Whitespace groups related elements, separates sections
73
- **Position**: Top-left starts the reading flow (LTR languages)
74
-
75
- ```
76
- Primary action: Bold, accent color, prominent size
77
- Secondary action: Outlined or text-only, subdued
78
- Tertiary action: Text link, smallest
79
- ```
80
-
81
- ### 2. Limited Color Palette
82
-
83
- 95% of minimalist interfaces use a restricted palette.
84
-
85
- **Core palette structure:**
86
- - 1 neutral background (white, off-white, or dark mode equivalent)
87
- - 1-2 accent colors (one primary, one optional secondary)
88
- - Semantic colors: success (green), warning (amber), error (red), info (blue)
89
- - Text: 2-3 shades (primary, secondary, disabled)
90
-
91
- ```css
92
- /* Example minimal palette */
93
- --bg-primary: #FFFFFF;
94
- --bg-secondary: #F8F9FA;
95
- --text-primary: #1A1A1A;
96
- --text-secondary: #6B7280;
97
- --accent: #2563EB;
98
- --accent-hover: #1D4ED8;
99
- ```
100
-
101
- ### 3. Typography
102
-
103
- One typeface, multiple weights. Never more than two font families.
104
-
105
- **Hierarchy through weight and size, not different fonts:**
106
- - Headings: Semibold or bold, larger size
107
- - Body: Regular weight, comfortable reading size (16px minimum)
108
- - Captions: Regular or medium, smaller size, secondary color
109
-
110
- **Line height**: 1.4-1.6 for body text, 1.2-1.3 for headings
111
-
112
- ### 4. Spacing System
113
-
114
- Use consistent spacing tokens—never arbitrary values.
115
-
116
- ```
117
- 4px (xs) — Tight spacing within components
118
- 8px (sm) — Related elements
119
- 16px (md) — Standard spacing
120
- 24px (lg) — Section separation
121
- 32px (xl) — Major sections
122
- 48px (2xl) — Page-level spacing
123
- ```
124
-
125
- **Rule**: Space between elements = relationship strength. Closer = more related.
126
-
127
- ### 5. Whitespace as Design Element
128
-
129
- Empty space is not wasted space. It:
130
- - Reduces cognitive load
131
- - Creates visual breathing room
132
- - Emphasizes important elements
133
- - Communicates hierarchy
134
-
135
- ```
136
- ❌ Cramped form with no padding
137
- ✅ Generous padding, grouped fields with clear sections
138
- ```
139
-
140
- ---
141
-
142
- ## Avoiding AI Slop
143
-
144
- AI slop = generic, over-engineered, feature-bloated design that looks "designed" but lacks soul.
145
-
146
- ### Red Flags (Don't Do This)
147
-
148
- | Pattern | Problem | Fix |
149
- |---------|---------|-----|
150
- | Gradient everything | Looks like a template | Flat colors, subtle shadows only |
151
- | Rounded corners on everything | Generic "modern" look | Consistent radius, not excessive |
152
- | Unnecessary animations | Distracting, slow | Purposeful micro-interactions only |
153
- | Stock illustrations everywhere | Feels corporate/hollow | Use sparingly or not at all |
154
- | Feature overload | "Look how much it does!" | Ship less, ship focused |
155
- | Symmetric grids always | Predictable, boring | Intentional asymmetry when appropriate |
156
- | Drop shadows on everything | Cluttered, dated | Minimal elevation, purposeful depth |
157
- | Glassmorphism/neumorphism by default | Trendy but often inaccessible | Use sparingly, ensure contrast |
158
-
159
- ### AI Slop Content Patterns to Avoid
160
-
161
- - Generic hero sections with vague taglines ("Empower your workflow")
162
- - Cookie-cutter landing page layouts
163
- - Feature grids with icons that could apply to anything
164
- - Excessive use of buzzwords in UI copy
165
- - Decorative elements that add no meaning
166
-
167
- ### What Makes Design Feel Human
168
-
169
- - **Personality in copywriting** — Real voice, not corporate speak
170
- - **Intentional imperfection** — Hand-drawn elements, custom illustrations
171
- - **Constraint** — Knowing what NOT to include
172
- - **Context-awareness** — Design serves the specific use case, not generic patterns
173
- - **Consistency over novelty** — Boring is often better
174
-
175
- ---
176
-
177
- ## Component Guidelines
178
-
179
- ### Buttons
180
-
181
- ```
182
- Primary: Solid background, high contrast text, clear CTA
183
- Secondary: Outlined or ghost, lower visual weight
184
- Tertiary: Text-only, for less important actions
185
- Disabled: 50% opacity, no pointer events
186
-
187
- Sizing:
188
- - Small: 32px height, compact UI
189
- - Medium: 40px height, default
190
- - Large: 48px height, touch targets, primary CTAs
191
- ```
192
-
193
- ### Forms
194
-
195
- - Labels above inputs (not placeholder-as-label)
196
- - Clear focus states (visible ring, color change)
197
- - Inline validation, not just on submit
198
- - Logical tab order
199
- - Required field indicators (asterisk or text)
200
- - Helpful hint text for complex fields
201
-
202
- ```
203
- ❌ Placeholder text as the only label
204
- ❌ Error messages appearing somewhere else on screen
205
- ❌ Submit button disabled with no explanation why
206
-
207
- ✅ Clear labels, visible focus, inline errors, enabled submit with validation
208
- ```
209
-
210
- ### Cards
211
-
212
- - Consistent padding (16-24px)
213
- - Clear content hierarchy
214
- - Single primary action if any
215
- - Subtle shadow or border, not both
216
- - Avoid nesting cards within cards
217
-
218
- ### Navigation
219
-
220
- - Primary nav: 5-7 items maximum
221
- - Mobile: Hamburger menu or bottom nav (not both)
222
- - Current state clearly indicated
223
- - Breadcrumbs for deep hierarchies
224
- - Search accessible on complex sites
225
-
226
- ### Tables
227
-
228
- - Left-align text, right-align numbers
229
- - Zebra striping OR grid lines, not both
230
- - Sticky headers for long tables
231
- - Sort indicators when sortable
232
- - Row actions: hover reveal or action column
233
- - Pagination or infinite scroll, clear indication of more data
234
-
235
- ### Modals/Dialogs
236
-
237
- - Clear title describing the action
238
- - Single primary action, cancel always available
239
- - Focus trapped within modal
240
- - Escape key closes (unless destructive action)
241
- - Background overlay with click-to-close
242
- - Don't nest modals
243
-
244
- ---
245
-
246
- ## Responsive Design
247
-
248
- ### Breakpoints (Standard)
249
-
250
- ```
251
- sm: 640px — Small tablets, large phones landscape
252
- md: 768px — Tablets portrait
253
- lg: 1024px — Tablets landscape, small laptops
254
- xl: 1280px — Desktops
255
- 2xl: 1536px — Large desktops
256
- ```
257
-
258
- ### Mobile-First Patterns
259
-
260
- - Stack columns on mobile, expand on desktop
261
- - Touch targets: minimum 44x44px
262
- - Thumb-friendly zones for critical actions
263
- - Simplify navigation for mobile
264
- - Reduce content density, not just shrink
265
-
266
- ### What Changes on Mobile
267
-
268
- | Desktop | Mobile |
269
- |---------|--------|
270
- | Horizontal nav | Hamburger or bottom nav |
271
- | Multi-column grid | Single column or 2-col max |
272
- | Hover states | Tap states (no hover on touch) |
273
- | Side panels | Full-screen overlays |
274
- | Data tables | Cards or simplified tables |
275
-
276
- ---
277
-
278
- ## Accessibility Checklist
279
-
280
- Not optional. Design for everyone.
281
-
282
- - [ ] Color contrast: 4.5:1 minimum for text
283
- - [ ] Don't rely on color alone (add icons, text, patterns)
284
- - [ ] Focus states visible and clear
285
- - [ ] Keyboard navigation works
286
- - [ ] Alt text on meaningful images
287
- - [ ] Form labels associated with inputs
288
- - [ ] Error messages clear and specific
289
- - [ ] Touch targets 44x44px minimum
290
- - [ ] Motion can be reduced (respects prefers-reduced-motion)
291
- - [ ] Text resizable without breaking layout
292
-
293
- ---
294
-
295
- ## Implementation Checklist
296
-
297
- Before shipping any interface:
298
-
299
- ### UX Verification
300
- - [ ] Primary action is immediately obvious
301
- - [ ] User can accomplish goal in minimum steps
302
- - [ ] Error states are helpful, not just red
303
- - [ ] Loading states exist for async operations
304
- - [ ] Empty states guide users to next action
305
-
306
- ### UI Verification
307
- - [ ] Spacing follows consistent scale
308
- - [ ] Typography hierarchy is clear
309
- - [ ] Color palette is limited and intentional
310
- - [ ] Components are consistent throughout
311
- - [ ] No orphan elements (everything aligned to grid)
312
-
313
- ### Anti-Slop Check
314
- - [ ] Could remove any element without losing function?
315
- - [ ] Does every gradient/shadow/animation serve a purpose?
316
- - [ ] Would a non-designer find it cluttered?
317
- - [ ] Is the copywriting specific to this product?
318
- - [ ] Does it look distinct from a template?
319
-
320
- ---
321
-
322
- ## Quick Reference
323
-
324
- ### When Designing
325
-
326
- 1. **Start with user intent** — What are they trying to do?
327
- 2. **Minimize choices** — Each decision = cognitive load
328
- 3. **Establish hierarchy** — What's most important?
329
- 4. **Apply constraints** — Limited colors, spacing scale, one typeface
330
- 5. **Remove until it breaks** — Then add back only what's needed
331
-
332
- ### When Reviewing
333
-
334
- Ask these questions:
335
- - Can I remove anything?
336
- - Is the primary action obvious?
337
- - Does the spacing feel consistent?
338
- - Is there unnecessary decoration?
339
- - Would this work on mobile?
340
-
341
- ---
342
-
343
- ## References
344
-
345
- For detailed design token specifications and component patterns, see:
346
- - `references/design-tokens.md` — Spacing, color, typography scales