asciify-engine 4.12.1 → 4.14.0

package/skills/asciify-engine/references/applying-asciify.md

@@ -0,0 +1,234 @@
+# Applying Asciify: the house design
+
+How asciify.org puts characters into a real interface. Read this before choosing a component or a background, then take the call from [components.md](components.md) and its options from [kit.md](kit.md). Every rule here is one you can check in the browser.
+
+The site's claim is the brief: ASCII that belongs in your interface. Characters are a material the interface uses for a job (showing work, confirming an outcome, moving between states, setting one ground for a page), drawn in the page's own ink, inside its own shapes, at its own pace.
+
+## 1. Give the characters a job
+
+Pick by what the field does for the person, not by how it looks.
+
+| Job | Use |
+| --- | --- |
+| Show that work is running | `buttonLoading`, `statusOrb`, `thinking`, `streamText`, `skeleton`, `imageGenerate`, `pullRefresh` |
+| Confirm or refuse an outcome | `statusOrb` success, warning or error; `slideToConfirm`; `codeInput` `verify()`; `beam` `success()` or `error()` |
+| Show a value changing | `odometer`, `pill` counts, `blockChart` |
+| Move between states or views | `tabs`, `pageDissolve`, `commandPalette`, `toastStack`, `disintegrate` |
+| Answer a gesture | `likeBurst`, `swipeDeck`, `compare`, `accordion`, `dropzone` |
+| Carry a brand moment or media | `decode`, `wordmark`, `asciiVideo`, `artPanel`, `pricingGlow`, `fieldBackground` `notFound` |
+| Set the page's one ground | `fieldBackground` `hero`, or `background()` with a preset (section 9) |
+
+Do not use characters:
+
+- behind body copy, forms, tables, code, docs pages or navigation;
+- on every card in a grid, or as a second ground on a page that has one;
+- as the only carrier of a state: the label, the live region or the HTML still says it;
+- for a loader with no real work behind it, or for decoration that never answers an event.
+
+Test: hide the canvas. If the interface loses no feedback and the field was not the page's one ground, remove it. A ground earns its place by answering the interface. On asciify.org the hero field pulses when the command is copied:
+
+```ts
+import { fieldBackground } from 'asciify-engine/kit';
+
+const bg = fieldBackground(hero, { preset: 'hero', clear: heroCopy });
+copyButton.addEventListener('click', () => bg.pulse(copyButton));
+```
+
+## 2. Ink: quiet by default, colour only for meaning
+
+Inks come from theme tokens, defined for both schemes. The kit re-reads them when `prefers-color-scheme` changes and when `class` or `data-theme` changes on `<html>` or `<body>`, so define the dark values under both selectors. These are the engine's own fallbacks and the site's graphite:
+
+```css
+:root {
+  --ascii-ink: #76746e;        /* grounds, rings, quiet strokes */
+  --ascii-ink-strong: #1d1d1b; /* a component that is the focus */
+  --ascii-success: #17844a; --ascii-warning: #9a6700; --ascii-error: #c93636;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) { --ascii-ink: #7a7872; --ascii-ink-strong: #d8d6cf; --ascii-success: #3ccf7e; --ascii-warning: #f5b83d; --ascii-error: #ff6b6b; }
+}
+:root[data-theme="dark"] { --ascii-ink: #7a7872; --ascii-ink-strong: #d8d6cf; --ascii-success: #3ccf7e; --ascii-warning: #f5b83d; --ascii-error: #ff6b6b; }
+```
+
+Rules:
+
+- **Default to graphite.** Leave `ink` unset: components pick `--ascii-ink` or `--ascii-ink-strong` and background presets use their graphite. On another brand, map these tokens to its muted text colour, never to its accent.
+- **Colour means something.** Green, amber and red are for outcomes only, and come from `--ascii-success`, `--ascii-warning` and `--ascii-error`. The site's phosphor marks live states only and is never a button or text.
+- **Palettes are deliberate.** `beam` `colorful`, `voiceOrb` `aurora` and `fieldBackground` `brand` are chosen palettes for one moment the user asked for, not a page default.
+- **Never a new colour.** No hex that is not a token, no black canvas on a light page, no white glow on a coloured image.
+
+```ts
+import { background, halftone, statusOrb, beam } from 'asciify-engine/kit';
+
+background(pricing, { preset: halftone, clear: pricingCopy, ink: '--ascii-ink' }); // the token, re-read per theme
+const orb = statusOrb(orbSlot); // strong ink at rest; outcomes read --ascii-success, --ascii-warning, --ascii-error
+beam(planCard, { palette: 'mono', mode: 'pulse' }); // the quiet beam; 'colorful' only when asked for
+orb.loading();
+```
+
+## 3. Text over a field: clear zone plus frosted veil
+
+Text never sits on raw characters, and never in a box. Two layers do the work:
+
+1. **The clear zone.** Pass the text block as `clear`; the field fades out around it (`fieldBackground` in a soft ellipse, the GPU background presets in a feathered rectangle 32px out, canvas presets in a soft ellipse).
+2. **The veil.** A frosted, radially masked wash of the ground behind the text, so characters blur and fade toward the words instead of stopping at an edge. This is asciify.org's CSS:
+
+```css
+.hero-copy { position: relative; isolation: isolate; }
+.hero-copy::before {
+  content: ""; position: absolute; z-index: -1; inset: -36px -64px; pointer-events: none;
+  background: color-mix(in oklab, var(--bg) 62%, transparent);
+  -webkit-backdrop-filter: blur(9px) saturate(1.1); backdrop-filter: blur(9px) saturate(1.1);
+  -webkit-mask-image: radial-gradient(closest-side, #000 52%, rgb(0 0 0 / .6) 74%, transparent);
+  mask-image: radial-gradient(closest-side, #000 52%, rgb(0 0 0 / .6) 74%, transparent);
+}
+/* A smaller block, such as a card's title and button: a tighter veil from the surface it sits on. */
+.card-copy::before { inset: -24px -40px; background: color-mix(in oklab, var(--surface-2) 58%, transparent); }
+```
+
+- No solid panels, cards or hard-edged scrims behind headline copy. Buttons keep their own opaque fill.
+- A header over a field: mask the field to about a quarter strength under the header strip, as the site does: `mask-image: linear-gradient(to bottom, rgb(0 0 0 / .26), rgb(0 0 0 / .26) 56px, #000 152px, #000 80%, transparent)`.
+- **Contrast.** Body and lede text 4.5:1, display text of 24px and up 3:1, measured against the busiest frame under the text, in both themes. Fix a failure with the clear zone, the veil, a lower `opacity` or larger cells. Never dim, recolour or shadow the text to fix it.
+
+## 4. Density and cell size by surface
+
+| Surface | Cell size | Characters | Site reference |
+| --- | --- | --- | --- |
+| Page hero ground | 10–12px, broad shapes | Sparse: `' .:+*#'` in the mono face | `fieldBackground` `hero` (10px), `drift` (11px), `halftone` (14px dot spacing) |
+| Section band or card stage | 7–10px | Fuller ramp for images (`' .:-=+*#%@'`), quiet ramp for grounds | images 7px, character fields 10px, halftone 9px |
+| Control: button, pill, tabs, code input, odometer | Leave it to the kit | The kit fits cells to the element's text | Use a monospaced label for `buttonLoading` |
+
+- One density per surface: a stage does not mix a 7px image and a 12px ground.
+- Nothing under 6px on a phone; the GPU grounds already enlarge their shapes under 760px.
+- Tune with `look: { cellSize }` on a component or `cellSize` on `background()`, and only after looking at it at 1x and 2x.
+
+```ts
+import { background, drift } from 'asciify-engine/kit';
+
+const band = background(featureBand, { preset: drift, cellSize: 12, clear: bandCopy }); // a touch quieter than the default 11
+band.update({ charset: ' .:+*#' }); // the hero's sparse ramp
+```
+
+## 5. Radii and containment
+
+The kit clips every field to its host's computed corner radii, so the shape must be on the host.
+
+- Put `border-radius` on the element you pass, from the project's tokens, never a literal. asciify.org: `--r-xs` 8px, `--r-inner` 18px, `--r-panel` 24px, `--r-dialog` 28px, and every control a pill (`--r-control: 999px`).
+- Nest radii: an inner frame inset by `p` takes `calc(var(--r-panel) - p)`, as the site's video frame does (`calc(var(--r-panel) - 8px)` inside an 8px padding).
+- Give `overflow: hidden` and a background to hosts the kit draws inside: `artPanel`, `imageGenerate`, `compare`, `accordion`, `dropzone`.
+- Some components draw past their host on purpose: `voiceOrb` 8%, `codeInput` 16px, `toastStack` 24px, `likeBurst` 40px (`outset`), `swipeDeck` 56px (`outset`). Their container must have that much room, or bound them:
+
+```ts
+import { likeBurst, swipeDeck } from 'asciify-engine/kit';
+
+likeBurst(likeButton, { limit: postBody, outset: 24 }); // nothing above the post body, sparks inside the card's padding
+swipeDeck(stack, { outset: 32 }); // the stage's own padding, so a fling thins out before its edge
+```
+
+Check: with the page zoomed to 200%, no character lands outside a rounded corner or past a container edge.
+
+## 6. Motion
+
+- **Interface: 280ms or less.** Anything a person waits on: tab indicator (`tabs` defaults to 280), panel open (`accordion` 280), tone change (`pill` 240), poster fade (280), view swap (`pageDissolve` 140 + 160).
+- **Decorative: 800ms or less.** One-shot flourishes: `disintegrate` 620, `dropzone` develop 720, the like burst. `decode` defaults to 900, so pass `duration: 800` or less.
+- **Ambient loops: slow.** Keep `speed` at or below the preset's own. Motion should be noticed on the second look, not the first.
+- **Easing.** CSS around the field uses the house ease-out, `--ease: cubic-bezier(.23, 1, .32, 1)`, with 140ms for control colour changes. The kit's own motion runs on `cubic-bezier(.16, 1, .3, 1)`. No linear or ease-in entries; a spring only where the material earns a settle (a like, a badge).
+- **Reduced motion.** The kit draws each state settled in one frame and each background as one still; poster fades become instant. Drop your own transitions too, and never hide a playing canvas with CSS instead.
+- **Off screen.** The kit pauses fields off screen and in hidden tabs. Call `pause()` on fields inside closed overlays. Give video and any field that is the content, not a texture, a visible pause control.
+
+```ts
+import { tabs, decode } from 'asciify-engine/kit';
+
+tabs(tablist, { duration: 280, panels: 'attribute' }); // interface
+decode(headline, { duration: 800, settle: 'text' }); // decorative, under the 800ms ceiling
+```
+
+```css
+:root { --ease: cubic-bezier(.23, 1, .32, 1); --fast: 140ms; }
+@media (prefers-reduced-motion: reduce) { .tab, .panel, .btn { transition: none; animation: none; } }
+```
+
+## 7. Performance
+
+- **About 12 fields per page.** At most 12 kit fields hold a WebGL context at once (`setFieldBudget` changes it). asciify.org's home page runs 12. Past that, share: one `pill()` call over a list draws every pill with one field.
+- **Lazy by default.** Fields mount within half a viewport and release beyond one. Use `lazy: false` only for the hero in the first viewport.
+- **Posters.** Give every field above the fold, and every field that matters without WebGL, a still per theme, and swap it on theme change with `update({ poster })` rather than remounting.
+- **Canvas presets cost CPU, not contexts.** Count them toward the page anyway; one animated ground per viewport.
+- **Import by name.** Presets are separate exports, so import only those you mount.
+- **Destroy on unmount.** In React, create the handle in an effect and return its `destroy`.
+
+```ts
+import { fieldBackground, setFieldBudget } from 'asciify-engine/kit';
+
+setFieldBudget(10); // a page with heavy media of its own
+const dark = matchMedia('(prefers-color-scheme: dark)');
+const still = (isDark: boolean) => `/stills/hero-${isDark ? 'dark' : 'light'}.webp`;
+const ground = fieldBackground(hero, { preset: 'hero', clear: heroCopy, lazy: false, poster: still(dark.matches) });
+dark.addEventListener('change', event => ground.update({ poster: still(event.matches) }));
+```
+
+## 8. Accessibility
+
+- **Canvases are decoration.** Kit fields are `aria-hidden` and ignore the pointer. Only the canvases that are the content take a `label`: `fieldBackground` `notFound`, `asciiVideo`, `artPanel`.
+- **Real text stays in the DOM.** `decode`, `wordmark` and `streamText` keep the actual words selectable and readable; `odometer` and `pill` counts add a hidden copy; `blockChart` adds a hidden table. Do not replace text with a field.
+- **Status is announced.** Pass a live region to `buttonLoading` (`announce`) and `thinking` (`label`), write `statusOrb` outcomes to one yourself, and give `pullRefresh` its `messages`. `toastStack` adds its own `role="status"` region.
+- **Keyboard and focus.** The kit wires keys for `tabs`, `commandPalette`, `slideToConfirm`, `compare`, `accordion`, `swipeDeck` and `codeInput`; keep them (`manage` stays true). Keep a Refresh button beside pull to refresh. A field never covers a focus ring: `beam` draws inside the border, so a 2px outline at 3px offset stays clear.
+
+```ts
+import { statusOrb, buttonLoading } from 'asciify-engine/kit';
+
+// <p id="publish-status" role="status" aria-live="polite"></p>
+const orb = statusOrb(orbSlot, { ring: true });
+const button = buttonLoading(publishButton, { announce: publishStatus });
+publishButton.addEventListener('click', async () => {
+  orb.loading(); button.start('Publishing');
+  await save().then(() => { orb.success(); button.succeed('Published'); }, () => { orb.error(); button.fail('Retry'); });
+});
+```
+
+## 9. Backgrounds
+
+`background(element, { preset })` draws any of the 26 presets from asciify.org/backgrounds under the element's content. Choose by surface:
+
+| Surface | Presets | Notes |
+| --- | --- | --- |
+| Product hero, pricing, docs landing, behind copy | `drift`, `halftone`, or `fieldBackground` `hero` | GPU grounds that clear around `clear`. `halftone` is the calmest; `fieldBackground` `hero` is asciify.org's own hero, with ripples and `pulse()`. |
+| A brand or name moment | `wordField` (id `field`), `fieldBackground` `brand` | Your word in the field; keep copy off its centre. |
+| Art-first hero with little copy | `fluid` | The original Asciify hero, 7px cells at 0.7 opacity. Not behind reading text. |
+| Quiet texture: section bands, footers, empty states, side panels | `caustics`, `contour`, `facet`, `etch`, `moire`, `weave`, `veil`, `dune`, `silk` | Canvas, no cursor, slow. The safest behind text after `halftone`. |
+| An interactive moment the visitor plays with | `wave`, `aurora`, `noise`, `stars`, `pulse`, `voidWell` | They answer the cursor. Keep them away from forms and body copy. |
+| A themed subject the page is about | `rain`, `grid`, `morph`, `fire`, `dna`, `terrain`, `circuit` | Loud. Use only when the subject matches (DNA for a biotech page), with low opacity and copy beside, not over. |
+
+Keep them calm:
+
+- `speed` at or below the preset's default; `cursor: false` near forms and copy.
+- On canvas presets behind text, `opacity` 0.5–0.8; GPU grounds already draw quietly.
+- Always `clear` the copy and add the veil from section 3; on the /backgrounds page the copy also sits on the side the field fades toward.
+- One background per page section, under one `isolation: isolate` host with its own background colour.
+- `setPreset()` cross-fades in place for a picker; do not mount a second background.
+
+```ts
+import { background, contour, caustics } from 'asciify-engine/kit';
+
+const section = background(features, { preset: contour, clear: featuresCopy, opacity: 0.6, cursor: false });
+themePicker.addEventListener('change', () => section.setPreset(caustics)); // keeps clear, opacity and cursor
+```
+
+```ts
+import { background, drift } from 'asciify-engine/kit';
+
+const bg = background(hero, { preset: drift, clear: heroCopy, poster: '/stills/drift-light.webp' });
+signUpButton.addEventListener('click', () => bg.field?.pulse({ element: signUpButton, strength: 1.2 })); // GPU presets expose the field
+```
+
+## 10. Checklist before you finish
+
+- [ ] Every field has a job from section 1; hiding it loses feedback, or it is the page's one ground.
+- [ ] Ink comes from tokens in both themes; colour appears only for outcomes or a requested palette.
+- [ ] Text over a field has `clear` plus the veil; 4.5:1 for body, 3:1 for display, at the busiest frame, light and dark.
+- [ ] Cell size matches the surface; nothing under 6px on a 390px-wide phone.
+- [ ] Every host carries its radius from tokens; nothing draws past a corner or container edge at 200% zoom.
+- [ ] Interface motion ≤ 280ms, decorative ≤ 800ms, on the house ease-out; reduced motion shows settled stills.
+- [ ] No more than about 12 fields per page; first-viewport fields have posters per theme; everything else is lazy.
+- [ ] Canvases are `aria-hidden` unless labelled content; real text is in the DOM; status reaches a live region.
+- [ ] Every handle is destroyed on unmount, and the page still works with WebGL off.