# Optional ProDyn adapter

Apply this adapter only when the deliverable is authorized to use ProDyn. The portable craft references are brand-neutral; their availability does not authorize ProDyn branding, a client-export identity change or a stable-to-Mk.ii migration.

## Authority and scope

In an authorized checkout, read these repository-root paths before implementation:

- `AGENTS.md`
- `dsm/prodyn-threadline-design-system.md` — DSM 2.2 baseline and M1–M18 scope.
- `dsm/tokens.css` and `dsm/tokens.json` — stable numeric authority and mirror.
- `dsm/mk-ii/README.md` and `dsm/mk-ii/tokens.css` — approved, explicitly opted-in blue palette.
- `dsm/motion/guide.md` and relevant registered specimen.
- `licenses/README.md` — font and private-repository rights.

This adapter was checked against repository revision `fd8ceb4f5edc5373721e40c4d7135c2772b901c8`. Current canonical files override this summary. No token values, motion contracts or M-numbers are introduced here.

The pixel-craft brief authorizes **optional illustration experiments and a learning lab**, not new default page motion or a retro theme for existing consumers. A future production adoption outside the current brief follows ordinary DSM review; do not present this guide as a registry promotion.

## Keep the shell and illustration separate

| Layer | Source of truth | Application |
|---|---|---|
| Page chrome, real controls, headings, captions, focus | Current DSM tokens/type/layout/motion contracts | Preserve the operational field, ivory type hierarchy, square geometry and localized signal. |
| Authored illustration | Its own documented image palette, grid, light and subject | Art colors may describe a painted object, sky or light; do not convert them into new UI roles or overwrite `--pd-*` variables. |
| Optional tape/CRT/digital illustration study | `references/retro-effects.md`, within the current experiment scope | Clip processing to the image. Label approximations and keep the clean still. |
| Brand assets | Canonical actual logo/document-header assets | Never raster-distort, recolor, regenerate or apply a tape/glitch pass to them. |

A distinct image palette is not permission to re-theme the shell. Store illustration colors as image-generation data with an explicit art scope, not invented brand tokens. An effects comparison should be a Learn surface: still while reading, deliberate comparison/replay only if implemented and verified. The manual explicitly permits quiet reading/comparison surfaces to omit ambient loops; omission is not permission to substitute whole-page glitch.

## Stable and Mk.ii are distinct choices

**Stable:** load the actual `dsm/tokens.css`. Do not synthesize “close enough” cyan/ivory values. For verification only, the source declares `--pd-field: #050A0F`, `--pd-ivory: #EDE8E4`, `--pd-signal: #30B0D0`, `--pd-cyan-deep: #20708A`, `--pd-trace: #87ECFF` and `--pd-spark: #22D3EE`. Consumer styles reference variables rather than copying this inventory into a parallel theme.

**Mk.ii, only when opted in:** load `dsm/mk-ii/tokens.css` **after** the base and place `data-pd-palette="mk-ii"` on the approved page or subtree. The file alone changes nothing. Do not mark unrequested siblings or bulk-migrate stable consumers.

Exact Mk.ii overrides include:

| Role | Canonical value | Use |
|---|---|---|
| `--pd-signal` | `#75a4ff` | Sparse signal, selection and focus |
| `--pd-cyan-deep` | `#284f87` | Blue depth; legacy token name retained |
| `--pd-trace` | `#c1d6ff` | Traces/data values, not body copy |
| `--pd-spark` | `#a9c6ff` | Tiny active highlights |
| `--pd-panel` | `#080f17` | Instrument panel |
| `--pd-raised` | `#0d1722` | Raised surface |
| `--pd-text-dim` | `#87949f` | Secondary labels |
| `--pd-text-muted` | `#a8b1b9` | Supporting copy |
| `--pd-signal-filter` | `drop-shadow(0 0 5px rgba(117,164,255,.32))` | Bounded filter on a small signal/trace |

Read the actual token file for the complete layer; this is an explanatory subset, not a replacement stylesheet. Use `--pd-signal-filter` as a `filter`, never as a `box-shadow`, and do not enlarge it into a bloom recipe. Existing hardcoded cyan motion assets do not automatically become blue. Mk.ii preserves the original cyan logo pixels, field/ivory foundation, type, state colors, geometry and motion contracts.

Check contrast on the composed background rather than assuming any dim/glass/deep-blue token works for essential text or focus. Copper and ok/warn/alert remain exception/state roles at approximately 5% visual presence; neither synthwave art nor blue selection redefines their meaning in the interface.

## M12 is not a marketing-effects loophole

The existing **M12 CRT phosphor overlay is console/telemetry-only, never marketing pages**. Its canonical scanlines are 1px per 3px at alpha .14, with the documented vignette, signal text glow and slow 7s alternate breathe, never strobe. Use its actual registered implementation/tokens when that operational surface is appropriate; do not tune M12 to match this guide's generic art-demo parameters.

The optional **image-local display approximation** in this package is a different experiment. It is not “M12 for illustrations,” not a new M-number, and not permission to apply scanlines to a marketing page or its typography. Record the experiment's bounded art context and preserve the ordinary shell. Do not create fake live telemetry to justify M11/M12.

M8 remains the default whole-page atmosphere, and exact M1 remains the polished footer default where appropriate. M10 remains a deliberate technical/diagnostic choice, not a decorative synthwave grid. M13 still needs explicit per-page approval; selecting another renderer does not remove that gate. None of these contracts are changed by the lab.

## Fonts and distribution

- Use `--pd-font-display`, `--pd-font-body` and `--pd-font-hud` with exact matching self-hosted family declarations. Oxanium is display/body fallback; Departure Mono is HUD, not long prose.
- Oxanium and Departure Mono have supplied SIL OFL notices. Include those notices if an authorized deliverable copies their files.
- PP Neue Machina remains private-retention-only pending confirmed commercial/web rights. Do not serve, embed, redistribute or outline-convert it as a workaround.
- Keep the portable core free of ProDyn logos, fonts, private reference images and absolute local paths. An adapter that points to authorized canonical assets is not a grant to ship those assets.
- The repository has no blanket public redistribution license. “Shareable skill” means an allowlisted package with an explicit owner-approved license/scope, not an automatic public relicensing of DSM prose or third-party work. Reference links and original recipes do not transfer source-image rights.

## Verify the boundary, not just the picture

1. Confirm exact token imports, stable isolation and explicit Mk.ii opt-in. Inspect actual computed roles, not only file presence.
2. Verify the real logo is unchanged and actual Oxanium/Departure glyphs render where required; font loading alone is insufficient.
3. Compare source/native-grid export with effected preview/export. The clean image contract and softened-effect contract must not be conflated.
4. Confirm no effect canvas/filter covers captions, controls, brand assets or focus indicators. Real meaning remains in semantic HTML with no-JS and unavailable-renderer fallback.
5. Verify keyboard, 390/700/1440 layouts, effects off, reset and export. If playback exists, test live reduced preference, pause, interruption, hidden/offscreen handling and cleanup; no strobe or autonomous sound.
6. Run affected repository tests and `python3 scripts/validate.py` from the repository root. Preview on loopback only. Keep raw research, caches and private assets out of the portable allowlist.

Use the portable [style-selection](../references/style-selection.md) matrix to suggest one relevant opportunity. It is a menu of optional techniques, not a requirement to combine VHS, CRT, glitch, synthwave and retro-sci-fi or impose them on ProDyn's default identity.