| name | amw-pretext |
| description | Pretext-driven typography, text measurement, layout, virtualized tables, ASCII-on-canvas, calligrams, 3D/motion text. Triggers on "pretext", "@chenglou/pretext", "text-on-path", "balanced headline", "shrink-wrap text", "virtualized list", "kinetic typography", "auto-fit font". Does NOT claim generic design vocabulary — design-principles retains those. Use when applying pretext-based typography or layout. Trigger with "pretext". |
Pretext
Orchestrated by: SKILL. Do not activate for generic "make the type nice" requests — those stay in the base typography system. Activate only on the narrow triggers above.
Overview
Precision text-layout engine for when CSS flow is insufficient. Wraps @chenglou/pretext — a headless, DOM-free text measurement library — across 81 technique files covering API functions, measurement prerequisites, layout patterns, obstacle-aware flow, kinetic typography, virtualized tables, 3D/motion text, integration patterns, workflow assemblies, and CJK typography. Routes each narrow trigger (shrink-wrap, text-on-path, balanced headline, virtualized list, etc.) to the matching TECH file. Output reuses existing project typography tokens; pretext never introduces new fonts or motion systems.
Instructions
The decide → pick → follow → build → resize → validate workflow runs in six steps:
- Walk the
## Technique selection tree to pick the category.
- Open ONLY the matching
references/TECH-NN-<slug>.md (never the whole catalog).
- Call
prepare() once before any layout call.
- Reuse the project's typography tokens (pretext exposes metrics, not typographic decisions).
- Call
clearCache() on the resize path.
- Validate font-string parity before shipping.
The full step-by-step procedure — with the TECH routing links — lives in _how-to-use.
[_how-to-use.md] Instructions · How to use this skill
Activation
No dedicated slash command — this skill has no matching /amw-* shortcut. Invoked by the design-principles orchestrator during Phase B when the approved design requires precision text layout beyond what CSS flow provides (virtualization, shrink-wrap, obstacle-aware flow, kinetic typography). Also callable directly when the user explicitly names pretext or its API.
This skill is autonomous and self-contained — any agent (the main-agent, a sub-agent, or an external orchestrator) can use it by reading this SKILL.md and its references. The skill's techniques are NOT limited to what matching commands expose.
Position in flow
OUTPUT. Pretext is the precision text-layout engine the plugin reaches for when CSS flow is insufficient (variable-height virtualization, shrink-wrap bubbles, obstacle-aware editorial flow, kinetic typography, auto-fit font search). All pretext-powered output must reuse the project's existing typography tokens — pretext does NOT introduce new fonts or motion systems, it just exposes the per-line metrics.
Technique selection
Always start with the decision guide — if CSS already solves the problem (line-clamp, text-overflow, text-wrap: balance), skip pretext entirely. See TECH-72-use-pretext-decision-guide.
[TECH-72-use-pretext-decision-guide.md] What it does · When to use · How it works · Minimal example · Gotchas · Cross-references
Then route by category (every technique below is one TECH file in references/; full one-line descriptions at _index):
[_index.md] API functions (TECH-01 — TECH-13) · Measurement prerequisites (TECH-14 — TECH-18) · Layout patterns / obstacle routing (TECH-19 — TECH-31) · Typography techniques (TECH-32 — TECH-44) · Motion / interactive demos (TECH-45 — TECH-55) · Tables (TECH-56 — TECH-58) · Integration patterns (TECH-59 — TECH-66) · Workflow assemblies (TECH-67 — TECH-71) · Consult / decision-routing (TECH-72 — TECH-78) · Cross-references
| Category | Range | Coverage |
|---|
| API functions | TECH-01 — TECH-13 | prepare(), layout(), walkLineRanges(), measureLineStats(), clearCache(), setLocale(), prepareRichInline(), profilePrepare() |
| Measurement prerequisites | TECH-14 — TECH-18 | DOM-free paragraph height, textarea pre-wrap parity, CJK keep-all, font-loading sync, font-string parity |
| Layout / obstacle patterns | TECH-19 — TECH-31 | flow around shapes, fit into container, multi-column handoff, balanced headline, auto-fit font, line-clamp truncate, layout-shift prevention, overflow prediction |
| Typography techniques | TECH-32 — TECH-44 | multilingual/bidi/emoji, kinetic width, wavy baseline, text-on-path, generative poster, typographic ASCII, calligrams, glyph mask, illuminated manuscript, variable-font waves, glyph morphing, outline calligram |
| Motion / interactive demos | TECH-45 — TECH-55 | accordions, chat bubbles, editorial spreads, multi-column engines, justification, cycling auto-fit, CSS filters, glyph paths, Three.js, splat editor, variable ASCII canvas |
| Tables | TECH-56 — TECH-58 | virtualized + resizable + sticky-header grid tables |
| Integration patterns | TECH-59 — TECH-66 | React hooks, Svelte/Astro islands, vanilla TS, SSR/Node-canvas, progressive enhancement, wrapper module, single-file ESM, ResizeObserver |
| Workflow assemblies | TECH-67 — TECH-71 | Masonry, virtualized list, SmartPage A4 auto-fit, streaming AI chat, auto-height textarea |
| Consult / route / mobile | TECH-73 — TECH-78 | design-pipeline consult, dragon-text reflow, rich-note atomic pills, postext (RN), font strategy, style profiles |
| CJK typography (JA + ZH stub) | TECH-80 — TECH-81 | Japanese web typography (kinsoku, BudouX <wbr>, word-break:auto-phrase engine matrix, text-align:justify suppression on mobile cards, font-feature-settings:"palt", quoted-phrase protection) + Chinese-typography placeholder |
Output
- Artifacts — HTML pages / JS modules using
@chenglou/pretext (wrapper module, layout component, virtualized table, etc.). Path is inferred from the project (user path → framework convention → ./design/<subtype>/ → fallback ./design/mockups/).
- Job-completion report at
$MAIN_ROOT/reports/webdesigner/<ts±tz>_<title-slug>_<8-char-hash>.md listing every artifact + the per-item checklist verdict.
Full output contract (artifact-path inference rules, report shape, mandatory checklist) lives in TECH-79-output-contract. Before reporting complete: every checklist item there MUST be PASS or N/A. Any FAIL triggers a remediation loop.
[TECH-79-output-contract.md] 1. Artifacts (work product) · 2. Job-completion report (mandatory) · Completion checklist (FAIL on any → remediation loop, do not deliver partial work)
Prerequisites
- Runtime (user installs — NOT auto-installed by the plugin):
@chenglou/pretext via npm / bun — adds ~15 KB to the user's bundle. Documented in each TECH file; not mandatory for every design task.
- Optional runtime companions:
opentype.js@1.3.4 (glyph paths), flubber@0.4.2 (glyph morph), canvas (Node SSR). All loaded conditionally by the TECH that needs them.
- Plugin-side: none — this skill is pure documentation / routing.
Examples
Each TECH file under ./references/ contains a "Minimal example" section with near-runnable code. Start with TECH-72-use-pretext-decision-guide.md to determine if pretext is needed, then read the matching TECH file for the specific technique.
Concrete example — auto-height textarea:
- Input: "make this textarea auto-height as the user types"
- Routing: Decision tree → "Workflow assembly" → TECH-71
[TECH-71-auto-height-textarea.md] What it does · When to use · How it works · Minimal example · Gotchas · Cross-references
- Output: ~80 LOC component using
prepare() once at mount, layout() per keystroke, whiteSpace: pre-wrap parity per TECH-15, wrapper module per TECH-64. Saved to the project's component folder (Vite layout → src/components/AutoTextarea.tsx).
[TECH-64-wrapper-module.md] What it does · When to use · How it works · Minimal example · Gotchas · Cross-references
[TECH-15-textarea-prewrap.md] What it does · When to use · How it works · Minimal example · Gotchas · Cross-references
Concrete example — virtualized list with variable-height rows:
- Input: "render a 10k-row chat log with smooth scrolling"
- Routing: Decision tree → "Workflow assembly" → TECH-68, companion measurement TECH-14 and TECH-18
[TECH-18-font-string-parity.md] What it does · When to use · How it works · Minimal example · Gotchas · Cross-references
[TECH-14-dom-free-height.md] What it does · When to use · How it works · Minimal example · Gotchas · Cross-references
[TECH-68-virtualized-list.md] What it does · When to use · How it works · Minimal example · Gotchas · Cross-references
- Output: virtualized-list component that pre-measures every row height in a single
prepare() pass, stores them in a binary index for O(log n) scroll-to-row, and layouts only the visible window. No row reflow on resize — call clearCache() and re-measure (TECH-66).
Error Handling
| Symptom | Cause | Fix |
|---|
| Measurement results differ from browser render | Font string mismatch between prepare() call and CSS/canvas renderer | Follow TECH-18: font-string parity — pass the exact same CSS font string to both. |
| Layout produces wrong line count after resize | prepare() called in the resize loop | prepare() must be called once at stable font load time; only call layout() on resize. See TECH-66. |
| Canvas text blurry on retina | Missing HiDPI backing-store scaling | Scale canvas by devicePixelRatio at setup. See TECH non-negotiables. |
@chenglou/pretext not found | Library not installed in user's project | npm install @chenglou/pretext or bun add @chenglou/pretext. Not auto-installed by this plugin. |
system-ui measurement drift across OS | Font resolved differently per OS | Use named, loaded fonts only. See TECH-77 (font strategy). |
Resources
- SKILL — orchestrator; pretext must reuse the design-principles typography tokens, not introduce new fonts.
- typography-system — type scale + families pretext extends (never replaces).
[typography-system.md] I. Modular type scale · II. Font-weight hierarchy (only 2–3 levels) · III. Line-height · IV. Letter-spacing · V. Font-pairing rules · VI. Recommended font stacks (avoiding AI slop) · VII. Fallback-stack syntax · VIII. Forbidden AI-giveaway fonts (T-043)
- ai-slop-avoid — review every kinetic / calligram output against item 9 (over-cute effects).
[ai-slop-avoid.md] I. Visual style · II. Typography · III. Layout · IV. Content and copy · V. Interaction and motion · VI. Color · Self-check workflow · VII. Content density principle (positive stance) · VIII. Content anti-patterns (T-042) · IX. Anti-AI-cliché visual checklist (T-044) · X. Production-test tells (taste-skill, MIT)
[_index.md] API functions (TECH-01 — TECH-13) · Measurement prerequisites (TECH-14 — TECH-18) · Layout patterns / obstacle routing (TECH-19 — TECH-31) · Typography techniques (TECH-32 — TECH-44) · Motion / interactive demos (TECH-45 — TECH-55) · Tables (TECH-56 — TECH-58) · Integration patterns (TECH-59 — TECH-66) · Workflow assemblies (TECH-67 — TECH-71) · Consult / decision-routing (TECH-72 — TECH-78) · Cross-references
Non-negotiables
- Never activate on "make the type nice" / "pick a font" — those belong to typography-system.
[typography-system.md] I. Modular type scale · II. Font-weight hierarchy (only 2–3 levels) · III. Line-height · IV. Letter-spacing · V. Font-pairing rules · VI. Recommended font stacks (avoiding AI slop) · VII. Fallback-stack syntax · VIII. Forbidden AI-giveaway fonts (T-043)
- No Framer Motion, no GSAP — plugin-wide ban. Pretext's frame-by-frame Canvas / SVG approach IS the approved kinetic-text alternative.
- The font string passed to
prepare() MUST be loaded and byte-identical to what the renderer uses.
prepare() MUST live outside animation / render loops. layout() is the hot path.- HiDPI: scale the canvas backing store by
devicePixelRatio at setup.
- No pseudocode — every code snippet in a TECH file is runnable or near-runnable.
- Responses stay in the user's language.
