@minhduydev/mdpi 0.3.0

package/dist/template/.pi/skills/frontend-design/references/tailwind/utilities-styling.md

@@ -0,0 +1,165 @@
+# Tailwind Styling Utilities
+
+Spacing, typography, colors, borders, shadows, transforms.
+
+## Spacing
+
+### Padding
+```html
+<div class="p-4">All</div>
+<div class="px-6">X axis</div>
+<div class="py-3">Y axis</div>
+<div class="pt-8 pr-4 pb-2 pl-6">Individual</div>
+```
+
+### Margin
+```html
+<div class="m-4">All</div>
+<div class="mx-auto">Center</div>
+<div class="my-6">Y axis</div>
+<div class="-mt-4">Negative</div>
+<div class="ml-auto">Push right</div>
+```
+
+### Scale
+```
+0=0px, px=1px, 0.5=2px, 1=4px, 2=8px, 3=12px, 4=16px
+6=24px, 8=32px, 12=48px, 16=64px, 24=96px
+v4: Any value: mt-17, px-29
+```
+
+## Typography
+
+```html
+<!-- Size -->
+<p class="text-xs">12px</p>
+<p class="text-sm">14px</p>
+<p class="text-base">16px</p>
+<p class="text-lg">18px</p>
+<p class="text-xl">20px</p>
+<p class="text-2xl">24px</p>
+<p class="text-4xl">36px</p>
+
+<!-- Weight -->
+<p class="font-light">300</p>
+<p class="font-normal">400</p>
+<p class="font-medium">500</p>
+<p class="font-semibold">600</p>
+<p class="font-bold">700</p>
+
+<!-- Line height -->
+<p class="leading-tight">1.25</p>
+<p class="leading-normal">1.5</p>
+<h1 class="text-4xl/tight">Combined</h1>
+
+<!-- Transform -->
+<p class="uppercase">UPPER</p>
+<p class="lowercase">lower</p>
+<p class="capitalize">Cap</p>
+
+<!-- Decoration -->
+<p class="underline">Underline</p>
+<p class="line-through">Strike</p>
+
+<!-- Overflow -->
+<p class="truncate">Truncate...</p>
+<p class="line-clamp-3">Clamp 3</p>
+```
+
+## Colors
+
+```html
+<!-- Text -->
+<p class="text-black">Black</p>
+<p class="text-gray-500">Gray</p>
+<p class="text-primary">CSS var</p>
+<p class="text-muted-foreground">Muted</p>
+
+<!-- Background -->
+<div class="bg-white">White</div>
+<div class="bg-blue-500">Blue</div>
+<div class="bg-background">CSS var</div>
+
+<!-- Opacity modifier -->
+<div class="bg-black/75">75%</div>
+<div class="text-blue-500/50">50%</div>
+```
+
+## Gradients
+
+```html
+<div class="bg-linear-to-r from-blue-500 to-purple-600">Linear</div>
+<div class="bg-linear-45 from-pink-500 to-yellow-500">Angle (v4)</div>
+<div class="bg-linear-to-br from-pink-500 via-red-500 to-yellow-500">Via</div>
+<div class="bg-linear-to-r/oklch from-indigo-500 to-teal-400">OKLCH (v4)</div>
+```
+
+## Borders
+
+```html
+<!-- Width -->
+<div class="border">1px all</div>
+<div class="border-2">2px all</div>
+<div class="border-t">Top only</div>
+
+<!-- Color -->
+<div class="border border-gray-300">Gray</div>
+<div class="border border-border">CSS var</div>
+
+<!-- Radius -->
+<div class="rounded">0.25rem</div>
+<div class="rounded-lg">0.5rem</div>
+<div class="rounded-full">Pill</div>
+<div class="rounded-t-lg">Top only</div>
+```
+
+## Shadows
+
+```html
+<div class="shadow-sm">Small</div>
+<div class="shadow">Default</div>
+<div class="shadow-lg">Large</div>
+<div class="shadow-xl">XL</div>
+<div class="shadow-lg shadow-blue-500/50">Colored</div>
+<div class="inset-shadow-sm">Inset (v4)</div>
+```
+
+## Transforms
+
+```html
+<div class="scale-105">Scale</div>
+<div class="rotate-45">Rotate</div>
+<div class="translate-x-4">Move</div>
+
+<!-- 3D (v4) -->
+<div class="rotate-x-45">X</div>
+<div class="rotate-y-30">Y</div>
+<div class="perspective-distant">Perspective</div>
+```
+
+## Transitions
+
+```html
+<div class="transition-all">All</div>
+<div class="transition-colors">Colors</div>
+<div class="transition-transform">Transform</div>
+<div class="duration-300">300ms</div>
+<div class="ease-in-out">Easing</div>
+```
+
+## Other
+
+```html
+<div class="opacity-50">50%</div>
+<div class="cursor-pointer">Pointer</div>
+<div class="select-none">No select</div>
+```
+
+## Arbitrary Values
+
+```html
+<div class="p-[17px]">Custom</div>
+<div class="bg-[#bada55]">Hex</div>
+<div class="w-[calc(100%-2rem)]">Calc</div>
+<div class="grid-cols-[1fr_500px_2fr]">Grid</div>
+```

package/dist/template/.pi/skills/frontend-design/references/tailwind/v4-config.md

@@ -0,0 +1,147 @@
+# Tailwind CSS v4 Configuration
+
+v4.1.x (current: v4.1.18) - CSS-first config, no tailwind.config.js needed.
+
+## Installation
+
+### Vite (Recommended)
+```bash
+npm i tailwindcss @tailwindcss/vite
+```
+
+```ts
+// vite.config.ts
+import tailwindcss from "@tailwindcss/vite"
+export default { plugins: [tailwindcss()] }
+```
+
+```css
+/* src/index.css */
+@import "tailwindcss";
+```
+
+### PostCSS
+```bash
+npm i tailwindcss @tailwindcss/postcss
+```
+
+```js
+// postcss.config.js
+export default { plugins: ["@tailwindcss/postcss"] }
+```
+
+## CSS-First Configuration
+
+Configure in CSS with `@theme`:
+
+```css
+@import "tailwindcss";
+
+@theme {
+  /* OKLCH colors for vivid, wide-gamut */
+  --color-brand-50: oklch(0.97 0.02 264);
+  --color-brand-500: oklch(0.55 0.22 264);
+  --color-brand-900: oklch(0.25 0.15 264);
+
+  /* Fonts */
+  --font-display: "Satoshi", sans-serif;
+  --font-body: "Inter", system-ui, sans-serif;
+
+  /* Spacing, breakpoints, easing */
+  --spacing-18: calc(var(--spacing) * 18);
+  --breakpoint-3xl: 1920px;
+  --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
+
+  /* Shadows */
+  --shadow-glow: 0 0 20px oklch(0.55 0.22 264 / 0.3);
+}
+```
+
+Usage: `<div class="bg-brand-500 font-display shadow-glow">`
+
+## Key v4 Changes from v3
+
+| v3 | v4 |
+|----|-----|
+| `@tailwind base/components/utilities` | `@import "tailwindcss"` |
+| `tailwind.config.js` | `@theme` directive |
+| `content: [...]` array | Automatic detection |
+| sRGB colors | OKLCH/P3 colors |
+| `bg-opacity-50` | `bg-black/50` modifier |
+| Plugin for container queries | Built-in `@container` |
+
+## Automatic Content Detection
+
+No `content` array. Auto-ignores `.gitignore` and binary files.
+
+Add sources manually if needed:
+```css
+@source "../node_modules/@my-company/ui-lib";
+```
+
+## Dynamic Values
+
+Any value works without config:
+```html
+<div class="grid grid-cols-15">
+<div class="mt-17 px-29">
+<div data-active class="data-active:bg-blue-500">
+```
+
+## OKLCH Colors
+
+Wider gamut, more vivid:
+```css
+@theme {
+  --color-primary-50: oklch(0.98 0.02 250);
+  --color-primary-500: oklch(0.65 0.22 250);
+  --color-primary-900: oklch(0.25 0.15 250);
+}
+```
+
+Opacity modifier: `<div class="bg-primary-500/50">`
+
+## Custom Utilities & Variants
+
+```css
+@utility glass {
+  background: oklch(1 0 0 / 0.1);
+  backdrop-filter: blur(10px);
+  border: 1px solid oklch(1 0 0 / 0.2);
+}
+
+@custom-variant theme-dark (&:where([data-theme="dark"] *));
+```
+
+## Layer Organization
+
+```css
+@layer base { h1 { @apply text-4xl font-bold; } }
+@layer components { .btn { @apply px-4 py-2 rounded-lg; } }
+@layer utilities { .text-balance { text-wrap: balance; } }
+```
+
+## Dark Mode
+
+Class strategy by default:
+```html
+<html class="dark">
+  <div class="bg-white dark:bg-zinc-900">
+```
+
+## Migration from v3
+
+```bash
+npx @tailwindcss/upgrade
+```
+
+- Move `tailwind.config.js` to `@theme`
+- Replace `@tailwind` with `@import "tailwindcss"`
+- Remove `content` array
+- Replace `bg-opacity-*` with `/opacity` modifier
+
+## Performance
+
+- Full builds: 3.5x+ faster
+- Incremental: 8x+ faster
+- No-new-CSS: 100x+ faster (microseconds)

package/dist/template/.pi/skills/frontend-design/references/tailwind/v4-features.md

@@ -0,0 +1,128 @@
+# Tailwind CSS v4 New Features
+
+v4/v4.1 additions: gradients, 3D transforms, masks, text shadows, new variants.
+
+## Container Queries (Built-in)
+
+No plugin needed:
+```html
+<div class="@container">
+  <div class="grid grid-cols-1 @sm:grid-cols-2 @lg:grid-cols-4">
+</div>
+
+<!-- Max-width -->
+<div class="grid-cols-3 @max-md:grid-cols-1">
+
+<!-- Range -->
+<div class="@min-md:@max-xl:hidden">
+```
+
+## Gradients
+
+```html
+<!-- Angle-based -->
+<div class="bg-linear-45 from-indigo-500 to-pink-500">
+
+<!-- OKLCH interpolation -->
+<div class="bg-linear-to-r/oklch from-indigo-500 to-teal-400">
+
+<!-- Conic and radial -->
+<div class="bg-conic from-red-500 to-red-500">
+<div class="bg-radial from-white to-zinc-900">
+```
+
+## 3D Transforms
+
+```html
+<div class="perspective-distant">
+  <div class="rotate-x-45 rotate-z-30 transform-3d">
+</div>
+```
+
+## @starting-style (Enter Transitions)
+
+```html
+<div popover class="transition-all starting:open:opacity-0 starting:open:scale-95">
+```
+
+## not-* Variant
+
+```html
+<div class="not-hover:opacity-75">
+<div class="not-supports-backdrop-blur:bg-white">
+```
+
+## Text Shadows (v4.1)
+
+```html
+<p class="text-shadow-sm">Small</p>
+<p class="text-shadow-lg">Large</p>
+<p class="text-shadow-lg text-shadow-blue-500/50">Colored</p>
+```
+
+## Masks (v4.1)
+
+```html
+<div class="mask-t-from-50%">Fade from top</div>
+<div class="mask-b-from-20% mask-b-to-80%">Bottom fade</div>
+<div class="mask-radial-from-70%">Radial</div>
+<div class="mask-b-from-50% mask-radial-from-80%">Combined</div>
+```
+
+## Other v4.1 Utilities
+
+```html
+<!-- Colored drop shadows -->
+<svg class="drop-shadow-xl drop-shadow-cyan-500/50">
+
+<!-- Overflow wrap -->
+<p class="wrap-break-word">Break words</p>
+<p class="wrap-anywhere">Break anywhere</p>
+
+<!-- Safe alignment -->
+<div class="flex justify-center-safe">
+
+<!-- Baseline alignment -->
+<div class="items-baseline-last">
+
+<!-- Color scheme -->
+<html class="color-scheme-dark">
+
+<!-- Field sizing -->
+<textarea class="field-sizing-content">
+
+<!-- Inert styling -->
+<div class="inert:opacity-50" inert>
+```
+
+## New v4.1 Variants
+
+```html
+<!-- Pointer device -->
+<div class="pointer-fine:p-2 pointer-coarse:p-4">
+
+<!-- Form validation (after interaction) -->
+<input class="user-valid:border-green-500 user-invalid:border-red-500">
+
+<!-- Details content -->
+<details class="details-content:mt-3">
+
+<!-- Inverted colors -->
+<div class="inverted-colors:shadow-none">
+
+<!-- Noscript -->
+<div class="noscript:block hidden">Enable JS</div>
+```
+
+## Source Directives (v4.1)
+
+```css
+/* Ignore paths */
+@source not "./src/legacy";
+
+/* Safelist utilities */
+@source inline("underline");
+
+/* Brace expansion */
+@source inline("{hover:,}bg-red-{100..900..100}");
+```

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

@@ -0,0 +1,217 @@
+---
+name: frontend-ui-engineering
+description: "Builds production-quality UIs. Auto-load when editing *.tsx,*.jsx,*.css,*.scss. Use when building or modifying user-facing interfaces, creating components, implementing layouts, managing state, or when output needs to look production-quality rather than AI-generated. Risk: Medium."
+---
+
+# Frontend UI Engineering
+
+## Overview
+
+Build production-quality user interfaces that are accessible, performant, and visually polished. The goal is UI that looks like it was built by a design-aware engineer at a top company — not like it was generated by an AI. This means real design system adherence, proper accessibility, thoughtful interaction patterns, and no generic "AI aesthetic."
+
+## When to Use
+
+- Building new UI components or pages
+- Modifying existing user-facing interfaces
+- Implementing responsive layouts
+- Adding interactivity or state management
+- Fixing visual or UX issues
+
+## When NOT to Use
+
+- Backend/logic-only work with no user-facing surface — use `incremental-implementation` or domain skills
+- Pure design-system/token work without implementation — use `design-system-audit` / `frontend-design`
+- Throwaway prototypes where production quality doesn't matter
+- The UI is already polished and the task is a non-visual change
+
+## Related Skills
+
+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. |
+| `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. |
+| `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`. |
+
+**Pipeline:** `design-taste-frontend` → `frontend-ui-engineering` → `accessibility-audit` + `performance-optimization`
+
+## Component Architecture
+
+### File Structure
+
+Colocate everything related to a component:
+
+```
+src/components/
+  TaskList/
+    TaskList.tsx          # Component implementation
+    TaskList.test.tsx     # Tests
+    TaskList.stories.tsx  # Storybook stories (if using)
+    use-task-list.ts      # Custom hook (if complex state)
+    types.ts              # Component-specific types (if needed)
+```
+
+### Component Patterns
+
+**Prefer composition over configuration:**
+
+```tsx
+// Good: Composable
+<Card>
+  <CardHeader>
+    <CardTitle>Tasks</CardTitle>
+  </CardHeader>
+  <CardBody>
+    <TaskList tasks={tasks} />
+  </CardBody>
+</Card>
+
+// Avoid: Over-configured
+<Card
+  title="Tasks"
+  headerVariant="large"
+  bodyPadding="md"
+  content={<TaskList tasks={tasks} />}
+/>
+```
+
+**Keep components focused — one responsibility per component.**
+
+**Separate data fetching from presentation:**
+- Container components handle data (loading, error, empty states)
+- Presentation components handle rendering
+
+## State Management
+
+Choose the simplest approach that works:
+
+```
+Local state (useState)           → Component-specific UI state
+Lifted state                     → Shared between 2-3 sibling components
+Context                          → Theme, auth, locale (read-heavy, write-rare)
+URL state (searchParams)         → Filters, pagination, shareable UI state
+Server state (React Query, SWR)  → Remote data with caching
+Global store (Zustand, Redux)    → Complex client state shared app-wide
+```
+
+**Avoid prop drilling deeper than 3 levels.** Use context or restructure.
+
+## Design System Adherence
+
+### Avoid the AI Aesthetic
+
+AI-generated UI has recognizable patterns. Avoid all of them:
+
+| AI Default | Production Quality |
+|---|---|
+| Purple/indigo everything | Use the project's actual color palette |
+| Excessive gradients | Flat or subtle gradients matching the design system |
+| Rounded everything (rounded-2xl) | Consistent border-radius from the design system |
+| Generic hero sections | Content-first layouts |
+| Lorem ipsum-style copy | Realistic placeholder content |
+| Oversized padding everywhere | Consistent spacing scale |
+| Stock card grids | Purpose-driven layouts |
+| Shadow-heavy design | Subtle or no shadows unless design system specifies |
+
+### Spacing and Layout
+
+Use a consistent spacing scale. Don't invent values:
+
+```css
+/* Use the scale: 0.25rem increments */
+/* Good */  padding: 1rem;      /* 16px */
+/* Good */  gap: 0.75rem;       /* 12px */
+/* Bad */   padding: 13px;      /* Not on any scale */
+```
+
+### Typography
+
+Respect type hierarchy: h1 (one per page) → h2 → h3 → body → small. Don't skip heading levels.
+
+### Color
+
+- Use semantic color tokens (`text-primary`, `bg-surface`) — not raw hex values
+- Ensure sufficient contrast (4.5:1 normal text, 3:1 large text)
+- Don't rely solely on color for information (add icons, text, or patterns)
+
+## Accessibility (WCAG 2.1 AA)
+
+### Keyboard Navigation
+
+Every interactive element must be keyboard accessible. Use native `<button>` and `<a>` — not `<div onClick>`.
+
+### ARIA Labels
+
+```tsx
+// Icon-only buttons need aria-label
+<button aria-label="Close dialog"><XIcon /></button>
+
+// Form inputs need labels
+<label htmlFor="email">Email</label>
+<input id="email" type="email" />
+```
+
+### Focus Management
+
+Trap focus inside modals while open, return focus on close. Move focus when content changes significantly.
+
+### Meaningful Empty and Error States
+
+Never show blank screens. Every component must handle: loading state, empty state, error state, and the normal data state.
+
+## Responsive Design
+
+Design for mobile first, then expand:
+
+```tsx
+<div className="
+  grid grid-cols-1      /* Mobile: single column */
+  sm:grid-cols-2        /* Small: 2 columns */
+  lg:grid-cols-3        /* Large: 3 columns */
+  gap-4
+">
+```
+
+Test at: 320px, 768px, 1024px, 1440px.
+
+## Loading and Transitions
+
+- Use skeleton loading for content (not spinners)
+- Use optimistic updates for perceived speed
+- `aria-busy="true"` on loading regions
+- Avoid layout shifts during loading (reserve space)
+
+## Common Rationalizations
+
+| 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)
+
+## 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
+- [ ] Responsive: works at 320px, 768px, 1024px, 1440px
+- [ ] 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