@minhduydev/mdpi 0.3.0

package/dist/template/.pi/skills/figma/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: figma
+description: Use when implementing UI from Figma designs, extracting design tokens, or downloading assets via Framelink MCP. MUST load when user shares a Figma URL or references Figma files. Requires API token.
+---
+
+# Figma Design Data (MCP)
+
+## When to Use
+
+- When you need to fetch layout, styles, or assets from a Figma file via MCP.
+
+## When NOT to Use
+
+- When no Figma file key/node ID is available or design data isn't required.
+
+
+## Prerequisites
+
+Set your Figma API key as an environment variable:
+
+```bash
+export FIGMA_API_KEY="your-figma-personal-access-token"
+```
+
+To create a Figma Personal Access Token:
+
+1. Go to Figma → Settings → Account → Personal access tokens
+2. Create a new token with read access
+3. See: https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens
+
+## Quick Start
+
+After loading this skill, use `skill_mcp` to invoke Figma tools:
+
+```
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123", "nodeId": "1234:5678"}')
+```
+
+## Available Tools
+
+### get_figma_data
+
+Fetch comprehensive Figma file data including layout, content, visuals, and component information.
+
+| Parameter | Type   | Required | Description                                                                                       |
+| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
+| `fileKey` | string | Yes      | The Figma file key (from URL: `figma.com/file/<fileKey>/...` or `figma.com/design/<fileKey>/...`) |
+| `nodeId`  | string | No       | Specific node ID (from URL param `node-id=<nodeId>`). Format: `1234:5678` or `1234-5678`          |
+| `depth`   | number | No       | Levels deep to traverse. Only use if explicitly requested by user.                                |
+
+**Returns:** YAML-formatted design data with:
+
+- `metadata` - File/node information
+- `nodes` - Simplified node tree with layout, styles, text content
+- `globalVars` - Shared styles and variables
+
+### download_figma_images
+
+Download SVG and PNG images/icons from a Figma file.
+
+| Parameter   | Type   | Required | Description                                   |
+| ----------- | ------ | -------- | --------------------------------------------- |
+| `fileKey`   | string | Yes      | The Figma file key                            |
+| `nodes`     | array  | Yes      | Array of node objects to download (see below) |
+| `localPath` | string | Yes      | Absolute path to save images                  |
+| `pngScale`  | number | No       | Export scale for PNGs (default: 2)            |
+
+**Node object structure:**
+
+```json
+{
+  "nodeId": "1234:5678",
+  "fileName": "icon-name.svg",
+  "imageRef": "optional-for-image-fills"
+}
+```
+
+## Workflow
+
+### 1. Extract File Key and Node ID from Figma URL
+
+Figma URLs follow these patterns:
+
+- `https://www.figma.com/file/<fileKey>/<fileName>?node-id=<nodeId>`
+- `https://www.figma.com/design/<fileKey>/<fileName>?node-id=<nodeId>`
+
+Example: `https://www.figma.com/design/abc123xyz/MyDesign?node-id=1234-5678`
+
+- `fileKey`: `abc123xyz`
+- `nodeId`: `1234-5678` (or `1234:5678` - both formats work)
+
+### 2. Fetch Design Data
+
+```
+# Fetch specific frame/component
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123xyz", "nodeId": "1234:5678"}')
+
+# Fetch entire file (use sparingly - can be large)
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123xyz"}')
+```
+
+### 3. Download Assets (Optional)
+
+```
+skill_mcp(skill_name="figma", tool_name="download_figma_images", arguments='{
+  "fileKey": "abc123xyz",
+  "nodes": [
+    {"nodeId": "1234:5678", "fileName": "hero-image.png"},
+    {"nodeId": "5678:9012", "fileName": "icon-arrow.svg"}
+  ],
+  "localPath": "/absolute/path/to/assets"
+}')
+```
+
+## Examples
+
+### Implement a Component from Figma
+
+```
+# User provides: https://www.figma.com/design/abc123/Dashboard?node-id=100-200
+
+# 1. Fetch the design data
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123", "nodeId": "100-200"}')
+
+# 2. Review the returned YAML for:
+#    - Layout structure (flex, grid, spacing)
+#    - Typography (font, size, weight, line-height)
+#    - Colors (fills, strokes)
+#    - Dimensions and constraints
+
+# 3. Implement the component using the extracted data
+```
+
+### Extract Design Tokens
+
+```
+# Fetch a design system file
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "designSystemKey"}')
+
+# The globalVars section contains:
+# - Color styles
+# - Typography styles
+# - Effect styles (shadows, blurs)
+```
+
+### Download Icons
+
+```
+skill_mcp(skill_name="figma", tool_name="download_figma_images", arguments='{
+  "fileKey": "iconLibraryKey",
+  "nodes": [
+    {"nodeId": "10:20", "fileName": "icon-home.svg"},
+    {"nodeId": "10:30", "fileName": "icon-settings.svg"},
+    {"nodeId": "10:40", "fileName": "icon-user.svg"}
+  ],
+  "localPath": "/project/src/assets/icons",
+  "pngScale": 2
+}')
+```
+
+## Data Structure
+
+The `get_figma_data` tool returns simplified, AI-optimized data:
+
+```yaml
+metadata:
+  name: "Component Name"
+  lastModified: "2024-01-15T..."
+
+nodes:
+  - id: "1234:5678"
+    name: "Button"
+    type: "FRAME"
+    layout:
+      mode: "HORIZONTAL"
+      padding: { top: 12, right: 24, bottom: 12, left: 24 }
+      gap: 8
+    size: { width: 120, height: 48 }
+    fills:
+      - type: "SOLID"
+        color: { r: 0.2, g: 0.4, b: 1, a: 1 }
+    cornerRadius: 8
+    children:
+      - id: "1234:5679"
+        name: "Label"
+        type: "TEXT"
+        content: "Click me"
+        textStyle:
+          fontFamily: "Inter"
+          fontSize: 16
+          fontWeight: 600
+
+globalVars:
+  styles:
+    "S:abc123": { name: "Primary", fills: [...] }
+```
+
+## Tips
+
+- **Always use nodeId** when provided - fetching entire files is slow and context-heavy
+- **Node IDs with `-` or `:`** both work - the MCP handles conversion
+- **Check globalVars** for reusable styles before hardcoding values
+- **Use depth parameter sparingly** - only when explicitly needed
+- **For images/icons**, identify nodes with `imageRef` in the data for proper downloading
+- **SVG vs PNG**: Use `.svg` for icons/vectors, `.png` for photos/complex images
+
+## Troubleshooting
+
+**"Invalid API key"**: Ensure `FIGMA_API_KEY` environment variable is set correctly.
+
+**"File not found"**: Verify the fileKey is correct and you have access to the file.
+
+**"Node not found"**: Check the nodeId format. Try both `1234:5678` and `1234-5678`.
+
+**Large response**: Use `nodeId` to fetch specific frames instead of entire files.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll approximate the design values" | Figma has exact values. Approximations compound into inconsistent UIs. |
+| "The design tokens aren't exported yet" | Extract what exists. Even partial tokens prevent arbitrary values. |
+| "Auto-layout doesn't translate to CSS" | Figma auto-layout maps directly to flexbox/grid. Use the mapping, don't guess. |
+
+## Red Flags
+
+- Design values manually transcribed instead of extracted
+- Auto-layout ignored in CSS implementation
+- Component variants in Figma not matched in code
+- Design tokens extracted but not applied consistently
+- Figma interactions implemented as different behaviors in code
+
+## Verification
+
+After implementing from Figma:
+
+- [ ] Design tokens are extracted and applied (not manually transcribed)
+- [ ] Implementation matches Figma at all specified breakpoints
+- [ ] Component variants in code match Figma component set
+- [ ] Auto-layout behaviors are correctly mapped to CSS flexbox/grid
+- [ ] Interactive states (hover, pressed, disabled) match Figma prototypes

package/dist/template/.pi/skills/frontend-design/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: frontend-design
+description: MUST load when building any web UI with React-based frameworks — components, pages, or full applications. Covers Tailwind CSS v4, shadcn/ui, Motion animations. Base UI implementation skill; combine with aesthetic overlays (minimalist-ui, high-end-visual-design) for specific styles.
+---
+
+# Frontend Design
+
+## When to Use
+
+- Building UI with React frameworks (Next.js, Vite, Remix)
+- Creating visually distinctive, memorable interfaces
+- Implementing accessible components with shadcn/ui
+- Styling with Tailwind CSS v4
+- Adding animations and micro-interactions
+- Creating visual designs, posters, brand materials
+
+## When NOT to Use
+
+- Backend-only tasks or minimal UI with no visual design requirements.
+
+## Reference Documentation
+
+### Tailwind CSS v4.1
+
+- `./references/tailwind/v4-config.md` - Installation, @theme, CSS-first config
+- `./references/tailwind/v4-features.md` - Container queries, gradients, masks, text shadows
+- `./references/tailwind/utilities-layout.md` - Display, flex, grid, position
+- `./references/tailwind/utilities-styling.md` - Spacing, typography, colors, borders
+- `./references/tailwind/responsive.md` - Breakpoints, mobile-first, container queries
+
+Search: `@theme`, `@container`, `OKLCH`, `mask-`, `text-shadow`
+
+### shadcn/ui (CLI v3.6)
+
+- `./references/shadcn/setup.md` - Installation, visual styles, component list
+- `./references/shadcn/core-components.md` - Button, Card, Dialog, Select, Tabs, Toast
+- `./references/shadcn/form-components.md` - Form, Field, Input Group, 2026 components
+- `./references/shadcn/theming.md` - CSS variables, OKLCH, dark mode
+- `./references/shadcn/accessibility.md` - ARIA, keyboard, screen reader
+
+Search: `Field`, `InputGroup`, `Spinner`, `ButtonGroup`, `next-themes`
+
+### Animation (Motion + Tailwind)
+
+- `./references/animation/motion-core.md` - Timing system, easing constants, performance rules, reduced motion, core patterns
+- `./references/animation/motion-advanced.md` - AnimatePresence, scroll, orchestration, TypeScript
+
+**Stack**:
+| Animation Type | Tool |
+|----------------|------|
+| Hover/transitions | Tailwind CSS (`transition-*`) |
+| shadcn states | `tailwindcss-animate` (built-in) |
+| Gestures/layout/exit | Motion (`motion/react`) |
+| Complex SVG morphing | anime.js v4 (niche only) |
+
+### Visual Design
+
+- `./references/canvas/philosophy.md` - Design movements, core principles
+- `./references/canvas/execution.md` - Multi-page systems, quality standards
+
+For sophisticated compositions: posters, brand materials, design systems.
+
+### Design Systems (Deep Guides)
+
+- `./references/design/color-system.md` - OKLCH, semantic tokens, dark mode architecture
+- `./references/design/typography-rules.md` - Fluid type, modular scale, OpenType features
+- `./references/design/interaction.md` - State models, focus, dialogs/popovers, loading patterns
+- `./references/design/ux-writing.md` - Button copy, error structure, empty states, i18n
+
+Search: `AI Slop Test`, `tinted neutrals`, `focus-visible`, `verb + object`, `65ch`
+
+## Design Thinking
+
+Before coding, commit to BOLD aesthetic direction:
+
+- **Purpose**: What problem? Who uses it?
+- **Tone**: Pick extreme - brutally minimal, maximalist chaos, retro-futuristic, organic, luxury, playful, editorial, brutalist, art deco, soft/pastel, industrial
+- **Differentiation**: What makes this UNFORGETTABLE?
+
+Bold maximalism and refined minimalism both work. Key is intentionality.
+
+## Anti-Patterns (AI Fingerprints — NEVER)
+
+These patterns immediately signal "AI made this." Avoid them all.
+
+### Typography
+
+- **Banned fonts**: Inter, Roboto, Arial, Open Sans, Lato, Montserrat, Space Grotesk, system-ui as display font
+- Monospace used as "developer aesthetic" shorthand
+- Big icons centered above every heading
+- Using `px` for body text (use `rem`/`em` to respect user settings)
+
+### Color
+
+- **AI palette**: Cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds
+- Gray text on colored backgrounds (use darker shade of background color instead)
+- Pure `#000` or `#fff` (always tint — pure black/white don't exist in nature)
+- Gradient text on headings or metrics
+- `rgba()` / heavy alpha transparency as primary palette (design smell — define explicit colors)
+
+### Layout
+
+- Cards nested inside cards (use typography, spacing, dividers for hierarchy within a card)
+- Identical card grids (icon + heading + text repeated 3-6 times)
+- Hero metric template (big number + small label + gradient accent)
+- Center-aligning everything
+- Same spacing everywhere (no visual rhythm)
+
+### Visual
+
+- Glassmorphism used decoratively (blur cards, glow borders)
+- Thick colored border on one side of rounded rectangles
+- Sparklines as decoration (not connected to real data)
+- Generic drop shadows on everything
+- Rounded rectangles as the only shape language
+
+### Motion
+
+- Bounce or elastic easing (real objects decelerate smoothly)
+- Animating `height`, `width`, `padding`, `margin` (causes layout recalculation)
+- Default `ease` (compromise that's rarely optimal — use exponential easing)
+- Missing `prefers-reduced-motion` handling
+
+> **The AI Slop Test**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem.
+
+## Best Practices
+
+1. **Accessibility First**: Radix primitives, `:focus-visible` (not `:focus`), semantic HTML, 44px touch targets
+2. **Mobile-First**: Start mobile, layer responsive variants with `min-width` queries
+3. **Design Tokens**: Two-layer system — primitives (`--blue-500`) + semantic (`--color-primary: var(--blue-500)`); dark mode redefines semantic layer only
+4. **Dark Mode**: Not inverted light mode — lighter surfaces create depth (no shadows); desaturate accents; base at `oklch(15-18% …)`
+5. **Container Queries**: Use `@container` for component layout, viewport queries for page layout
+6. **Performance**: `transform` + `opacity` only for animations; CSS purging; avoid dynamic class names
+7. **TypeScript**: Full type safety
+8. **Expert Craftsmanship**: Every detail matters — squint test for hierarchy validation
+
+## Core Stack Summary
+
+**Tailwind v4.1**: CSS-first config via `@theme`. Single `@import "tailwindcss"`. OKLCH colors. Container queries built-in.
+
+**shadcn/ui v3.6**: Copy-paste Radix components. Visual styles: Vega/Nova/Maia/Lyra/Mira. New: Field, InputGroup, Spinner, ButtonGroup.
+
+**Motion**: `import { motion, AnimatePresence } from 'motion/react'`. Declarative React animations. Use `tailwindcss-animate` for shadcn states.
+
+## Typography
+
+→ Consult `./references/design/typography-rules.md` for full fluid type system
+
+Choose distinctive fonts. Pair display with body:
+
+- **Preferred**: Instrument Sans, Plus Jakarta Sans, Outfit, Onest, Figtree, Urbanist (sans); Fraunces, Newsreader (editorial)
+- **Fluid sizing**: `clamp(1rem, 0.5rem + 2vw, 1.5rem)` — never fixed `px` for body
+- **Modular scale**: Pick one ratio (1.25 major third, 1.333 perfect fourth) — 5 sizes max
+- **Measure**: `max-width: 65ch` for body text
+- **OpenType**: `tabular-nums` for data, `diagonal-fractions` for recipes, `all-small-caps` for abbreviations
+
+```css
+@theme {
+  --font-display: "Fraunces", serif;
+  --font-body: "Instrument Sans", sans-serif;
+}
+```
+
+## Color
+
+→ Consult `./references/design/color-system.md` for OKLCH deep guide
+
+Use OKLCH for perceptually uniform colors. Two-layer token system:
+
+```css
+@theme {
+  /* Primitives */
+  --blue-500: oklch(0.55 0.22 264);
+  --amber-400: oklch(0.75 0.18 80);
+  /* Semantic (redefine these for dark mode) */
+  --color-primary: var(--blue-500);
+  --color-accent: var(--amber-400);
+  /* Tinted neutrals — chroma 0.01 for subconscious brand cohesion */
+  --color-surface: oklch(0.97 0.01 264);
+  --color-surface-dark: oklch(0.16 0.01 264);
+}
+```
+
+## Motion
+
+→ Consult `./references/animation/motion-core.md` for Motion API
+
+**Timing**: 100-150ms instant feedback | 200-300ms state changes | 300-500ms layout | exit = 75% of enter
+
+**Easing**: Exponential only — `cubic-bezier(0.16, 1, 0.3, 1)` for entrances. Never `ease`, never bounce/elastic.
+
+**Performance**: Only animate `transform` and `opacity`. Height expand → `grid-template-rows: 0fr → 1fr`.
+
+**Accessibility**: `prefers-reduced-motion` is mandatory (affects ~35% of adults over 40). Swap spatial animations for crossfades.
+
+```tsx
+import { motion, AnimatePresence } from 'motion/react';
+
+<motion.div initial={{ opacity: 0, y: 12 }} animate={{ opacity: 1, y: 0 }}
+  transition={{ duration: 0.3, ease: [0.16, 1, 0.3, 1] }} />
+
+<AnimatePresence>
+  {show && <motion.div exit={{ opacity: 0 }} transition={{ duration: 0.2 }} />}
+</AnimatePresence>
+```
+
+CSS stagger: `animation-delay: calc(var(--i, 0) * 50ms)` — cap total at 500ms.
+
+## Spatial Composition
+
+- **4pt spacing system**: 4, 8, 12, 16, 24, 32, 48, 64, 96px — not 8pt (too coarse at small gaps)
+- **`gap` over margins** for sibling spacing (eliminates margin collapse)
+- **Self-adjusting grids**: `repeat(auto-fit, minmax(280px, 1fr))` — responsive without breakpoints
+- **Container queries** for components: `container-type: inline-size` on wrapper, `@container` on children
+- **Optical text alignment**: `margin-left: -0.05em` for text that appears indented due to letterform whitespace
+- Asymmetry, overlap, diagonal flow, grid-breaking elements. Generous negative space OR controlled density.
+
+## Interaction
+
+→ Consult `./references/design/interaction.md`
+
+Design all 8 states: Default, Hover, Focus, Active, Disabled, Loading, Error, Success. Use `:focus-visible` not `:focus`. Native `<dialog>` + `inert` for modals. Popover API for tooltips/dropdowns. Skeleton screens over spinners. Undo over confirmation dialogs.
+
+## UX Writing
+
+→ Consult `./references/design/ux-writing.md`
+
+Button labels: specific verb + object ("Save changes" not "OK"). Error formula: What happened + Why + How to fix. Empty states are onboarding opportunities. Plan for 30% text expansion (i18n).
+
+## Backgrounds
+
+Create atmosphere: gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, grain overlays.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "The AI aesthetic is fine for now" | AI default styles (purple gradients, oversized cards) signal low quality. Use the design system. |
+| "I'll make it responsive later" | Retrofitting responsive design is 3x harder than building it mobile-first. |
+| "Accessibility is a nice-to-have" | It's a legal requirement in many jurisdictions and an engineering quality standard. |
+| "This is just a prototype" | Prototypes become production code. Build the foundation right from the start. |
+
+## Red Flags
+
+- Components exceeding 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