Migrate

microservices/.agent/workflows/pencil-build.md

@@ -0,0 +1,214 @@
+---
+description: Build Pencil Design files - Standard (component linking) hoặc Monolithic (merged)
+---
+
+# Pencil Design Build Workflow
+
+## Overview
+Build system cho Pencil Design files với 2 modes:
+- **Standard**: Build individual pages với component linking (injecting refs)
+- **Monolithic**: Merge tất cả pages + component library thành 1 file
+
+## Prerequisites
+- Python 3.11+
+- `jq` (optional, for validation)
+
+---
+
+## Build Modes
+
+### 1. Monolithic Build (Recommended)
+Merge tất cả pages và component library thành 1 file `tPOS.pen`.
+
+```bash
+# Build monolithic file
+// turbo
+python3 scripts/build.py --monolithic
+
+# Custom output filename
+python3 scripts/build.py --monolithic --output myDesign.pen
+
+# Alternative syntax
+python3 scripts/build.py --mode monolithic
+python3 scripts/build.py -m  # short form
+```
+
+**Output:**
+- File: `tPOS.pen` (project root)
+- Chứa: Desktop page + Mobile page + Tablet page + Component Library page
+- Size: ~326KB
+- Structure: 4 top-level frames
+
+**Use case:**
+- ✅ Mở toàn bộ design trong Pencil
+- ✅ Share với designer khác
+- ✅ Archive/backup complete design
+- ✅ Export sang tool khác
+
+---
+
+### 2. Standard Build (Component Linking)
+Build individual pages với component refs được inject từ library.
+
+```bash
+# Build separate pages
+// turbo
+python3 scripts/build.py
+
+# Alternative
+python3 scripts/build.py --mode standard
+```
+
+**Output:**
+- Directory: `build/`
+- Files: `tPOS-desktop-home.pen`, `tPOS-mobile-home.pen`, `tPOS-tablet-home.pen`
+- Mỗi file chứa injected components từ `tPOS-ui-kit.pen`
+
+**Use case:**
+- ✅ Development workflow với component refs
+- ✅ Testing component linking system
+- ✅ Smaller individual files
+
+---
+
+### 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
+# Verify output structure
+jq '{version, childrenCount: (.children | length), childrenNames: [.children[].name]}' tPOS.pen
+
+# Check file size
+ls -lh tPOS.pen
+
+# Validate JSON syntax
+jq empty tPOS.pen && echo "✅ Valid JSON"
+```
+
+---
+
+## Configuration
+
+Edit `pencil.config.json`:
+
+```json
+{
+  "version": "1.0",
+  "sourceDir": "src",
+  "buildDir": "build",
+  "componentLibrary": "src/components/tPOS-ui-kit.pen",
+  "buildOptions": {
+    "minify": false,
+    "validateAfterBuild": true,
+    "preserveComments": true
+  }
+}
+```
+
+---
+
+## Troubleshooting
+
+### Error: Component library not found
+```bash
+# Check path in config
+jq '.componentLibrary' pencil.config.json
+
+# Verify file exists
+ls -la src/components/*.pen
+```
+
+### Error: No .pen files found
+```bash
+# Check source directory
+ls -la src/pages/*.pen
+```
+
+### Python syntax error
+```bash
+# Use Python 3.11+
+python3 --version
+
+# Ensure using python3, not python
+which python3
+```
+
+---
+
+## Examples
+
+### 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
+python3 scripts/build.py -m
+```
+
+### Build both modes
+```bash
+# Standard build
+python3 scripts/build.py
+
+# Monolithic build
+python3 scripts/build.py -m
+```
+
+### Compare outputs
+```bash
+# Check differences
+jq '.children | length' tPOS.pen
+jq '.children | length' build/tPOS-desktop-home.pen
+```