diff --git a/.agent/skills/pencil-design/SKILL.md b/.agent/skills/pencil-design/SKILL.md index 84fdc8c2..640a766a 100644 --- a/.agent/skills/pencil-design/SKILL.md +++ b/.agent/skills/pencil-design/SKILL.md @@ -221,6 +221,58 @@ mkdir -p src/foundations src/atoms src/molecules src/organisms python3 scripts/extract-atomic.py ``` +### Creating New Components + +When adding components to Atomic Design structure: + +**1. Create `.pen` file in appropriate directory:** +```bash +# Atoms: Buttons, inputs, badges +touch src/atoms/pos-controls.pen + +# Molecules: 2-3 atoms combined +touch src/molecules/order-items.pen + +# Organisms: Complex sections +touch src/organisms/pos-layout.pen +``` + +**2. Use proper component structure:** +```json +{ + "version": "2.6", + "children": [ + { + "type": "frame", + "id": "numpad_key_001", + "name": "Atom/NumpadKey/Standard", + "reusable": true, + "width": 64, + "height": 64, + "fill": "$bg-elevated", + "cornerRadius": "$radius-md", + "children": [...] + } + ] +} +``` + +**3. Follow naming convention:** +``` +{Level}/{Component}/{Variant}/{State} + +Examples: +- Atom/NumpadKey/Standard +- Atom/NumpadKey/Action/Clear +- Molecule/OrderItem/Standard +- Organism/Dialog/Confirm +``` + +**4. Rebuild library:** +```bash +python3 scripts/build.py --library +``` + ## Common Mistakes / Lỗi Thường Gặp ### 1. Hardcoding Colors @@ -281,6 +333,29 @@ open tPOS.pen } ``` +### 5. Missing Width for Centering +**Problem**: Setting `alignItems: "center"` without explicit width. The frame only takes content width, making horizontal centering ineffective. +**Solution**: Add `width: "fill_container"` to parent frame. + +```json +// ❌ BAD: Centering won't work +{ + "type": "frame", + "layout": "vertical", + "alignItems": "center", + "children": [...] +} + +// ✅ GOOD: Explicit width enables centering +{ + "type": "frame", + "width": "fill_container", + "layout": "vertical", + "alignItems": "center", + "children": [...] +} +``` + ## Quick Reference / Tham Chiếu Nhanh ### Common Element Types @@ -308,12 +383,12 @@ open tPOS.pen | Command | Purpose | |---------|---------| -| `python3 scripts/build.py --library` | Build Component Lib | -| `python3 scripts/build.py -m` | Monolithic build | -| `python3 scripts/build.py` | Standard build | -| `python3 scripts/build.py -m --output name.pen` | Custom output | -| `jq empty file.pen && echo "✅ Valid"` | Validate JSON | -| `jq '.variables' file.pen` | Extract tokens | +| `python3 scripts/build.py --library` | Build component library from Atomic sources | +| `python3 scripts/build.py -m` | Monolithic build (all pages + library) | +| `python3 scripts/build.py` | Standard build (inject refs) | +| `python3 scripts/build.py -m --output name.pen` | Custom output filename | +| `jq empty file.pen && echo "✅ Valid"` | Validate JSON syntax | +| `jq '.variables' file.pen` | Extract design tokens | ### Token Categories diff --git a/.agent/workflows/pencil-build.md b/.agent/workflows/pencil-build.md index 240795c5..49c8585d 100644 --- a/.agent/workflows/pencil-build.md +++ b/.agent/workflows/pencil-build.md @@ -71,6 +71,53 @@ python3 scripts/build.py --mode standard --- +### 3. Library Build (Atomic Design Consolidation) +Merge atomic components from `src/atoms/`, `src/molecules/`, `src/organisms/` into single library file. + +```bash +# Build library from Atomic Design sources +// turbo +python3 scripts/build.py --library + +# Alternative syntax +python3 scripts/build.py --lib +python3 scripts/build.py -l +``` + +**Output:** +- File: `src/components/tPOS-ui-kit.pen` +- Merges: All components from `atoms/`, `molecules/`, `organisms/` +- Includes: Design tokens from `foundations/design-tokens.pen` + +**Expected Output:** +``` +🔨 Building Component Library +================================================== +✓ Loaded design tokens from design-tokens.pen +Scanning atoms... + ✓ Added 2 components from badges.pen + ✓ Added 2 components from buttons.pen + ✓ Added 4 components from pos-controls.pen +Scanning molecules... + ✓ Added 6 components from order-items.pen +Scanning organisms... + ✓ Added 3 components from cards.pen + ✓ Added 6 components from pos-layout.pen + +================================================== +✅ Library build complete! +📄 Output: src/components/tPOS-ui-kit.pen +🧩 Components: 32 +🎨 Tokens: 14 +``` + +**Use case:** +- ✅ After adding new components to atomic directories +- ✅ Rebuild component library for pages to reference +- ✅ Consolidate distributed components into single file + +--- + ## Validation ```bash @@ -136,7 +183,14 @@ which python3 ## Examples -### Quick rebuild +### Rebuild library after adding components +```bash +# After creating new pos-controls.pen in src/atoms/ +// turbo +python3 scripts/build.py --library +``` + +### Quick rebuild monolithic ```bash # Rebuild monolithic after editing pages // turbo