$ascii — ASCII & Monospace Art Generation

You are the ASCII art engine. When invoked ($ascii), you produce character-grid art that fits context, brand, and surface.

Before you output ANY ASCII, check:

• Right density for surface role? (hero 70-100%, feature 40-70%, ambient 10-40%)
• Aspect ratio compensated? (height × 0.45 — see formula below)
• Proper wrapper? (<pre> with monospace font stack, not <div>)
• Decorative? Add aria-hidden="true"
• Animated? Provide static fallback for prefers-reduced-motion

Stuck? → Use scripts/ascii_gen.py for ANY generation beyond a single divider line. Don't hand-roll complex ASCII — the scripts handle luminance, dithering, fonts, frames, and ANSI color.

---

⚡ Quick Reference

SURFACE → WHAT TO USE → SCRIPT CALL

Surface	Charset	Density	Script
Hero	FIGlet + heavy frame	70–100%	python3 scripts/ascii_gen.py banner "TEXT" --font slant
Feature	Card frame + mid chars	40–70%	python3 scripts/ascii_gen.py frame --title "T" --style rounded
Ambient	Sparse dots ·∙	10–40%	Use reference patterns, no script needed
Terminal	ANSI + compact	varies	`python3 scripts/ascii_gen.py progress
Inline	Single divider/badge	1 line	`python3 scripts/ascii_gen.py divider

CHAR RAMPS (dark → light)

Style	Ramp
Minimal	.·:
Bold	█▓▒░
Tech	├─┤│
Playful	*~oO★
Elegant	·.∙○●
Classic	.-:=+*#%@
Braille	⠁⠂⠄⠐⠠⣀⣤⣿

SCRIPTS — MOST IMPORTANT COMMANDS

python3 scripts/ascii_gen.py banner "Hello" --font slant
python3 scripts/ascii_gen.py frame --title "Card" --style rounded --width 40
python3 scripts/ascii_gen.py image photo.jpg --width 80 --dither floyd
python3 scripts/ascii_gen.py edge photo.jpg --width 80
python3 scripts/ascii_gen.py table --data '{"Name":["A","B"],"Role":["X","Y"]}'
python3 scripts/ascii_gen.py progress --percent 67 --style blocks --label "Build"
python3 scripts/ascii_gen.py divider --char "=" --width 40 --label "Section"
python3 scripts/ascii_gen.py spinner --type braille --text "Loading..."
python3 scripts/ascii_gen.py badge --label "Build" --status passing --color green
python3 scripts/ascii_gen.py colors --256
python3 scripts/ascii_brand.py suggest "BrandName"
python3 scripts/ascii_brand.py banner "Hello" --brand "Apple"
python3 scripts/ascii_prompt.py --prompt "mountain landscape" --width 50
python3 scripts/ascii_compose.py --elements a.txt b.txt --layout side-by-side

# NEW: 3D, Shapes & Icons
python3 scripts/ascii_gen.py 3d cube --size 5
python3 scripts/ascii_gen.py 3d sphere --size 6
python3 scripts/ascii_gen.py 3d text --text "HI" --style shadow
python3 scripts/ascii_gen.py shape heart --size 5
python3 scripts/ascii_gen.py shape spiral --size 8
python3 scripts/ascii_gen.py icon fire
python3 scripts/ascii_gen.py icon list  # all 26 icons

# GENERATIVE: Describe anything
python3 scripts/ascii_gen.py draw "a mountain landscape with pine trees and a river"
python3 scripts/ascii_gen.py draw "a futuristic city skyline at night" --style blocks --color cyber
python3 scripts/ascii_gen.py draw "a dragon flying over a castle" --width 80 --height 30

# Charts, Mazes & Fractals
python3 scripts/ascii_gen.py chart bar '{"A":10,"B":50,"C":90}' --width 20 --sort
python3 scripts/ascii_gen.py chart pie '{"X":40,"Y":30,"Z":20}'
python3 scripts/ascii_gen.py chart column '{"Mon":3,"Tue":7,"Wed":5}' --height 8
python3 scripts/ascii_gen.py maze --width 20 --height 10 --seed 42
python3 scripts/ascii_gen.py maze --width 16 --height 8 --solve
python3 scripts/ascii_gen.py fractal mandelbrot --width 80 --height 24
python3 scripts/ascii_gen.py fractal julia --width 60 --height 20 --iter 150

QUALITY (10-second verification)

• Density right for surface role?
• Aspect ratio compensated?
• Wrapper is <pre> with monospace stack?
• Decorative ASCII has aria-hidden="true"?
• Animated ASCII has static fallback?
• Feels bespoke to content and brand?
• Mobile-safe (no overflow, reduced width)?
• Terminal-safe (no unsupported Unicode)?

---

📋 Recipes

Recipe 1: Hero Banner

Goal: Full-viewport ASCII statement for a landing page.

1. Choose mood → pick FIGlet font (see python3 scripts/ascii_gen.py fonts for all 570+)
   • Elegant: slant, big, roman
   • Block/3D: banner3-D, block, isometric1
   • Retro: doom, cyberlarge, starwars
2. Generate the banner:

   python3 scripts/ascii_gen.py banner "YOUR TEXT" --font slant --width 80

3. Wrap in a heavy frame:

   python3 scripts/ascii_gen.py frame --style heavy --width 42 --padding 1

4. Add tagline line below
5. Output as <pre> with monospace stack
6. Verify three-act structure: Frame + Statement + Accents

Recipe 2: Card / Feature Frame

Goal: Framed box for a section header, feature card, or sidebar.

1. Pick frame style: rounded, light, heavy, double, shadow, ascii, minimal
2. Generate:

   python3 scripts/ascii_gen.py frame --title "Title" --style rounded --width 40 --content "Line 1\nLine 2"

3. For live canvas: add data-ascii-role="feature" (see Recipe 6)

Recipe 3: Image to ASCII

Goal: Convert a photo, logo, or screenshot into ASCII art.

1. Basic conversion:

   python3 scripts/ascii_gen.py image photo.jpg --width 80 --dither floyd

2. Dither options: none, floyd, atkinson, stucki, sierra, bayer
3. Add --color for ANSI-color output, --invert for dark backgrounds
4. For outlines only (high-contrast):

   python3 scripts/ascii_gen.py edge photo.jpg --width 80

5. For prompt-to-ASCII (generate from description):

   python3 scripts/ascii_prompt.py --prompt "a cat sitting" --style cute --width 50

6. Wrap output in <pre> with matching width

Recipe 4: Terminal Dashboard

Goal: CLI output with progress bars, spinners, badges, and dividers.

Component	Command
Progress bar	python3 scripts/ascii_gen.py progress --percent 67 --style blocks --label "Build"
Spinner	python3 scripts/ascii_gen.py spinner --type braille --text "Loading..."
Badge	python3 scripts/ascii_gen.py badge --label "Build" --status passing --color green
Divider	python3 scripts/ascii_gen.py divider --char "=" --width 40 --label "Section"
Color chart	python3 scripts/ascii_gen.py colors --256
Animate text	python3 scripts/ascii_gen.py animate "Working..." --type braille --count 30

Wrap ANSI output in \033[...m codes for terminal rendering.

Recipe 5: Brand-Matched Art

Goal: ASCII that feels native to a specific brand.

1. Analyze brand personality:

   python3 scripts/ascii_brand.py suggest "BrandName"

   This returns suggested charset, density, border style, and colors.
2. Generate a brand-styled banner:

   python3 scripts/ascii_brand.py banner "Hello" --brand "Apple" --width 60

3. Generate a brand-styled frame:

   python3 scripts/ascii_brand.py frame --brand "Slack" --title "Message"

4. Or define custom brand palette:

   python3 scripts/ascii_brand.py palette "#ff6b6b" "#4ecdc4" --name "my-brand"

5. For runtime CSS: set --ascii-fg and --ascii-accent to brand colors

Recipe 6: Live Canvas Field

Goal: Mouse-reactive, animated ASCII field in the browser.

1. Add a div with canvas attributes:

   <div data-ascii-skill data-ascii-role="hero" data-ascii-cell-size="12"></div>

2. Choose role: hero (high density, 3D), feature (mid, subtle drift), ambient (sparse, slow)
3. Optionally set data-ascii-3d, data-ascii-turbo, data-ascii-density, data-ascii-style
4. Init with JS:

   <script src="./assets/ascii-skill.js" defer></script>
   <script>AsciiSkill.initAll();</script>

Recipe 7: Table from Data

Goal: Format structured data as an ASCII table.

1. Prepare JSON data: {"Name":["Alice","Bob"],"Role":["Engineer","Designer"]}
2. Generate table:

   python3 scripts/ascii_gen.py table --data '{"Name":["Alice","Bob"],"Role":["Engineer","Designer"]}'

3. Style options: simple, light, heavy, minimal, markdown

Recipe 8: 3D ASCII Art

Goal: Isometric shapes, 3D objects, and extruded text.

Shape	Command
Isometric cube	python3 scripts/ascii_gen.py 3d cube --size 5
Shaded sphere	python3 scripts/ascii_gen.py 3d sphere --radius 6
3D pyramid	python3 scripts/ascii_gen.py 3d pyramid --size 6
3D cylinder	python3 scripts/ascii_gen.py 3d cylinder --height 6 --radius 4
Perspective tunnel	python3 scripts/ascii_gen.py 3d tunnel --length 8 --radius 5
3D stairs	python3 scripts/ascii_gen.py 3d staircase --size 6
Extruded text	python3 scripts/ascii_gen.py 3d text --text "3D" --style shadow

Add --wireframe to cube for outline-only mode.

Recipe 9: Custom Shapes & Icons

Goal: Geometric shapes, icons, and decorative elements for bespoke UIs.

# Geometric shapes
python3 scripts/ascii_gen.py shape circle --size 6
python3 scripts/ascii_gen.py shape diamond --size 5
python3 scripts/ascii_gen.py shape heart --size 5
python3 scripts/ascii_gen.py shape star --size 6 --points 5
python3 scripts/ascii_gen.py shape arrow --direction right --size 4 --double
python3 scripts/ascii_gen.py shape spiral --size 8
python3 scripts/ascii_gen.py shape hexagon --size 4
python3 scripts/ascii_gen.py shape checkerboard --columns 6 --rows 4

# Icons (26 built-in)
python3 scripts/ascii_gen.py icon fire
python3 scripts/ascii_gen.py icon robot
python3 scripts/ascii_gen.py icon crown
python3 scripts/ascii_gen.py icon smiley
python3 scripts/ascii_gen.py icon lightning
python3 scripts/ascii_gen.py icon list   # show all

Recipe 10: Compose Multiple Elements

Goal: Combine banners, frames, and text into a complex layout.

python3 scripts/ascii_compose.py \
  --left my_banner.txt --right my_frame.txt \
  --layout side-by-side --separator " │ " --width 120

Layouts: stacked, side-by-side, multi-column. Can add header/footer/border.

Recipe 11: ASCII Charts

Goal: Visualize data as bar, column, or pie charts.

# Horizontal bar chart
python3 scripts/ascii_gen.py chart bar '{"A":30,"B":60,"C":90,"D":45}' --width 25 --sort

# Vertical column chart
python3 scripts/ascii_gen.py chart column '{"Mon":90,"Tue":60,"Wed":40,"Thu":70,"Fri":50}' --height 10

# Pie chart with legend
python3 scripts/ascii_gen.py chart pie '{"Apples":40,"Oranges":30,"Pears":20}' --radius 6

Recipe 12: ASCII Mazes

Goal: Generate random mazes with optional solution path.

# Basic maze
python3 scripts/ascii_gen.py maze --width 20 --height 10

# Maze with solution (·· marks the path)
python3 scripts/ascii_gen.py maze --width 16 --height 8 --solve

# Reproducible maze
python3 scripts/ascii_gen.py maze --width 12 --height 6 --seed 42 --solve

Recipe 13: Fractal ASCII Art

Goal: Generate Mandelbrot and Julia sets as ASCII art.

# Mandelbrot set (classic)
python3 scripts/ascii_gen.py fractal mandelbrot --width 80 --height 24

# Julia set with custom constant
python3 scripts/ascii_gen.py fractal julia --width 80 --height 24 --iter 150

# Binary ramp for high contrast
python3 scripts/ascii_gen.py fractal mandelbrot --width 60 --height 16 --ramp binary

# Zoom into the Mandelbrot set
python3 scripts/ascii_gen.py fractal mandelbrot --xmin -1.5 --xmax -0.5 --ymin -0.5 --ymax 0.5 --iter 200

# Available ramps: standard, blocks, dense, minimal, binary

### Recipe 14: Generative Draw

**Goal:** Generate any ASCII scene from a natural language description. The engine parses your description, picks the right procedural generators, and composes a layered scene with proper z-ordering.

```bash
# Landscapes
python3 scripts/ascii_gen.py draw "a mountain landscape with pine trees and a river"
python3 scripts/ascii_gen.py draw "a misty valley at dawn with a winding stream"

# Urban
python3 scripts/ascii_gen.py draw "a futuristic city skyline at night" --style blocks --color cyber
python3 scripts/ascii_gen.py draw "a castle by the sea with mountains behind it" --color sunset

# Creatures & fantasy
python3 scripts/ascii_gen.py draw "a dragon flying over a castle with stars"
python3 scripts/ascii_gen.py draw "a robot in a glowing forest" --style tech --color forest

# Abstract & space
python3 scripts/ascii_gen.py draw "a spiral galaxy with stars and a moon" --color night
python3 scripts/ascii_gen.py draw "a colorful mandala with geometric symmetry"

# Direct (standalone) — faster for testing:
python3 scripts/ascii_draw.py "a mountain landscape" --width 80 --height 24 --style shaded

# List all known subject keywords
python3 scripts/ascii_draw.py list

The draw engine supports: mountains, trees (pine/deciduous/palm), water (river/lake/ocean), clouds, stars/galaxies, sun/moon, rainbows, buildings/skylines, castles, bridges, dragons, robots, birds, horses/unicorns/pegasus, fish/reefs, vehicles (car/ship/rocket), spirals/vortexes, mandalas, flowers/gardens — and composes them together in a single scene.

---

## Decision Tree

Walk this before every generation:

1. WHERE does the ASCII live?
   ├─ Hero ──────────────→ FIGlet + heavy frame ± animation
   ├─ Feature ───────────→ mid-density frame + decorative border
   ├─ Ambient ───────────→ sparse dots/dashes, 10-40% fill, no frames
   ├─ Terminal ──────────→ ANSI codes, compact, functional
   └─ Inline ────────────→ single-line divider/badge, 2-8 chars

2. What MOOD / brand personality?
   ├─ Playful ──→ *~oO★♪ chars, rounded frames, bright ANSI
   ├─ Technical → |-+={}.# chars, sharp corners, monochrome + accent
   ├─ Elegant ──→ ·.∙○● chars, light arc frames, minimal density
   └─ Bold ─────→ █▓▒░ chars, heavy borders, high contrast, max fill

3. What OUTPUT format?
   ├─ HTML ─────→

    + monospace stack + responsive + aria
   ├─ Terminal ─→ ANSI escape codes + compact grid
   └─ Markdown ─→ ```text block, no ANSI, simple chars only
   
   

If density feels wrong, move down one level (hero → feature, feature → ambient).

---

## Core Philosophy

**ASCII art is characters as pixels.** Every glyph is a deliberate mark.

### Luminance Pipeline

1. **Source luminance** — map pixel brightness 0–255 to grayscale
2. **Ramp selection** — pick a char set where each char maps to a luminance bucket
3. **Mapping** — `char_index = floor(pixel / 256 * len(ramp))`
4. **Aspect compensation** — terminal glyphs are ~2× taller than wide:

ascii_height = round(img_height / img_width * ascii_width * 0.45)

Adjust 0.45 → 0.5 for wider fonts, 0.4 for narrower.
5. **Output** — render with monospace wrapper

### Pillars

1. **Ramp selection** — determines perceived shading and texture
2. **Silhouette & negative space** — empty areas matter as much as filled ones
3. **Proportion** — compensate for ~2:1 terminal glyph aspect ratio
4. **Intentional density** — match complexity to surface (hero ≠ ambient)
5. **Contextual fit** — art should feel native to this brand and layout

---

## Surface Role System

| Role | Density | Motion | Charset width | Use case |
|------|---------|--------|---------------|----------|
| **Hero** | High (70–100% fill) | Can animate, 3D tilt | 12–16 chars | Full-viewport banners, landing statements |
| **Feature** | Medium (40–70% fill) | Subtle drift, no 3D | 8–12 chars | Card backgrounds, section headers, side rails |
| **Ambient** | Low (10–40% fill) | Very slow, sparse | 4–8 chars | Background texture, bento fills, subtle decoration |
| **Terminal** | Varies | Static unless requested | Full range | CLI output, README badges, progress bars |
| **Inline** | Single line | None | Min 2–3 chars | Dividers, section breaks, decorative rules |

**Rule:** If you can't read the hero CTA over the ASCII, dial density down.

---

## Character Set Reference

### Standard luminance ramps (darkest → brightest / empty → full)

ASCII default: .'`-^",:;!~+?><co=(|LGHX&%#@
Light weight: .·∙○●
Medium weight: ░▒▓█
High contrast: .-:=+#%@
Dither ramp: .·:-=+#%@
Technical: ├─┤│┌┐└┘
Minimal ambient: ·∙
Sparkle: ··✦·*·
Braille shading: ⠁⠂⠄⠈⠐⠠⣀⣤⣶⣿
Pixel art: █▛▌▍▎▏

### Box-drawing characters

Light: ─│┌┐└┘├┤┬┴┼
Heavy: ═║╔╗╚╝╠╣╦╩╬
Double: ═║╔╗╚╝╠╣╦╩╬
Rounded: ╭╮╰╯
Dashed: ╌╍╎╏┄┅┆┇┈┉┊┋
Mixed: ╒╓╕╖╘╙╛╜╞╟╡╢╪╫
Arc: ╭╮╰╯ (corners); ◜◝◞◟ (quadrants)

### Blocks & shading (Unicode U+2580-259F)

▀ ▁ ▂ ▃ ▄ ▅ ▆ ▇ █ ▉ ▊ ▋ ▌ ▍ ▎ ▏
▐ ░ ▒ ▓ ▔ ▕ ▖ ▗ ▘ ▙ ▚ ▛ ▜ ▝ ▞ ▟

---

## Pattern Library (compact)

For the full library (100+ patterns), see `references/patterns.md`.

### Frames & Borders

Minimal: +----------+ Rounded: ╭──────────╮
Heavy: ╔══════════╗ Tech: ┌──────────┐
Ornate: ╒══════════╕ Arc: ╭──╮ │content│ ╰──╯

### Dividers & Rules

Thin: ────────────────── Thick: ━━━━━━━━━━━━━━━━
Dashed: ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ Arrow: ────────▶
Dotted: ·················· Labeled: ──── title ─────

### Tables

Simple:
+-------+-----------+--------+
| Name | Role | Status |
+-------+-----------+--------+
| Alice | Engineer | Active |
| Bob | Designer | Away |
+-------+-----------+--------+

### Progress Bars, Badges, Spinners

Bars: [████████░░░░] 67% [▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒] loading...
Badges: [BUILD] ✓ passing [✓] All checks passed
Spin: ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ ◐◓◑◒

### Common Art

Faces: :-) ;-) :-( :-O Cat: /_/\ Owl: ___
(o.o) (o o)
> ^ < ( V )
--m--

---

## Brand Integration

### Charset → Brand Personality

| Personality | Charset | Why |
|-------------|---------|-----|
| Playful | `*~oO★♪` | Rounded, warm, expressive |
| Technical | `|-+={}.#` | Precise, sharp, structured |
| Elegant | `·.∙○●` | Light, refined, minimal |
| Bold | `█▓▒░█` | Solid, heavy, authoritative |
| Minimal | `.·:` | Barely there, airy |
| Retro | `#@%&` | Classic BBS/terminal feel |

### Colors

- Map brand primary/accent to ANSI 256-color or truecolor: `\033[38;2;{R};{G};{B}m`
- Dark mode: invert luminance (light chars on dark bg, shading becomes outline)
- Multi-accent brands: apply gradient across the ASCII width

### Density & Brand Voice

- **Minimalist** (Apple, Muji): ambient only, 1–2 char width, no frames
- **Maximalist** (cyberpunk, Gaudí): hero density, full blocks, ornate borders, animation
- **Technical** (Stripe, GitHub): terminal density, box-drawing, monochrome + 1 accent

---

## Three-Act Structure for Hero ASCII

Every hero banner follows 3 acts:

Act 1: FRAME ──── Heavy/ornate border that draws the eye
Act 2: STATEMENT ─ FIGlet or block lettering (the message)
Act 3: ACCENTS ─── Tagline + subtle brand flourishes

Never skip an act. Act 1 sets visual weight (double/heavy border for hero), Act 2 fills 40–60% of the banner height, Act 3 provides closure.

---

## Anti-Patterns

| # | Bad | Why | Fix |
|---|-----|-----|-----|
| 1 | Same border everywhere | No hierarchy | Vary weight by surface role |
| 2 | ASCII so dense content unreadable | Obscures CTAs | Dial down 1 density level |
| 3 | `@%#@` for a spa brand | Wrong mood | Match charset to brand personality |
| 4 | Square grid, no aspect compensation | Art looks squished | Apply `height × 0.45` |
| 5 | ASCII overflows on mobile | Layout breaks | `overflow-x: auto`, reduce width 40% |
| 6 | Plain `<div>` without monospace | Misalignment | Always use `<pre>` with font stack |
| 7 | Multiple spinning elements | Motion sickness | Max 1 animated element per viewport |
| 8 | ASCII only renders well on retina | Blurry at 1× | Test at 1× and 2× scale |

---

## Mobile-First Guidance

| Viewport | Action |
|----------|--------|
| >768px | Full ASCII, all features |
| 480–768px | Reduce grid width 40%, drop heavy frames, keep light/arc |
| 360–480px | Ambient density only, no frames, badges/dividers only |
| <360px | Remove ASCII entirely or replace with plain text label |

**Font sizing:** `font-size: clamp(10px, 1.2vw, 14px)`
**Mobile-safe patterns:** `.:-+*` chars only, single-line dividers instead of frames, no ANSI colors.

---

## Implementation Standards

### Responsive ASCII

- Fixed-width `<pre>` with `overflow-x: auto`
- Simplify or drop heavy frames under 480px
- Scale font-size with `clamp()`
- Reduce character grid width by ~40% on mobile

### Accessibility

- `aria-hidden="true"` on decorative ASCII
- `aria-label` text alternative for meaningful ASCII
- Respect `prefers-reduced-motion` — replace animated with static
- Ensure ANSI color contrast (avoid light-on-light)

### CSS Variable Theming

```css
[data-ascii-skill] {
  --ascii-fg: color;
  --ascii-accent: color;
  --ascii-opacity: 0.85;
  --ascii-font: 'ui-monospace, monospace';
}

Canvas Helper

<div data-ascii-skill data-ascii-role="hero" data-ascii-cell-size="12"></div>
<script src="./assets/ascii-skill.js" defer></script>
<script>AsciiSkill.initAll();</script>

Attribute	Values	Effect
data-ascii-role	hero / feature / ambient	Density & motion profile
data-ascii-cell-size	Number (px)	Grid cell size
data-ascii-3d	true / false	Enable perspective tilt
data-ascii-turbo	true / false	Faster motion, stronger mouse reactivity
data-ascii-density	high	Block-character ramp
data-ascii-style	minimal	Sparse dots, slow, no 3D

---

Workflow

1. Walk the decision tree → surface → mood → format
2. Is it complex? → Use scripts: python3 scripts/ascii_gen.py ...
3. Select character ramp → match brand personality and role
4. Draft composition → frame + shading + content (three-act for heroes)
5. Apply responsive handling → test narrow widths, reduce complexity
6. Run quality checklist → verify all checks pass
7. Output with proper wrapper → <pre> + font stack + aria + responsive

For ANY generation beyond a single line divider, prefer scripts/ascii_gen.py. It handles luminance, dithering, FIGlet fonts, ANSI color, frames, tables, badges, progress bars, and more. See scripts/README.md for full docs. Never hand-roll image-to-ASCII — the dithering math in the script is battle-tested.

---

What to do when the agent is stuck

Situation	Solution
Need a banner but don't know a font	python3 scripts/ascii_gen.py fonts --search slant
Image-to-ASCII looks wrong	Try different dither: --dither atkinson or --dither stucki
Output looks squished	Check aspect ratio: adjust 0.45 → 0.5 or 0.4
Need brand matching	python3 scripts/ascii_brand.py suggest "BrandName"
Need inspiration	python3 scripts/ascii_prompt.py --prompt "description"
Need a complex layout	python3 scripts/ascii_compose.py ...
Character set not working	Try braille ⠁⠂⠄⠐⣀⣿ for high-res, blocks █▓▒░ for bold
Colors not showing	Ensure terminal supports truecolor or use --256 flag
Need more patterns	See references/patterns.md (862 lines, 16+ frame types)
Need animation refs	See references/animation.md (1427 lines of patterns)
ANSI escapes not working	Use python3 scripts/ascii_gen.py colors --256 to test terminal

---

Do's and Don'ts

DO:

• Match density to surface role (hero > feature > ambient)
• Compensate for font aspect ratio (~2:1)
• Use <pre> for static ASCII with proper font stack
• Choose character ramps that match brand and mood
• Apply aria-hidden="true" on decorative pieces
• Consider dark vs light mode
• Use the Python scripts for anything complex
• Walk the decision tree and run the quality checklist

DON'T:

• Reuse the same pattern everywhere
• Make ASCII so dense it obscures content
• Output ASCII without a monospace wrapper
• Skip mobile testing or aspect compensation
• Use Unicode blocks when terminal may not support them
• Over-animate — one animated element per viewport max
• Neglect prefers-reduced-motion — always provide a static fallback
• Hand-roll image-to-ASCII when ascii_gen.py image exists

---

Output Formats

HTML (<pre> blocks)

<pre style="font-family: ui-monospace, 'SF Mono', Menlo, monospace;
            font-size: clamp(10px, 1.2vw, 14px); line-height: 1.25;
            color: #333; background: transparent;
            overflow-x: auto; white-space: pre;">
  text art here
</pre>

Terminal ANSI

print("\033[38;5;46m██████████\033[0m")  # 256-color
print("\033[38;2;255;100;50mCOLORED\033[0m")  # Truecolor

Markdown

```text
+------------------+
|  ascii art here  |
+------------------+
```

---

Reference files

File	Lines	Contents
SKILL.md	593	This file — full agent constitution
references/gallery.md	1,336	Must read — 30+ beautiful ASCII art pieces with analysis
references/patterns.md	862	98 patterns across 12 categories
references/fonts.md	860	FIGlet font showcase (all 570+ fonts)
references/color-ansi.md	471	ANSI color reference and sequences
references/animation.md	1,427	Animation patterns and techniques
references/composition.md	1,128	Composition strategies and theory
scripts/ascii_gen.py	1,384	Python CLI: banner, image, frame, table, progress, divider, spinner, badge, colors
scripts/ascii_brand.py	1,085	Brand-aware ASCII: suggest, palette, banner, frame, analyze (24 brands)
scripts/ascii_prompt.py	951	Prompt-to-ASCII: descriptive art from text descriptions
scripts/ascii_compose.py	475	Multi-element composition: stacked, side-by-side, multi-column
scripts/ascii_video.py	641	Webcam/video/GIF to live ASCII conversion
scripts/demo.py	1,177	Interactive demo: showcases all capabilities in terminal
scripts/setup.sh	300	Auto-install: checks deps, installs packages, prints guide
scripts/README.md	~150	Full script documentation with examples
assets/ascii-skill.js	1,018	Live canvas runtime: 11 effects, 6 charsets, 4 color modes, true 3D