@longtq2501/next-spring-skills 1.4.0 → 1.6.0

package/README.md

@@ -27,6 +27,14 @@ npx @longtq2501/next-spring-skills
 
 This will copy the `skills/` directory and `AGENT.md` into your current project folder.
 
+Meta-Prompt:
+
+> "Triển khai [Task của bạn] theo chuẩn Design Intelligence + Next.js Performance." 
+
+> "Triển khai [Backend Task] theo chuẩn Spring Boot Pro Max (Performance & Clean Code)."
+
+> "Sửa lỗi [Mô tả lỗi] theo chuẩn Debug & Fix Pro Max."
+
 ## 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.4.0",
+  "version": "1.6.0",
   "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/component-aesthetics.md

@@ -0,0 +1,58 @@
+# Component Aesthetics
+
+Standardizing the "feel" of components like cards, buttons, and sections ensures a premium, cohesive user experience.
+
+## 1. The 8px Spacing System
+
+A consistent spacing system is the foundation of professional-looking UI. Always use multiples of 8px (or 4px for fine-tuning).
+
+- **Nano**: `4px` (`p-1`, `m-1`) - Micro-spacing for icons/text.
+- **Small**: `8px` (`p-2`, `m-2`) - Default gap for small items.
+- **Base**: `16px` (`p-4`, `m-4`) - Standard padding for cards/modals.
+- **Large**: `24px` (`p-6`, `m-6`) - Generous padding for landing sections.
+- **Huge**: `32px` (`p-8`, `m-8`) - Container margins.
+
+> [!TIP]
+> Use `gap-{n}` instead of margins whenever possible to keep layout logic centralized in the container.
+
+## 2. Border Radius Scale
+
+Consistent rounded corners make the UI feel modern and approachable. Avoid "sharp" 0px corners or "clipping" 2px corners.
+
+- **Soft (md)**: `6px` / `0.375rem` - Checkboxes, small inputs.
+- **Standard (lg)**: `8px` / `0.5rem` - Default button radius.
+- **Premium (xl)**: `12px` / `0.75rem` - Cards, dropdown menus.
+- **Super (2xl)**: `16px` / `1rem` - Large modals, image containers.
+- **Full**: `9999px` - Pills, circular avatars.
+
+## 3. Shadow & Depth (Elevation)
+
+Shadows should be subtle and multi-layered. Avoid single, dark, blurry shadows.
+
+```css
+/* Custom utility for Premium Shadow */
+.shadow-premium {
+  box-shadow: 
+    0 1px 2px rgba(0, 0, 0, 0.05),
+    0 4px 6px -1px rgba(0, 0, 0, 0.1),
+    0 2px 4px -1px rgba(0, 0, 0, 0.06);
+}
+
+/* Glassmorphism Border (Adds depth without heavy shadows) */
+.border-premium {
+  border: 1px solid hsl(var(--border) / 0.5);
+  background-clip: padding-box;
+}
+```
+
+## 4. Visual Hierarchy Techniques
+
+- **Surface Contrast**: In dark mode, nested components should be *lighter* than their parents to simulate light reflection.
+  - Body Background: `hsl(240 10% 3.9%)`
+  - Card/Overlay: `hsl(240 10% 7.5%)`
+- **Ghost Dividers**: Instead of solid lines, use `border-muted/30` or just whitespace (`gap`) to separate content.
+
+## Best Practices
+1. **Consistency is King**: If one card has `rounded-xl`, all equivalent cards must have `rounded-xl`.
+2. **Inner Radius Logic**: If a parent has `rounded-xl` (12px), the child should have `rounded-lg` (8px) to maintain a concentric look.
+3. **Subtle Borders**: Never use `#eee` or `black` for borders. Use `hsl(var(--border))` with varying opacities.

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/design-tokens.md

@@ -0,0 +1,68 @@
+# Modern Design Tokens
+
+Design tokens are the visual atoms of your design system. Standardizing these ensures professional color harmony, readable typography, and consistent aesthetics across the application.
+
+## 1. Color Harmony (HSL)
+
+Always use HSL (Hue, Saturation, Lightness) for colors. It is intuitive and allows for programmatically generating shades.
+
+### Core Palette
+Avoid generic "pure" colors. Use curated HSL values.
+
+```css
+:root {
+  /* Neutral Palette - Slate/Zinc */
+  --background: 240 10% 3.9%;
+  --foreground: 0 0% 98%;
+  --muted: 240 3.7% 15.9%;
+  --muted-foreground: 240 5% 64.9%;
+
+  /* Primary - Deep Indigo/Blue */
+  --primary: 263.4 70% 50.4%;
+  --primary-foreground: 210 20% 98%;
+
+  /* Accent - Soft Violet */
+  --accent: 240 3.7% 15.9%;
+  --accent-foreground: 0 0% 98%;
+}
+```
+
+### Semantic Colors
+Define clear colors for status to improve UX.
+
+- **Success**: Emerald (`142.1 70.6% 45.3%`)
+- **Warning**: Amber (`37.9 92.1% 50.2%`)
+- **Destructive**: Rose (`346.8 77.2% 49.8%`)
+
+## 2. Typography Excellence
+
+Premium UIs rely on high-quality font stacks and proper spacing.
+
+### Font Stacks
+Use modern, highly legible fonts.
+
+```css
+/* Tailwind Config */
+fontFamily: {
+  sans: ['var(--font-geist-sans)', 'Inter', 'system-ui', 'sans-serif'],
+  display: ['Outfit', 'var(--font-geist-sans)'],
+}
+```
+
+### Hierarchy & Leading
+- **Body Text**: `tracking-tight` and `leading-relaxed` (1.625).
+- **Headings**: `tracking-tighter` and `leading-tight` (1.2) for a modern, compact look.
+- **Micro-copy**: `uppercase`, `tracking-widest`, `text-xs`, `font-semibold`.
+
+## 3. Dark Mode Strategy
+
+Modern apps must prioritize dark mode. Use "Soft Dark" instead of "Pure Black" (`#000000`) for backgrounds to reduce eye strain.
+
+- **Background**: `hsl(240 10% 3.9%)`
+- **Surface/Card**: `hsl(240 10% 6%)`
+- **Border**: `hsl(240 5% 15%)`
+
+## Best Practices
+1. **Never use Hex/RGB for primary tokens**: Use HSL to allow for opacity modifiers (e.g., `bg-primary/20`).
+2. **Limit Colors**: Stick to 1 Primary, 1 Neutral, and the 3 Semantic colors.
+3. **Contrast First**: Always verify your foreground/background contrast using APCA or WCAG 2.1 standards.

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/premium-effects.md

@@ -0,0 +1,61 @@
+# Premium Effects
+
+These advanced visual techniques provide the "WOW" factor that differentiates a professional application from a basic one.
+
+## 1. Glassmorphism
+
+A modern aesthetic that uses semi-transparent, blurred backgrounds to create a "frosted glass" look.
+
+```tsx
+/* Standard Glassmorphism Card */
+<div className="
+  bg-white/10 backdrop-blur-md 
+  border border-white/20 rounded-2xl
+  shadow-xl
+">
+  Content appears on a glass surface
+</div>
+```
+
+### Critical Rules for Glassmorphism:
+- **Background**: Ensure the underlying background has enough color/texture for the blur to be noticeable.
+- **Borders**: Always use a semi-transparent white/light border (`border-white/20`) to define the edges.
+- **Contrast**: Check text readability carefully; dark mode often works better with glassmorphism.
+
+## 2. Sophisticated Gradients
+
+Avoid hard, two-color linear gradients. Use multi-stop or mesh gradients for a premium feel.
+
+```css
+/* Mesh Gradient Example */
+.bg-mesh {
+  background-color: hsla(240, 100%, 5%, 1);
+  background-image:
+    radial-gradient(at 0% 0%, hsla(253,16%,7%,1) 0, transparent 50%),
+    radial-gradient(at 50% 0%, hsla(225,39%,30%,1) 0, transparent 50%),
+    radial-gradient(at 100% 0%, hsla(339,49%,30%,1) 0, transparent 50%);
+}
+```
+
+- **Brand Glow**: Use a subtle gradient on primary buttons or active states.
+- **Text Gradients**: Use `bg-clip-text text-transparent bg-gradient-to-r` for high-impact headlines.
+
+## 3. Grain & Texture
+
+Adding subtle noise or textures prevents the UI from looking "too flat."
+
+- **SVG Noise**: A very low opacity (1-3%) SVG noise layer over backgrounds.
+- **Pattern Overlays**: Subtle dot grids or geometric patterns at 5% opacity.
+
+## 4. Micro-interactions (The "Alive" Feel)
+
+Use Framer Motion to add organic movement.
+
+- **Hover Reveal**: Animate an element's opacity or position slightly when a parent card is hovered.
+- **Floating Effects**: Subtle vertical floating for cards or high-priority icons (`animate={{ y: [0, -4, 0] }}`).
+- **Staggered Entry**: Use `staggerChildren` in Framer Motion to reveal lists item by item instead of all at once.
+
+## Best Practices
+1. **Don't Overdo It**: Too many effects (blur + gradient + grain + noise) can look messy and impact performance.
+2. **Performance First**: `backdrop-blur` is heavy on GPUs. Use it sparingly, mainly for navbars or small overlays.
+3. **Accessibility**: Never communicate information *only* through a visual effect; ensure proper contrast and ARIA labels.

package/skills/nextjs/premium-inputs.md

@@ -0,0 +1,65 @@
+# Premium Inputs & Buttons
+
+The most interactive elements of your application deserve the most attention. Standardizing these prevents "clunky" or "ugly" user interfaces.
+
+## 1. Button Archetypes
+
+Every button should have a clear purpose and a distinct visual style.
+
+| Variant | Usage | Style |
+|:---|:---|:---|
+| **Primary** | Main Action (Save, Submit) | Solid brand color, high contrast. |
+| **Secondary** | Secondary Action (Cancel, Edit) | Outline or subtle background. |
+| **Ghost** | Tertiary Action (Navigation) | No background/border until hover. |
+| **Subtle** | Low-priority utility | Very low contrast background. |
+
+### Interactive States (The "Vibe")
+Always add micro-interactions to buttons to make them feel responsive.
+
+```tsx
+<button className="
+  px-4 py-2 rounded-lg font-medium transition-all
+  hover:scale-[1.02] active:scale-[0.98]
+  hover:brightness-110 active:brightness-90
+  focus-visible:ring-2 focus-visible:ring-primary/50
+">
+  Click Me
+</button>
+```
+
+## 2. Input Polish
+
+Modern inputs should feel deep and clean.
+
+- **Height**: Minimum `40px` (h-10) for readability and touch targets.
+- **Padding**: Horizontal `12px` (px-3), Vertical `8px` (py-2).
+- **Focus State**: Use a subtle inner shadow or a distinct (but not jarring) border glow.
+
+```tsx
+<input className="
+  w-full bg-background border border-input rounded-md px-3 py-2
+  placeholder:text-muted-foreground
+  focus:outline-none focus:ring-2 focus:ring-primary/20 focus:border-primary
+  transition-shadow
+" />
+```
+
+## 3. Shared Field Patterns
+
+- **Label Placement**: Place labels 4px-8px above the input. Use `text-sm font-medium`.
+- **Help/Error Text**: Use `text-[12px]` (text-xs) and ensure `Destructive` color for errors.
+- **Required Indicator**: Use a subtle dot or `*` in the brand color, not just plain red.
+
+## 4. Loading States
+
+Never leave a user guessing. If a button triggers an async action, it *must* show a loading state.
+
+- **Spinner**: Small, centered, matching the text color.
+- **Text change**: Optionally change "Submit" to "Submitting...".
+- **Disabling**: Disable the button to prevent double-submissions.
+
+## Best Practices
+1. **Touch Targets**: Ensure all clickable elements are at least `44x44px` on mobile.
+2. **Clear Affordance**: Buttons should look like buttons (radius, slight shadow, or distinct color).
+3. **Contrast**: Ensure text inside buttons is highly readable (Primary foreground vs Primary background).
+4. **No Placeholders as Labels**: Never use `placeholder` as a substitute for a real `<label>`.

package/skills/nextjs/responsive-design.md

@@ -0,0 +1,56 @@
+# Responsive Design
+
+Ensuring the application is usable and beautiful on every screen size, from mobile phones to ultra-wide monitors. We follow a **Mobile-First** approach.
+
+## 1. Mobile-First Workflow
+
+Always start with mobile styles (default) and use Tailwind breakpoints to "add" complexity for larger screens.
+
+- **Mobile (Default)**: Single column, full-width buttons, condensed headers.
+- **Tablet (`md:`)**: Two columns, sidebar reveals, increased padding.
+- **Desktop (`lg:`)**: Multi-column layouts, full navigation menus, expanded content.
+
+```tsx
+/* Responsive Container Example */
+<div className="
+  grid grid-cols-1 gap-4 
+  md:grid-cols-2 lg:grid-cols-3
+  p-4 md:p-8
+">
+  {/* Content adapts to screen size */}
+</div>
+```
+
+## 2. Standard Breakpoints
+
+Stick to Tailwind's default breakpoints for consistency:
+
+| Breakpoint | Prefix | Width | Usage |
+|:---|:---|:---|:---|
+| **Small** | `sm:` | 640px | Small tablets / Large phones |
+| **Medium** | `md:` | 768px | Tablets (Portrait) |
+| **Large** | `lg:` | 1024px | Laptops / Tablets (Landscape) |
+| **Extra Large**| `xl:` | 1280px | Desktops |
+
+## 3. Fluid Typography & Spacing
+
+Instead of hardcoding sizes, use relative units or clamp functions for elements that need to scale smoothly.
+
+- **Prefer**: `text-base md:text-lg` over a static size.
+- **Stacking**: Use `flex-col md:flex-row` for components that should stack on mobile but be side-by-side on desktop.
+
+## 4. Touch-Friendly UI (Mobile)
+
+- **Hit Targets**: Buttons and links must be at least `44x44px`.
+- **No Hover for Logic**: Never hide critical functionality behind a hover state on mobile (mobile has no hover).
+- **Navigation**: Use "Hamburger" menus or bottom bars for mobile navigation.
+
+## 5. Responsive Media
+
+- **Images**: Use `next/image` with `sizes` attribute to prevent loading massive images on small screens.
+- **Aspect Ratio**: Use `aspect-video` or `aspect-square` to maintain proportions during resizing.
+
+## Best Practices
+1. **Test in Browser**: Always verify by resizing the browser or using Device Mode in DevTools.
+2. **Avoid "Hiding" Content**: Try to reorganize content rather than using `hidden` to remove logic for mobile users.
+3. **Overflow Handling**: Always use `overflow-x-hidden` on the main container to prevent accidental horizontal scrolling.