gh-trabian-fluxwing-skills/skills/fluxwing-component-creator/docs/06-ascii-patterns.md

# ASCII Patterns - Visual Toolkit

Complete library of ASCII characters and patterns for uxscii components.

## Box-Drawing Characters

### Basic Borders

**Light (Default)**
```
┌─────┐
│ Box │
└─────┘
```
Characters: `┌ ─ ┐ │ └ ┘`

**Rounded (Friendly)**
```
╭─────╮
│ Box │
╰─────╯
```
Characters: `╭ ─ ╮ │ ╰ ╯`

**Double (Emphasis)**
```
╔═════╗
║ Box ║
╚═════╝
```
Characters: `╔ ═ ╗ ║ ╚ ╝`

**Heavy (Strong)**
```
┏━━━━━┓
┃ Box ┃
┗━━━━━┛
```
Characters: `┏ ━ ┓ ┃ ┗ ┛`

### Complex Borders

**With Dividers**
```
┌─────────┬─────────┐
│  Col 1  │  Col 2  │
├─────────┼─────────┤
│  Data   │  Data   │
└─────────┴─────────┘
```

**Nested**
```
╭─────────────────╮
│ Outer           │
│ ┌─────────────┐ │
│ │ Inner       │ │
│ └─────────────┘ │
╰─────────────────╯
```

## Component State Patterns

### Buttons

**Default**
```
▓▓▓▓▓▓▓▓▓▓
▓ Click  ▓
▓▓▓▓▓▓▓▓▓▓
```

**Hover (Highlighted)**
```
░▓▓▓▓▓▓▓▓▓▓░
░▓ Click  ▓░
░▓▓▓▓▓▓▓▓▓▓░
```

**Focus (Ring)**
```
┏━━━━━━━━━━┓✨
┃  Click   ┃
┗━━━━━━━━━━┛
```

**Disabled (Grayed)**
```
┌ ─ ─ ─ ─ ┐
│  Click  │
└ ─ ─ ─ ─ ┘
```

**Pressed/Active**
```
▓▓▓▓▓▓▓▓▓▓
▓▓Click ▓▓
▓▓▓▓▓▓▓▓▓▓
```

### Form Inputs

**Text Input (Empty)**
```
[____________________]
```

**Text Input (Filled)**
```
[john@example.com    ]
```

**Text Input (Focus)**
```
┏━━━━━━━━━━━━━━━━━━━━┓
┃john@example.com│   ┃
┗━━━━━━━━━━━━━━━━━━━━┛
```

**Text Input (Error)**
```
[invalid-email       ]⚠️
❌ Please enter valid email
```

**Text Input (Success)**
```
[john@example.com    ]✅
```

**Text Input (Disabled)**
```
[────────────────────]
```

**Password (Masked)**
```
[••••••••            ]
```

**Password (With Toggle)**
```
[••••••••            ]👁️
```

### Checkboxes & Radios

**Checkbox (Unchecked)**
```
[□] Option 1
```

**Checkbox (Checked)**
```
[✓] Option 1
```

**Checkbox (Indeterminate)**
```
[▬] Option 1
```

**Radio (Unselected)**
```
○ Option A
```

**Radio (Selected)**
```
◉ Option A
```

### Selects & Dropdowns

**Select (Closed)**
```
[Choose option ▼]
```

**Select (Open)**
```
[Current option ▼]
╭────────────────╮
│ Option 1       │
│ ● Option 2     │
│ Option 3       │
╰────────────────╯
```

### Sliders

**Slider (Basic)**
```
├────────●───────┤
0%              100%
```

**Slider (With Value)**
```
├────────●───────┤ 45%
```

**Range Slider**
```
├────●────●──────┤
   20%   80%
```

## Status Indicators

### Icons

**Success**: ✅ ✓ ●
**Error**: ❌ ✗ ⚠️ ⛔
**Warning**: ⚠️ ⚡ △
**Info**: ℹ️ ⓘ ◉
**Loading**: ⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏

### Progress Bars

**Loading (40%)**
```
████▓▓▓▓▓▓ 40%
```

**Loading (Indeterminate)**
```
▓▓▓░░░░░░░
```

**Steps**
```
● ━━━ ● ━━━ ○ ━━━ ○
```

### Badges

**Count Badge**
```
[Inbox] ●3
```

**Status Badge**
```
● Online
○ Offline
```

**Label Badge**
```
▓ New ▓
```

## Data Display

### Lists

**Unordered**
```
• Item 1
• Item 2
• Item 3
```

**Ordered**
```
1. First
2. Second
3. Third
```

**Nested**
```
• Parent
  ├─ Child 1
  ├─ Child 2
  └─ Child 3
```

### Tables

**Simple**
```
┌─────┬─────┬─────┐
│ A   │ B   │ C   │
├─────┼─────┼─────┤
│ 1   │ 2   │ 3   │
│ 4   │ 5   │ 6   │
└─────┴─────┴─────┘
```

**With Header**
```
╔═══════╦═══════╦═══════╗
║ Name  ║ Email ║ Status║
╠═══════╬═══════╬═══════╣
║ Alice ║ a@... ║ ✓     ║
║ Bob   ║ b@... ║ ○     ║
╚═══════╩═══════╩═══════╝
```

### Cards

**Basic**
```
╭─────────────╮
│ Title       │
├─────────────┤
│ Content...  │
╰─────────────╯
```

**With Actions**
```
╭─────────────────────╮
│ Card Title          │
├─────────────────────┤
│ Content goes here   │
│                     │
│        [Action] ─┐  │
╰─────────────────────╯
```

**Metric Card**
```
╭───────────╮
│ Revenue   │
├───────────┤
│ $24,567   │
│ +12.5% ↗  │
╰───────────╯
```

## Navigation

### Tabs

**Horizontal**
```
[Active] [Tab 2] [Tab 3]
─────────
Content for active tab
```

**Vertical**
```
┌─ ● Tab 1
├─ ○ Tab 2
└─ ○ Tab 3
```

### Breadcrumbs

```
Home > Products > Details
```

### Pagination

```
‹ Prev  [1] 2 3 4 5  Next ›
```

### Menu

**Dropdown**
```
File ▼
╭──────────╮
│ New      │
│ Open     │
│ Save     │
├──────────┤
│ Exit     │
╰──────────╯
```

**Sidebar**
```
╭─────────╮
│ • Home  │
│ • Users │
│ • Data  │
│ • Info  │
╰─────────╯
```

## Modals & Overlays

### Modal

**Simple**
```
╔═══════════════════╗
║ Modal Title       ║
╠═══════════════════╣
║ Content here...   ║
║                   ║
║     [OK] [Cancel] ║
╚═══════════════════╝
```

**With Close**
```
╔═══════════════════╗✕
║ Title             ║
╠═══════════════════╣
║ Content...        ║
╚═══════════════════╝
```

### Toast/Alert

**Success**
```
╭─────────────────╮
│ ✅ Saved!       │
╰─────────────────╯
```

**Error**
```
╭─────────────────────╮
│ ❌ Error: Try again │
╰─────────────────────╯
```

**Warning**
```
╭────────────────────╮
│ ⚠️ Warning message │
╰────────────────────╯
```

## Arrows & Indicators

### Directional
```
↑ ↓ ← →
↗ ↘ ↙ ↖
⬆ ⬇ ⬅ ➡
▲ ▼ ◀ ▶
```

### Trend
```
↗️ Up trend
→ Flat
↘️ Down trend
```

### Expand/Collapse
```
▼ Expanded
▶ Collapsed
```

## Spacing & Alignment

**CRITICAL FOR SCREEN RENDERING**: These rules prevent alignment issues in `.rendered.md` files.

### 1. Boundary Alignment - Content MUST Stay Inside Borders

**Golden Rule**: All text and content MUST be contained within component borders. Nothing floats outside.

**❌ INCORRECT - Text outside borders:**
```
╔════════════════════════════════════════╗
║                                        ║
║        Video Title Here                ║
║                            ┌─────────┐ ║
║                            │  12:34  │ ║
╚════════════════════════════└─────────┘═╝

Video Title Here                            ← WRONG: Outside the box!
MrBeast ✓                                   ← WRONG: Floating metadata!
24M views · 2 days ago
```

**✅ CORRECT - All content inside borders:**
```
╔════════════════════════════════════════╗
║                                        ║
║        Video Title Here                ║
║                            ┌─────────┐ ║
║                            │  12:34  │ ║
║                                        ║
║  Video Title Here                      ║
║  MrBeast ✓                             ║
║  24M views · 2 days ago                ║
╚════════════════════════════════════════╝
```

**Rule**: If a box has borders, ALL related content must appear between those borders.

### 2. Vertical Spacing - Consistent Gaps Between Components

**Standard vertical gaps:**
- **1 line** - Tight spacing (related items within same section)
- **2 lines** - Standard spacing (between different components)
- **3 lines** - Section dividers (major layout breaks)

**❌ INCORRECT - Inconsistent spacing:**
```
╭────────────╮
│ Button 1   │
╰────────────╯
╭────────────╮
│ Button 2   │
╰────────────╯


╭────────────╮
│ Button 3   │
╰────────────╯
```

**✅ CORRECT - Consistent 2-line gaps:**
```
╭────────────╮
│ Button 1   │
╰────────────╯

╭────────────╮
│ Button 2   │
╰────────────╯

╭────────────╮
│ Button 3   │
╰────────────╯
```

**Nested component spacing:**
```
╭─────────────────────────────────╮
│ Outer Container                 │
│                                 │  ← 1 line padding
│  ╭─────────────────────────╮   │
│  │ Inner Component         │   │
│  ╰─────────────────────────╯   │
│                                 │  ← 1 line padding
╰─────────────────────────────────╯
```

### 3. Horizontal Alignment - Consistent Padding and Text Columns

**Standard left padding:**
- **2 characters** - Minimum readable padding (compact layouts)
- **4 characters** - Standard padding (default for most screens)
- **6 characters** - Generous padding (spacious layouts)

**❌ INCORRECT - No padding, text against border:**
```
╭────────────────────╮
│Title               │  ← No space after │
│Content here        │
╰────────────────────╯
```

**✅ CORRECT - Consistent 2-char padding:**
```
╭────────────────────╮
│  Title             │  ← 2 spaces after │
│  Content here      │
╰────────────────────╯
```

**Text column alignment:**
```
╭──────────────────────────────────╮
│  Label:        Value             │  ← Aligned columns
│  Name:         Sarah Johnson     │
│  Email:        sarah@example.com │
│  Status:       Active            │
╰──────────────────────────────────╯
```

**Center alignment for titles:**
```
╭──────────────────────────────────╮
│                                  │
│         Welcome Back             │  ← Centered
│      Sign in to continue         │  ← Centered
│                                  │
╰──────────────────────────────────╯
```

**Right alignment for metadata:**
```
╭──────────────────────────────────╮
│  Post Title                      │
│  u/username · 3h ago       [123] │  ← Right-aligned vote count
╰──────────────────────────────────╯
```

### 4. Grid Layouts - Multi-Column Screens

**2-column grid with proper spacing:**

**❌ INCORRECT - Inconsistent gaps, misaligned:**
```
╭──────────╮╭──────────╮  ← No gap
│ Card 1   ││ Card 2   │
╰──────────╯╰──────────╯

╭──────────╮   ╭──────────╮  ← Different gap
│ Card 3   │   │ Card 4   │
╰──────────╯   ╰──────────╯
```

**✅ CORRECT - Consistent 2-char gaps, aligned columns:**
```
╭──────────╮  ╭──────────╮
│ Card 1   │  │ Card 2   │
╰──────────╯  ╰──────────╯

╭──────────╮  ╭──────────╮
│ Card 3   │  │ Card 4   │
╰──────────╯  ╰──────────╯
```

**3-column grid:**
```
╭────────╮  ╭────────╮  ╭────────╮
│ Card 1 │  │ Card 2 │  │ Card 3 │
╰────────╯  ╰────────╯  ╰────────╯

╭────────╮  ╭────────╮  ╭────────╮
│ Card 4 │  │ Card 5 │  │ Card 6 │
╰────────╯  ╰────────╯  ╰────────╯
```

**Sidebar + main layout:**
```
╭─────────╮  ╭──────────────────────────────╮
│ Sidebar │  │ Main Content                 │
│         │  │                              │
│ • Home  │  │  ╭─────────────────────╮     │
│ • Users │  │  │ Content Card        │     │
│ • Data  │  │  ╰─────────────────────╯     │
│         │  │                              │
╰─────────╯  ╰──────────────────────────────╯
```

### 5. Screen Composition Rules

**Full screen example combining all rules:**

```
╔══════════════════════════════════════════════════════╗
║                                                      ║
║                   Screen Title                       ║  ← Centered, 1 line padding
║                                                      ║
╠══════════════════════════════════════════════════════╣
║  Navigation Bar                                      ║  ← 2-char padding
╠══════════════════════════════════════════════════════╣
║                                                      ║  ← 1 line section gap
║  ╭────────────────────────╮  ╭────────────────────╮ ║
║  │  Left Card             │  │  Right Card        │ ║  ← 2-col grid, 2-char gap
║  │                        │  │                    │ ║
║  │  Content with 2-char   │  │  Aligned content   │ ║  ← All content inside borders
║  │  left padding          │  │  stays in bounds   │ ║
║  │                        │  │                    │ ║
║  ╰────────────────────────╯  ╰────────────────────╯ ║
║                                                      ║  ← 2 line component gap
║                                                      ║
║  ╭──────────────────────────────────────────────╮   ║
║  │  Full-width Component                        │   ║  ← Centered in parent
║  │                                              │   ║
║  │  Text content properly padded                │   ║
║  │                                              │   ║
║  ╰──────────────────────────────────────────────╯   ║
║                                                      ║
╚══════════════════════════════════════════════════════╝
```

### 6. Common Patterns - Feed Layouts

**YouTube-style feed (CORRECT):**
```
╔═══════════════════════════╗  ╔═══════════════════════════╗
║                           ║  ║                           ║
║     Thumbnail Area        ║  ║     Thumbnail Area        ║
║                           ║  ║                           ║
║               ┌────────┐  ║  ║               ┌────────┐  ║
║               │ 12:34  │  ║  ║               │ 8:45   │  ║
║               └────────┘  ║  ║               └────────┘  ║
║                           ║  ║                           ║
║  DON'T TRY THIS           ║  ║  Watermelon Candy VS REAL ║
║                           ║  ║                           ║
║  MrBeast ✓                ║  ║  Crafty Panda ✓           ║
║  24M views · 2 days ago   ║  ║  543K views · 1 day ago   ║
╚═══════════════════════════╝  ╚═══════════════════════════╝
```

**Reddit-style post feed (CORRECT):**
```
╭──────────────────────────────────────────────────────╮
│  ▲  Which bank offers best savings in 2025?         │
│ 342                                                  │
│  ▼  Posted by u/financeguru · 3h ago                │
│                                                      │
│      I've been researching high-yield savings        │
│      accounts and comparing rates...                 │
│                                                      │
│      💬 156 comments  📤 Share  🔖 Save              │
╰──────────────────────────────────────────────────────╯

╭──────────────────────────────────────────────────────╮
│  ▲  PSA: Chase added Zelle fraud protection          │
│ 289                                                  │
│  ▼  Posted by u/bankwatcher · 5h ago                │
│                                                      │
│      Just got an email that Chase is now offering    │
│      Zelle fraud reimbursement...                    │
│                                                      │
│      💬 87 comments  📤 Share  🔖 Save               │
╰──────────────────────────────────────────────────────╯
```

### 7. Overflow Handling

**When content is too long:**

**❌ INCORRECT - Breaking borders:**
```
╭──────────────╮
│ This is a very long title that goes past the border │
╰──────────────╯
```

**✅ CORRECT - Truncate with ellipsis:**
```
╭──────────────────────────╮
│ This is a very long ti...│
╰──────────────────────────╯
```

**✅ CORRECT - Wrap within bounds:**
```
╭──────────────────────────╮
│ This is a very long      │
│ title that wraps to      │
│ multiple lines           │
╰──────────────────────────╯
```

### 8. Alignment Checklist for Screen Composition

Before saving any `.rendered.md` file, verify:

- [ ] **Boundary**: All text is inside component borders (no floating text)
- [ ] **Vertical**: Consistent gaps between components (1-3 lines)
- [ ] **Horizontal**: Consistent left padding (2-4 chars minimum)
- [ ] **Grid**: Multi-column layouts have aligned columns and consistent gaps
- [ ] **Overflow**: Long content is truncated or wrapped, never breaking borders
- [ ] **Nested**: Inner components have proper padding from outer containers
- [ ] **Metadata**: Related info (timestamps, counts) aligned consistently

### Quick Reference - Standard Measurements

```
Padding (horizontal):   2-4 chars (standard)
Gaps (vertical):        1-2 lines (standard)
Grid gaps:              2 chars (between columns)
Section breaks:         3 lines
Border padding:         1 line top/bottom
```

## Tips for Consistent Patterns

1. **Choose one border style per component** - Don't mix light/rounded/heavy
2. **Use consistent spacing** - Multiples of 4 characters work well
3. **Align related elements** - Keep boxes at same width when stacked
4. **Test in monospace** - Always preview in monospace font
5. **Consider state transitions** - Visual changes should be clear

## Copy-Paste Ready

```
Light box: ┌─┐│└┘
Rounded: ╭─╮│╰╯
Double: ╔═╗║╚╝
Heavy: ┏━┓┃┗┛

Checkbox: [□] [✓]
Radio: ○ ◉
Status: ✅ ❌ ⚠️ ℹ️
Arrows: ↑↓←→ ↗↘
```

Use these patterns to create beautiful, consistent uxscii components!