215 lines
4.5 KiB
Markdown
215 lines
4.5 KiB
Markdown
---
|
|
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
|
|
```
|