---
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
```