Omd:Shader Hero

omd-shader-hero — one scene, two brand inks

A launch hero gets one look from someone who owes you nothing. Mesh gradients are the most generic shader look on the web, and blending two complementary brand hues turns them brown. This skill does the opposite: two flat inks, the base color and one brand color, printed as an ordered-dither field that folds slowly like light through a screen print. Every pixel is one ink or the other, so nothing blends and nothing goes muddy. The copy sits on a hard-edged knockout in the base ink, like a cut-out panel on a riso poster.

The script picks both inks, the text color and the contrast from DESIGN.md. No color is chosen by taste.

Working example: examples/hero.html, filled from the fictional examples/DESIGN.example.md. Scripts: scripts/tokens.mjs (inks + contrast), scripts/verify.mjs (real-render proof).

1. When to use / when not

Use when:

• a launch, product, waitlist, event or rebrand page needs one first screen with motion;
• the project has a DESIGN.md with a brand color and a dark (or light) base (Core v2 Foundations tokens, Foundations prose pairs, or Google-compatible colors: frontmatter);
• a graphic, printed, confident look fits the brand.

Don't use when:

• there is no DESIGN.md or no brand color. tokens.mjs exits 3 and you stop; run omd-init or ask. Never pick "nice" colors to fill the gap (unknown means absent);
• the brand is soft, photographic or luxury-quiet. A dither field is loud. Use the brief's photography instead (tf-shaders "photo first");
• the page needs several shader scenes. One scene, plus at most one small accent elsewhere (tf-shaders rule). For a whole scroll story use omd-landing.

2. Procedure

1. Read tokens, don't choose them.

   bashCopy code
   node <skill>/scripts/tokens.mjs DESIGN.md                 # prints the decision as JSON
   node <skill>/scripts/tokens.mjs DESIGN.md --scheme light  # light base instead of dark
   

   The script reads three formats, in this order: - **color.<role>**: \#hex`tokens,Name (`#hex`)pairs inside the Foundations section, then frontmattercolors:`. Then it:
   • drops state and utility roles (danger, error, warning, success, info, border, divider, focus, disabled, overlay, shadow, hover, pressed, active);
   • takes the darkest token as the base ink (the lightest for light);
   • takes one brand ink: the role named primary/brand if there is one, else the most saturated brand color, skipping any too close to the base.
2. Text color is computed. The script checks the text candidates (ink/neutral tokens at the opposite end of the scheme) against both inks and their midpoint and picks the best one. The copy then sits on an opaque base-ink knockout, so the bar it must clear is the text token on the base ink. With the fixture that is 18.8:1. If even that is under 4.5:1, the script warns: pick another text token.
3. Write the hero. Copy examples/hero.html (or port it, see §6) and fill it:

   bashCopy code
   node <skill>/scripts/tokens.mjs DESIGN.md --write path/to/hero.html
   

   That rewrites the #hero-vars CSS block (--hero-c0 base, --hero-c1 brand, --hero-text, --hero-scrim, --hero-scrim-a) and the #hero-tokens JSON.
4. Copy is real. Headline + one sentence + one CTA. Use the user's actual product line. Never invent metrics, customers or investors (tf-shaders §0).
5. Verify on a real GPU (§5) and look at the frames at full size.

3. The scene and its two parameters

Paper's ditheringFragmentShader: shape = warp (slow folding bands), type = 4x4 (ordered Bayer), colorBack = base ink, colorFront = brand ink.

Layout rules:

• Knockout, not scrim. The copy box sits on an opaque base-ink panel with hard edges (inset 2rem × 2.5rem around the copy). A translucent scrim, or a feathered edge, would lay base over brand dots and recreate the mud. Small text (the footer label) gets its own knockout too.
• Contrast: 4.5:1 for the headline and the sub copy. The headline is large enough that WCAG would accept 3:1, but this skill doesn't rely on that. verify.mjs fails below 4.5:1 for either.
• Hero copy paints on the first frame: no opacity: 0, no waiting for the canvas. The canvas fades in over 600ms above an already complete CSS poster.
• Korean display type follows /hangul: keep-all + overflow-wrap: anywhere, line-height 1.3, tracking -0.02em (never below -0.03em), text-wrap: balance, font-synthesis: none.
• Background on html, never on body (a body background paints over a negative-z scene; tf-shaders pitfall).
• Radius, type scale and spacing come from DESIGN.md too. The fixture defines no radius, so the CTA is square.

4. Library, license, budget, fallback

Library: @paper-design/shaders 0.0.81 (vanilla ShaderMount + ditheringFragmentShader), WebGL2. Licenses verified 2026-10-13 from the npm tarballs' LICENSE files, npm metadata and the GitHub license API:

Paper wins on reach, weight and telemetry. shaders is the upgrade path only for a project that already ships WebGPU scenes. There, keep this token pipeline, the knockout and the fallback, and pass disableTelemetry. Both licenses allow use in skills and templates. The example imports Paper from a pinned CDN URL and does not vendor it. If you vendor Paper's files, copy its NOTICE with them.

Budget:

• JS: 7.0 KiB gzip library + 1.1 KiB gzip scene code.
• GPU: one full-viewport quad, two colors, ordered dither. minPixelRatio: 1 and maxPixelCount 1920×1080, since the cell size is the resolution. Paper pauses offscreen and in hidden tabs.
• No images, no video, no font beyond the UI face.

Fallback (part of the design, not an afterthought):

• CSS halftone poster under the canvas: dots of the brand ink on the base ink (radial-gradient 6px cells), masked toward two corners. It is the first paint, the no-WebGL2 path (ShaderMount throws without a context; the page probes getContext('webgl2') first), and the state when the CDN is unreachable. verify.mjs forces this path.
• prefers-reduced-motion: reduce: speed 0 at a fixed frame (STILL_FRAME, 8000ms). That's one still composition with no rAF loop.

5. Verify on a real GPU

bashCopy code
npm i -D playwright-core && npx playwright-core install chromium   # fresh Playwright Chromium, not your own Chrome
node <skill>/scripts/verify.mjs path/to/hero.html ./hero-verify --frames 48 --seconds 12

It runs four passes (1440px GPU, 390px mobile, reduced-motion, no-WebGL) with --enable-gpu --ignore-gpu-blocklist --use-angle=metal (macOS), and for each one:

• records the WebGL renderer, so you know whether a real GPU or SwiftShader drew the frames;
• steps the shader clock deterministically across 12s and saves frames (ffmpeg → demo GIF/MP4);
• measures contrast: hides the copy, samples the scene behind the headline and sub copy in every frame, and takes the worst ratio against the text color. It fails below 4.5:1 for either;
• checks that the canvas (not the poster) is on screen, that the field moves, that the headline is at full opacity on load, that reduced motion is still, and that no-WebGL shows the poster with no canvas.

Measured on 2026-10-13 with the fixture (headless Chromium 149, ANGLE Metal Renderer: Apple M5 Pro): worst headline and sub copy 18.81:1 in every pass (1440px, 390px, reduced motion), 13.1:1 on the no-WebGL poster. All checks passed.

6. Next.js / React port

Server-render the section, copy, knockout and poster as plain HTML/CSS (the poster needs no JS). Generate the CSS variables at build time from tokens.mjs --json, not at runtime. Mount the scene in a 'use client' leaf:

tsxCopy code
useEffect(() => {
  if (!probeWebGL2() || !ref.current) return;           // poster stays; nothing to clean up
  let m: { dispose(): void } | undefined;
  (async () => {
    const { ShaderMount, ditheringFragmentShader } = await import('@paper-design/shaders');
    try { m = new ShaderMount(ref.current!, ditheringFragmentShader, uniforms, undefined, reduce ? 0 : speed, 8000, 1, 1920 * 1080); }
    catch { /* keep the poster */ }
  })();
  return () => m?.dispose();
}, []);

7. Attribution

From the owner's tf-shaders experiment (skill/shader-landing/SKILL.md, RESEARCH.md, scripts/shoot.mjs, 2026-10): one scene plus at most one accent, the stated JS budget, the CSS poster under every canvas, background on html, quiet state behind type, contrast checked at the worst frame, first-frame hero copy, reduced motion as a state change, and the real-GPU screenshot loop. This skill adds the token pipeline, the two-ink dither, the knockout, measured contrast and the WebGL2 runtime choice.

Don't

• Don't add a third color or blend the two inks (gradients, translucent overlays, feathered panels). Two flat inks are the whole point; a blend between complementary hues is mud.
• Don't use a color that isn't a DESIGN.md token, and never a state color (danger red as the brand ink).
• Don't put text directly on the dither field. Copy goes on the knockout; small text gets its own.
• Don't swap shaders per breakpoint or animate compile-time props. Changing an ink value or px is a uniform write and is fine.
• Don't stack the hero on a body background, and don't fade the headline in.
• Don't load Paper and shaders on the same page.