@minhduydev/mdpi 0.4.1 → 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/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