@longtq2501/next-spring-skills 1.5.0 → 1.6.1

package/README.md

@@ -27,6 +27,15 @@ npx @longtq2501/next-spring-skills
 
 This will copy the `skills/` directory and `AGENT.md` into your current project folder.
 
+Meta-Prompt:
+```bash
+"Implement [Frontend Task] following Design Intelligence + Next.js Performance standards."
+
+"Implement [Backend Task] following Spring Boot Pro Max standards (Performance & Clean Code)."
+
+"Resolve [Error Description] following Debug & Fix Pro Max standards."
+```
+
 ## Workflow
 
 This repository is designed for **AI-Human Collaboration**. For every new task:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longtq2501/next-spring-skills",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Standardized best practices and code patterns for Next.js and Spring Boot",
   "bin": {
     "next-spring-skills": "bin/cli.js"

package/skills/SKILL.md

@@ -92,6 +92,30 @@ See [performance.md](./nextjs/performance.md) for React optimization and data fe
 
 ---
 
+## Design Intelligence (Pro Max)
+
+Standardized design systems, color palettes, and UX guidelines.
+
+### Core Database
+See [SKILL.md](./ui-ux-pro-max/SKILL.md) for styles, palettes, and font pairings.
+
+### Next.js Integration
+See [design-intelligence.md](./nextjs/design-intelligence.md) for mapping design to high-performance code.
+
+---
+
+## Troubleshooting & Debugging (Pro Max)
+
+Systematic workflows for identifying and fixing complex issues.
+
+### Unified Workflow
+See [debug-and-fix.md](./debug-and-fix.md) for the 5-step debugging process (Observation → Verification).
+
+### Next.js Debug Tricks
+See [debug-tricks.md](./nextjs/debug-tricks.md) for `nezt/mcp` and build path debugging.
+
+---
+
 ## AI Agent Workflow
 
 ### Interaction Protocol

package/skills/debug-and-fix.md

@@ -0,0 +1,64 @@
+# Skill: Debug & Fix (Pro Max Standards)
+
+Systematic workflow for identifying root causes and applying high-performance fixes across Next.js and Spring Boot.
+
+## 1. The Pro Max Debugging Workflow
+
+Follow these 5 steps for ANY issue (Bug, Performance, or UX):
+
+### Step 1: Observation & Data Collection
+- **Frontend**: Check Browser Console, Network Tab, and `next-development.log`.
+- **Backend**: Check Spring Boot logs (`log.info/error`) and Hibernate SQL output.
+- **Tools**: Use `curl -X POST /_next/mcp` to get real-time dev server errors.
+
+### Step 2: Hypothesis Generation
+Based on the data, identify the most likely layer of failure:
+- **UI/UX**: Component state, Tailwind classes, or React lifecycle.
+- **Logic**: Frontend hooks or Backend Service implementation.
+- **Performance**: DB Query (N+1), heavy JS bundle, or inefficient re-renders.
+
+### Step 3: Isolation & Reproduction
+- **Bisect**: Comment out components/logic to find the exact line causing the crash.
+- **Repro**: Define the exact sequence of user actions that triggers the issue.
+- **Mock**: Use `MockMVC` (Backend) or `Vitest` (Frontend) to isolate the unit.
+
+### Step 4: Resolution (Clean Fix)
+Apply the fix according to project standards:
+- **Frontend**: Use `useMemo`, `useCallback`, or `next/image`.
+- **Backend**: Use proper Enum comparison (`==`), custom exceptions, and DB-level filtering.
+- **Refactor**: If the fix introduces complexity, refactor surrounding code to maintain readability.
+
+### Step 5: Verification & Documentation
+- **Verify**: Test the fix across different viewports and states.
+- **Update Ledger**: Update `ISSUES.md` (Archive) with root cause and impact.
+- **Regression**: Ensure no other features were broken.
+
+---
+
+## 2. Standard Issue Categories
+
+| Category | Priority | Lead Indicator | Standard Action |
+|----------|----------|----------------|-----------------|
+| **Performance** | P0/P1 | LCP > 2.5s / API > 2s | `query_optimization.md` / `performance.md` |
+| **Logic/Bug** | P0/P1 | 500 Error / Crash | `error_handling_design.md` / `debug-tricks.md` |
+| **UX/UI** | P2/P3 | Visual glitch / Delay | `ux-feedback.md` / `design-intelligence.md` |
+
+---
+
+## 3. Universal Trigger Prompt
+
+To trigger this workflow for a specific issue, use:
+
+> **"Sửa lỗi [Mô tả lỗi] theo chuẩn Debug & Fix Pro Max."**
+
+**What this triggers in me:**
+1. **Log Analysis**: I will proactively look for logs/errors in the workspace.
+2. **Systematic Plan**: I will update `ISSUES.md` and propose a scoped fix.
+3. **Verified Execution**: I will implement the fix and verify it before delivery.
+
+---
+
+## Related Skills
+- **Agent Workflow**: `skills/agent-workflow.md` (Ledger management)
+- **Debug Tricks**: `skills/nextjs/debug-tricks.md` (Next.js specific tools)
+- **Performance**: `skills/nextjs/performance.md` & `skills/spring/performance_optimization.md`

package/skills/nextjs/design-intelligence.md

@@ -0,0 +1,76 @@
+# Skill: Design Intelligence (Next.js 15 + UI/UX Pro Max)
+
+Bridge the gap between pure design logic and high-performance Next.js implementation.
+
+## 1. The Design Workflow
+
+When building a new feature or page, follow this hierarchical retrieval pattern:
+
+1.  **Analyze**: Extract product type and style keywords from the request.
+2.  **Generate**: Run the design system generator (use `--design-system`).
+3.  **Integrate**: Map the generated variables to shadcn/ui or Tailwind tokens.
+
+### Generator Command
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<product_type> <keywords>" --design-system
+```
+
+---
+
+## 2. Integrated Implementation Patterns
+
+### Mapping to shadcn/ui
+Generated design system variables should be mapped to `globals.css` to respect the high-performance theming engine of shadcn.
+
+// Bad: Hardcoding values in components
+<div style={{ backgroundColor: '#0080FF' }}>...</div>
+
+// Good: Map to CSS variables
+// globals.css
+:root {
+  --primary: 221.2 83.2% 53.3%; /* From generated palette */
+  --radius: 0.75rem; /* From generated style */
+}
+
+### Performance-Aware Effects
+High-end effects must use Next.js optimized patterns to maintain 60FPS.
+
+| Style | Next.js Implementation Detail |
+|-------|-------------------------------|
+| **Glassmorphism** | Use `backdrop-blur` sparingly. Prefer `bg-white/80` in light mode for contrast. |
+| **Parallax** | Use `will-change: transform` and Framer Motion's `useScroll`. |
+| **Dark Mode** | Use `next-themes` to prevent hydration mismatch. |
+
+---
+
+## 3. Tooling & Automation
+
+### Automated Design System (Hierarchical)
+Always use the `--persist` flag when starting a project to create a `MASTER.md` file.
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "fintech dashboard glassmorphism" --design-system --persist -p "BankPro"
+```
+
+1.  Read `design-system/MASTER.md` for global rules.
+2.  Check for page-specific overrides in `design-system/pages/<page_name>.md`.
+
+---
+
+## 4. Quick Trigger Prompt (Universal)
+
+To trigger the full power of this integration for ANY task or project, use this concise prompt:
+
+> **"Triển khai [Task] theo chuẩn Design Intelligence + Next.js Performance."**
+
+**What this triggers in me:**
+1.  **Search**: I will automatically query `skills/ui-ux-pro-max/` for the best design system.
+2.  **Plan**: I will create a `task.md` with integrated design & performance phases.
+3.  **Execute**: I will use CSS variables for theming and Next.js Best Practices for code.
+
+---
+
+## Related Skills
+- **UI Libraries**: `skills/nextjs/ui-libraries.md` (Integration with shadcn/ui)
+- **Performance**: `skills/nextjs/performance.md` (Visual Performance rules)
+- **Design Database**: `skills/ui-ux-pro-max/SKILL.md` (Original CSV data)

package/skills/nextjs/performance.md

@@ -52,6 +52,17 @@ Ensure the server or CDN uses GZIP/Brotli to compress JSON responses.
 
 ---
 
+## 4. Visual Performance (Design Intelligence)
+
+Design choices impact technical performance. Balance aesthetics with the 60FPS target:
+
+1.  **Glassmorphism**: Limit `backdrop-blur` usage. Multiple layers can cause heavy CPU/GPU load on lower-end devices.
+2.  **Animations**: Use `will-change: transform` for hardware acceleration. Avoid animating `width`, `height`, or `margin`.
+3.  **SVGs vs Emojis**: Never use emojis for UI icons. SVGs offer superior performance (vector), accessibility (aria-label), and brand consistency.
+
+---
+
 ## Related Skills
+- **Design Intelligence**: `skills/nextjs/design-intelligence.md`
 - **Interactivity & Animation**: `skills/nextjs/interactivity.md`
 - **UI State Management**: `skills/nextjs/ui-state.md`

package/skills/nextjs/ui-libraries.md

@@ -74,9 +74,16 @@ Use CSS variables in `globals.css` for theming instead of hardcoding colors in T
 }
 ```
 
-## Common Libraries in Next.js
+## Design System Integration (Pro Max)
 
-- **shadcn/ui**: All-purpose, clean, professional.
-- **Radix UI**: Foundational primitives.
-- **Headless UI**: Good for Tailwind + simple components.
-- **Magic UI / Aceternity UI**: For high-end marketing and background effects (often uses Framer Motion).
+For professional projects, do not choose colors or styles manually. Use the Design Intelligence system:
+
+1.  **Generate**: Run `python3 skills/ui-ux-pro-max/scripts/search.py` to get recommended palettes and styles.
+2.  **Map**: Translate generated CSS variables to `globals.css`.
+3.  **Audit**: Follow the `Pre-Delivery Checklist` in `skills/ui-ux-pro-max/SKILL.md` (no emojis, cursor pointers, etc.).
+
+---
+
+## Related Skills
+- **Design Intelligence**: `skills/nextjs/design-intelligence.md`
+- **Component Aesthetics**: `skills/nextjs/component-aesthetics.md`

package/skills/spring/query_optimization.md

@@ -10,6 +10,7 @@ Advanced patterns for scaling and optimizing database access in high-traffic app
 3. **Composite Indexing**: Query under 10ms by indexing multiple columns used in WHERE/JOIN.
 4. **Leftmost Prefix**: Lead with the most selective column in composite indexes.
 5. **Slow Query Guards**: Use `@QueryHints` to set timeouts and prevent resource starvation.
+6. **P95 Targets**: Ensure API response time < 2s by optimizing database index paths.
 
 ---
 

package/skills/spring/repository_design.md

@@ -14,8 +14,9 @@ public interface MyRepository extends JpaRepository<MyEntity, Long> {
 2. **@Query (JPQL)**: Use for 3+ conditions or joins.
 3. **Named Parameters**: Always use `@Param("name")` instead of `?1`.
 4. **Aggregations**: Always wrap with `COALESCE(SUM(...), 0)` to avoid NPE.
-5. **Paginated Results**: Use `Page<T>` for UI, `Slice<T>` for infinite scroll.
-6. **Native Queries**: Use ONLY for UPSERT or join-table operations.
+5. **Filtering**: Always filter in DB (`WHERE`) instead of loading into Java memory.
+6. **Constants**: Replace magic numbers (e.g., Page size) with named constants.
+7. **Paginated Results**: Use `Page<T>` for UI, `Slice<T>` for infinite scroll.
 
 **Performance note:** JOIN FETCH, `@EntityGraph`, `@BatchSize`, and N+1 avoidance are covered in `skills/spring/query_optimization.md`. This skill focuses on **design and structure** — what type of query to write and how to name/organize it.
 
@@ -96,8 +97,10 @@ boolean existsByStudentIdAndLessonId(Long studentId, Long lessonId);
 // ❌ Too complex — derived query becomes unreadable
 List<SessionRecord> findByStudentIdAndTutorIdAndMonthAndPaidAndStatusNotIn(...);
 
-// ✅ Use @Query for anything with 3+ conditions or joins
-@Query("SELECT sr FROM SessionRecord sr WHERE ...")
+// ✅ Use @Query for anything with 3+ conditions or joins. 
+// Standard: Filter in DB to save memory and CPU.
+@Query("SELECT sr FROM SessionRecord sr WHERE sr.tutor.id = :id AND sr.status = :status")
+List<SessionRecord> findByTutorAndStatus(@Param("id") Long id, @Param("status") Status status);
 ```
 
 **Rule of thumb:** derived query with more than 2 conditions → switch to `@Query`.

package/skills/spring/service_design.md

@@ -11,9 +11,10 @@ public class MyServiceImpl implements MyService { ... }
 ### Critical Rules
 1. **Always split interface/impl** — inject the interface, hide the implementation.
 2. **Method Order**: Validate → Load → Mutate → Save → Return.
-3. **Transactions**: Use `@Transactional(readOnly = true)` for GET, and `@Transactional` for POST/PUT/DELETE.
-4. **Exceptions**: Throw domain-specific exceptions (ResourceNotFound, AlreadyExists).
-5. **Mapping**: Use private `mapToResponse()` or a dedicated Mapper.
+3. **Transactions**: Use `@Transactional(readOnly = true)` for GET, and `@Transactional` for POST/PUT/DELETE. Split heavy logic from write transactions.
+4. **Exceptions**: Throw domain-specific exceptions. **NEVER** swallow exceptions (e.g., JSON processing).
+5. **Enums**: Always compare using `==`. Never use `.name().equals()`.
+6. **Mapping**: Use private `mapToResponse()` or a dedicated Mapper.
 
 ### 📄 Templates
 - [Standard Service Template](./templates/ServiceTemplate.java)
@@ -180,6 +181,18 @@ public TutorResponse createTutor(TutorRequest request) {
     Tutor tutor = tutorRepository.save(newTutor); // step 2 — if this fails, step 1 rolls back
     return mapToResponse(tutor);
 }
+
+// Pro Tip: Split heavy processing from the write transaction to reduce lock time
+public void processHeavyReport() {
+    // 1. Load data (readOnly)
+    Data data = service.getData(id); 
+    
+    // 2. Heavy CPU calculation (No transaction)
+    Result result = calculate(data); 
+    
+    // 3. Save result (Write transaction)
+    service.saveResult(result); 
+}
 ```
 
 ---
@@ -317,6 +330,13 @@ throw new RuntimeException("Tutor not found with id: " + id);
 throw new ResourceNotFoundException("Tutor not found with id: " + id);   // -> 404
 throw new AlreadyExistsException("Email already exists: " + email);       // -> 409
 throw new InvalidInputException("Password must be at least 8 characters"); // -> 400
+
+// Rule: Never swallow technical exceptions. Re-throw or wrap them.
+try {
+    return objectMapper.writeValueAsString(data);
+} catch (JsonProcessingException e) {
+    throw new TechnicalException("Failed to serialize data", e); // Correct
+}
 ```
 
 **Common exception → HTTP status mapping:**

package/skills/ui-ux-pro-max/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: ui-ux-pro-max
+description: UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks.
+---
+# ui-ux-pro-max
+
+Comprehensive design guide for web and mobile applications. Contains 67 styles, 96 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 13 technology stacks. Searchable database with priority-based recommendations.
+
+## Prerequisites
+
+Check if Python is installed:
+
+```bash
+python3 --version || python --version
+```
+
+If Python is not installed, install it based on user's OS:
+
+**macOS:**
+```bash
+brew install python3
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt update && sudo apt install python3
+```
+
+**Windows:**
+```powershell
+winget install Python.Python.3.12
+```
+
+---
+
+## How to Use This Skill
+
+When user requests UI/UX work (design, build, create, implement, review, fix, improve), follow this workflow:
+
+### Step 1: Analyze User Requirements
+
+Extract key information from user request:
+- **Product type**: SaaS, e-commerce, portfolio, dashboard, landing page, etc.
+- **Style keywords**: minimal, playful, professional, elegant, dark mode, etc.
+- **Industry**: healthcare, fintech, gaming, education, etc.
+- **Stack**: React, Vue, Next.js, or default to `html-tailwind`
+
+### Step 2: Generate Design System (REQUIRED)
+
+**Always start with `--design-system`** to get comprehensive recommendations with reasoning:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
+```
+
+This command:
+1. Searches 5 domains in parallel (product, style, color, landing, typography)
+2. Applies reasoning rules from `ui-reasoning.csv` to select best matches
+3. Returns complete design system: pattern, style, colors, typography, effects
+4. Includes anti-patterns to avoid
+
+**Example:**
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"
+```
+
+### Step 2b: Persist Design System (Master + Overrides Pattern)
+
+To save the design system for hierarchical retrieval across sessions, add `--persist`:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name"
+```
+
+This creates:
+- `design-system/MASTER.md` — Global Source of Truth with all design rules
+- `design-system/pages/` — Folder for page-specific overrides
+
+**With page-specific override:**
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name" --page "dashboard"
+```
+
+This also creates:
+- `design-system/pages/dashboard.md` — Page-specific deviations from Master
+
+**How hierarchical retrieval works:**
+1. When building a specific page (e.g., "Checkout"), first check `design-system/pages/checkout.md`
+2. If the page file exists, its rules **override** the Master file
+3. If not, use `design-system/MASTER.md` exclusively
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+After getting the design system, use domain searches to get additional details:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
+```
+
+**When to use detailed searches:**
+
+| Need | Domain | Example |
+|------|--------|---------|
+| More style options | `style` | `--domain style "glassmorphism dark"` |
+| Chart recommendations | `chart` | `--domain chart "real-time dashboard"` |
+| UX best practices | `ux` | `--domain ux "animation accessibility"` |
+| Alternative fonts | `typography` | `--domain typography "elegant luxury"` |
+| Landing structure | `landing` | `--domain landing "hero social-proof"` |
+
+### Step 4: Stack Guidelines (Default: html-tailwind)
+
+Get implementation-specific best practices. If user doesn't specify a stack, **default to `html-tailwind`**.
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --stack html-tailwind
+```
+
+Available stacks: `html-tailwind`, `react`, `nextjs`, `vue`, `svelte`, `swiftui`, `react-native`, `flutter`, `shadcn`, `jetpack-compose`
+
+---
+
+## Search Reference
+
+### Available Domains
+
+| Domain | Use For | Example Keywords |
+|--------|---------|------------------|
+| `product` | Product type recommendations | SaaS, e-commerce, portfolio, healthcare, beauty, service |
+| `style` | UI styles, colors, effects | glassmorphism, minimalism, dark mode, brutalism |
+| `typography` | Font pairings, Google Fonts | elegant, playful, professional, modern |
+| `color` | Color palettes by product type | saas, ecommerce, healthcare, beauty, fintech, service |
+| `landing` | Page structure, CTA strategies | hero, hero-centric, testimonial, pricing, social-proof |
+| `chart` | Chart types, library recommendations | trend, comparison, timeline, funnel, pie |
+| `ux` | Best practices, anti-patterns | animation, accessibility, z-index, loading |
+| `react` | React/Next.js performance | waterfall, bundle, suspense, memo, rerender, cache |
+| `web` | Web interface guidelines | aria, focus, keyboard, semantic, virtualize |
+| `prompt` | AI prompts, CSS keywords | (style name) |
+
+### Available Stacks
+
+| Stack | Focus |
+|-------|-------|
+| `html-tailwind` | Tailwind utilities, responsive, a11y (DEFAULT) |
+| `react` | State, hooks, performance, patterns |
+| `nextjs` | SSR, routing, images, API routes |
+| `vue` | Composition API, Pinia, Vue Router |
+| `svelte` | Runes, stores, SvelteKit |
+| `swiftui` | Views, State, Navigation, Animation |
+| `react-native` | Components, Navigation, Lists |
+| `flutter` | Widgets, State, Layout, Theming |
+| `shadcn` | shadcn/ui components, theming, forms, patterns |
+| `jetpack-compose` | Composables, Modifiers, State Hoisting, Recomposition |
+
+---
+
+## Example Workflow
+
+**User request:** "Làm landing page cho dịch vụ chăm sóc da chuyên nghiệp"
+
+### Step 1: Analyze Requirements
+- Product type: Beauty/Spa service
+- Style keywords: elegant, professional, soft
+- Industry: Beauty/Wellness
+- Stack: html-tailwind (default)
+
+### Step 2: Generate Design System (REQUIRED)
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service elegant" --design-system -p "Serenity Spa"
+```
+
+**Output:** Complete design system with pattern, style, colors, typography, effects, and anti-patterns.
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+```bash
+# Get UX guidelines for animation and accessibility
+python3 skills/ui-ux-pro-max/scripts/search.py "animation accessibility" --domain ux
+
+# Get alternative typography options if needed
+python3 skills/ui-ux-pro-max/scripts/search.py "elegant luxury serif" --domain typography
+```
+
+### Step 4: Stack Guidelines
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "layout responsive form" --stack html-tailwind
+```
+
+**Then:** Synthesize design system + detailed searches and implement the design.
+
+---
+
+## Output Formats
+
+The `--design-system` flag supports two output formats:
+
+```bash
+# ASCII box (default) - best for terminal display
+python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system
+
+# Markdown - best for documentation
+python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown
+```
+
+---
+
+## Tips for Better Results
+
+1. **Be specific with keywords** - "healthcare SaaS dashboard" > "app"
+2. **Search multiple times** - Different keywords reveal different insights
+3. **Combine domains** - Style + Typography + Color = Complete design system
+4. **Always check UX** - Search "animation", "z-index", "accessibility" for common issues
+5. **Use stack flag** - Get implementation-specific best practices
+6. **Iterate** - If first search doesn't match, try different keywords
+
+---
+
+## Common Rules for Professional UI
+
+These are frequently overlooked issues that make UI look unprofessional:
+
+### Icons & Visual Elements
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **No emoji icons** | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis like 🎨 🚀 ⚙️ as UI icons |
+| **Stable hover states** | Use color/opacity transitions on hover | Use scale transforms that shift layout |
+| **Correct brand logos** | Research official SVG from Simple Icons | Guess or use incorrect logo paths |
+| **Consistent icon sizing** | Use fixed viewBox (24x24) with w-6 h-6 | Mix different icon sizes randomly |
+
+### Interaction & Cursor
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Cursor pointer** | Add `cursor-pointer` to all clickable/hoverable cards | Leave default cursor on interactive elements |
+| **Hover feedback** | Provide visual feedback (color, shadow, border) | No indication element is interactive |
+| **Smooth transitions** | Use `transition-colors duration-200` | Instant state changes or too slow (>500ms) |
+
+### Light/Dark Mode Contrast
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Glass card light mode** | Use `bg-white/80` or higher opacity | Use `bg-white/10` (too transparent) |
+| **Text contrast light** | Use `#0F172A` (slate-900) for text | Use `#94A3B8` (slate-400) for body text |
+| **Muted text light** | Use `#475569` (slate-600) minimum | Use gray-400 or lighter |
+| **Border visibility** | Use `border-gray-200` in light mode | Use `border-white/10` (invisible) |
+
+### Layout & Spacing
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Floating navbar** | Add `top-4 left-4 right-4` spacing | Stick navbar to `top-0 left-0 right-0` |
+| **Content padding** | Account for fixed navbar height | Let content hide behind fixed elements |
+| **Consistent max-width** | Use same `max-w-6xl` or `max-w-7xl` | Mix different container widths |
+
+---
+
+## Pre-Delivery Checklist
+
+Before delivering UI code, verify these items:
+
+### Visual Quality
+- [ ] No emojis used as icons (use SVG instead)
+- [ ] All icons from consistent icon set (Heroicons/Lucide)
+- [ ] Brand logos are correct (verified from Simple Icons)
+- [ ] Hover states don't cause layout shift
+- [ ] Use theme colors directly (bg-primary) not var() wrapper
+
+### Interaction
+- [ ] All clickable elements have `cursor-pointer`
+- [ ] Hover states provide clear visual feedback
+- [ ] Transitions are smooth (150-300ms)
+- [ ] Focus states visible for keyboard navigation
+
+### Light/Dark Mode
+- [ ] Light mode text has sufficient contrast (4.5:1 minimum)
+- [ ] Glass/transparent elements visible in light mode
+- [ ] Borders visible in both modes
+- [ ] Test both modes before delivery
+
+### Layout
+- [ ] Floating elements have proper spacing from edges
+- [ ] No content hidden behind fixed navbars
+- [ ] Responsive at 375px, 768px, 1024px, 1440px
+- [ ] No horizontal scroll on mobile
+
+### Accessibility
+- [ ] All images have alt text
+- [ ] Form inputs have labels
+- [ ] Color is not the only indicator
+- [ ] `prefers-reduced-motion` respected

package/skills/ui-ux-pro-max/data/charts.csv

@@ -0,0 +1,26 @@
+No,Data Type,Keywords,Best Chart Type,Secondary Options,Color Guidance,Performance Impact,Accessibility Notes,Library Recommendation,Interactive Level
+1,Trend Over Time,"trend, time-series, line, growth, timeline, progress",Line Chart,"Area Chart, Smooth Area",Primary: #0080FF. Multiple series: use distinct colors. Fill: 20% opacity,⚡ Excellent (optimized),✓ Clear line patterns for colorblind users. Add pattern overlays.,"Chart.js, Recharts, ApexCharts",Hover + Zoom
+2,Compare Categories,"compare, categories, bar, comparison, ranking",Bar Chart (Horizontal or Vertical),"Column Chart, Grouped Bar",Each bar: distinct color. Category: grouped same color. Sorted: descending order,⚡ Excellent,✓ Easy to compare. Add value labels on bars for clarity.,"Chart.js, Recharts, D3.js",Hover + Sort
+3,Part-to-Whole,"part-to-whole, pie, donut, percentage, proportion, share",Pie Chart or Donut,"Stacked Bar, Treemap",Colors: 5-6 max. Contrasting palette. Large slices first. Use labels.,⚡ Good (limit 6 slices),⚠ Hard for accessibility. Better: Stacked bar with legend. Avoid pie if >5 items.,"Chart.js, Recharts, D3.js",Hover + Drill
+4,Correlation/Distribution,"correlation, distribution, scatter, relationship, pattern",Scatter Plot or Bubble Chart,"Heat Map, Matrix",Color axis: gradient (blue-red). Size: relative. Opacity: 0.6-0.8 to show density,⚠ Moderate (many points),⚠ Provide data table alternative. Use pattern + color distinction.,"D3.js, Plotly, Recharts",Hover + Brush
+5,Heatmap/Intensity,"heatmap, heat-map, intensity, density, matrix",Heat Map or Choropleth,"Grid Heat Map, Bubble Heat",Gradient: Cool (blue) to Hot (red). Scale: clear legend. Divergent for ±data,⚡ Excellent (color CSS),⚠ Colorblind: Use pattern overlay. Provide numerical legend.,"D3.js, Plotly, ApexCharts",Hover + Zoom
+6,Geographic Data,"geographic, map, location, region, geo, spatial","Choropleth Map, Bubble Map",Geographic Heat Map,Regional: single color gradient or categorized colors. Legend: clear scale,⚠ Moderate (rendering),⚠ Include text labels for regions. Provide data table alternative.,"D3.js, Mapbox, Leaflet",Pan + Zoom + Drill
+7,Funnel/Flow,funnel/flow,"Funnel Chart, Sankey",Waterfall (for flows),Stages: gradient (starting color → ending color). Show conversion %,⚡ Good,✓ Clear stage labels + percentages. Good for accessibility if labeled.,"D3.js, Recharts, Custom SVG",Hover + Drill
+8,Performance vs Target,performance-vs-target,Gauge Chart or Bullet Chart,"Dial, Thermometer",Performance: Red→Yellow→Green gradient. Target: marker line. Threshold colors,⚡ Good,✓ Add numerical value + percentage label beside gauge.,"D3.js, ApexCharts, Custom SVG",Hover
+9,Time-Series Forecast,time-series-forecast,Line with Confidence Band,Ribbon Chart,Actual: solid line #0080FF. Forecast: dashed #FF9500. Band: light shading,⚡ Good,✓ Clearly distinguish actual vs forecast. Add legend.,"Chart.js, ApexCharts, Plotly",Hover + Toggle
+10,Anomaly Detection,anomaly-detection,Line Chart with Highlights,Scatter with Alert,Normal: blue #0080FF. Anomaly: red #FF0000 circle/square marker + alert,⚡ Good,✓ Circle/marker for anomalies. Add text alert annotation.,"D3.js, Plotly, ApexCharts",Hover + Alert
+11,Hierarchical/Nested Data,hierarchical/nested-data,Treemap,"Sunburst, Nested Donut, Icicle",Parent: distinct hues. Children: lighter shades. White borders 2-3px.,⚠ Moderate,⚠ Poor - provide table alternative. Label large areas.,"D3.js, Recharts, ApexCharts",Hover + Drilldown
+12,Flow/Process Data,flow/process-data,Sankey Diagram,"Alluvial, Chord Diagram",Gradient from source to target. Opacity 0.4-0.6 for flows.,⚠ Moderate,⚠ Poor - provide flow table alternative.,"D3.js (d3-sankey), Plotly",Hover + Drilldown
+13,Cumulative Changes,cumulative-changes,Waterfall Chart,"Stacked Bar, Cascade",Increases: #4CAF50. Decreases: #F44336. Start: #2196F3. End: #0D47A1.,⚡ Good,✓ Good - clear directional colors with labels.,"ApexCharts, Highcharts, Plotly",Hover
+14,Multi-Variable Comparison,multi-variable-comparison,Radar/Spider Chart,"Parallel Coordinates, Grouped Bar",Single: #0080FF 20% fill. Multiple: distinct colors per dataset.,⚡ Good,⚠ Moderate - limit 5-8 axes. Add data table.,"Chart.js, Recharts, ApexCharts",Hover + Toggle
+15,Stock/Trading OHLC,stock/trading-ohlc,Candlestick Chart,"OHLC Bar, Heikin-Ashi",Bullish: #26A69A. Bearish: #EF5350. Volume: 40% opacity below.,⚡ Good,⚠ Moderate - provide OHLC data table.,"Lightweight Charts (TradingView), ApexCharts",Real-time + Hover + Zoom
+16,Relationship/Connection Data,relationship/connection-data,Network Graph,"Hierarchical Tree, Adjacency Matrix",Node types: categorical colors. Edges: #90A4AE 60% opacity.,❌ Poor (500+ nodes struggles),❌ Very Poor - provide adjacency list alternative.,"D3.js (d3-force), Vis.js, Cytoscape.js",Drilldown + Hover + Drag
+17,Distribution/Statistical,distribution/statistical,Box Plot,"Violin Plot, Beeswarm",Box: #BBDEFB. Border: #1976D2. Median: #D32F2F. Outliers: #F44336.,⚡ Excellent,"✓ Good - include stats table (min, Q1, median, Q3, max).","Plotly, D3.js, Chart.js (plugin)",Hover
+18,Performance vs Target (Compact),performance-vs-target-(compact),Bullet Chart,"Gauge, Progress Bar","Ranges: #FFCDD2, #FFF9C4, #C8E6C9. Performance: #1976D2. Target: black 3px.",⚡ Excellent,✓ Excellent - compact with clear values.,"D3.js, Plotly, Custom SVG",Hover
+19,Proportional/Percentage,proportional/percentage,Waffle Chart,"Pictogram, Stacked Bar 100%",10x10 grid. 3-5 categories max. 2-3px spacing between squares.,⚡ Good,✓ Good - better than pie for accessibility.,"D3.js, React-Waffle, Custom CSS Grid",Hover
+20,Hierarchical Proportional,hierarchical-proportional,Sunburst Chart,"Treemap, Icicle, Circle Packing",Center to outer: darker to lighter. 15-20% lighter per level.,⚠ Moderate,⚠ Poor - provide hierarchy table alternative.,"D3.js (d3-hierarchy), Recharts, ApexCharts",Drilldown + Hover
+21,Root Cause Analysis,"root cause, decomposition, tree, hierarchy, drill-down, ai-split",Decomposition Tree,"Decision Tree, Flow Chart",Nodes: #2563EB (Primary) vs #EF4444 (Negative impact). Connectors: Neutral grey.,⚠ Moderate (calculation heavy),✓ clear hierarchy. Allow keyboard navigation for nodes.,"Power BI (native), React-Flow, Custom D3.js",Drill + Expand
+22,3D Spatial Data,"3d, spatial, immersive, terrain, molecular, volumetric",3D Scatter/Surface Plot,"Volumetric Rendering, Point Cloud",Depth cues: lighting/shading. Z-axis: color gradient (cool to warm).,❌ Heavy (WebGL required),❌ Poor - requires alternative 2D view or data table.,"Three.js, Deck.gl, Plotly 3D",Rotate + Zoom + VR
+23,Real-Time Streaming,"streaming, real-time, ticker, live, velocity, pulse",Streaming Area Chart,"Ticker Tape, Moving Gauge",Current: Bright Pulse (#00FF00). History: Fading opacity. Grid: Dark.,⚡ Optimized (canvas/webgl),⚠ Flashing elements - provide pause button. High contrast.,Smoothed D3.js, CanvasJS
+24,Sentiment/Emotion,"sentiment, emotion, nlp, opinion, feeling",Word Cloud with Sentiment,"Sentiment Arc, Radar Chart",Positive: #22C55E. Negative: #EF4444. Neutral: #94A3B8. Size = Frequency.,⚡ Good,⚠ Word clouds poor for screen readers. Use list view.,"D3-cloud, Highcharts, Nivo",Hover + Filter
+25,Process Mining,"process, mining, variants, path, bottleneck, log",Process Map / Graph,"Directed Acyclic Graph (DAG), Petri Net",Happy path: #10B981 (Thick). Deviations: #F59E0B (Thin). Bottlenecks: #EF4444.,⚠ Moderate to Heavy,⚠ Complex graphs hard to navigate. Provide path summary.,"React-Flow, Cytoscape.js, Recharts",Drag + Node-Click