feat: Enhance Atomic Design methodology with detailed naming conventions, architecture, and design token guidance, and update skill metadata.

2026-01-31 20:00:32 +07:00
parent bd49f4fe3b
commit bafe9efa21
1 changed files with 121 additions and 237 deletions
--- 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