Introduction

asciicn draws pictures with characters. It is a WebGL2 and Canvas2D engine that turns a tone into a glyph, about 50 shadcn components built on it (ten of them animated city backgrounds), an ASCII Studio for tuning a look, and an agent skill that teaches your coding agent to build new effects on the same engine.

Every component draws real glyphs: letters, block elements, Braille dots, CP437 and PETSCII characters, katakana. Cells snap to whole device pixels, so the text stays sharp at any zoom and on any screen.

What you get

• The engine. ascii-core installs into lib/ascii as plain source: charsets, palettes, cell metrics, the AsciiGrid canvas and mapTones, which turns a grid of tones into glyphs. ascii-shader adds AsciiShader, a WebGL2 renderer that draws a GLSL field as glyphs from a glyph atlas, with colour modes, pointer interaction, audio input and CRT effects. ascii-export saves any frame as .txt, .ans, .svg or .png, and records .webm.
• The components. City skylines, 3D scenes, shader fields, image and video filters, text effects and terminal-style interface pieces, each installable with npx shadcn add. Browse them in the catalog.
• The backgrounds. Ten animated cities, from Tokyo at night to fog over the Golden Gate Bridge. See them in the backgrounds gallery.
• The Studio. /studio lets you pick a background or component, change its charset, colours and CRT effects, and export the frame or the JSX.
• The agent skill. A SKILL.md and references that teach Claude Code, Codex, Cursor and other agents the engine: which charset suits which picture, how to write a field, where to place it on a page, how to colour it from your theme, and how to check it in a browser. Installation adds it to your project.

How ASCII art works here

A picture becomes a grid of cells, each one glyph tall and about half a glyph wide. The engine measures a tone for every cell, from 0 (empty) to 1 (full), and picks the glyph whose ink coverage matches: a space, then . and :, up to # and @. That list of glyphs is a charset.

Some charsets carry more detail than one tone per cell. Braille glyphs hold a 2x4 grid of dots, so a braille cell samples eight points and lights each dot on its own. Quadrant blocks sample 2x2. The edge charset reads the direction of the edge under the cell and draws -, /, | or \ along it.

Colour is separate from the glyph. In mono every glyph uses --ascii-ink. truecolor gives each glyph the colour of its source, ansi16 snaps it to a terminal's 16 colours, duotone maps tone onto a two-or-more stop ramp, and palette uses your theme colours.

Charsets

Pass chars="…" to use your own ramp, from empty to dense. Charsets shows each one.

Ask your agent for any ASCII effect

Once the skill is installed, describe what you want and where it goes. Name the page, the mood, the charset if you have one in mind, and anything that must stay readable:

• "Behind the hero on the home page, add slow Braille contour lines in our accent colour. Keep the headline readable."
• "On the status page, draw the last 90 days of uptime as a row of ANSI blocks, green for up and red for incidents."
• "Make the 404 page a green-phosphor CRT terminal that types out the missing path."
• "Turn the team photos on the about page into ASCII portraits that sharpen into the photo on hover."
• "On the pricing page, redraw our logo in quadrant blocks and have it scramble in when it scrolls into view."

You don't need to know which component or API fits. The skill sends the agent through four steps:

1. Set up the engine. It checks for lib/ascii and installs ascii-core and ascii-shader if they're missing.
2. Pick the technique. A GLSL field on AsciiShader for anything that moves or varies per cell, an AsciiGrid for grids it computes on the CPU (3D meshes, simulations, terminal panes), and the image sampler for photos and video. It reads the closest example for technique and installs one only when it is exactly what you asked for.
3. Build the component. It writes a typed component with props you can tweak, chooses a charset and colour mode that suit the picture, places it behind or inside your content, and colours it from your theme.
4. Check it in a browser. It looks at the result in light and dark mode, at desktop and phone widths and with reduced motion, and fixes what doesn't read.

How the docs are organised

• Get started: this page, Installation and Theming.
• Examples: the catalog, then one page per component, grouped into City skylines, 3D & scenes, Shaders & fields, Media & filters, Text & typography, and Terminal & UI.
• Engine: how lib/ascii works, for when you want to build an effect yourself. Start with the ASCII engine and Write your own.

Principles

• Real glyphs, crisp. Every effect draws characters, never pixel dots, and every cell lands on whole device pixels.
• Your theme, not ours. Glyphs read your --primary and --background tokens through the --ascii-* variables, so they change when your theme changes.
• Quiet by default. Motion is slow. Every animated effect shows one finished frame when the visitor prefers reduced motion, and pauses offscreen and in hidden tabs.
• Real text stays text. ASCII headings and labels are still HTML, so they can be selected, read aloud and indexed. Decorative canvases are hidden from screen readers.
• Source you own. Everything installs as files in your project. You and your agent can read and change all of it.