@longtq2501/next-spring-skills 1.3.0 → 1.5.0

package/AGENT.md

@@ -1,5 +1,8 @@
 # Agent Instructions
 
+> [!IMPORTANT]
+> **MANDATORY STARTUP STEP**: Upon starting a new session or entering this project, the AI Agent **MUST** immediately read `skills/SKILL.md` to index all available standards and architectural patterns. Do not proceed with code generation until you have understood the patterns in the `skills/` directory.
+
 Rules for contributing to this repository.
 
 ## Style Guidelines

package/README.md

@@ -1,5 +1,7 @@
 # Next-Spring Skills
 
+[![npm version](https://img.shields.io/npm/v/@longtq2501/next-spring-skills.svg)](https://www.npmjs.com/package/@longtq2501/next-spring-skills)
+
 Modular best practices, code templates, and interaction protocols for full-stack projects using **Next.js** and **Spring Boot**.
 
 ## Key Directories
@@ -11,6 +13,11 @@ Modular best practices, code templates, and interaction protocols for full-stack
 
 ---
 
+## NPM Package
+📦 **Registry**: [https://www.npmjs.com/package/@longtq2501/next-spring-skills](https://www.npmjs.com/package/@longtq2501/next-spring-skills)
+
+---
+
 ## Installation
 You can instantly add these skills to any project using `npx`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longtq2501/next-spring-skills",
-  "version": "1.3.0",
+  "version": "1.5.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

@@ -69,6 +69,9 @@ See [webrtc.md](./nextjs/webrtc.md) for real-time media and signaling.
 ### Quality Assurance
 See [testing.md](./nextjs/testing.md) for Vitest and React Testing Library patterns.
 
+### Architecture & Monorepo
+See [monorepo.md](./nextjs/monorepo.md) for Turborepo and code-sharing strategies.
+
 ### Accessibility (a11y)
 See [accessibility.md](./nextjs/accessibility.md) for semantic HTML and ARIA.
 

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-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/monorepo.md

@@ -0,0 +1,116 @@
+# Skill: Monorepo Management - Turborepo (Production Blueprint)
+
+Guidelines for building a scalable, high-performance monorepo for enterprise-level multi-platform projects.
+
+## TL;DR - Quick Reference
+
+### Critical Rules
+1. **Orchestration**: Use Turborepo for build pipeline and remote caching.
+2. **Modular Packages**: Extract logic to `packages/` to ensure 95%+ code reusability.
+3. **Internal Linking**: Use `workspace:*` for local package dependencies.
+4. **Consistency**: Share ESLint, Prettier, Tailwind, and TS configs across all apps.
+5. **Types First**: Shared DTOs in `packages/types` are the single source of truth for FE/BE sync.
+
+---
+
+## 1. Enterprise Directory Structure
+
+```text
+/my-monorepo/
+├── apps/                           # Deployable Applications
+│   ├── web/                        # Next.js 14 App Router
+│   ├── admin/                      # Admin Dashboard
+│   ├── mobile/                     # React Native (Expo)
+│   ├── desktop/                    # Electron
+│   └── api/                        # Spring Boot (Backend)
+├── packages/                       # Shared Domain Logic
+│   ├── ui/                         # Core UI (Shadcn/React)
+│   ├── types/                      # Shared Interfaces & DTOs
+│   ├── validators/                 # Zod/Validation Logic
+│   ├── utils/                      # Shared Helpers (Date, String)
+│   ├── api-client/                 # Axios/Fetch Wrapper
+│   └── database/                   # Prisma/DB Client
+├── infra/                          # Shared Configuration
+│   ├── tailwind-config/
+│   ├── eslint-config/
+│   └── typescript-config/
+├── turbo.json                      # Build Pipeline Config
+└── package.json                    # Workspace Definition
+```
+
+---
+
+## 2. Core Configurations
+
+### turbo.json (The Brain)
+Defines task dependencies and caching outputs.
+
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "pipeline": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": [".next/**", "dist/**", "out/**"]
+    },
+    "lint": {},
+    "test": {
+      "cache": true
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    }
+  }
+}
+```
+
+### package.json (The Workspace)
+Must include `workspaces` (npm/yarn) or `pnpm-workspace.yaml`.
+
+```json
+{
+  "private": true,
+  "workspaces": ["apps/*", "packages/*"],
+  "scripts": {
+    "dev": "turbo dev",
+    "build": "turbo build",
+    "test": "turbo test"
+  }
+}
+```
+
+---
+
+## 3. Shared Packages Pattern
+
+### How to share a package (ex: Types)
+1. Create `packages/types/package.json` with a scoped name like `@repo/types`.
+2. Export your types/interfaces from `index.ts`.
+3. In `apps/web/package.json`, add `"@repo/types": "workspace:*"`.
+
+// Good: Shared DTO Example
+export interface OrderDTO {
+  id: string;
+  status: 'PENDING' | 'DONE';
+  items: string[];
+}
+
+---
+
+## 4. Scaling & Efficiency
+
+### Remote Caching
+Enable `turbo login` and `turbo link` in CI/CD to share build artifacts across the team, reducing build times from minutes to seconds.
+
+### Monolith to Monorepo Migration
+- **Step 1**: Move your monolithic `src/` to `apps/main-app/`.
+- **Step 2**: Identify shared logic (utils, constants) and move them to `packages/`.
+- **Step 3**: Introduce internal packages and replace local imports with `@repo/...`.
+
+---
+
+## Related Skills
+- **Frontend Testing**: `skills/nextjs/testing.md`
+- **Performance**: `skills/nextjs/performance.md`
+- **Agent Workflow**: `skills/agent-workflow.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.

package/skills/nextjs/testing.md

@@ -1,86 +1,90 @@
-# Skill: Frontend Testing - Vitest & RTL
+# Advanced Frontend Testing - Vitest
 
-Guidelines for testing React components and logic using Vitest and React Testing Library (RTL).
+When building frontend features, **testing logic is as important as building the UI**. This skill ensures that every piece of business logic (hooks, utils, state) is verified automatically.
 
-## TL;DR - Quick Reference
+## 1. Logic-First Testing Strategy
 
-### Critical Rules
-1. **User-Centric Testing**: Test how the user interacts with the app (e.g., clicking buttons), not implementation details (e.g., state).
-2. **Vitest**: Use Vitest for speed and compatibility with Vite/Next.js.
-3. **Screen Queries**: Prefer `getByRole`, `getByLabelText`, and `getByText` over `test-id`.
-4. **Mocking**: Use `vi.mock()` for modules and **MSW (Mock Service Worker)** for API calls.
-5. **Async Handling**: Use `findBy...` or `waitFor` to handle elements that appear after an async operation.
+Always separate business logic from UI components. This makes testing easier and more reliable.
 
----
+### Testing Utility Functions
+Test pure functions that transform data or perform calculations.
 
-## 1. Utility & Logic Testing (Vitest)
-Test pure JavaScript/TypeScript functions and logic.
+```typescript
+// utils/price.test.ts
+import { describe, it, expect } from 'vitest'
+import { formatCurrency } from './price'
 
-// Good: Testing a utility function
-import { describe, it, expect } from 'vitest';
-import { calculateTotal } from './math';
+describe('formatCurrency', () => {
+  it('should format numbers to VND correctly', () => {
+    expect(formatCurrency(100000)).toBe('100.000 ₫')
+  })
+})
+```
 
-describe('calculateTotal', () => {
-  it('should sum items correctly with tax', () => {
-    const items = [{ price: 100 }, { price: 200 }];
-    const result = calculateTotal(items, 0.1);
-    expect(result).toBe(330);
-  });
-});
+### Testing Custom Hooks
+Use `renderHook` to test hooks that contain state or side effects.
 
----
+```typescript
+// hooks/useCounter.test.ts
+import { renderHook, act } from '@testing-library/react'
+import { useCounter } from './useCounter'
 
-## 2. Component Testing (React Testing Library)
-Test UI behavior and interaction.
+it('should increment correctly', () => {
+  const { result } = renderHook(() => useCounter())
+  act(() => result.current.increment())
+  expect(result.current.count).toBe(1)
+})
+```
 
-// Good: Testing a Button component
-import { render, screen, fireEvent } from '@testing-library/react';
-import { Button } from './Button';
+## 2. Integration Testing (Components + Logic)
 
-it('should call onClick when clicked', () => {
-  const handleClick = vi.fn();
-  render(<Button onClick={handleClick}>Click Me</Button>);
-  
-  fireEvent.click(screen.getByText(/click me/i));
-  
-  expect(handleClick).toHaveBeenCalledTimes(1);
-});
+Test how the UI interacts with the underlying logic and services.
 
----
+- **Mock Service Worker (MSW)**: Always intercept network calls. Never hit the live API during tests.
+- **User Actions**: Use `@testing-library/user-event` for more realistic interaction simulation than `fireEvent`.
 
-## 3. Async & API Testing (MSW)
-Using Mock Service Worker to intercept network requests.
+```tsx
+// components/LoginForm.test.tsx
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { LoginForm } from './LoginForm'
 
-// Good: Testing a component that fetches data
-it('should display products from API', async () => {
-  render(<ProductList />);
+it('should show error when login fails', async () => {
+  const user = userEvent.setup()
+  render(<LoginForm />)
   
-  // findBy queries are async and will wait
-  const item = await screen.findByText('Laptop');
-  expect(item).toBeInTheDocument();
-});
-
----
-
-## 4. Hooks Testing
-Use `@testing-library/react-hooks` or the built-in `renderHook` from RTL.
-
-// Good: Testing a custom hook
-import { renderHook, act } from '@testing-library/react';
-import { useCounter } from './useCounter';
-
-it('should increment counter', () => {
-  const { result } = renderHook(() => useCounter());
+  await user.type(screen.getByLabelText(/email/i), 'wrong@example.com')
+  await user.click(screen.getByRole('button', { name: /login/i }))
   
-  act(() => {
-    result.current.increment();
-  });
-
-  expect(result.current.count).toBe(1);
-});
-
----
-
-## Related Skills
-- **Interactivity & Animation**: `skills/nextjs/interactivity.md`
-- **Performance**: `skills/nextjs/performance.md`
+  expect(await screen.findByText(/invalid credentials/i)).toBeInTheDocument()
+})
+```
+
+## 3. Mocking Next.js Patterns
+
+Next.js 15+ patterns require specific mocking strategies. Admin - Menu Management
+
+- **Navigation**: Mock `useRouter` and `usePathname`.
+- **Server Actions**: Wrap calls in `vi.fn()` to track submissions.
+
+```typescript
+// Setup file or top of test
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({ push: vi.fn() }),
+  usePathname: () => '/home',
+}))
+```
+
+## 4. Automated Testing Protocol for Agents
+
+When requested to build a feature, the agent should:
+1.  **Draft the Logic**: Write the function/hook.
+2.  **Generate the Test**: Immediately create a `.test.ts(x)` file covering edge cases.
+3.  **Run Vitest**: Use `npm test` to verify logic before even building the UI.
+4.  **Connect to UI**: Build the component and add integration tests.
+
+## Best Practices
+1. **Coverage over UI**: prioritize testing complex logic over simple "it renders" tests.
+2. **No implementation details**: Don't test internal state variables; test the output visible to the user.
+3. **Environment**: Ensure `jsdom` is configured in `vitest.config.ts`.
+4. **Clean up**: Use `afterEach(() => cleanup())` to prevent state leakage between tests.

package/skills/nextjs/ux-feedback.md

@@ -0,0 +1,56 @@
+# UX Feedback Patterns
+
+Ensuring the application feels responsive and communicates clearly with the user. A premium app never leaves the user wondering "Is it working?".
+
+## 1. Skeleton Screens
+
+Always prefer skeletons over generic spinners for page transitions. Skeletons should precisely match the layout of the final content.
+
+- **Pulse Animation**: Use a subtle pulse (`animate-pulse`) instead of a fast blink.
+- **Shape Matching**: If it's a circle avatar, the skeleton must be a circle. If it's a 16px title, the skeleton must be 16x100px.
+
+```tsx
+/* Simple Stat Card Skeleton */
+<div className="p-4 rounded-xl border border-border animate-pulse">
+  <div className="h-4 w-24 bg-muted rounded mb-2" />
+  <div className="h-8 w-16 bg-muted-foreground/20 rounded" />
+</div>
+```
+
+## 2. Optimistic UI
+
+For actions that are likely to succeed (like toggling a like button or marking a task as done), update the UI *before* the server responds.
+
+- **Immediate Feedback**: The user sees the change instantly.
+- **Rollback Logic**: If the request fails, revert the UI and show a toast.
+
+> [!NOTE]
+> React's `useOptimistic` hook is the standard for implementing this in Next.js.
+
+## 3. Non-Intrusive Toasts 
+
+Use toasts for feedback on background actions (Save, Delete, Update).
+
+- **Position**: Usually `bottom-right` or `top-center`.
+- **Duration**: `3-5 seconds` is enough for most messages.
+- **Interaction**: Allow users to swipe or click to dismiss early.
+- **Icons**: Always include a small icon (Checkmark for success, Alert for error).
+
+## 4. Empty & Error States
+
+Never show a blank white screen when there's an error or no data.
+
+- **Empty State**: Use an illustration or a clear message + a "Call to Action" (e.g., "No items found. Create your first one?").
+- **Error State**: Provide a clear explanation and a "Retry" button.
+
+## 5. Layout Transitions (Exit/Enter)
+
+Use `<AnimatePresence>` to prevent elements from simply "disappearing" or "popping in."
+
+- **Exit**: Fade out + slide down.
+- **Enter**: Fade in + slide up.
+
+## Best Practices
+1. **Consistency**: Use the same animation durations (e.g., 200ms or 300ms) for all similar transitions.
+2. **Avoid Flash of Unstyled Content (FOUC)**: Use server-side state or Suspense to ensure some content is ready before rendering.
+3. **Progressive Disclosure**: Only show the most important information first; reveal details on interaction to keep the UI clean.