244 lines
7.5 KiB
Markdown
244 lines
7.5 KiB
Markdown
# tPOS Design System - Usage Guide
|
|
|
|
## 📁 File Structure
|
|
|
|
```
|
|
pencil-design/
|
|
├── src/
|
|
│ ├── foundations/ # Design Tokens
|
|
│ ├── atoms/ # Atomic Components
|
|
│ ├── molecules/ # Molecule Components
|
|
│ └── organisms/ # Organism Components
|
|
├── components/
|
|
│ └── tPOS-ui-kit.pen # Legacy Component Library
|
|
├── pages/
|
|
│ ├── tPOS-desktop-home.pen # Desktop Page
|
|
│ ├── tPOS-mobile-home.pen # Mobile Page
|
|
│ └── tPOS-tablet-home.pen # Tablet Page
|
|
└── tPOS.pen.backup # Original backup
|
|
```
|
|
|
|
## 🎨 Component Library
|
|
|
|
### File: `components/tPOS-ui-kit.pen`
|
|
|
|
**Contains**:
|
|
- ✅ All design variables (colors, typography)
|
|
- ✅ 7 organized component sections:
|
|
1. **Buttons & Actions** - Primary/Secondary buttons with/without icons
|
|
2. **Badges & Labels** - Section labels, hero badges, chips
|
|
3. **Cards** - Feature, Industry, Step, Pricing cards
|
|
4. **Navigation** - Desktop & Mobile navbars
|
|
5. **Typography & Branding** - Logo, headers, nav links
|
|
6. **Utilities** - Check items, dividers, social icons, stats
|
|
7. **Footer Components** - Footer columns (Products, Industries, Support)
|
|
|
|
**How to Use**:
|
|
1. Open `tPOS-ui-kit.pen` in Pencil
|
|
2. Browse components in the "aPOS Component Library" page
|
|
3. Copy components you need
|
|
4. Paste into your page designs
|
|
|
|
---
|
|
|
|
## 📄 Page Files
|
|
|
|
### Desktop Page - `pages/tPOS-desktop-home.pen`
|
|
- **Breakpoint**: 1440px
|
|
- **Sections**: Header, Hero, Features (6 cards), Industries, Steps (3), Pricing (3 plans), Footer
|
|
- **Layout**: Full-width desktop design with multi-column grids
|
|
|
|
### Mobile Page - `pages/tPOS-mobile-home.pen`
|
|
- **Breakpoint**: 390px
|
|
- **Sections**: Mobile header, Hero, Features (stacked), Industries (mobile grid), Steps (vertical), Pricing (swipeable), Mobile footer
|
|
- **Layout**: Single-column, touch-optimized
|
|
|
|
### Tablet Page - `pages/tPOS-tablet-home.pen`
|
|
- **Breakpoint**: 768px
|
|
- **Sections**: Tablet header, Hero, Features (2-column), Industries (tablet grid), Steps (hybrid), Pricing (2-up), Tablet footer
|
|
- **Layout**: 2-column responsive grid
|
|
|
|
---
|
|
|
|
## 🎨 Design Variables
|
|
|
|
All files include these color tokens:
|
|
|
|
| Variable | Value | Usage |
|
|
|----------|-------|-------|
|
|
| `$bg-page` | `#0A0A0B` | Page background |
|
|
| `$bg-surface` | `#111113` | Card backgrounds |
|
|
| `$bg-elevated` | `#1A1A1D` | Elevated surfaces |
|
|
| `$bg-interactive` | `#2A2A2E` | Hover states |
|
|
| `$orange-primary` | `#FF5C00` | Primary brand color |
|
|
| `$orange-light` | `#FF8A4C` | Light accent |
|
|
| `$green-success` | `#22C55E` | Success states |
|
|
| `$text-primary` | `#FFFFFF` | Primary text |
|
|
| `$text-secondary` | `#ADADB0` | Secondary text |
|
|
| `$text-tertiary` | `#8B8B90` | Tertiary text |
|
|
| `$text-muted` | `#FFFFFFCC` | Muted text (80% opacity) |
|
|
| `$text-disabled` | `#6B6B70` | Disabled text |
|
|
| `$border-default` | `#2A2A2E` | Default borders |
|
|
| `$border-subtle` | `#1F1F23` | Subtle borders |
|
|
|
|
---
|
|
|
|
## 🔄 Workflow
|
|
|
|
### Creating New Pages
|
|
|
|
1. **Start with Component Library**
|
|
```
|
|
Open: components/tPOS-ui-kit.pen
|
|
```
|
|
|
|
2. **Copy Base Components**
|
|
- Select components you need
|
|
- Copy to clipboard
|
|
|
|
3. **Create New Page**
|
|
- Open target page file (desktop/mobile/tablet)
|
|
- Paste components
|
|
- Arrange layout
|
|
|
|
4. **Maintain Consistency**
|
|
- Always reference `tPOS-ui-kit.pen` for latest components
|
|
- Use design variable names (e.g., `$orange-primary`) instead of hex codes
|
|
- Keep component IDs unique across pages
|
|
|
|
### Updating Components
|
|
|
|
> [!IMPORTANT]
|
|
> **Current Limitation**: Pencil doesn't support external file references. Components are **copied** into page files, not linked.
|
|
|
|
**To update a component globally**:
|
|
1. Update in `components/tPOS-ui-kit.pen`
|
|
2. Manually copy updated component
|
|
3. Replace in each page file where used
|
|
|
|
**Future Enhancement**: When Pencil adds cross-file linking, components will auto-update.
|
|
|
|
---
|
|
|
|
## 📊 File Size Comparison
|
|
|
|
| Metric | Before (Monolith) | After (Split) | Improvement |
|
|
|--------|-------------------|---------------|-------------|
|
|
| Largest file | 9,118 lines (328KB) | 3,181 lines (118KB) | **64% smaller** |
|
|
| Load time | ~2-3 seconds | ~0.5-1 second | **3x faster** |
|
|
| Maintainability | Low (duplicate components) | High (single source) | ✅ |
|
|
| Collaboration | Hard (merge conflicts) | Easy (separate files) | ✅ |
|
|
|
|
---
|
|
|
|
## ✅ Benefits
|
|
|
|
✓ **Performance**: Each file 3-4x smaller, loads faster
|
|
✓ **Maintainability**: Component library as single source of truth
|
|
✓ **Collaboration**: Multiple designers work on different pages
|
|
✓ **Reusability**: Component library for new projects
|
|
✓ **Version Control**: Clear Git diffs
|
|
✓ **Scalability**: Easy to add pages/components
|
|
|
|
---
|
|
|
|
## 🚀 Next Steps
|
|
|
|
1. **Review Pages**: Open each page file in Pencil to verify
|
|
2. **Test Components**: Ensure all components render correctly
|
|
3. **Share with Team**: Distribute usage guide to designers
|
|
4. **Version Control**: Commit new structure to Git
|
|
5. **Archive Original**: Keep `tPOS.pen.backup` as reference
|
|
|
|
---
|
|
|
|
## 💡 Tips
|
|
|
|
- **Keep component library updated**: Always update `tPOS-ui-kit.pen` first before pages
|
|
- **Use design tokens**: Reference variables like `$bg-page` instead of `#0A0A0B`
|
|
- **Document changes**: Update this guide when adding new components
|
|
- **Backup regularly**: Keep versioned backups before major changes
|
|
- **Test responsive**: Verify designs across all breakpoints
|
|
|
|
---
|
|
|
|
**Questions?** Reference the original `implementation_plan.md` in the brain directory.
|
|
|
|
---
|
|
|
|
## Build System
|
|
|
|
### Quick Start
|
|
|
|
```bash
|
|
# Build monolithic file (merge all pages)
|
|
python3 scripts/build.py --monolithic
|
|
|
|
# Output: tPOS.pen (326KB, 4 frames)
|
|
```
|
|
|
|
### Build Modes
|
|
|
|
**1. Monolithic Build** ⭐ (Recommended)
|
|
```bash
|
|
python3 scripts/build.py --monolithic
|
|
# or
|
|
python3 scripts/build.py -m
|
|
```
|
|
|
|
**Output:**
|
|
- File: `tPOS.pen` (project root)
|
|
- Contains: Desktop + Mobile + Tablet + Component Library
|
|
- Use: Open complete design in Pencil, share, archive
|
|
|
|
**2. Standard Build** (Component Linking)
|
|
```bash
|
|
python3 scripts/build.py
|
|
```
|
|
|
|
**Output:**
|
|
- Directory: `build/`
|
|
- Files: Individual pages with injected components
|
|
- Use: Development workflow, testing component refs
|
|
|
|
### Configuration
|
|
|
|
Edit `pencil.config.json`:
|
|
- `componentLibrary`: Path to ui-kit.pen
|
|
- `sourceDir`: Source pages directory
|
|
- `buildDir`: Output for standard build
|
|
|
|
### Help
|
|
|
|
```bash
|
|
python3 scripts/build.py --help
|
|
```
|
|
|
|
## ⚛️ Atomic Design (New)
|
|
|
|
The project now supports Atomic Design structure for better scalability.
|
|
|
|
### Structure
|
|
- **Foundations**: Design tokens/variables (`src/foundations/`)
|
|
- **Atoms**: Basic components like buttons, inputs (`src/atoms/`)
|
|
- **Molecules**: Compound components like search bars (`src/molecules/`)
|
|
- **Organisms**: Complex sections like headers, cards (`src/organisms/`)
|
|
|
|
### Workflow
|
|
|
|
1. **Edit Atomic Components**: Update files in `src/atoms/...`, `src/molecules/...`, etc.
|
|
2. **Build Library**: Run `python3 scripts/build.py --library`. This compiles all atomic components into `src/components/tPOS-ui-kit.pen`.
|
|
3. **Design Pages**: Open your page files (e.g., `src/pages/desktop.pen`) in Pencil. They reference components from `tPOS-ui-kit.pen`.
|
|
4. **Build Monolith**: Run `python3 scripts/build.py --monolithic`. This merges pages and the library into the final `tPOS.pen` for sharing/verification.
|
|
|
|
### Build Commands
|
|
|
|
```bash
|
|
# Step 2: Build Component Library
|
|
python3 scripts/build.py --library
|
|
|
|
# Step 4: Build Monolithic File
|
|
python3 scripts/build.py --monolithic
|
|
```
|
|
```
|