npm - @minhduydev/mdpi - Versions diffs - 0.4.0 → 0.5.0 - Mend

@minhduydev/mdpi 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (48) hide show

package/dist/template/.pi/skills/ui-quality-audit/SKILL.md ADDED Viewed

@@ -0,0 +1,329 @@
+---
+name: ui-quality-audit
+description: 5-dimension UI quality scoring audit — accessibility, performance, theming, responsive, and anti-pattern detection with P0-P3 severity tags
+---
+# UI Quality Audit
+## When to Use
+- Before merging UI changes to production
+- When triaging a backlog of UI issues
+- During design system reviews
+- When retrofitting quality into existing components
+- As a gate check before launching new features
+## When NOT to Use
+- Quick visual review (use `design-system-audit` instead)
+- Non-UI code (backend, APIs, data processing)
+- When the component is not yet implemented (audit after implementation)
+---
+## Severity Levels
+| Level | Label | Action |
+|-------|-------|--------|
+| **P0** | Ship blocker | Do not deploy. Immediate fix required. |
+| **P1** | Must fix this release | Fix before the next production release. |
+| **P2** | Should fix | Fix when time permits. Not blocking. |
+| **P3** | Nice to have | Polish improvement. Low priority. |
+---
+## 5-Dimension Scoring Rubric
+Each dimension is scored 0–4. A score of 0 means critical failures exist. A score of 4 means the dimension is flawless.
+### 1. Accessibility (Weight: High)
+**Focus:** Keyboard navigation, ARIA, color contrast, focus management, semantic HTML.
+| Score | Description |
+|-------|-------------|
+| **4** | Perfect WCAG 2.1 AA compliance. No violations. Keyboard navigable, proper ARIA, 4.5:1+ contrast everywhere. |
+| **3** | Minor issues (P2-P3 only). Most flows accessible. Some ARIA labels could be more descriptive. |
+| **2** | Moderate issues (P1). Some interactive elements not keyboard-accessible. Contrast failures on non-critical text. |
+| **1** | Major issues (P0-P1). Keyboard traps, missing alt text on critical images, form labels missing. |
+| **0** | Critical failures. Page is not navigable by keyboard. No focus indicators. ARIA missing entirely. |
+**P0 checks (ship blockers):**
+- [ ] Keyboard trap exists — user cannot tab through all interactive elements
+- [ ] `outline: none` without `:focus-visible` fallback
+- [ ] Missing form labels on required inputs
+- [ ] Color contrast < 3:1 on any text (P0 if body text, P1 if decorative)
+**P1 checks (must fix this release):**
+- [ ] Color contrast < 4.5:1 but ≥ 3:1
+- [ ] Missing `alt` text on informative images
+- [ ] Missing `aria-label` on icon-only buttons
+- [ ] Skip-to-content link missing
+- [ ] Heading hierarchy skipped (h1 → h3)
+**P2 checks (should fix):**
+- [ ] ARIA labels present but unhelpful (e.g., "button" as label)
+- [ ] Focusable elements in illogical tab order
+- [ ] Missing `lang` attribute on `<html>`
+- [ ] Redundant ARIA on semantic HTML
+**P3 checks (nice to have):**
+- [ ] ARIA live regions missing for dynamic content
+- [ ] Touch targets slightly below 44px (40px-43px)
+---
+### 2. Performance (Weight: High)
+**Focus:** Bundle size, render performance, animation performance, image optimization.
+| Score | Description |
+|-------|-------------|
+| **4** | Lighthouse 90+ in all categories. Images optimized. Bundle < 200KB gzip. No layout shifts. |
+| **3** | Lighthouse 80-89. Minor optimization opportunities. Bundle < 400KB. |
+| **2** | Lighthouse 60-79. Moderate issues. Large images unoptimized. Render-blocking resources. |
+| **1** | Lighthouse < 60. Major issues. Massive bundle. No lazy loading. Layout shifts present. |
+| **0** | Critical failures. Bundle > 1MB. No code splitting. Unoptimized images everywhere. CLS > 0.25. |
+**P0 checks:**
+- [ ] Cumulative Layout Shift (CLS) > 0.25
+- [ ] Largest Contentful Paint (LCP) > 4s
+- [ ] No lazy loading on below-fold images
+- [ ] Bundle size > 1MB (gzip)
+**P1 checks:**
+- [ ] CLS > 0.1
+- [ ] LCP > 2.5s
+- [ ] Images loaded without dimensions (causing reflow)
+- [ ] No code splitting on route boundaries
+- [ ] Unoptimized images (no WebP/AVIF, no responsive sizes)
+**P2 checks:**
+- [ ] Animations running on CPU (not GPU-composited)
+- [ ] Font files > 200KB total
+- [ ] Third-party scripts blocking main thread
+- [ ] Missing `loading="lazy"` on below-fold images
+**P3 checks:**
+- [ ] `will-change` applied permanently
+- [ ] No `preconnect` for critical origins
+- [ ] No `font-display: swap` for web fonts
+---
+### 3. Theming (Weight: Medium)
+**Focus:** Token consistency, dark mode support, color contrast, typography scale.
+| Score | Description |
+|-------|-------------|
+| **4** | Complete design token system. Full dark mode. Consistent spacing/typography/color. OKLCH colors. |
+| **3** | Token system exists with gaps. Dark mode works but misses some surfaces. Mostly consistent. |
+| **2** | Partial token usage. Hardcoded colors/spacing in some places. Dark mode partial or absent. |
+| **1** | Minimal token system. Mostly hardcoded values. No dark mode. Typography scale inconsistent. |
+| **0** | No design tokens. All hardcoded values. No theming system. Arbitrary colors and spacing. |
+**P0 checks:**
+- [ ] Hardcoded colors prevent dark mode entirely
+- [ ] Missing contrast in dark mode — text invisible on dark backgrounds
+**P1 checks:**
+- [ ] Spacing doesn't follow 4pt or 8pt scale — arbitrary values used
+- [ ] More than 1-2 accent colors fighting for attention
+- [ ] Font size scale doesn't follow consistent ratio (1.25x or similar)
+**P2 checks:**
+- [ ] Token naming inconsistent (mix of `--color-primary` and `--blue-500`)
+- [ ] Typography scale gaps — missing sizes for specific use cases
+- [ ] Component uses hardcoded colors outside the token system
+**P3 checks:**
+- [ ] OKLCH not used where color gamut matters
+- [ ] Missing transition on theme switch (`color-scheme` transition)
+---
+### 4. Responsive (Weight: Medium)
+**Focus:** Breakpoint coverage, touch targets, content reflow, viewport configuration.
+| Score | Description |
+|-------|-------------|
+| **4** | Perfect at all breakpoints (320px-2560px). Touch targets 44px+. No horizontal scroll. Content reflows properly. |
+| **3** | Minor issues at edge breakpoints (320px or 2560px). Most views work well. |
+| **2** | Moderate issues. Some pages have horizontal scroll. Touch targets < 44px. Content overlaps at certain widths. |
+| **1** | Major issues. Mobile layout broken. Content cut off. Interactive elements overlap. |
+| **0** | Critical failures. Desktop-only layout. No responsive meta tag. Unusable on mobile. |
+**P0 checks:**
+- [ ] Page unusable at 375px width (content cut off, overlapping)
+- [ ] Missing `<meta name="viewport" content="width=device-width, initial-scale=1">`
+- [ ] Horizontal scroll on main content at standard breakpoints
+**P1 checks:**
+- [ ] Touch targets < 44px on interactive elements
+- [ ] Content does not reflow at 400% zoom (WCAG failure)
+- [ ] Tables not responsive (no horizontal scroll or card conversion)
+**P2 checks:**
+- [ ] Images don't scale down on small viewports
+- [ ] Font sizes too small to read on mobile (< 16px for body)
+- [ ] Gaps/whitespace not adjusted for small screens
+**P3 checks:**
+- [ ] `prefers-reduced-motion` media query missing
+- [ ] `prefers-color-scheme` not respected for dark mode
+- [ ] Print stylesheet missing
+---
+### 5. Anti-Patterns (Weight: Medium)
+**Focus:** AI fingerprints, dead code, over-engineering, inconsistent patterns.
+| Score | Description |
+|-------|-------------|
+| **4** | No AI fingerprints. No dead code. Consistent component patterns. No over-engineering. |
+| **3** | Minor anti-patterns. 1-2 instances of extraneous abstraction or inconsistent naming. |
+| **2** | Moderate. Multiple AI fingerprint patterns. Dead code present. Inconsistent patterns across similar components. |
+| **1** | Major. Pervasive AI-generated patterns. Significant dead code. Architecture is inconsistent. |
+| **0** | Critical. Codebase reads as entirely AI-generated. No coherent patterns. Massive dead code. |
+**P0 checks:**
+- [ ] `div onClick` as button pattern without proper ARIA
+- [ ] Purple/blue gradient hero sections (AI fingerprint)
+- [ ] 3-column identical card pattern (AI fingerprint)
+- [ ] Emojis used instead of icons or text
+**P1 checks:**
+- [ ] Glassmorphism applied without functional purpose
+- [ ] Bounce/elastic easing on UI elements
+- [ ] Inter/Roboto/Arial fonts specified
+- [ ] Dead code or commented-out components in active files
+**P2 checks:**
+- [ ] Over-engineered abstractions (component with 15+ props when 5 would do)
+- [ ] Inconsistent naming conventions (`user-card`, `UserCard`, `user_card`)
+- [ ] Prop drilling through 5+ component levels without context
+- [ ] Unnecessary `useMemo`/`useCallback` wrapping simple values
+**P3 checks:**
+- [ ] Generic placeholder content ("Lorem ipsum", "John Doe", "Acme Corp")
+- [ ] Hardcoded English strings without i18n wrapper
+- [ ] Missing `key` props or using index as key
+---
+## Audit Report Format
+When producing an audit, use this format:
+```markdown
+## UI Quality Audit: [Component/Page]
+### Overall Score: [X]/20 (Average: [X.X]/4)
+| Dimension | Score | P0 | P1 | P2 | P3 |
+|-----------|-------|----|----|----|------|
+| Accessibility | [0-4] | [#] | [#] | [#] | [#] |
+| Performance | [0-4] | [#] | [#] | [#] | [#] |
+| Theming | [0-4] | [#] | [#] | [#] | [#] |
+| Responsive | [0-4] | [#] | [#] | [#] | [#] |
+| Anti-patterns | [0-4] | [#] | [#] | [#] | [#] |
+### Critical (P0)
+1. **[Issue]** — [Component] — [Fix recommendation]
+2. **[Issue]** — [Component] — [Fix recommendation]
+### Must Fix (P1)
+1. ...
+### Should Fix (P2)
+1. ...
+### Nice to Have (P3)
+1. ...
+```
+### Example filled report:
+```markdown
+## UI Quality Audit: UserProfilePage
+### Overall Score: 12/20 (Average: 2.4/4)
+| Dimension | Score | P0 | P1 | P2 | P3 |
+|-----------|-------|----|----|----|------|
+| Accessibility | 2 | 1 | 2 | 1 | 0 |
+| Performance | 3 | 0 | 1 | 1 | 1 |
+| Theming | 4 | 0 | 0 | 0 | 1 |
+| Responsive | 2 | 1 | 1 | 1 | 0 |
+| Anti-patterns | 1 | 1 | 2 | 0 | 1 |
+### Critical (P0)
+1. **[A11y]** Avatar button without label — keyboard users cannot access profile menu.
+   → Add `aria-label="Open profile menu"` to button.
+2. **[Responsive]** Profile table overflows at 375px — horizontal scroll on main content.
+   → Convert table to stacked card layout on mobile.
+### Must Fix (P1)
+1. **[A11y]** Color contrast 3.8:1 on bio text (gray-500 on white).
+   → Use gray-600 instead.
+2. **[Perf]** Avatar image loaded at 800×800, displayed at 40×40.
+   → Add `?w=80&q=75` to image URL or use proper responsive srcset.
+```
+---
+## Audit Workflow
+1. **Scan** — Run all automated checks (axe-core, Lighthouse, bundle analyzer)
+2. **Score** — Fill each dimension using the rubric above
+3. **Tag** — Categorize findings by severity (P0-P3)
+4. **Fix P0** — Address all ship-blockers immediately
+5. **Plan P1** — Schedule remaining must-fix items for this release
+6. **Triage P2-P3** — Decide what to fix vs. backlog
+## Don't
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Keyboard trap — user cannot tab through all elements | Ensure logical tab order with proper focus management | Keyboard trap makes site unusable for non-mouse users |
+| `outline: none` without `:focus-visible` alternative | Custom focus ring via `:focus-visible` | Removing focus breaks keyboard navigation |
+| Color contrast < 3:1 on body text | Darken text to meet minimum 3:1 contrast | Below 3:1 is illegible for low-vision users |
+| CLS > 0.25 (Cumulative Layout Shift) | Reserve space with aspect-ratio containers and fixed dimensions | High CLS degrades Core Web Vitals |
+| No lazy loading on below-fold images | Add `loading="lazy"` to all images below the fold | Eager loading wastes bandwidth and slows page load |
+| Page unusable at 375px width | Implement responsive layout that reflows at all breakpoints | Mobile users are the primary audience |
+| `<div onClick>` as interactive button | Use `<button type="button">` with proper ARIA | div onClick has no keyboard/screen reader semantics |
+| Purple/blue gradient hero sections | Single flat accent or subtle tonal gradient | Purple/blue gradient is the #1 AI generation fingerprint |
+## Verification
+- [ ] Accessibility scored and all P0 items identified
+- [ ] Performance scored with Lighthouse evidence
+- [ ] Theming scored with token audit evidence
+- [ ] Responsive scored with screenshots at 375px, 768px, 1440px
+- [ ] Anti-patterns scored with code review evidence
+- [ ] Audit report generated with all 5 dimensions, severity tags, and fix recommendations
+- [ ] P0 items resolved before merge
+- [ ] P1 items have assigned fix tickets

package/dist/template/.pi/skills/v0/SKILL.md ADDED Viewed

@@ -0,0 +1,264 @@
+---
+name: v0
+description: Use when generating UI with v0 (Vercel's AI-powered generator). Covers prompt engineering, CLI/SDK/MCP integration, shadcn/ui-aware patterns. MUST load before any v0 workflow.
+---
+# v0 — Vercel AI UI Generator
+## Overview
+v0 (v0.app) is Vercel's AI-powered UI and application generator. It generates React components using **shadcn/ui** primitives + **Tailwind CSS**, targeting **Next.js App Router** by default.
+In February 2026, v0 evolved to **v2.0** — a full production development platform. Beyond UI generation, it now supports: importing GitHub repos into sandboxes, git branching/PRs/merging from the browser, database integrations (Snowflake, AWS DBs), enterprise SSO, and agent-based workflows.
+v0 generates "code that looks like a senior frontend engineer wrote it."
+## When to Use
+- Generating shadcn/ui components or pages with AI
+- Writing effective v0 prompts using the 5-block brief
+- Adding v0-generated code to projects via CLI or SDK
+- Integrating v0 with IDEs via MCP (`https://mcp.v0.dev`)
+- Building programmatic UI generation workflows with the v0 SDK
+- Designing brand-aware v0 output via custom shadcn/ui registries
+## When NOT to Use
+- Plain UI without AI generation (use `frontend-design` skill)
+- Backend-only or non-UI tasks
+- When you already have the component and only need manual edits
+## Relationship to Other Skills
+| Skill | Role |
+|-------|------|
+| `shadcn-ui` | Upstream — ensures shadcn/ui is configured correctly before v0 generation |
+| `frontend-design` | Downstream — use for manual refinement of v0 output, design system application |
+| `design-taste-frontend` | Aesthetic baseline applied to v0 generations |
+**Pipeline**: `shadcn-ui` → `v0` → `frontend-design`
+## Prompt Engineering: The 5-Block Component Brief
+Every v0 prompt should include these 5 blocks. Missing blocks = v0 guesses = expensive iterations.
+| # | Block | Question | Example |
+|---|-------|----------|---------|
+| 1 | **What it is** | What component? | "A subscription pricing card for a SaaS dashboard" |
+| 2 | **Behavior** | How does it work? | "Three tiers (Free/Pro/Enterprise), monthly/yearly toggle switches pricing, clicking a tier highlights it" |
+| 3 | **States** | What states? | "Loading spinner while pricing loads, error state if fetch fails, empty state if no tiers returned" |
+| 4 | **Props / Data Shape** | What's the contract? | "`tiers: Tier[]`, `billing: 'monthly' | 'yearly'`, `onSelect: (tier) => void`" |
+| 5 | **Visual Intent** | What should it look like? | "shadcn Card layout, data-first, accent color on recommended tier, generous whitespace, no shadows" |
+### Prompt Patterns
+| Pattern | Example | Why |
+|---------|---------|-----|
+| **Constraint anchoring** | "Use only shadcn/ui primitives and Tailwind classes" | Prevents unknown imports |
+| **Negative instruction** | "Do not use inline styles or external CSS files" | Eliminates anti-patterns |
+| **Type contract** | "Define TypeScript interface for all props first" | Forces explicit API surface |
+| **Responsive breakpoints** | "Mobile-first: stack on sm, 2-col on md, 3-col on lg" | Correct Tailwind prefixes |
+| **State specification** | "Lift filter state to the parent via onFilterChange" | Proper unidirectional data flow |
+| **System context** | "You are generating for Next.js App Router with shadcn/ui Vega style..." | Foundation for consistency |
+### Anti-Patterns in Prompts
+| Anti-Pattern | Fix |
+|-------------|-----|
+| One-word prompt ("Pricing page") | Write a 5-block brief |
+| Generating full pages | Generate component by component, compose pages manually |
+| Hard-coded data | Generate data-less components, wire real data separately |
+| "Make it look like Stripe" | Describe visual intent concretely, not by brand reference |
+| 10+ refinements in one follow-up | 1-2 changes per loop; rewrite brief from scratch if complex |
+| UI-first architecture | Design API/schema first, then generate UI that matches it |
+| Passing API secrets through prompts | Never send secrets through v0 chat |
+## Integration Paths
+### Path A — shadcn CLI Pull (Recommended)
+1. Generate UI on [v0.app](https://v0.app)
+2. Click **"Add to Codebase"** → copy the command:
+   ```bash
+   npx shadcn@latest add "https://v0.dev/chat/b/<project_id>?token=<token>"
+   ```
+3. Run in your project root — pulls component + installs deps
+### Path B — v0 CLI
+```bash
+# One-time setup in existing Next.js project
+npx v0@latest init
+# Add specific generated component by ID
+npx v0@latest add <id>
+```
+The `v0` CLI (v2.2.5) installs deps: `@radix-ui/react-icons`, `clsx`, `lucide-react`.
+### Path C — SDK (Programmatic)
+```bash
+npm install v0-sdk
+```
+```typescript
+import { v0 } from 'v0-sdk'
+const client = v0.createClient({ apiKey: process.env.V0_API_KEY })
+// Create a chat
+const chat = await client.chats.create({
+  message: "Build a pricing card with three tiers and monthly/yearly toggle"
+})
+// Stream the response
+for await (const chunk of chat.stream()) {
+  console.log(chunk)
+}
+// Initialize with existing files
+await client.chats.init({
+  files: [{ path: 'components/ui/button.tsx', content: '...' }]
+})
+```
+### v0 SDK Ecosystem
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `v0-sdk` | 0.16.4 | Core TypeScript SDK — chats, projects, deployments |
+| `@v0-sdk/react` | 0.5.0 | Headless React components for v0 content |
+| `@v0-sdk/ai-tools` | 0.3.8 | AI SDK tools for agents (~20 tools) |
+| `create-v0-sdk-app` | 0.2.1 | Scaffold SDK-powered apps |
+### Path D — MCP Server
+Connect IDEs to v0 via MCP:
+```json
+{
+  "mcpServers": {
+    "v0": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://mcp.v0.dev", "--header", "Authorization: Bearer ${V0_API_KEY}"]
+    }
+  }
+}
+```
+Supports: Cursor, Claude Desktop, VS Code, Windsurf, any MCP-compatible IDE.
+## Platform API (Public Beta)
+REST API at `https://api.v0.dev/v1`. Covers: chats, projects, deployments, users, webhooks, MCP servers.
+```typescript
+// Direct REST
+const res = await fetch('https://api.v0.dev/v1/chats', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${process.env.V0_API_KEY}`,
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    message: "Build a login form with email/password fields"
+  })
+})
+```
+## Integration with shadcn/ui
+v0 generates code using shadcn/ui by default. Key integration points:
+- **Before generating**: Run `npx shadcn init` in your project
+- **Custom design systems**: Publish a shadcn/ui Registry with your design tokens → v0 generates brand-consistent output
+- **Registry MCP**: Connect your registry to v0 for design-aware generation
+- **`components.json`**: v0 respects your project's aliases and style config
+- **Check deps**: After pulling v0 code, verify all shadcn components are installed
+### Design System Integration
+```json
+// components.json — exposed to v0 for brand-aware generation
+{
+  "style": "vega",
+  "tsx": true,
+  "tailwind": { "cssVariables": true },
+  "aliases": { "components": "@/components", "ui": "@/components/ui" }
+}
+```
+## v0 2.0 Platform (Feb 2026)
+Key capabilities beyond UI generation:
+- **Import any GitHub repo** into sandbox with auto-pulled Vercel env vars
+- **Git panel** — branching, PRs, merging from the browser
+- **DB integrations** — Snowflake, AWS databases, Neon + Drizzle scaffolding
+- **Enterprise** — deployment protection, access controls, SSO, signed Git commits
+- **Agents** — plan and build end-to-end agentic workflows
+- **Design Mode** — floating toolbar, layers viewer, measure overlay
+- **Cmd+K** — command palette navigation
+- **Shopify integration** — storefront building
+- **Auto merge conflict resolution**
+## Best Patterns
+### Component-First Decomposition
+Instead of: "Build a dashboard page"
+Do:
+1. Generate `StatCard` → pull → verify
+2. Generate `DataTable` → pull → verify
+3. Generate `ChartWidget` → pull → verify
+4. Compose in the page manually
+### System Prompt Template
+When using the SDK or Platform API, set a system prompt:
+```
+You are a shadcn/ui component generator.
+Framework: Next.js 15+ App Router.
+Language: TypeScript strict mode.
+Styling: Tailwind CSS v4 with CSS variables.
+Imports: use @/ path alias.
+Data: accept via props, never hard-code.
+States: loading, empty, error, normal.
+Accessibility: ARIA labels, keyboard nav, focus management.
+Dark mode: CSS variable overrides.
+```
+### v0 → Production Workflow
+1. **Spec** → Define data model, user flow, design tokens
+2. **Generate** → v0 with 5-block brief for each component
+3. **Pull** → Add to codebase via CLI
+4. **Review** → Check TypeScript types, accessibility, theme compliance
+5. **Wire** → Connect real data sources, auth, API routes
+6. **Harden** → Loading states, error boundaries, edge cases
+7. **Deploy** → Vercel preview + production
+## Common Pitfalls
+| Pitfall | Fix |
+|---------|-----|
+| Treating v0 output as production-ready | v0 handles presentation only — you need auth, data, logic |
+| Letting v0 define your data model | Your domain expertise defines the model; v0 adapts |
+| Client-only generation | Plan SSR boundaries; v0 generates client components by default |
+| Not checking shadcn deps before pulling | `npx shadcn info --json` to verify installed components |
+| Generating without design tokens | Set system prompt with CSS variable references |
+| Skipping review | Every v0 component needs human review for correctness |
+## Verification
+- [ ] Generated components use project design tokens (CSS variables, not hard-coded hex)
+- [ ] All components accept typed props (no hard-coded data)
+- [ ] Loading, empty, error states handled
+- [ ] Required shadcn/ui primitives installed (`npx shadcn info --json`)
+- [ ] TypeScript compiles without errors
+- [ ] Keyboard navigation and ARIA labels verified
+- [ ] Light and dark mode both render correctly
+- [ ] Components refactored for reusability (not page-specific)