diff --git a/.agent/skills/pencil-design/SKILL.md b/.agent/skills/pencil-design/SKILL.md index 52060321..52316712 100644 --- a/.agent/skills/pencil-design/SKILL.md +++ b/.agent/skills/pencil-design/SKILL.md @@ -1,11 +1,11 @@ --- name: pencil-design -description: Pencil UI/UX design tool workflows, file format parsing, component systems, và Atomic Design Hierarchy cho enterprise UI Kits. Use for reading .pen files, extracting content, converting to code (HTML/CSS/React/Blazor), modular design workflows, và organizing large-scale design systems. +description: Pencil UI/UX design tool với Atomic Design Hierarchy cho enterprise UI Kits. Design system modularization, component extraction, code conversion (HTML/CSS/React/Blazor), và enterprise-scale design workflows. compatibility: "Pencil 2.6+, JSON parsing" metadata: author: Velik Ho - version: "2.0" - references: "pencil.evolus.vn, Pencil GitHub, Atomic Design methodology" + version: "3.0" + references: "pencil.evolus.vn, Atomic Design by Brad Frost, Material Design, Figma Design Systems" --- # Pencil Design Tool / Công cụ thiết kế Pencil @@ -339,40 +339,48 @@ Page Frame ### 7.2 Component Naming Convention -**Traditional (Simple Projects):** -``` -Component/{Category}/{Variant} -- Component/Button/Primary -- Component/Button/Secondary -- Component/Card/Feature -- Component/Card/Pricing -``` +Atomic Design uses strict hierarchical naming: -**Atomic Design (Enterprise):** ``` {AtomicLevel}/{Component}/{Variant}/{State} - -Atoms: -- Atom/Button/Primary/Default -- Atom/Button/Primary/Hover -- Atom/Button/Primary/Disabled -- Atom/Badge/Section/Default -- Atom/Input/Text/Default -- Atom/Input/Text/Error - -Molecules: -- Molecule/FormField/Text/Default -- Molecule/FormField/Text/WithError -- Molecule/SearchBar/Default -- Molecule/CardHeader/WithIcon - -Organisms: -- Organism/Card/Feature/Default -- Organism/Navigation/Desktop/Default -- Organism/Navigation/Mobile/Collapsed -- Organism/Footer/TwoColumn/Default ``` +**Examples:** + +**Atoms** (smallest building blocks): +- `Atom/Button/Primary/Default` +- `Atom/Button/Primary/Hover` +- `Atom/Button/Primary/Disabled` +- `Atom/Button/Secondary/Default` +- `Atom/Badge/Section/Default` +- `Atom/Input/Text/Default` +- `Atom/Input/Text/Error` +- `Atom/Input/Text/Disabled` + +**Molecules** (combinations of atoms): +- `Molecule/FormField/Text/Default` +- `Molecule/FormField/Text/WithError` +- `Molecule/SearchBar/Default` +- `Molecule/SearchBar/Focused` +- `Molecule/CardHeader/WithIcon` +- `Molecule/CardHeader/Plain` + +**Organisms** (complex UI sections): +- `Organism/Card/Feature/Default` +- `Organism/Card/Pricing/Enterprise` +- `Organism/Navigation/Desktop/Default` +- `Organism/Navigation/Mobile/Collapsed` +- `Organism/Navigation/Mobile/Expanded` +- `Organism/Footer/TwoColumn/Default` +- `Organism/Footer/FourColumn/Default` + +**Naming Rules:** +1. ✅ **Always include atomic level** (Atom/Molecule/Organism) +2. ✅ **Use PascalCase** for all parts +3. ✅ **Include variant** even if only one exists (use "Default") +4. ✅ **Add state** for interactive components (Default/Hover/Active/Focus/Disabled/Loading) +5. ✅ **Be descriptive** - Name should explain purpose without seeing component + ### 7.3 Component States & Variants **Every interactive component should have states:** @@ -477,55 +485,19 @@ project-name/ └── USAGE_GUIDE.md # Documentation ``` -### 7.4 Modular Design Architecture (Hybrid Approach) +### 7.5 Atomic Design Architecture **Problem**: Large monolithic `.pen` files (5000+ lines) cause: - ❌ Slow performance (2-3 second load times) - ❌ Maintenance challenges (duplicate components) - ❌ Collaboration bottlenecks (merge conflicts) - ❌ Poor reusability +- ❌ Difficult to scale for enterprise applications -**Solution**: Split into modular structure +**Solution**: Atomic Design Hierarchy - Industry standard for enterprise UI Kits -#### File Structure Patterns +#### Atomic Design Structure -**Option A: By Responsive Breakpoints** -``` -project-name/ -├── components/ -│ └── ui-kit.pen # Component library -├── pages/ -│ ├── desktop-home.pen # Desktop (1440px) -│ ├── tablet-home.pen # Tablet (768px) -│ └── mobile-home.pen # Mobile (390px) -└── original.pen.backup # Backup -``` - -**Option B: By Features** -``` -project-name/ -├── components/ -│ └── ui-kit.pen -├── pages/ -│ ├── hero.pen -│ ├── features.pen -│ ├── pricing.pen -│ └── footer.pen -``` - -**Option C: Hybrid** ⭐ (Recommended for Medium Projects) -``` -project-name/ -├── components/ -│ └── ui-kit.pen # Atoms + Design Tokens -├── pages/ -│ ├── desktop-{feature}.pen # Desktop pages -│ ├── mobile-{feature}.pen # Mobile pages -│ └── tablet-{feature}.pen # Tablet pages -└── USAGE_GUIDE.md # Workflow docs -``` - -**Option D: Atomic Design Hierarchy** 🏆 (Recommended for Enterprise) ``` project-name/ ├── src/ @@ -569,175 +541,94 @@ project-name/ └── USAGE_GUIDE.md ``` -**Benefits of Atomic Design:** +#### Why Atomic Design? + +**Benefits:** - ✅ **Industry Standard** - Used by Figma, Material Design, Ant Design - ✅ **Maximum Scalability** - Easy to add components at any level - ✅ **Clear Hierarchy** - Atoms → Molecules → Organisms → Templates → Pages - ✅ **Team Collaboration** - Different designers own different atomic levels - ✅ **Reusability** - Components compose naturally from smaller pieces - ✅ **Discoverability** - Intuitive folder structure for finding components +- ✅ **Maintainability** - Small, focused files (< 500 lines each) +- ✅ **Version Control** - Minimal merge conflicts with parallel work -**When to use Atomic Design:** +**Recommended for:** - ✅ Enterprise applications with 50+ components -- ✅ Design system shared across multiple products -- ✅ Team of 3+ designers working in parallel +- ✅ Design systems shared across multiple products +- ✅ Teams of 3+ designers working in parallel - ✅ Long-term maintenance (2+ years) -- ✅ Need component documentation & showcases +- ✅ Component documentation & showcases +- ✅ Cross-platform design consistency -#### Component Library Structure +#### Design Tokens Foundation -**ui-kit.pen should contain:** +**design-tokens.pen should contain:** -1. **Design Variables** (always included) - ```json - "variables": { - "bg-page": { "type": "color", "value": "#0A0A0B" }, - "text-primary": { "type": "color", "value": "#FFFFFF" }, - ... - } - ``` - -2. **Component Showcase Page** - - Organized by category sections - - Section 1: Buttons & Actions - - Section 2: Badges & Labels - - Section 3: Cards - - Section 4: Navigation - - Section 5: Typography & Branding - - Section 6: Utilities - - Section 7: Footer Components - -#### Extraction Workflow - -**Step 1: Analyze Original File** -```bash -# Check file stats -wc -l original.pen -du -h original.pen - -# Identify pages and components -grep '"name":' original.pen | grep -E "(Page|Component)" -``` - -**Step 2: Create Directory Structure** -```bash -mkdir -p components pages -``` - -**Step 3: Extract with Python Script** -```python -import json - -# Read original -with open('original.pen', 'r') as f: - data = json.load(f) - -variables = data['variables'] - -# Extract Component Library -comp_lib = { - 'version': '2.6', - 'children': [], - 'variables': variables +```json +{ + "version": "2.6", + "children": [{ + "type": "frame", + "name": "Design Tokens Reference", + "layout": "vertical", + "gap": 20, + "children": [ + { + "type": "text", + "content": "Design System Tokens", + "fontSize": 32, + "fill": "$text-primary" + } + ] + }], + "variables": { + // Colors - Semantic naming + "bg-page": {"type": "color", "value": "#0A0A0B"}, + "bg-surface": {"type": "color", "value": "#1A1A1C"}, + "bg-elevated": {"type": "color", "value": "#222225"}, + "text-primary": {"type": "color", "value": "#FFFFFF"}, + "text-secondary": {"type": "color", "value": "#ADADB0"}, + "text-tertiary": {"type": "color", "value": "#8B8B90"}, + "orange-primary": {"type": "color", "value": "#FF5C00"}, + "orange-light": {"type": "color", "value": "#FF8A4C"}, + "border-default": {"type": "color", "value": "#3B3B40"}, + "border-subtle": {"type": "color", "value": "#27272A"}, + + // Typography + "font-primary": {"type": "string", "value": "Roboto"}, + "text-xs": {"type": "number", "value": 11}, + "text-sm": {"type": "number", "value": 13}, + "text-base": {"type": "number", "value": 14}, + "text-lg": {"type": "number", "value": 16}, + "text-xl": {"type": "number", "value": 18}, + "text-2xl": {"type": "number", "value": 24}, + "text-3xl": {"type": "number", "value": 32}, + + // Spacing (8px grid) + "space-1": {"type": "number", "value": 4}, + "space-2": {"type": "number", "value": 8}, + "space-3": {"type": "number", "value": 12}, + "space-4": {"type": "number", "value": 16}, + "space-5": {"type": "number", "value": 20}, + "space-6": {"type": "number", "value": 24}, + "space-8": {"type": "number", "value": 32}, + "space-10": {"type": "number", "value": 40}, + + // Border Radius + "radius-sm": {"type": "number", "value": 6}, + "radius-md": {"type": "number", "value": 10}, + "radius-lg": {"type": "number", "value": 16}, + "radius-full": {"type": "number", "value": 100}, + + // Breakpoints + "breakpoint-mobile": {"type": "number", "value": 390}, + "breakpoint-tablet": {"type": "number", "value": 768}, + "breakpoint-desktop": {"type": "number", "value": 1440} + } } - -# Find component library page (e.g., id: 'CompLib') -for child in data['children']: - if child.get('name') == 'Component Library': - child['x'] = 0 # Reset position - child['y'] = 0 - comp_lib['children'].append(child) - break - -# Write component library -with open('components/ui-kit.pen', 'w') as f: - json.dump(comp_lib, f, indent=2) - -# Extract pages similarly -# - Desktop: find by name "Desktop Page" -# - Mobile: find by name "Mobile Page" -# - Tablet: find by name "Tablet Page" ``` -**Step 4: Validate Extracted Files** -```python -import json -import os - -files_to_check = [ - 'components/ui-kit.pen', - 'pages/desktop-home.pen', - 'pages/mobile-home.pen', - 'pages/tablet-home.pen' -] - -for filepath in files_to_check: - with open(filepath, 'r') as f: - data = json.load(f) - - assert 'version' in data - assert 'children' in data and len(data['children']) > 0 - assert 'variables' in data - - print(f'✅ {filepath} - Valid') -``` - -**Step 5: Create Usage Guide** - -Generate `USAGE_GUIDE.md`: -```markdown -# Design System - Usage Guide - -## Component Library -- File: `components/ui-kit.pen` -- Contains: Design tokens + All reusable components - -## Workflow -1. Open `components/ui-kit.pen` -2. Copy components you need -3. Paste into page files -4. Maintain design token references - -## Important -⚠️ Pencil doesn't support external file refs (yet) -Components are COPIED, not linked -``` - -#### Current Limitations - -> [!WARNING] -> **No External File References**: Pencil 2.6 doesn't support linking components across files. -> -> **Workaround**: Manual Import Workflow -> 1. Update component in `ui-kit.pen` -> 2. Copy updated component -> 3. Replace in each page file manually - -**Future**: When Pencil adds cross-file linking, this will auto-update. - -#### Benefits - -| Metric | Before (Monolith) | After (Modular) | Improvement | -|--------|-------------------|-----------------|-------------| -| Largest file | 9,118 lines (328KB) | 3,181 lines (118KB) | **64% smaller** | -| Load time | ~2-3 seconds | ~0.5-1 second | **3x faster** | -| Collaboration | Hard (conflicts) | Easy (parallel work) | ✅ | -| Reusability | Low (duplicates) | High (single source) | ✅ | - -#### When to Use Modular Approach - -✅ **Use when:** -- File > 5,000 lines -- Multiple responsive breakpoints -- Team collaboration needed -- Component reuse across projects - -❌ **Skip when:** -- Simple single-page designs -- Solo designer, no collaboration -- Prototypes or wireframes -- File < 2,000 lines - #### Atomic Design Extraction Workflow **For large enterprise UI Kits (2,000+ lines), convert to Atomic Design structure:** @@ -1027,17 +918,7 @@ Examples: 5. **Version control** - Commit source files (`src/`), gitignore `build/` 6. **Configuration consistency** - Đảm bảo `pencil.config.json` đúng paths -### 8.4 Khi quản lý modular designs - -1. **Component Library First** - Always create/update `ui-kit.pen` before pages -2. **Consistent Naming** - Use predictable names: `{breakpoint}-{feature}.pen` -3. **Design Token Sync** - Ensure all files share same `variables` object -4. **Version Control** - Commit component library and pages separately -5. **Documentation** - Maintain `USAGE_GUIDE.md` with workflow instructions -6. **Backup Strategy** - Keep `original.pen.backup` before major refactoring -7. **Validation Script** - Always validate JSON structure after extraction - -### 8.5 Khi sử dụng Atomic Design (Enterprise) +### 8.4 Atomic Design Best Practices 1. **Foundations First** - Design tokens (`design-tokens.pen`) là single source of truth 2. **Build Bottom-Up** - Atoms → Molecules → Organisms → Templates → Pages @@ -1054,6 +935,9 @@ Examples: - Commit: `src/` (all atomic files) - Gitignore: `build/` (generated files) - Tag releases: `v1.0.0` khi có breaking changes trong design tokens +13. **Component Library** - Luôn update atomic files trước khi build pages +14. **Validation** - Always validate JSON structure sau khi extraction +15. **Backup Strategy** - Keep `original.pen.backup` trước khi refactor sang Atomic Design ## 9. Common Mistakes / Lỗi Thường Gặp