heraspec 0.1.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 (47) hide show
  1. package/LICENSE +22 -0
  2. package/README.md +57 -0
  3. package/bin/heraspec.js +3803 -0
  4. package/bin/heraspec.js.map +7 -0
  5. package/dist/core/templates/skills/CHANGELOG.md +117 -0
  6. package/dist/core/templates/skills/README-template.md +58 -0
  7. package/dist/core/templates/skills/README.md +36 -0
  8. package/dist/core/templates/skills/content-optimization-skill.md +104 -0
  9. package/dist/core/templates/skills/data/charts.csv +26 -0
  10. package/dist/core/templates/skills/data/colors.csv +97 -0
  11. package/dist/core/templates/skills/data/landing.csv +31 -0
  12. package/dist/core/templates/skills/data/pages-proposed.csv +22 -0
  13. package/dist/core/templates/skills/data/pages.csv +10 -0
  14. package/dist/core/templates/skills/data/products.csv +97 -0
  15. package/dist/core/templates/skills/data/prompts.csv +24 -0
  16. package/dist/core/templates/skills/data/stacks/flutter.csv +53 -0
  17. package/dist/core/templates/skills/data/stacks/html-tailwind.csv +56 -0
  18. package/dist/core/templates/skills/data/stacks/nextjs.csv +53 -0
  19. package/dist/core/templates/skills/data/stacks/react-native.csv +52 -0
  20. package/dist/core/templates/skills/data/stacks/react.csv +54 -0
  21. package/dist/core/templates/skills/data/stacks/svelte.csv +54 -0
  22. package/dist/core/templates/skills/data/stacks/swiftui.csv +51 -0
  23. package/dist/core/templates/skills/data/stacks/vue.csv +50 -0
  24. package/dist/core/templates/skills/data/styles.csv +59 -0
  25. package/dist/core/templates/skills/data/typography.csv +58 -0
  26. package/dist/core/templates/skills/data/ux-guidelines.csv +100 -0
  27. package/dist/core/templates/skills/documents-skill.md +114 -0
  28. package/dist/core/templates/skills/e2e-test-skill.md +119 -0
  29. package/dist/core/templates/skills/integration-test-skill.md +118 -0
  30. package/dist/core/templates/skills/module-codebase-skill.md +110 -0
  31. package/dist/core/templates/skills/scripts/CODE_EXPLANATION.md +394 -0
  32. package/dist/core/templates/skills/scripts/SEARCH_ALGORITHMS_COMPARISON.md +421 -0
  33. package/dist/core/templates/skills/scripts/SEARCH_MODES_GUIDE.md +238 -0
  34. package/dist/core/templates/skills/scripts/core.py +385 -0
  35. package/dist/core/templates/skills/scripts/search.py +73 -0
  36. package/dist/core/templates/skills/suggestion-skill.md +118 -0
  37. package/dist/core/templates/skills/templates/accessibility-checklist.md +40 -0
  38. package/dist/core/templates/skills/templates/example-prompt-full-theme.md +333 -0
  39. package/dist/core/templates/skills/templates/page-types-guide.md +338 -0
  40. package/dist/core/templates/skills/templates/pages-proposed-summary.md +273 -0
  41. package/dist/core/templates/skills/templates/pre-delivery-checklist.md +42 -0
  42. package/dist/core/templates/skills/templates/prompt-template-full-theme.md +313 -0
  43. package/dist/core/templates/skills/templates/responsive-design.md +40 -0
  44. package/dist/core/templates/skills/ui-ux-skill.md +584 -0
  45. package/dist/core/templates/skills/unit-test-skill.md +111 -0
  46. package/dist/index.js +1736 -0
  47. package/package.json +71 -0
@@ -0,0 +1,584 @@
1
+ # Skill: UI/UX (Cross-Cutting)
2
+
3
+ ## Purpose
4
+
5
+ This skill is used to handle style, interface, UX, UI for all project types. Uses UI/UX Builder search engine (built upon [UI UX Pro Max Skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill)) with multiple search modes (BM25, Vector, Hybrid) to search for design intelligence from a database containing 57 UI styles, 95 color palettes, 56 font pairings, 24 chart types, 9+ page types, and 98 UX guidelines.
6
+
7
+ ## When to Use
8
+
9
+ - When creating or updating user interfaces
10
+ - When designing responsive layouts
11
+ - When ensuring accessibility (WCAG compliance)
12
+ - When creating component styles
13
+ - When optimizing user experience
14
+ - When finding appropriate color palettes, typography, or UI styles
15
+
16
+ ## Prerequisites
17
+
18
+ **Python 3.x is required:**
19
+
20
+ ```bash
21
+ # Check if Python is installed
22
+ python3 --version || python --version
23
+
24
+ # macOS
25
+ brew install python3
26
+
27
+ # Ubuntu/Debian
28
+ sudo apt update && sudo apt install python3
29
+
30
+ # Windows
31
+ winget install Python.Python.3.12
32
+ ```
33
+
34
+ ## Step-by-Step Process
35
+
36
+ ### Step 1: Analyze User Requirements
37
+
38
+ Extract key information from user request:
39
+ - **Product type**: SaaS, e-commerce, portfolio, dashboard, landing page, etc.
40
+ - **Style keywords**: minimal, playful, professional, elegant, dark mode, etc.
41
+ - **Industry**: healthcare, fintech, gaming, education, etc.
42
+ - **Stack**: React, Vue, Next.js, or default `html-tailwind`
43
+
44
+ ### Step 2: Search Relevant Domains
45
+
46
+ Use `scripts/search.py` multiple times to gather comprehensive information. Search until you have enough context.
47
+
48
+ **Search Mode Tips:**
49
+ - Use **BM25 (default)** for simple keyword queries
50
+ - Use **Vector mode** (`--mode vector`) for natural language queries or when you need semantic matches
51
+ - Use **Hybrid mode** (`--mode hybrid`) for best overall results
52
+
53
+ **Recommended search order:**
54
+
55
+ 1. **Product** - Get style recommendations for product type
56
+ ```bash
57
+ python3 scripts/search.py "<product-type>" --domain product
58
+ # Or with semantic search:
59
+ python3 scripts/search.py "<product-type>" --domain product --mode vector
60
+ ```
61
+
62
+ 2. **Style** - Get detailed style guide (colors, effects, frameworks)
63
+ ```bash
64
+ python3 scripts/search.py "<style-keywords>" --domain style
65
+ # For natural language queries:
66
+ python3 scripts/search.py "elegant dark theme for modern apps" --domain style --mode hybrid
67
+ ```
68
+
69
+ 3. **Typography** - Get font pairings with Google Fonts imports
70
+ ```bash
71
+ python3 scripts/search.py "<typography-keywords>" --domain typography
72
+ ```
73
+
74
+ 4. **Color** - Get color palette (Primary, Secondary, CTA, Background, Text, Border)
75
+ ```bash
76
+ python3 scripts/search.py "<product-type>" --domain color
77
+ ```
78
+
79
+ 5. **Landing** - Get page structure (if landing page)
80
+ ```bash
81
+ python3 scripts/search.py "<landing-keywords>" --domain landing
82
+ ```
83
+
84
+ 6. **Chart** - Get chart recommendations (if dashboard/analytics)
85
+ ```bash
86
+ python3 scripts/search.py "<chart-type>" --domain chart
87
+ ```
88
+
89
+ 7. **UX** - Get best practices and anti-patterns
90
+ ```bash
91
+ python3 scripts/search.py "animation" --domain ux
92
+ python3 scripts/search.py "accessibility" --domain ux
93
+ ```
94
+
95
+ 8. **Stack** - Get stack-specific guidelines (default: html-tailwind)
96
+ ```bash
97
+ python3 scripts/search.py "<keyword>" --stack html-tailwind
98
+ # Or with semantic search:
99
+ python3 scripts/search.py "make layout responsive" --stack html-tailwind --mode vector
100
+ ```
101
+
102
+ ### Step 3: Synthesize Search Results
103
+
104
+ Combine all search results to create a complete design system:
105
+ - Color palette from color search
106
+ - Typography from typography search
107
+ - UI style from style search
108
+ - UX guidelines from ux search
109
+ - Stack-specific patterns from stack search
110
+
111
+ ### Step 4: Implement Design
112
+
113
+ Implement UI following:
114
+ - Color palette found
115
+ - Typography pairings with Google Fonts
116
+ - UI style patterns
117
+ - Stack-specific best practices
118
+ - UX guidelines and accessibility rules
119
+
120
+ ### Step 5: Pre-Delivery Checklist
121
+
122
+ Before delivering UI code, verify:
123
+
124
+ **Visual Quality:**
125
+ - [ ] No emojis used as icons (use SVG instead - Heroicons, Lucide, Simple Icons)
126
+ - [ ] All icons from consistent icon set
127
+ - [ ] Brand logos are correct (verified from Simple Icons)
128
+ - [ ] Hover states don't cause layout shift
129
+
130
+ **Interaction:**
131
+ - [ ] All clickable elements have `cursor-pointer`
132
+ - [ ] Hover states provide clear visual feedback
133
+ - [ ] Transitions are smooth (150-300ms)
134
+ - [ ] Focus states visible for keyboard navigation
135
+
136
+ **Light/Dark Mode:**
137
+ - [ ] Light mode text has sufficient contrast (4.5:1 minimum)
138
+ - [ ] Glass/transparent elements visible in light mode (`bg-white/80` not `bg-white/10`)
139
+ - [ ] Borders visible in both modes
140
+ - [ ] Test both modes before delivery
141
+
142
+ **Layout:**
143
+ - [ ] Floating elements have proper spacing from edges
144
+ - [ ] No content hidden behind fixed navbars
145
+ - [ ] Responsive at 320px, 768px, 1024px, 1440px
146
+ - [ ] No horizontal scroll on mobile
147
+
148
+ **Accessibility:**
149
+ - [ ] All images have alt text
150
+ - [ ] Form inputs have labels
151
+ - [ ] Color is not the only indicator
152
+ - [ ] `prefers-reduced-motion` respected
153
+
154
+ ## Required Input
155
+
156
+ - **Product type**: SaaS, e-commerce, portfolio, dashboard, landing page, etc.
157
+ - **Style keywords**: minimal, playful, professional, elegant, dark mode, etc.
158
+ - **Industry**: healthcare, fintech, gaming, education, etc.
159
+ - **Stack**: React, Vue, Next.js, html-tailwind (default)
160
+ - **Target devices**: Desktop, mobile, tablet
161
+ - **Accessibility level**: WCAG AA or AAA
162
+
163
+ ## Expected Output
164
+
165
+ - Complete design system with color palette, typography, and UI style
166
+ - Stack-specific implementation code
167
+ - Responsive and accessible UI components
168
+ - UX-optimized user flows
169
+
170
+ ## Search Reference
171
+
172
+ ### Available Domains
173
+
174
+ | Domain | Use For | Example Keywords |
175
+ |--------|---------|------------------|
176
+ | `product` | Product type recommendations | SaaS, e-commerce, portfolio, healthcare, beauty, service |
177
+ | `style` | UI styles, colors, effects | glassmorphism, minimalism, dark mode, brutalism |
178
+ | `typography` | Font pairings, Google Fonts | elegant, playful, professional, modern |
179
+ | `color` | Color palettes by product type | saas, ecommerce, healthcare, beauty, fintech, service |
180
+ | `landing` | Page structure, CTA strategies | hero, hero-centric, testimonial, pricing, social-proof |
181
+ | `pages` | Page type templates (home, about, post, etc.) | home, about, post, category, pricing, faq, contact, product |
182
+ | `chart` | Chart types, library recommendations | trend, comparison, timeline, funnel, pie |
183
+ | `ux` | Best practices, anti-patterns | animation, accessibility, z-index, loading |
184
+ | `prompt` | AI prompts, CSS keywords | (style name) |
185
+
186
+ ### Available Stacks
187
+
188
+ | Stack | Focus |
189
+ |-------|-------|
190
+ | `html-tailwind` | Tailwind utilities, responsive, a11y (DEFAULT) |
191
+ | `react` | State, hooks, performance, patterns |
192
+ | `nextjs` | SSR, routing, images, API routes |
193
+ | `vue` | Composition API, Pinia, Vue Router |
194
+ | `svelte` | Runes, stores, SvelteKit |
195
+ | `swiftui` | Views, State, Navigation, Animation |
196
+ | `react-native` | Components, Navigation, Lists |
197
+ | `flutter` | Widgets, State, Layout, Theming |
198
+
199
+ ## Tone & Rules
200
+
201
+ ### Common Rules for Professional UI
202
+
203
+ **Icons & Visual Elements:**
204
+ - ✅ Use SVG icons (Heroicons, Lucide, Simple Icons)
205
+ - ✅ Use fixed viewBox (24x24) with w-6 h-6
206
+ - ✅ Stable hover states (color/opacity transitions, not scale transforms)
207
+ - ❌ NO emoji icons (🎨 🚀 ⚙️)
208
+ - ❌ NO incorrect brand logos
209
+
210
+ **Interaction & Cursor:**
211
+ - ✅ Add `cursor-pointer` to all clickable/hoverable cards
212
+ - ✅ Provide visual feedback (color, shadow, border) on hover
213
+ - ✅ Use `transition-colors duration-200` (150-300ms)
214
+ - ❌ NO instant state changes or too slow (>500ms)
215
+
216
+ **Light/Dark Mode Contrast:**
217
+ - ✅ Glass card light mode: `bg-white/80` or higher
218
+ - ✅ Text contrast light: `#0F172A` (slate-900) for text
219
+ - ✅ Muted text light: `#475569` (slate-600) minimum
220
+ - ✅ Border visibility: `border-gray-200` in light mode
221
+ - ❌ NO `bg-white/10` (too transparent)
222
+ - ❌ NO `#94A3B8` (slate-400) for body text
223
+ - ❌ NO `border-white/10` (invisible)
224
+
225
+ **Layout & Spacing:**
226
+ - ✅ Floating navbar: `top-4 left-4 right-4` spacing
227
+ - ✅ Content padding: Account for fixed navbar height
228
+ - ✅ Consistent max-width: Same `max-w-6xl` or `max-w-7xl`
229
+ - ❌ NO navbar stuck to `top-0 left-0 right-0`
230
+ - ❌ NO content hidden behind fixed elements
231
+
232
+ ### Code Style
233
+
234
+ - **Default stack**: `html-tailwind` (unless specified)
235
+ - **Mobile-first**: Responsive design approach
236
+ - **Accessibility**: WCAG AA minimum
237
+ - **Icons**: Heroicons, Lucide, Simple Icons (SVG only)
238
+ - **Transitions**: 150-300ms for smooth interactions
239
+
240
+ ### Naming Conventions
241
+
242
+ - **Tailwind**: Use utility classes
243
+ - **Components**: Semantic naming
244
+ - **CSS Variables**: For theming
245
+
246
+ ### Limitations
247
+
248
+ - ❌ DO NOT use emoji as icons
249
+ - ❌ DO NOT hardcode colors (use variables or search results)
250
+ - ❌ DO NOT skip accessibility
251
+ - ❌ DO NOT create fixed-width layouts (unless necessary)
252
+ - ❌ DO NOT use inline styles (except dynamic values)
253
+ - ❌ DO NOT create non-responsive components
254
+ - ❌ DO NOT use scale transforms for hover (causes layout shift)
255
+
256
+ ## Available Scripts
257
+
258
+ - `scripts/search.py` - Main search script for UI/UX Builder database
259
+ - `scripts/core.py` - Core search engine (BM25, Vector, Hybrid)
260
+
261
+ ## Search Modes
262
+
263
+ UI/UX Builder supports multiple search algorithms for different use cases:
264
+
265
+ UI/UX Builder supports 3 search modes for different use cases:
266
+
267
+ 1. **BM25 (default)** - Keyword-based search
268
+ - ✅ Fastest, zero dependencies
269
+ - ✅ Best for exact keyword matches
270
+ - ✅ Works out of the box
271
+
272
+ 2. **Vector** - Semantic search
273
+ - ✅ Understands meaning and synonyms
274
+ - ✅ Better results (~15-20% improvement)
275
+ - ⚠️ Requires: `pip install sentence-transformers scikit-learn`
276
+
277
+ 3. **Hybrid** - Best of both worlds
278
+ - ✅ Combines BM25 + Vector
279
+ - ✅ Best results (~25% improvement)
280
+ - ⚠️ Requires: `pip install sentence-transformers scikit-learn`
281
+
282
+ **Usage:**
283
+ ```bash
284
+ # Search by domain (BM25 - default)
285
+ python3 scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
286
+
287
+ # Search with Vector mode (semantic)
288
+ python3 scripts/search.py "<keyword>" --domain <domain> --mode vector
289
+
290
+ # Search with Hybrid mode (best results)
291
+ python3 scripts/search.py "<keyword>" --domain <domain> --mode hybrid
292
+
293
+ # Search by stack
294
+ python3 scripts/search.py "<keyword>" --stack <stack> [-n <max_results>] [--mode <mode>]
295
+
296
+ # Examples
297
+ python3 scripts/search.py "beauty spa wellness" --domain product
298
+ python3 scripts/search.py "elegant dark theme" --domain style --mode vector
299
+ python3 scripts/search.py "modern minimal design" --domain style --mode hybrid
300
+ python3 scripts/search.py "layout responsive" --stack html-tailwind
301
+ ```
302
+
303
+ **Note:** If Vector/Hybrid mode is requested but dependencies are not installed, the system automatically falls back to BM25 mode with a warning message.
304
+
305
+ ## Multi-Page Website Package
306
+
307
+ ### When to Create Full Package vs Landing Page
308
+
309
+ **Create Full Package** when user requests:
310
+ - "Tạo website đầy đủ" / "Create complete website"
311
+ - "Tạo gói giao diện đầy đủ" / "Create full interface package"
312
+ - Multiple pages mentioned (home, about, contact, etc.)
313
+ - E-commerce site (needs product pages)
314
+ - Blog/content site (needs post and category pages)
315
+
316
+ **Create Landing Page Only** when user requests:
317
+ - "Tạo landing page" / "Create landing page"
318
+ - Single page conversion focus
319
+ - Marketing campaign page
320
+ - Product launch page
321
+
322
+ ### Default Page Set
323
+
324
+ When creating a complete website package (not specified), include these 9 pages:
325
+
326
+ 1. **Home** - Main homepage with hero, features, testimonials
327
+ 2. **About** - Company story, mission, team
328
+ 3. **Post Details** - Blog/article detail page
329
+ 4. **Category** - Blog/category listing page
330
+ 5. **Pricing** - Pricing plans and comparison
331
+ 6. **FAQ** - Frequently asked questions
332
+ 7. **Contact** - Contact form and information
333
+ 8. **Product Category** - E-commerce category listing (if applicable)
334
+ 9. **Product Details** - E-commerce product detail page (if applicable)
335
+
336
+ ### Multi-Page Workflow
337
+
338
+ **Step 1: Search Design System** (once for all pages)
339
+
340
+ ```bash
341
+ # Product type
342
+ python3 scripts/search.py "<product-type>" --domain product
343
+
344
+ # Style
345
+ python3 scripts/search.py "<style-keywords>" --domain style
346
+
347
+ # Color palette
348
+ python3 scripts/search.py "<product-type>" --domain color
349
+
350
+ # Typography
351
+ python3 scripts/search.py "<typography-keywords>" --domain typography
352
+ ```
353
+
354
+ **Step 2: Search Each Page Type**
355
+
356
+ ```bash
357
+ # Home page
358
+ python3 scripts/search.py "home homepage" --domain pages
359
+ # Or with semantic search for better results:
360
+ python3 scripts/search.py "homepage with hero section" --domain pages --mode hybrid
361
+
362
+ # About page
363
+ python3 scripts/search.py "about company story" --domain pages
364
+
365
+ # Post details
366
+ python3 scripts/search.py "post article blog" --domain pages
367
+
368
+ # Category page
369
+ python3 scripts/search.py "category archive listing" --domain pages
370
+
371
+ # Pricing page
372
+ python3 scripts/search.py "pricing plans tiers" --domain pages
373
+
374
+ # FAQ page
375
+ python3 scripts/search.py "faq questions help" --domain pages
376
+
377
+ # Contact page
378
+ python3 scripts/search.py "contact get-in-touch" --domain pages
379
+
380
+ # Product category (if e-commerce)
381
+ python3 scripts/search.py "product-category shop catalog" --domain pages
382
+
383
+ # Product details (if e-commerce)
384
+ python3 scripts/search.py "product-detail single-product" --domain pages
385
+ ```
386
+
387
+ **Step 3: Create Shared Components First**
388
+
389
+ Before individual pages, create:
390
+ - **Header/Navigation** - Consistent across all pages
391
+ - **Footer** - Consistent across all pages
392
+ - **Button components** - Primary, secondary, CTA styles
393
+ - **Card components** - For features, products, posts
394
+ - **Form components** - For contact, search
395
+ - **Layout wrapper** - Consistent spacing and max-width
396
+
397
+ **Step 4: Implement Pages in Order**
398
+
399
+ 1. **Home** - Establishes design system
400
+ 2. **About** - Uses same header/footer
401
+ 3. **Category** - Reuses card components
402
+ 4. **Post Details** - Uses category navigation
403
+ 5. **Pricing** - Standalone but consistent
404
+ 6. **FAQ** - Standalone but consistent
405
+ 7. **Contact** - Standalone but consistent
406
+ 8. **Product Category** (if e-commerce)
407
+ 9. **Product Details** (if e-commerce)
408
+
409
+ **Step 5: Ensure Consistency**
410
+
411
+ - ✅ Same color palette across all pages
412
+ - ✅ Same typography (heading + body fonts)
413
+ - ✅ Same spacing system
414
+ - ✅ Same navigation structure
415
+ - ✅ Same footer content
416
+ - ✅ Consistent button styles
417
+ - ✅ Consistent card styles
418
+
419
+ ### Code Organization
420
+
421
+ **File Structure:**
422
+ ```
423
+ src/
424
+ ├── components/
425
+ │ ├── shared/
426
+ │ │ ├── Header.tsx (or Header.html)
427
+ │ │ ├── Footer.tsx (or Footer.html)
428
+ │ │ ├── Button.tsx
429
+ │ │ └── Card.tsx
430
+ │ └── [page-specific components]
431
+ ├── pages/
432
+ │ ├── index.html (or Home.tsx)
433
+ │ ├── about.html (or About.tsx)
434
+ │ ├── blog/
435
+ │ │ ├── [slug].html
436
+ │ │ └── category/[category].html
437
+ │ ├── pricing.html
438
+ │ ├── faq.html
439
+ │ ├── contact.html
440
+ │ └── products/ (if e-commerce)
441
+ │ ├── category/[category].html
442
+ │ └── [slug].html
443
+ └── styles/
444
+ └── globals.css (or tailwind.config.js)
445
+ ```
446
+
447
+ **Component Guidelines:**
448
+ - Extract common patterns into reusable components
449
+ - One component per file
450
+ - Keep components under 200-300 lines
451
+ - Use props/variables for customization
452
+
453
+ See `templates/page-types-guide.md` for detailed page templates.
454
+
455
+ ## Available Templates
456
+
457
+ - `templates/responsive-design.md` - Responsive checklist
458
+ - `templates/accessibility-checklist.md` - Accessibility checklist
459
+ - `templates/pre-delivery-checklist.md` - Pre-delivery verification
460
+ - `templates/page-types-guide.md` - Multi-page website package guide
461
+ - `templates/example-prompt-full-theme.md` - Example prompts for creating full theme packages
462
+ - `templates/prompt-template-full-theme.md` - Prompt templates (copy-paste ready)
463
+
464
+ ## Examples
465
+
466
+ See `examples/` directory for reference:
467
+ - `good-ux-patterns/` - Good patterns (high conversion, accessible)
468
+ - `bad-ux-patterns/` - Patterns to avoid (confusing, inaccessible)
469
+
470
+ ## Example Workflows
471
+
472
+ ### Example 1: Landing Page Only
473
+
474
+ **User request:** "Create landing page for professional skincare service"
475
+
476
+ **Agent should:**
477
+
478
+ ```bash
479
+ # 1. Search product type
480
+ python3 scripts/search.py "beauty spa wellness service" --domain product
481
+ # Or with semantic search for better results:
482
+ python3 scripts/search.py "professional skincare service business" --domain product --mode vector
483
+
484
+ # 2. Search style (based on industry: beauty, elegant)
485
+ python3 scripts/search.py "elegant minimal soft" --domain style
486
+ # Or with hybrid for best results:
487
+ python3 scripts/search.py "elegant minimal design for beauty services" --domain style --mode hybrid
488
+
489
+ # 3. Search typography
490
+ python3 scripts/search.py "elegant luxury" --domain typography
491
+
492
+ # 4. Search color palette
493
+ python3 scripts/search.py "beauty spa wellness" --domain color
494
+
495
+ # 5. Search landing page structure
496
+ python3 scripts/search.py "hero-centric social-proof" --domain landing
497
+
498
+ # 6. Search UX guidelines
499
+ python3 scripts/search.py "animation" --domain ux
500
+ python3 scripts/search.py "accessibility" --domain ux
501
+
502
+ # 7. Search stack guidelines (default: html-tailwind)
503
+ python3 scripts/search.py "layout responsive" --stack html-tailwind
504
+ ```
505
+
506
+ **Then:** Synthesize all search results and implement the design.
507
+
508
+ ### Example 2: Complete Website Package
509
+
510
+ **User request:** "Tạo gói website đầy đủ cho dịch vụ chăm sóc da chuyên nghiệp"
511
+
512
+ **Agent should:**
513
+
514
+ ```bash
515
+ # Step 1: Search design system (once for all pages)
516
+ # Use hybrid mode for better semantic understanding
517
+ python3 scripts/search.py "beauty spa wellness service" --domain product --mode hybrid
518
+ python3 scripts/search.py "elegant minimal soft design" --domain style --mode hybrid
519
+ python3 scripts/search.py "beauty spa wellness" --domain color
520
+ python3 scripts/search.py "elegant luxury typography" --domain typography --mode vector
521
+
522
+ # Step 2: Search each page type
523
+ python3 scripts/search.py "home homepage" --domain pages
524
+ python3 scripts/search.py "about company story" --domain pages
525
+ python3 scripts/search.py "post article blog" --domain pages
526
+ python3 scripts/search.py "category archive" --domain pages
527
+ python3 scripts/search.py "pricing plans" --domain pages
528
+ python3 scripts/search.py "faq questions" --domain pages
529
+ python3 scripts/search.py "contact" --domain pages
530
+
531
+ # Step 3: Search UX guidelines
532
+ python3 scripts/search.py "animation" --domain ux
533
+ python3 scripts/search.py "accessibility" --domain ux
534
+
535
+ # Step 4: Search stack guidelines
536
+ python3 scripts/search.py "layout responsive" --stack html-tailwind
537
+ # Or with semantic search:
538
+ python3 scripts/search.py "how to make layout responsive" --stack html-tailwind --mode vector
539
+ ```
540
+
541
+ **Then:**
542
+ 1. Create shared components (Header, Footer, Button, Card)
543
+ 2. Implement pages in order: Home → About → Category → Post Details → Pricing → FAQ → Contact
544
+ 3. Ensure consistency across all pages
545
+ 4. Verify with pre-delivery checklist
546
+
547
+ ## Tips for Better Results
548
+
549
+ 1. **Be specific with keywords** - "healthcare SaaS dashboard" > "app"
550
+ 2. **Use appropriate search mode:**
551
+ - **BM25 (default)** for simple keyword queries
552
+ - **Vector mode** (`--mode vector`) for natural language or when you need semantic matches
553
+ - **Hybrid mode** (`--mode hybrid`) for best overall results
554
+ 3. **Search multiple times** - Different keywords reveal different insights
555
+ 4. **Combine domains** - Style + Typography + Color = Complete design system
556
+ 5. **Always check UX** - Search "animation", "z-index", "accessibility" for common issues
557
+ 6. **Use stack flag** - Get implementation-specific best practices
558
+ 7. **Iterate** - If first search doesn't match, try different keywords or switch search mode
559
+ 8. **Split Into Multiple Files** - For better maintainability:
560
+ - Separate components into individual files (e.g., `Header.tsx`, `Footer.tsx`)
561
+ - Extract reusable styles into dedicated files
562
+ - Keep each file focused and under 200-300 lines
563
+
564
+ ### Search Mode Selection Guide
565
+
566
+ - **Use BM25 when:**
567
+ - You have clear, specific keywords
568
+ - Speed is priority
569
+ - Simple queries work well
570
+
571
+ - **Use Vector when:**
572
+ - Natural language queries ("elegant dark theme for modern apps")
573
+ - Need to find synonyms or related terms
574
+ - Dataset > 500 records
575
+
576
+ - **Use Hybrid when:**
577
+ - Need best possible results
578
+ - Mix of keyword and natural language queries
579
+ - Production use cases
580
+
581
+ ## Links to Other Skills
582
+
583
+ - **documents**: Use to document design system
584
+ - **content-optimization**: Use to optimize CTA placement and styling
@@ -0,0 +1,111 @@
1
+ # Skill: Unit Testing (Cross-Cutting)
2
+
3
+ ## Purpose
4
+
5
+ This skill is used to create unit tests for code components. Unit tests verify that individual functions, methods, or classes work correctly in isolation.
6
+
7
+ ## When to Use
8
+
9
+ - When testing individual functions or methods
10
+ - When testing class methods in isolation
11
+ - When testing utility functions
12
+ - When testing business logic
13
+ - When testing data transformations
14
+ - When ensuring code correctness before integration
15
+
16
+ ## Step-by-Step Process
17
+
18
+ ### Step 1: Identify Test Targets
19
+ - Analyze the code to identify testable units
20
+ - List all public methods/functions
21
+ - Identify edge cases and boundary conditions
22
+ - Determine expected inputs and outputs
23
+
24
+ ### Step 2: Set Up Test Framework
25
+ - Choose appropriate testing framework (Jest, PHPUnit, pytest, etc.)
26
+ - Configure test environment
27
+ - Set up test structure matching project conventions
28
+ - Ensure test framework is installed and configured
29
+
30
+ ### Step 3: Write Test Cases
31
+ - Create test file matching source file structure
32
+ - Write tests for each function/method
33
+ - Test normal cases (happy path)
34
+ - Test edge cases (null, empty, boundary values)
35
+ - Test error cases (invalid input, exceptions)
36
+ - Use descriptive test names
37
+
38
+ ### Step 4: Run and Verify
39
+ - Run tests to ensure they pass
40
+ - Check test coverage if available
41
+ - Refactor if needed
42
+ - Ensure tests are fast and isolated
43
+
44
+ ### Step 5: Document Test Cases
45
+ - Add comments for complex test scenarios
46
+ - Document test data and expected outcomes
47
+ - Update test documentation if needed
48
+
49
+ ## Required Input
50
+
51
+ - **Source code**: Code to be tested (functions, methods, classes)
52
+ - **Test framework**: Testing framework to use (Jest, PHPUnit, pytest, etc.)
53
+ - **Project structure**: Understanding of where tests should be placed
54
+ - **Dependencies**: List of dependencies that need to be mocked
55
+
56
+ ## Expected Output
57
+
58
+ - Complete unit test files
59
+ - Tests covering normal, edge, and error cases
60
+ - Test assertions verifying expected behavior
61
+ - Test data and fixtures if needed
62
+ - Passing test suite
63
+
64
+ ## Tone & Rules
65
+
66
+ ### Test Naming
67
+ - Use descriptive names: `test_user_registration_with_valid_email()`
68
+ - Follow pattern: `test_<what>_<condition>_<expected_result>`
69
+ - Use clear, readable test names
70
+
71
+ ### Test Structure
72
+ - Arrange: Set up test data and dependencies
73
+ - Act: Execute the code being tested
74
+ - Assert: Verify the results
75
+ - Clean up: Reset state if needed
76
+
77
+ ### Coverage Goals
78
+ - Aim for high coverage of critical paths
79
+ - Test all public methods
80
+ - Test edge cases and error handling
81
+ - Don't test implementation details
82
+
83
+ ### Limitations
84
+ - ❌ DO NOT test private methods directly (test through public interface)
85
+ - ❌ DO NOT write tests that depend on other tests
86
+ - ❌ DO NOT test external dependencies (use mocks)
87
+ - ❌ DO NOT write slow tests (use mocks for I/O)
88
+ - ❌ DO NOT test framework code
89
+
90
+ ## Available Templates
91
+
92
+ - `templates/unit-test-template.js` - JavaScript/Jest template
93
+ - `templates/unit-test-template.php` - PHP/PHPUnit template
94
+ - `templates/unit-test-template.py` - Python/pytest template
95
+
96
+ ## Available Scripts
97
+
98
+ - `scripts/generate-test-stubs.sh` - Generate test file stubs from source code
99
+
100
+ ## Examples
101
+
102
+ See `examples/` directory for reference:
103
+ - `good-unit-test/` - Well-structured unit tests
104
+ - `bad-unit-test/` - Examples to avoid
105
+
106
+ ## Links to Other Skills
107
+
108
+ - **integration-test**: Use after unit tests for integration testing
109
+ - **e2e-test**: Use for end-to-end testing
110
+ - **documents**: Use to document test strategy
111
+