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

description

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.

# 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.

# 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.

# 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

# 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:

{
  "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

# Check path in config
jq '.componentLibrary' pencil.config.json

# Verify file exists
ls -la src/components/*.pen

Error: No .pen files found

# Check source directory
ls -la src/pages/*.pen

Python syntax error

# Use Python 3.11+
python3 --version

# Ensure using python3, not python
which python3

---

Examples

Rebuild library after adding components

# After creating new pos-controls.pen in src/atoms/
// turbo
python3 scripts/build.py --library

Quick rebuild monolithic

# Rebuild monolithic after editing pages
// turbo
python3 scripts/build.py -m

Build both modes

# Standard build
python3 scripts/build.py

# Monolithic build
python3 scripts/build.py -m

Compare outputs

# Check differences
jq '.children | length' tPOS.pen
jq '.children | length' build/tPOS-desktop-home.pen