@minhduydev/mdpi 0.4.0 → 0.5.0

package/dist/template/.pi/skills/frontend-design/references/shadcn/setup.md

@@ -1,56 +1,161 @@
 # shadcn/ui Setup
 
-CLI v3.6.x (current: v3.6.3) - Copy-paste components, Radix UI + Tailwind v4.
+CLI v4.x (current: shadcn@4.11.0) — Copy-paste components, Radix UI / Base UI + Tailwind v4.
 
-## New Project
+## Create a New Project
 
 ```bash
 npx shadcn create
 ```
 
 Interactive setup:
-- Visual style: Vega, Nova, Maia, Lyra, Mira
-- Component library: Radix UI or Base UI
-- Icon library (including Phosphor)
-- Next.js 16 support
+- **Visual style**: Vega, Nova, Maia, Lyra, Mira
+- **Component library**: Radix UI or Base UI
+- **Icon library** (Lucide, Phosphor, etc.)
+- **Next.js 16**, Vite, Laravel, React Router, Astro, TanStack Start support
+- **Template scaffolding** via `npx shadcn init --template`
 
 ## Existing Project
 
 ```bash
-npx shadcn@latest init
+npx shadcn@latest init --preset <code>
 npx shadcn@latest add button card dialog
 npx shadcn@latest add --all
+npx shadcn@latest add <username>/<repo>/<item>  # GitHub Registry
 ```
 
 Components install to `components/ui/`.
 
+## Key CLI v4 Commands
+
+```bash
+# Inspection
+npx shadcn info                     # Full project config (for agent context)
+npx shadcn info --json              # JSON output for programmatic use
+npx shadcn docs <component>         # Docs, code, examples from CLI
+
+# Preview changes before writing
+npx shadcn add button --dry-run     # Show what will be installed
+npx shadcn add button --diff        # Show diff against current
+npx shadcn add button --view        # Open component in browser
+
+# Project setup flags
+npx shadcn init --preset a1Dg5eFl    # Pack entire design system into short code
+npx shadcn init --template           # Scaffold project templates
+npx shadcn init --monorepo           # Monorepo setup
+npx shadcn init --base radix         # Choose primitives (radix | base)
+
+# Skills (AI Agent)
+npx skills add shadcn/ui             # Install agent prompt file
+npx shadcn skills generate           # Regenerate after adding components
+npx shadcn skills update             # Update monthly
+```
+
 ## Visual Styles
 
-| Style | Description |
-|-------|-------------|
-| **Vega** | Classic shadcn look |
-| **Nova** | Reduced padding, compact |
-| **Maia** | Soft, rounded, generous |
-| **Lyra** | Boxy, sharp, mono fonts |
-| **Mira** | Compact, dense interfaces |
+| Style | Characteristics |
+|-------|----------------|
+| **Vega** | Classic shadcn look — balanced, versatile |
+| **Nova** | Reduced padding, compact, space-efficient |
+| **Maia** | Soft, rounded corners, generous spacing |
+| **Lyra** | Boxy, sharp corners, monospace fonts |
+| **Mira** | Compact, dense, data-heavy interfaces |
+
+Styles rewrite component code, not just CSS — fonts, spacing, structure, primitives all adapt.
+
+## Presets
+
+Presets pack the entire design system into a reproducible short code:
+
+```bash
+# Export your preset
+npx shadcn preset export
+
+# Init a project with a preset
+npx shadcn init --preset a1Dg5eFl
+```
+
+A preset includes: colors, theme, icons, fonts, radius, spacing — everything in one code.
 
 ## Component Libraries
 
-- **Radix UI** (default): Full accessibility, React-only
-- **Base UI**: MUI unstyled components
+- **Radix UI** (default): Full accessibility, React-only, battle-tested
+- **Base UI**: MUI unstyled components, headless
+
+Select during `npx shadcn create` or with `--base` flag. CLI auto-detects your library when pulling components.
+
+## GitHub Registries (June 2026)
+
+Any public GitHub repo with a `registry.json` can be a component registry:
 
-Select during `npx shadcn create` or in `components.json`.
+```bash
+npx shadcn@latest add <username>/<repo>/<item>
+```
+
+Distribute: components, hooks, utilities, design tokens, feature kits, project conventions, CI workflows, templates. No build step — CLI reads `registry.json` directly.
+
+```json
+// registry.json (in any GitHub repo)
+{
+  "name": "my-components",
+  "items": [
+    {
+      "name": "data-table",
+      "type": "registry:component",
+      "files": [{ "path": "components/data-table.tsx" }]
+    }
+  ]
+}
+```
+
+## shadcn/skills — AI Agent Bridge
+
+```bash
+npx skills add shadcn/ui
+```
+
+Creates `.shadcn/skills.md` — a machine-readable file that gives AI coding agents project-aware context:
+
+- **Project context** — framework, aliases, installed components, icon library, base library (via `shadcn info --json`)
+- **CLI command reference** — all flags, smart merge, presets, templates
+- **Theming guidance** — CSS vars, OKLCH, dark mode, Tailwind v3/v4
+- **Registry authoring** — `registry.json` format
+- **Pattern enforcement** — FieldGroup for forms, ToggleGroup for options, semantic colors
+
+**Measured impact**: API errors 34% → 3%, correct variants 61% → 98%, first-try success 45% → 89%.
+
+**Critical workflows**:
+- Re-generate after adding components: `npx shadcn skills generate`
+- Update monthly: `npx shadcn skills update`
+- Reference file path (don't paste into context — 4K cutoff)
 
 ## MCP Server Support
 
-- OpenCode MCP (v3.6.3)
-- Codex MCP (v3.4.0)
+Connect AI editors to your registry:
+
+```json
+{
+  "mcpServers": {
+    "shadcn": {
+      "command": "npx",
+      "args": ["-y", "shadcn@canary", "registry:mcp"],
+      "env": {
+        "REGISTRY_URL": "https://your-registry.vercel.app/r/registry.json"
+      }
+    }
+  }
+}
+```
+
+Also: OpenCode MCP (v3.6.3), Codex MCP (v3.4.0).
 
 ## Registry System
 
 - Registry Directory: https://ui.shadcn.com/docs/directory
 - Custom registries via `components.json`
 - Namespaced components
+- `registry:base` — distribute entire design systems
+- `registry:font` — distribute font packages
 
 ## Component List
 
@@ -66,4 +171,6 @@ Select during `npx shadcn create` or in `components.json`.
 
 **Overlay**: Dropdown Menu, Context Menu, Popover, Collapsible
 
-**Other**: Toggle, Toggle Group, Kbd, Button Group, Item, Empty, Input OTP
+**2026 New**: Spinner, Kbd, KbdGroup, Button Group, Input Group, Field, Item, Empty, Input OTP
+
+**Other**: Toggle, Toggle Group

package/dist/template/.pi/skills/frontend-ui-engineering/SKILL.md

@@ -30,14 +30,15 @@ This skill composes with others for a complete frontend quality pipeline:
 
 | Skill | Relationship | When to combine |
 |-------|-------------|-----------------|
-| `frontend-design` | Sibling | `frontend-design` covers general UI patterns with React. `frontend-ui-engineering` adds production-quality standards (accessibility, AI-aesthetic avoidance). Load both for serious UI work. |
-| `design-taste-frontend` | Upstream | Apply design-taste rules FIRST to establish the aesthetic baseline. Then use `frontend-ui-engineering` for implementation quality. |
+| `design-taste-frontend` | Upstream | Apply aesthetic baseline FIRST. Then use `frontend-ui-engineering` for implementation quality. |
+| `frontend-design` | Upstream | `frontend-design` covers design system + tokens. `frontend-ui-engineering` adds component implementation patterns. |
 | `react-best-practices` | Complement | Load when building React/Next.js components — covers performance-specific patterns (memo, useMemo, server components). |
-| `accessibility-audit` | Gate | After building UI, run `accessibility-audit` to verify WCAG 2.1 AA compliance. |
+| `baseline-ui` | Upstream | Quick deslop pass before implementation — fixes spacing, typography, layout basics automatically. |
+| `fixing-accessibility` | Gate | After building UI, run `fixing-accessibility` for actionable WCAG 2.1 AA fixes. |
 | `performance-optimization` | Gate | After UI is working, profile with `performance-optimization` for Core Web Vitals. |
-| `mockup-to-code` | Upstream | If converting from Figma/mockup, run `mockup-to-code` first, then refine with `frontend-ui-engineering`. |
+| `ui-craft-principles` | Complement | Apply 16 craft principles (concentric radius, optical alignment, etc.) for polish. |
 
-**Pipeline:** `design-taste-frontend` → `frontend-ui-engineering` → `accessibility-audit` + `performance-optimization`
+**Pipeline:** `design-taste-frontend` → `frontend-design` → `frontend-ui-engineering` → `fixing-accessibility` + `performance-optimization`
 
 ## Component Architecture
 
@@ -102,11 +103,11 @@ Global store (Zustand, Redux)    → Complex client state shared app-wide
 
 ## Design System Adherence
 
-### Avoid the AI Aesthetic
+### Avoid Common Visual Anti-Patterns
 
-AI-generated UI has recognizable patterns. Avoid all of them:
+These patterns degrade implementation quality. For design-level aesthetic rules, see `design-taste-frontend`.
 
-| AI Default | Production Quality |
+| Degraded Pattern | Production Quality |
 |---|---|
 | Purple/indigo everything | Use the project's actual color palette |
 | Excessive gradients | Flat or subtle gradients matching the design system |
@@ -185,29 +186,20 @@ Test at: 320px, 768px, 1024px, 1440px.
 - `aria-busy="true"` on loading regions
 - Avoid layout shifts during loading (reserve space)
 
-## Common Rationalizations
+## Don't
 
-| Rationalization | Reality |
-|---|---|
-| "Accessibility is a nice-to-have" | It's a legal requirement in many jurisdictions and an engineering quality standard. |
-| "We'll make it responsive later" | Retrofitting responsive design is 3x harder than building it from the start. |
-| "The design isn't final, so I'll skip styling" | Use the design system defaults. Unstyled UI creates a broken first impression. |
-| "This is just a prototype" | Prototypes become production code. Build the foundation right. |
-| "The AI aesthetic is fine for now" | It signals low quality. Use the project's actual design system from the start. |
-
-## Red Flags
-
-- Components with more than 200 lines (split them)
-- Inline styles or arbitrary pixel values
-- Missing error states, loading states, or empty states
-- No keyboard navigation testing
-- Color as the sole indicator of state (red/green without text or icons)
-- Generic "AI look" (purple gradients, oversized cards, stock layouts)
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Components over 200 lines | Split into smaller focused sub-components | Large components violate single responsibility |
+| Inline styles or arbitrary pixel values | Use design tokens and consistent spacing scale | Inline styles are not maintainable |
+| Missing error, loading, or empty states | Handle all 4 data states (loading, empty, error, normal) | Users see blank screens without complete state handling |
+| Color as sole indicator of state | Add text labels or icons alongside color | Color-only cues are inaccessible to colorblind users |
+| `<div onClick>` instead of `<button>` | Use `<button type="button">` with proper styling | div onClick has no keyboard or screen reader semantics |
+| Prop drilling deeper than 3 levels | Use context, composition, or state management | Deep prop drilling couples components unnecessarily |
+| Skipping heading levels (h1 → h3) | Maintain sequential hierarchy (h1 → h2 → h3) | Skipped levels break screen reader page navigation |
 
 ## Verification
 
-After building UI:
-
 - [ ] Component renders without console errors
 - [ ] All interactive elements are keyboard accessible (Tab through the page)
 - [ ] Screen reader can convey the page's content and structure
@@ -215,3 +207,5 @@ After building UI:
 - [ ] Loading, error, and empty states all handled
 - [ ] Follows the project's design system (spacing, colors, typography)
 - [ ] No accessibility warnings in dev tools or axe-core
+- [ ] No `<div onClick>` as button replacement — all interactive elements use semantic HTML
+- [ ] Components < 200 lines; larger components split into sub-components

package/dist/template/.pi/skills/nextjs-app-router/SKILL.md

@@ -0,0 +1,334 @@
+---
+name: nextjs-app-router
+description: Use when building or refactoring Next.js App Router pages. Covers file conventions, layouts vs templates, parallel/intercepting routes, route groups, async params, streaming, RSC boundaries. MUST load before any App Router architecture work.
+---
+
+# Next.js App Router Patterns (Next.js 15+)
+
+## When to Use
+
+- Building new pages in Next.js App Router
+- Understanding or refactoring App Router file conventions
+- Designing route architecture (parallel routes, intercepting, groups)
+- Setting up layouts, error boundaries, and loading states
+- Making decisions about Server vs Client Components
+
+## When NOT to Use
+
+- Pages Router projects (`pages/` directory — use `react-best-practices`)
+- Non-Next.js React projects (Vite, Remix, React Router)
+- Pure API routes (not page structure)
+
+## File Conventions Reference
+
+| File | Purpose | Runs |
+|------|---------|------|
+| `page.tsx` | Route's unique UI | Server (default) |
+| `layout.tsx` | Shared UI that persists across navigations | Server (default) |
+| `template.tsx` | Shared UI that remounts on navigation | Server (default) |
+| `loading.tsx` | Suspense fallback while page loads | Server (default) |
+| `error.tsx` | Error boundary for the segment | Client |
+| `not-found.tsx` | 404 UI for the segment | Server (default) |
+| `default.tsx` | Fallback for parallel routes | Server (default) |
+| `route.tsx` | API endpoint for the segment | Server |
+
+## Layout vs Template
+
+**Layout**: persists across navigations, state preserved.
+
+```tsx
+// app/dashboard/layout.tsx
+export default function DashboardLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div>
+      <nav>Sidebar — stays mounted</nav>
+      <main>{children}</main>
+    </div>
+  )
+}
+```
+
+**Template**: remounts on every navigation. Use when you need:
+- Page transitions (AnimatePresence needs remount)
+- `useEffect` that must re-run on navigation
+- Resetting client state between pages
+
+```tsx
+// app/dashboard/template.tsx
+'use client'
+
+import { AnimatePresence, motion } from 'motion/react'
+
+export default function Template({ children }: { children: React.ReactNode }) {
+  return (
+    <AnimatePresence mode="wait">
+      <motion.div
+        key={usePathname()}
+        initial={{ opacity: 0 }}
+        animate={{ opacity: 1 }}
+        exit={{ opacity: 0 }}
+      >
+        {children}
+      </motion.div>
+    </AnimatePresence>
+  )
+}
+```
+
+**Rule**: Layout wraps Template wraps Page: `layout.tsx > template.tsx > page.tsx`
+
+## Route Groups — `(group)/`
+
+Use parentheses to group routes without affecting the URL:
+
+```
+app/
+├── (marketing)/
+│   ├── page.tsx          → /
+│   ├── about/page.tsx    → /about
+│   └── layout.tsx        # Marketing layout
+├── (dashboard)/
+│   ├── dashboard/page.tsx  → /dashboard
+│   └── layout.tsx          # Dashboard layout (different from marketing)
+```
+
+## Parallel Routes — `@folder/`
+
+Render multiple pages in the same layout simultaneously:
+
+```
+app/
+├── dashboard/
+│   ├── layout.tsx        # Accepts both props:
+│   ├── @analytics/       #   children, analytics, team
+│   │   └── page.tsx
+│   ├── @team/
+│   │   └── page.tsx
+│   └── page.tsx          # Default children
+```
+
+```tsx
+// app/dashboard/layout.tsx
+export default function DashboardLayout(props: {
+  children: React.ReactNode
+  analytics: React.ReactNode
+  team: React.ReactNode
+}) {
+  return (
+    <div className="grid grid-cols-2">
+      <div>{props.children}</div>
+      <div>{props.analytics}</div>
+      <div>{props.team}</div>
+    </div>
+  )
+}
+```
+
+Each slot needs a `default.tsx` for initial load and unmatched routes.
+
+## Intercepting Routes — `(.)folder/`
+
+Render a route in the context of another without full navigation:
+
+| Convention | Meaning |
+|-----------|---------|
+| `(.)folder/` | Same level |
+| `(..)folder/` | One level up |
+| `(..)(..)folder/` | Two levels up |
+| `(...)folder/` | From root |
+
+Common pattern: Photo modal:
+
+```
+app/
+├── photos/
+│   ├── page.tsx              # Photos grid: /
+│   └── [id]/
+│       └── page.tsx          # Photo detail: /photos/1
+└── @modal/
+    ├── default.tsx           # null return
+    └── (.)photos/
+        └── [id]/
+            └── page.tsx      # Modal overlay when navigating from photos grid
+```
+
+```tsx
+// app/layout.tsx
+export default function RootLayout({ children, modal }) {
+  return (
+    <>
+      {children}
+      {modal}
+    </>
+  )
+}
+```
+
+## Async Server Components
+
+```tsx
+// app/posts/[id]/page.tsx — no 'use client'
+export default async function PostPage({
+  params,
+}: {
+  params: Promise<{ id: string }>  // params is a Promise in Next.js 15+
+}) {
+  const { id } = await params
+  const post = await db.post.findUnique({ where: { id } })
+
+  return <article>{post.content}</article>
+}
+```
+
+**Next.js 15+**: `params`, `searchParams` are Promises — must `await` them.
+
+## Streaming with Suspense + loading.tsx
+
+```tsx
+// app/posts/page.tsx
+import { Suspense } from 'react'
+
+export default function PostsPage() {
+  return (
+    <div>
+      <h1>Posts</h1>
+      <Suspense fallback={<PostsSkeleton />}>
+        <PostsList />  {/* Streams in when ready */}
+      </Suspense>
+      <Suspense fallback={<StatsSkeleton />}>
+        <PostStats />  {/* Streams independently */}
+      </Suspense>
+    </div>
+  )
+}
+```
+
+- `loading.tsx` wraps the entire page in Suspense automatically
+- Manual `<Suspense>` gives finer control — stream sections independently
+- Wrap data-fetching Server Components in Suspense
+
+## RSC Boundary Rules
+
+```
+Server Component (default)
+  └─ can render → Client Components
+  └─ can pass → serializable props only (no functions, no JSX as props)
+  └─ can use → async/await, direct DB access, filesystem, secrets
+
+Client Component ('use client')
+  └─ can render → Server Components (passed as children)
+  └─ can use → hooks, event handlers, browser APIs, state
+  └─ cannot → async/await directly, access DB
+```
+
+**Boundary pattern** — push 'use client' as deep as possible:
+
+```tsx
+// ✅ Server Component (default) — data fetching here
+export default async function UserProfile({ userId }) {
+  const user = await db.user.findUnique({ where: { id: userId } })
+
+  return (
+    <div>
+      <h1>{user.name}</h1>
+      <EditButton />  {/* Only the interactive leaf is client */}
+    </div>
+  )
+}
+
+// ✅ Client leaf — only what needs interactivity
+'use client'
+function EditButton() {
+  const [open, setOpen] = useState(false)
+  return <button onClick={() => setOpen(true)}>Edit</button>
+}
+```
+
+## Error Handling
+
+```tsx
+// app/dashboard/error.tsx
+'use client'
+
+export default function DashboardError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string }
+  reset: () => void
+}) {
+  return (
+    <div>
+      <h2>Something went wrong!</h2>
+      <button onClick={() => reset()}>Try again</button>
+    </div>
+  )
+}
+```
+
+- `error.tsx` must be a Client Component
+- Errors bubble up to the nearest `error.tsx`
+- `reset()` re-renders the error boundary's children
+- `error.tsx` in a nested segment only catches errors in that segment and below
+
+## Middleware
+
+```tsx
+// middleware.ts (root level)
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get('token')
+
+  // Protect routes
+  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
+    return NextResponse.redirect(new URL('/login', request.url))
+  }
+
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*']
+}
+```
+
+## Metadata API
+
+```tsx
+// Static metadata
+export const metadata: Metadata = {
+  title: 'Dashboard',
+  description: 'Manage your account',
+}
+
+// Dynamic metadata (Server Components)
+export async function generateMetadata({ params }): Promise<Metadata> {
+  const post = await getPost(params.id)
+  return { title: post.title, description: post.excerpt }
+}
+```
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| Adding `'use client'` to a layout | Layouts are Server Components by default; only add `'use client'` when you need hooks |
+| Forgetting `default.tsx` for parallel routes | Every slot needs a `default.tsx` for initial load |
+| Passing functions as props from Server to Client | Functions are not serializable — define them in the client |
+| Using `useSearchParams()` in Server Component | Use `searchParams` prop (Promise in v15+) |
+| `params` treated as plain object (v15+) | `params` is now a Promise — must `await params` |
+| No Suspense boundary for async component | Wrap in `<Suspense>` or ensure `loading.tsx` exists |
+| `layout.tsx` doesn't receive `searchParams` | Only `page.tsx` gets `searchParams` |
+
+## Verification
+
+- [ ] Server Components are the default — `'use client'` only where interactive
+- [ ] `params` and `searchParams` are awaited (Next.js 15+)
+- [ ] Error boundaries (`error.tsx`) exist at appropriate levels
+- [ ] Loading states (`loading.tsx` or `<Suspense>`) for async pages
+- [ ] Parallel route slots each have `default.tsx`
+- [ ] Layout and template used correctly (persist vs remount)
+- [ ] Route groups used to share layouts without affecting URL
+- [ ] Functions and non-serializable data stay in Client Components