sheleg-design-skill 1.55.0 → 1.57.0

package/CHANGELOG.md

@@ -6,6 +6,130 @@ follow [SemVer](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [1.57.0] - 2026-08-30
+
+### The siblings are declared, the maps are derived, the descriptions stop scarring
+
+Five closures from the family audit of 2026-08-29 (SHD-05, SHD-01, SHD-03, SHD-09,
+SHD-11), one release.
+
+**The three sibling skills are declared, and every one has a written absent-branch
+(SHD-05, the audit's HIGH).** `SKILL.md` handed charts to a `dataviz` skill that
+exists on no consumer machine this skill ships to, and asserted `shadcn` /
+`migrate-radix-to-base` "are installed" — a promise this repository has no way to
+keep. Three changes, none of them a removal:
+
+- A `compatibility` front-matter line names all three as optional siblings with
+  in-text fallbacks — the Agent Skills field for environment expectations, spent on
+  the one expectation this skill actually has.
+- The chart handoff is now conditional in both homes: where a `dataviz` skill is
+  installed it consumes the pack as its parameter set, and **where none is
+  installed, the role table in `SURFACE_COMPOSITION.md` IS the chart contract**,
+  applied by hand — which is what that table always was, stated instead of implied.
+- The component-layer section says what absence costs: nothing. `npx shadcn@latest
+  add` does the adding without the skill, and the token mapping binds either way.
+
+**Every long reference now carries a derived `## Contents` list (SHD-01).** The
+authoring rule — a reference over 100 lines carries a map, because that is what a
+partial read sees — held in 2 of 46 qualifying files. Hand-adding 44 lists creates
+44 lists that rot, so the list is **derived**: `scripts/gen_contents.py` writes the
+entries from the file's own `## ` headings (fenced code blocked out), `--write`
+regenerates bundle + mirror + template source together, and
+`validate_contents_lists()` refuses a file whose list is missing *or drifted* —
+including the one pre-existing list whose entries had already wandered from the
+headings they mapped (`MOBILE_SURFACES.md`). A new pack without a Contents list now
+fails the gate with the remedy in the message.
+
+**Both host-facing manifest descriptions are generated, never hand-appended
+(SHD-03).** `plugin.json` and the plugin entry in `marketplace.json` had converged
+to what per-release appending always produces: `patchbay` and `nameplate` glossed
+twice, `deskmate` never glossed, and `chorus` carrying `deskmate`'s orphaned
+parenthesis. Both descriptions are now derived from `STYLE_PACK_INDEX.md`'s
+catalogue — the register and good-fit columns packs are already chosen by — via
+`scripts/gen_manifest_descriptions.py` (`npm run gen-descriptions`), and
+`validate_manifest_descriptions()` refuses a manifest that differs from the
+derivation. The generator also refuses to run when the catalogue and `styles/`
+disagree, so the index parity gate fires first, not silently.
+
+**The deck trigger names the register it owns (SHD-09).** "investor deck" /
+«презентация» was broad enough to catch every presentation request, including the
+`.pptx` files the pptx/pitch-deck neighbours own. Now: *"investor deck as a web
+page" / "веб-презентация"*, with the file-based register explicitly declined in the
+description tail. The T1 carrier word `deck` survives, and the umbrella advertises
+no presentation trigger for this skill, so no routing hook loses a word.
+
+**The layout deviation is recorded where a retrofit would look (SHD-11).**
+References at the skill root and tokens two levels deep predate the layout
+guidance, and every deep link, the `.cursor` byte-mirror and `install.sh`'s file
+list depend on them. CONTRIBUTING.md now records the deviation as deliberate so the
+next standards pass reads a decision instead of an accident.
+
+Gate: 5060 → 5598 checks (the floor moves with it); both new checks watched
+failing against the real tree first — 46 references and 2 manifests red before the
+regeneration, green after — and each ships a planted defect in the self-test. The
+Contents gate's first live catch was the next release's own file: v1.56.0's
+`MOTION_PRODUCTION.md` landed mid-flight without a list, and the rebase gate
+refused it until `npm run gen-contents` wrote one.
+
+## [1.56.0] - 2026-08-30
+
+### The render seam — what changes when motion stops being a page
+
+New companion document, `MOTION_PRODUCTION.md`. `MOTION_DOCTRINE.md` decides whether a
+thing on a page may move and how; this one starts at the question it never answered —
+what happens when the motion has to become a **file**, and what that costs.
+
+**The position it takes first, before naming any tool: a rendered asset is not page
+motion with a different extension.** Four things are given up and a page should give
+them up on purpose — the reduced-motion contract (a file has no user preference to
+read, so the obligation moves to the embedding page: no autoplay under the reduce
+query, a real poster frame, a control), the theme (every pack declares `Themes:` and a
+baked frame answers only one of them), the text (unselectable, untranslatable,
+unindexable), and the first frame's decode. The document states what a rendered asset
+is genuinely for — a surface you do not control, a piece with audio, a piece that must
+look identical everywhere — and carries the refusal phrase for the rest.
+
+**Two programmatic-video tools, measured on 2026-08-30 rather than characterised.**
+Both seek a headless browser frame by frame and encode with FFmpeg; they differ in the
+language the composition is written in and in what using them costs.
+
+- **Remotion** — the composition is a React component reading `useCurrentFrame()`. Its
+  licence is its own two-tier one, not an OSI licence: free for individuals, for-profit
+  organizations **with up to 3 employees**, non-profits and evaluation, and a paid
+  Company License above that. On `remotion` 4.0.518 after six years; FFmpeg bundled
+  since v4.0; `@remotion/player` is a React component that takes props.
+- **HyperFrames** — the composition is an HTML document with `data-start` /
+  `data-duration` timing and a seekable runtime (GSAP, CSS, WAAPI, Lottie, Three.js).
+  **Apache-2.0.** On `hyperframes` 0.8.20 and **pre-1.0**, which is stated as a real
+  risk rather than a footnote; requires Node 22+ and a separate FFmpeg. Its player is a
+  web component in an isolated iframe.
+
+**The recommendation is HyperFrames, and the reason is this library's own rule.** A
+pack's `styles/tokens/<pack>.css` is a `:root` block; in an HTML composition it is
+`<link>`ed in **unmodified** — the same file the site ships, which is the
+copy-never-transcribe rule the kits already follow, holding across the render seam. Two
+supporting reasons: Apache-2.0 removes a seat question that has nothing to do with
+design, and its determinism rules are the doctrine's anti-drift rules restated for a
+renderer.
+
+**Three conditions reverse it, and they are named rather than hedged:** motion driven
+by application state in the page (the Remotion player is a React component; the
+HyperFrames one is an iframe by design), a product that is a video pipeline rather
+than a page, and a team that cannot carry a pre-1.0 dependency. Where a brief hits none
+of them and the licence threshold is not close, the document says to use whichever the
+operator already knows instead of manufacturing a reason.
+
+### Also in this release
+
+- The token seam per tool, with the three families that need a decision the page never
+  forced: durations converted once at the edge (`frames = seconds × fps`, the token
+  staying the source), the reduced-motion branch that correctly fires on neither side
+  of a render, and webfonts, which are assets and must resolve before frame 0.
+- A ten-item pre-flight for a rendered asset, ending on the check that separates a tool
+  problem from a composition problem: a byte-identical re-render from the same input.
+- `MOTION_DOCTRINE.md` §10 gains the routing line, and states nothing itself — the
+  DOCMAP's single-home rule.
+
 ## [1.55.0] - 2026-08-30
 
 ### The thirty-ninth pack — somebody else's question, on a sheet that never stops being ruled

package/README.md

@@ -176,6 +176,7 @@ skills.
 | `SHELEG_DESIGN.md` | The full reference: architecture, layer-by-layer mechanics with code, the exact morph math, the DOM↔WebGL projection bridge, a build-from-scratch recipe, and why each piece works |
 | `SURFACE_COMPOSITION.md` | Two decisions the pack layer does not make: the six depth layers of a scene, read before writing CSS for a cinematic page; and the handoff to `dataviz`, read before drawing a chart in any pack — token names are not uniform across the thirteen and an undefined custom property fails silently |
 | `MOTION_DOCTRINE.md` | Whether to animate at all, before how: the frequency table that kills motion on high-repetition paths, the easing tree and the `ease-in` ban, the duration ceiling, the forbidden forms, and the reduced-motion contract. `SKILL.md` marks it required before any animation |
+| `MOTION_PRODUCTION.md` | What changes when motion leaves the page as a file: the four things a rendered asset gives up, the two programmatic-video tools measured side by side with the licence threshold and the pre-1.0 risk stated, which one this library recommends and the three conditions that reverse it, how a pack's token layer crosses the render seam, and where the reduced-motion obligation lands once there is no user to read a media query |
 | `DESIGN_SYNC_BRIDGE.md` | The Claude Design contract: what a pack sends to claude.ai/design and in what shape, the rule for each of the four reference types, and the border motion does not cross |
 | `FIGMA_BRIDGE.md` | The design↔code contract: how a pack's tokens map onto Figma variable collections and modes, how to implement a design without importing raw values, and what cannot cross the border |
 | `AI_PRODUCT_PATTERNS.md` | The surfaces a model drives: the five states of a call, streaming instead of spinners, latency, provenance and uncertainty, agent confirmations, and the bans that keep it honest |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sheleg-design-skill",
-  "version": "1.55.0",
+  "version": "1.57.0",
   "description": "Design taste as an installable agent skill. Cinematic scroll-driven landing pages built on one scroll clock and layered degrade-to-calm motion, a motion doctrine that decides whether to animate before it decides how, three calibration dials, and thirty-nine locked style packs with ready-made design tokens — instrument-console, editorial-luxury, workbench, briefing-room, atrium, orchard, outrank, babylove, patchbay, nameplate, field-notes, cyclorama, showroom, blueprint, prism, maquette, scoreboard, datasheet, manpage, pigeonhole, roster, ora, tenor, paperclip, ledger, router, daylight, notation, almanac, vitrine, proscenium, awning, bulletin, rimlight, onionskin, deskmate, test-drive, surveyor and chorus. Colour, slop and fork-reciprocity gates run as scripts, not opinions. Works with Cursor, Claude Code and any agent that reads a SKILL.md.",
   "bin": {
     "sheleg-design-skill": "bin/cli.js"
@@ -24,6 +24,8 @@
     "smoke": "node bin/cli.js --help",
     "palette": "python3 test/validate_palette.py",
     "sync-kits": "python3 scripts/sync-kit-tokens.py",
+    "gen-descriptions": "python3 scripts/gen_manifest_descriptions.py --write",
+    "gen-contents": "python3 scripts/gen_contents.py --write",
     "sloplint": "python3 test/sloplint.py",
     "selftest": "python3 test/validate.py --self-test && python3 test/validate_palette.py --self-test && python3 test/sloplint.py --self-test"
   },

package/plugins/sheleg-design/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "sheleg-design",
   "displayName": "SHELEG Design",
-  "description": "SHELEG Design methodology: cinematic scroll-driven landing pages (single scroll clock, layered degrade-to-calm motion, WebGL particle formations), a motion doctrine that decides whether to animate before it decides how, and thirty-nine pluggable visual style packs — instrument-console (dark console), editorial-luxury (warm editorial), workbench (light/dark product UI for dashboards and tools), briefing-room (dark 16:9 deck), atrium (warm consumer health), orchard, outrank, babylove (friendly consumer biotech), patchbay (a dark live schematic: one mint-cyan, 8% hairlines and no shadow, and an architecture diagram whose cords carry SMIL particles), field-notes (warm paper for dev tools sold on auditability), cyclorama (a pastel field on a 32s cycle), showroom (the product as the exhibit), blueprint (a drawing sheet, zero radius), prism (one iridescent wash over mono body), maquette (cream axonometric models on a dark table), scoreboard (warm paper, pixel numerals, a dark ledger of results), datasheet (an off-white spec sheet whose live instrument goes dark when it detects the reader is hiding), manpage (a developer landing page set in the reader's own system monospace on cream paper, with coral label chips that are real headings and a dark code frame as the argument), pigeonhole (a white sorting wall whose nine pastel categories are a filing scheme rather than a mood, each a two-layer chip whose label word is mandatory), roster (a white field in a faint grid of squares whose argument is other people's marks — client logotypes in pill-labelled industry columns, an engine's wordmark inside the headline — where the proof is a name rather than a number), ora (a warm coal field with cream ink and no third hue — the accent is the inverted field — a serif carrying every human sentence over a monospace carrying every machine fact, a terminal surface cut below the page, and a six-step verdict ramp, for products whose output is a machine's verdict about the reader), tenor (warm paper with zero radius and zero shadow, one hairline weight, an orange that exists only on hover and on focus, a sans tracked negative against a mono tracked positive, display at a line-height below one in an eight-to-twelve-character measure, and product proof delivered as silent looping video, for products arguing that a new kind of thing must be managed like an existing organisation), paperclip (neutral coal with no functional colour at all — every control monochrome and elevation made of hairlines, with the whole chromatic budget spent on a curtain of gradient capsules and twelve gradient section badges that cannot be clicked — for products that ask a person to run something that runs itself: agent teams, autonomous back-office, schedulers and budget-governed compute), ledger (warm cream paper ruled by a hairline at 12% ink and no shadow on any card, radius 15 nested concentrically, an ink primary button and a terracotta accent that never fills a control — it labels, as a 10px monospace uppercase kicker — with a seal on every card stating how its number is known, for the console of a product that answers questions about data: AI analysts, BI surfaces, query workspaces), router (a near-white field with a trace of blue and white cards standing on it, hairline seams instead of shadows anywhere, body at 14px and weight 450, and a status triplet in which the colour you paint with is not the colour you write with, for product consoles and the landing pages that have to look like them), daylight (a cool near-white portal field with generous radii and one very large soft shadow spent on a single object per screen, for client portals), notation (a near-white page drawn entirely in hairlines with a light serif over a monospace, no bold anywhere and an ink primary, for developer products sold on restraint), almanac (oatmeal paper with 2px seams and no 1px anywhere, a display set below a line-height of one, and mono tags notched through drawn boxes, for pages that assert a category), vitrine (a white hairline field with a serif display, an ink primary and one framed record carrying the evidence, for the front door of a product sold on trust). Ships the sheleg-design skill, the architecture reference, the motion doctrine, the Figma and Claude Design bridges, AI-surface patterns, style packs with ready-made token CSS, and the /sheleg-design command, and awning (a white forecourt where the accent is black and no hue reaches the chrome at all, a pill whose radius is a declared component token, one variable grotesque at 420/550 with no 700, and a single three-layer shadow, for commerce and platform front doors), and proscenium (a white field carrying two cool acts and one deep indigo act at the middle, an electric violet filling a control that stays nearly square at 4px against cards at 16, one family at nine weights, and a framed product panel the fold cuts off, for product-led marketing front doors whose argument is a demonstration), and bulletin (warm cream paper cut by flat pastel bands, every card and control a 1px ink outline standing on a hard zero-blur ink offset it travels into when pressed, a display face at 800 inside controls and 700 in the headline, and no tracking at any size, for front doors whose argument is breadth), and nameplate (a cool near-white slab under a page that is square on 87% of its elements, where the one round shape is reserved for a white 1px-bordered pill carrying somebody else's publication name as type, one family with the body at weight 500, and two uppercase registers tracked 0.06em and 0.175em, for pages whose argument is that named third parties will vouch for you: press placement, trust marks, certification and review aggregation), and rimlight (a white field with a cool grey act separator and one near-black act, a grotesque for every sentence and a monospace for every piece of chrome, square on 84% of its elements and tracked negative at every size, whose only elevation is a sixteen-layer coloured light rig — six layers lit and ten held at alpha 0, thrown from below-left — for a studio's own front door and the pages that sell what it makes), and onionskin (a white technical sheet at 96.5% zero radius — the squarest page in the library — where two bases do all the work and everything quiet is one of them at an alpha: text dims through the ink, structure dims through a navy that is never a word, over a dot grid with dashed hairlines and three faces at an 11px working size, for developer and AI infrastructure whose front page is a working document), deskmate, test-drive, surveyor, and chorus (warm off-white paper under a faint construction grid with a crosshair at every intersection, where the set piece is somebody else's question in a cut-corner bubble — 24px on three corners and 0 on the top right — over near-black slabs cut into the sheet, one coral that fills but never writes, and a periwinkle that only exists inside a gradient, for AI-search visibility, brand monitoring and community marketing whose proof is other people's conversations) (a warm beige working day lit from one source above the top edge, where a single four-stop ramp — peach, lilac, violet, deep navy — washes the field, fills a panel and fills one word of a heading, everything a hand touches is a pill at 56px and everything else a 32px slab, elevation is a field step with two shadows on a 10,211px page, and the set piece is a framed transcript whose quoted chat client keeps its own face, ink and status colours under a --quoted-* namespace, for products sold as a colleague rather than a tool: AI employees and chat-native agents).",
-  "version": "1.55.0",
+  "description": "SHELEG Design methodology: cinematic scroll-driven landing pages (single scroll clock, layered degrade-to-calm motion, WebGL particle formations), a motion doctrine that decides whether to animate before it decides how, and thirty-nine pluggable visual style packs, each with a ready-made token layer — instrument-console (near-black aerospace console; technical systems and infrastructure), editorial-luxury (cream and espresso; editorial, research, premium B2B), workbench (quiet light/dark UI; dashboards, admin, internal tools), briefing-room (dark 16:9 deck; investor and board presentations), atrium (cream daylight; consumer health and high-trust DTC), babylove (white with orange; SEO SaaS, long time-to-value, disconnected states), patchbay (black with mint-cyan; engines, buses, pipelines, OSS front doors), nameplate (cool slab with coral; press, certification and third-party trust), rimlight (white with blue light; studios, services and case studies), onionskin (white working sheet; developer and AI infrastructure), deskmate (warm beige with a dusk bleed; AI coworkers and chat-native agents), test-drive (warm paper with one coral; self-serve SaaS proven by the live product), surveyor (peach paper with teal and pink; visibility, monitoring and benchmark tools), chorus (warm paper under a crosshair grid, with a cut-corner bubble; AI-search visibility, brand monitoring and community marketing), outrank (white with violet; one brand across marketing and product), orchard (warm oat slabs; friendly biotech and wellness), field-notes (ruled green paper; auditable open-source developer tools), showroom (white gallery; product-led companies selling the app), blueprint (white technical stock; vector, storage and query infrastructure), prism (iridescent hard edge; command-first OSS infrastructure), maquette (near-black table; enterprise data infrastructure), cyclorama (looping pastel field; applied-AI consultancies), scoreboard (warm paper; growth, ads and accumulating metrics), datasheet (off-white specification; fraud, identity and device intelligence), manpage (cream manual; APIs, SDKs, CLIs and MCP servers), pigeonhole (filed white field; inbox, ticket and CRM triage), roster (faint square grid; platforms sold through who uses them), ora (warm coal; machine verdicts, audits and protocol traces), tenor (warm management paper; agent operations and autonomous back office), ledger (cream ruled console; analysts, BI and warehouse agents), paperclip (monochrome coal; orchestrators, schedulers and job runners), awning (white commerce forecourt; storefront, payroll and billing platforms), router (pale console with hairlines; dashboard, billing and inventory surfaces), daylight (bright portal with one shadow; client onboarding and service portals), notation (restrained technical hairlines; OSS, docs and developer workspaces), almanac (oatmeal editorial paper; manifestos and category-defining pages), vitrine (serif trust display; evaluated B2B, security and compliance), proscenium (white demo sequence; product tours and launch pages), bulletin (cheerful outlined bands; broad SMB and agency platforms). Ships the sheleg-design skill, the architecture reference, the motion doctrine, the Figma and Claude Design bridges, AI-surface patterns, the packs' token CSS, and the /sheleg-design command.",
+  "version": "1.57.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/sheleg-design/skills/sheleg-design/AI_PRODUCT_PATTERNS.md

@@ -14,6 +14,19 @@ and states, not a palette. Every token named here is workbench's.
 
 ---
 
+## Contents
+
+- 1. The five states of a model call
+- 2. Streaming beats spinners
+- 3. Latency has two numbers
+- 4. Provenance and uncertainty
+- 5. Agent actions: the confirm is the design
+- 6. Empty states carry the capability
+- 7. Chat is a shape, not the shape
+- 8. Cost, quota and scope
+- 9. Bans
+- Evidence
+
 ## 1. The five states of a model call
 
 Design all five before building any. Most AI UI ships state 2 and 3 only, then

package/plugins/sheleg-design/skills/sheleg-design/DESIGN_SYNC_BRIDGE.md

@@ -15,6 +15,16 @@ agent that does not have it — the pack stands on its own and nothing below app
 
 ---
 
+## Contents
+
+- 1. What crosses, and in what shape
+- 2. Style packs — the pack is the source of truth
+- 3. Figma — one border at a time
+- 4. Reference sweeps (Lazyweb, Mobbin, Refero) — layout crosses, identity does not
+- 5. Live-site extraction — the pack first, the sync second
+- 6. What cannot cross
+- 7. Round-trip discipline
+
 ## 1. What crosses, and in what shape
 
 A kit ships **three layers**, and they are a stack rather than a menu:

package/plugins/sheleg-design/skills/sheleg-design/FIGMA_BRIDGE.md

@@ -15,6 +15,13 @@ stands on its own and nothing below applies.
 
 ---
 
+## Contents
+
+- 1. Code → Figma (publish the pack as variables)
+- 2. Figma → code (implement a design without importing slop)
+- 3. What cannot cross
+- 4. Round-trip discipline
+
 ## 1. Code → Figma (publish the pack as variables)
 
 Use when a project has the pack in code and needs the design file to match — or

package/plugins/sheleg-design/skills/sheleg-design/MOBILE_SURFACES.md

@@ -9,7 +9,7 @@ pack's `## Responsive` section covers that, and this file does not repeat it.
 
 - What a pack decides here, and what it does not
 - The six rules every pack already carries — and one no pack answers
-- Reference sweeps (Lazyweb, Mobbin) — structure crosses, identity does not
+- Reference sweeps — structure crosses, identity does not
 
 ## What a pack decides here, and what it does not
 

package/plugins/sheleg-design/skills/sheleg-design/MOTION_DOCTRINE.md

@@ -8,6 +8,20 @@ Every number here is a decision someone else already paid for. Use them.
 
 ---
 
+## Contents
+
+- 1. Should this animate at all?
+- 2. Easing
+- 3. Duration
+- 4. Springs
+- 5. Forbidden forms
+- 6. Scroll motion
+- 7. Motion that came from a design tool
+- 8. Anti-drift
+- 9. Reduced motion
+- 10. Pre-flight
+- How the calibration dials bind
+
 ## 1. Should this animate at all?
 
 The first question is not "what animation" — it is "how often will a person see
@@ -305,6 +319,10 @@ Before calling motion done:
 - [ ] `markers` removed.
 - [ ] Reduced motion tested by actually turning it on.
 - [ ] The page still looks like the pack (§8).
+- [ ] Nothing in the diff is a rendered video standing in for page motion. If a file
+      IS the right answer, the obligations move with it —
+      [`MOTION_PRODUCTION.md`](./MOTION_PRODUCTION.md) owns that seam, including where
+      this section's contract lands once there is no user to read a media query.
 
 ---
 

package/plugins/sheleg-design/skills/sheleg-design/MOTION_PRODUCTION.md

@@ -0,0 +1,204 @@
+# Motion production — when motion leaves the page as a file
+
+[`MOTION_DOCTRINE.md`](./MOTION_DOCTRINE.md) decides whether a thing on a page may
+move, and how. This document starts one step later, at the only question it does not
+answer: **what happens when the motion has to become a file** — a launch video, a
+feature loop, a social cut, an OG card that moves, a changelog clip, a deck that
+plays.
+
+That is a different medium with different physics, and treating it as "the same
+animation, exported" is the mistake this document exists to prevent.
+
+## Contents
+
+- The boundary
+- Before the tool: what a rendered asset costs
+- The two tools, measured
+- The recommendation, and the three conditions that reverse it
+- The token seam
+- Reduced motion, on the other side of the render
+- Pre-flight for a rendered asset
+
+## The boundary
+
+| The motion is… | It belongs to | Read |
+|---|---|---|
+| in the page, driven by scroll, hover, focus or state | the page | `MOTION_DOCTRINE.md`, then `SHELEG_DESIGN.md` |
+| in the page, but authored as a timeline and played back | the page | `MOTION_DOCTRINE.md` §6 and §9 still bind |
+| a file the page embeds, or a file that never touches the page | **this document** | below |
+| a Lottie or a Figma export dropped into the page | the page | `MOTION_DOCTRINE.md` §7 |
+
+**Refusal phrase: "no render."** A brief that says *animate the hero* is page motion
+and stays page motion. Reaching for a rendered file there is a downgrade, and the
+next section prices it.
+
+## Before the tool: what a rendered asset costs
+
+A video in a hero looks like a shortcut and is a trade. Four things are given up, and
+a page should only give them up on purpose.
+
+1. **The reduced-motion contract.** A rendered file has no
+   `prefers-reduced-motion`. The doctrine's rule does not stop applying because the
+   motion moved into an MP4 — it moves to the **embedding page**, which owes a poster
+   frame, `autoplay` withheld under the reduce query, and a control. A hero video that
+   autoplays regardless is a doctrine violation wearing a different file extension.
+2. **The theme.** A pack's token layer answers a dark surface; a rendered frame cannot.
+   Every pack in this library declares `Themes:`, and a video baked against one of them
+   is wrong on the other. Either the surface behind it is fixed, or the asset is
+   rendered per theme, or the motion stays in the page.
+3. **The text.** Type in a rendered frame is not selectable, not translatable, not
+   readable by a screen reader and not indexable. A headline that matters is DOM.
+4. **The weight and the first frame.** The page's opening viewport now depends on a
+   decode. `frontend-performance` owns that number; this document only records that
+   the cost exists and lands on LCP.
+
+**What a rendered asset is genuinely for:** a surface you do not control (a social
+timeline, an app store, an ad slot, an email), a piece longer than an interaction, a
+piece with an audio track, and anything that must look identical on every machine.
+That last one is the whole reason both tools below exist.
+
+## The two tools, measured
+
+Both turn code into a deterministic MP4 by seeking a headless browser frame by frame
+and encoding the result. They differ in the language the composition is written in and
+in what using them costs. Read on 2026-08-30; version numbers and prices move, so
+re-read before quoting them.
+
+| | **Remotion** | **HyperFrames** |
+|---|---|---|
+| The composition is | a React component reading `useCurrentFrame()` | an HTML document with `data-start` / `data-duration` timing attributes and a seekable animation runtime |
+| Licence | its own two-tier licence, **not** an OSI one | **Apache-2.0** |
+| Free for | individuals, for-profit organizations **with up to 3 employees**, non-profits, and evaluation | everyone |
+| Paid when | a for-profit organization exceeds that size — Company License, read the current price from the vendor | never for the framework; the vendor's managed cloud render is a separate product |
+| First release | 2020 | 2026 |
+| Version on npm at the reading | `remotion` 4.0.518 | `hyperframes` 0.8.20 — **pre-1.0** |
+| FFmpeg | bundled since v4.0; no separate install | **required separately**, plus Node 22+ |
+| In-page playback | `@remotion/player`, a React component that takes props | `@hyperframes/player`, a web component that loads the composition in an **isolated iframe** |
+| Distributed rendering | AWS Lambda, Node SSR, Vercel, Cloud Run | AWS Lambda, Google Cloud Run, the vendor's managed cloud |
+| Agent surface | a skill set plus a documentation MCP | 20 skills behind one `/hyperframes` router, and a `/remotion-to-hyperframes` porting skill |
+
+Two asymmetries decide most briefs, and they point in opposite directions.
+
+- **Licence.** A studio of four people must pay to use Remotion commercially and may
+  use HyperFrames without asking anyone. There is no reading of the Remotion licence
+  under which a 4-person for-profit is free; the threshold is written into it.
+- **Maturity.** Remotion is on 4.0.518 after six years. HyperFrames has not shipped a
+  1.0. Everything below that number is allowed to move, and a composition written
+  today may need editing after a minor bump. That risk is real and is not cancelled by
+  the licence being friendlier.
+
+## The recommendation, and the three conditions that reverse it
+
+**Default to HyperFrames** for the work this skill is about — a designed page that
+occasionally needs a rendered motion asset. Three reasons, in order of weight:
+
+1. **The composition is written in the language the pack already speaks.** A pack's
+   `styles/tokens/<pack>.css` is a `:root` block of custom properties. In HyperFrames
+   it is `<link>`ed into the composition **unmodified** — the same file the site ships,
+   byte for byte, which is exactly the rule the kits already follow. In Remotion the
+   composition is React, and the token layer becomes a stylesheet imported into a
+   component tree: workable, and one translation step where a value can drift. This
+   library's entire position is that a token layer is copied and never transcribed, and
+   one of the two tools lets that hold across the render seam.
+2. **The licence removes a question that has nothing to do with design.** Apache-2.0
+   over a seat count.
+3. **The determinism rules are the doctrine's rules.** No wall clock, no unseeded
+   randomness, no fetch mid-frame, a locked output size, a finite length — the same
+   discipline `MOTION_DOCTRINE.md` §8 already demands of a page, restated for a
+   renderer. An author who has followed the doctrine has already followed this.
+
+**Reach for Remotion instead when any one of these is true.**
+
+- **The motion must be driven by application state in the page.** `@remotion/player` is
+  a React component: props go in, the composition re-renders, the page owns it. The
+  HyperFrames player is an iframe by design, which is excellent isolation and a wall
+  between your state and the timeline. A configurator, a live preview of a
+  user's edit, a chart the visitor drives — Remotion.
+- **The product is a video pipeline, not a page.** Prompt-to-video, per-customer
+  renders, template farms at volume. Remotion has six years of Lambda operations behind
+  it and a price per render, which is a business model rather than an obstacle.
+- **The team cannot carry a pre-1.0 dependency.** If a broken minor bump is a real cost
+  — a long-lived pipeline, a regulated client, a repository nobody will revisit for a
+  year — take the mature one and pay for it.
+
+**A brief that hits none of those and the licence threshold is not close** — one
+person, one landing page, one launch clip — can use either, and the tie-break is which
+one the operator already knows. Say so rather than manufacturing a reason.
+
+## The token seam
+
+Whatever the tool, the rule is the library's existing one and it does not relax:
+**a pack's token layer is copied, never transcribed**, and no colour literal appears
+outside it. The seam differs only in mechanism.
+
+**HyperFrames.** The composition is a document, so the token layer is a stylesheet:
+
+```html
+<head>
+  <link rel="stylesheet" href="./tokens/<pack>.css" />
+</head>
+<div data-composition-id="launch" data-width="1920" data-height="1080">
+  <h1 class="clip" data-start="0.4" data-duration="4">…</h1>
+</div>
+```
+
+Everything after that consumes `var(--…)`, exactly as a kit does.
+
+**Remotion.** Import the same file once at the composition root and consume the same
+custom properties from `style` objects or CSS modules. Do **not** rebuild the palette
+as a TypeScript object: two homes for one colour is the defect the DOCMAP's
+single-home rule exists to prevent, and it is invisible until the site and the video
+disagree in a screenshot.
+
+Three token families need a decision the page never forced:
+
+- **Durations.** A pack's `--dur-*` are page clocks in seconds. A renderer thinks in
+  frames. Convert at the edge — `frames = seconds × fps` — and keep the token as the
+  source. A duration typed twice is a duration that will drift.
+- **The reduced-motion branch.** Every token layer in this library carries one. It
+  **does not fire in a render**, because a renderer has no user preference. See below.
+- **Type.** A rendered frame has no font fallback worth the name: if the face has not
+  loaded before frame 0, the frame is wrong and stays wrong. Both tools require every
+  asset resolved before the first frame; a webfont is an asset.
+
+## Reduced motion, on the other side of the render
+
+This is the part neither tool does for you, and it is the doctrine's clause that most
+often gets dropped at this seam.
+
+- A rendered file **has no reduced-motion state**. The `@media (prefers-reduced-motion:
+  reduce)` block in the pack's token layer collapses nothing during a render, and that
+  is correct — there is no user there.
+- Therefore the obligation moves **to the page that embeds the file**, and it is
+  concrete: no `autoplay` under the reduce query, a poster frame that is a real frame
+  of the piece rather than a title card, a visible control, and no `loop` on anything a
+  reader has to read past.
+- If the asset exists *only* in a surface you do not control, say so in the pack's or
+  the project's notes. An unstated exemption reads as an oversight to the next reader,
+  which is how the clause quietly stops being followed.
+- **A JavaScript-driven reveal has the same shape and is easier to miss.** A media
+  query cannot stop a transform a script sets. Where a composition's motion is scripted,
+  the script reads the preference itself. `styles/chorus.md` carries the worked case —
+  a reference with zero reduced-motion rules and 383 script-set transforms.
+
+## Pre-flight for a rendered asset
+
+Run this before the render, not after. It is the doctrine's §10 with the four items a
+file adds.
+
+- [ ] The brief actually wants a file. Page motion was considered and rejected for a
+      stated reason.
+- [ ] The pack is chosen and its token layer is linked, not retyped.
+- [ ] Output size, fps and duration are fixed and written down. Nothing reads a clock.
+- [ ] Every asset — fonts, images, audio, video — resolves before frame 0.
+- [ ] No `Date.now()`, no `requestAnimationFrame`, no unseeded `Math.random()` anywhere
+      in the composition.
+- [ ] Durations came from the pack's tokens and were converted once.
+- [ ] The theme the asset is baked against is stated, and the surface behind it matches.
+- [ ] Any text that carries meaning is either also in the DOM, or its absence is a
+      deliberate, recorded choice.
+- [ ] The embedding page withholds autoplay under `prefers-reduced-motion: reduce`,
+      ships a poster and a control.
+- [ ] A byte-identical re-render was produced from the same input. If two runs differ,
+      something in the composition is reading the machine — pin the environment
+      (a container) before blaming the tool.

package/plugins/sheleg-design/skills/sheleg-design/SHELEG_DESIGN.md

@@ -26,6 +26,25 @@ build new sites on the same principles and understand *why* each piece works.
 
 ---
 
+## Contents
+
+- 0. The one-paragraph thesis
+- 1. Architecture at a glance
+- 2. Layer 1 — The scroll store (the single clock)
+- 3. Layer 2 — Smooth scroll (one position per frame)
+- 4. Layer 3 — The particle field (the scene-formation engine)
+- 5. Layer 4 — The 2D fallback (SignalMesh)
+- 6. Layer 5 — The projection bridge (fusing DOM and WebGL)
+- 7. Layer 6 — DOM choreography
+- 8. Layer 7 — Reveal primitives (act-themed entrances)
+- 9. Layer 8 — Scrubbed instruments (GSAP recipe)
+- 10. Cross-cutting rules
+- 11. Recipe — build a new SHELEG site from scratch
+- 12. Why it works (the deeper principles)
+- 13. File map (one file per idea)
+- Quick reference — each rule, and the failure it prevents
+- Three looks that are defaults, not decisions
+
 ## 0. The one-paragraph thesis
 
 A landing page feels "alive" not because it has many animations, but because a

package/plugins/sheleg-design/skills/sheleg-design/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: sheleg-design
-description: Use when deciding how something LOOKS or MOVES — cinematic landing pages and hero sections, particle/WebGL backgrounds, scroll-linked or scrubbed motion, layers that drift, dashboards, admin or internal tools, mobile screens, chat or agent interfaces, tokens, themes, palettes, typography and the Figma border. Triggers include "design a landing" / "дизайн лендинга", "build a landing page" / "сделай лендинг", "scroll animation" / "скролл-анимация", "dashboard style" / "стиль дашборда", "design tokens, style pack" / "дизайн-токены", "light/dark theme" / "светлая/тёмная тема", "figma variables" / "переменные фигмы, фигма в код", "mobile screen" / "мобильный экран", "palette, colors" / "палитра, цвета", "typography, font" / "типографика, шрифт", "how it looks, make it prettier" / "выглядит, красиво, красивее", "visual reference" / "визуальные референсы", "investor deck" / "презентация". Not for structure, copy or backend behavior.
+description: Use when deciding how something LOOKS or MOVES — cinematic landing pages and hero sections, particle/WebGL backgrounds, scroll-linked or scrubbed motion, layers that drift, dashboards, admin or internal tools, mobile screens, chat or agent interfaces, tokens, themes, palettes, typography and the Figma border. Triggers: "design a landing" / "дизайн лендинга", "build a landing page" / "сделай лендинг", "scroll animation" / "скролл-анимация", "dashboard style" / "стиль дашборда", "design tokens, style pack" / "дизайн-токены", "light/dark theme" / "светлая/тёмная тема", "figma variables" / "переменные фигмы, фигма в код", "mobile screen" / "мобильный экран", "palette, colors" / "палитра, цвета", "typography, font" / "типографика, шрифт", "how it looks, make it prettier" / "выглядит, красиво, красивее", "visual reference" / "визуальные референсы", "investor deck as a web page" / "веб-презентация". Not for structure, copy, backend behavior, or .pptx decks.
 license: MIT
+compatibility: Optional siblings — dataviz, shadcn, migrate-radix-to-base; each has an in-text fallback when absent.
 metadata:
-  version: 1.55.0
+  version: 1.57.0
 ---
 
 # SHELEG Design
@@ -38,6 +39,9 @@ duration ceiling, the forbidden forms, and the reduced-motion contract.
 - AI product surfaces: chat and agent UI, streaming output, run logs, model errors,
   generated-content and confirmation states ([`AI_PRODUCT_PATTERNS.md`](./AI_PRODUCT_PATTERNS.md))
 - Moving a visual system across the Figma border either way ([`FIGMA_BRIDGE.md`](./FIGMA_BRIDGE.md))
+- Motion that has to leave the page as a rendered file — a launch video, a feature
+  loop, a social cut ([`MOTION_PRODUCTION.md`](./MOTION_PRODUCTION.md)), which also
+  names the two programmatic-video tools and which one to reach for
 
 **Never apply the cinematic motion layer to:** product UI, docs sites, static content
 sites — or any page whose visual system or copy isn't finished yet. Product UI takes
@@ -153,10 +157,14 @@ as a definition of done, in that order:
 - **Scene depth — six layers** ([`SURFACE_COMPOSITION.md`](./SURFACE_COMPOSITION.md)),
   before writing CSS for a cinematic page. A scene has planes; everything on one
   plane is the failure no amount of easing repairs.
-- **Charts — hand the pack to `dataviz`** (same file), before drawing a chart in
-  any pack. Token names are not uniform across the thirty-nine packs — only `--bg`
-  and `--ink` resolve in every one — and an undefined custom property does not error,
-  it silently falls back. Guessing one is the quietest way to ship a wrong chart.
+- **Charts — the role contract in the same file, plus the `dataviz` handoff
+  where that skill exists**, before drawing a chart in any pack. Token names are
+  not uniform across the thirty-nine packs — only `--bg` and `--ink` resolve in
+  every one — and an undefined custom property does not error, it silently falls
+  back. Guessing one is the quietest way to ship a wrong chart. A `dataviz`
+  skill is an optional neighbour this skill does not ship: where none is
+  installed, the role table in `SURFACE_COMPOSITION.md` IS the chart contract,
+  applied by hand.
 - **Mobile surfaces** ([`MOBILE_SURFACES.md`](./MOBILE_SURFACES.md)), when the
   brief is a native app screen or a mobile-web view — not a desktop page whose
   only mobile concern is collapse. Five mobile rules the packs each state alone,
@@ -229,9 +237,13 @@ there, the work is bespoke scroll and WebGL, and reaching for a component kit is
 how a hero ends up looking like a settings screen.
 
 **Who does the work.** This section decides *whether* and *against which tokens*.
-The `shadcn` skill does the adding, searching and composing, and
-`migrate-radix-to-base` handles the Radix→Base move; both are installed and
-trigger on their own words. Do not restate their component docs here.
+Where the `shadcn` skill is installed it does the adding, searching and
+composing, and `migrate-radix-to-base` handles the Radix→Base move; both are
+**optional neighbours** this skill declares in its `compatibility` line and does
+not ship, and they trigger on their own words where present. Where they are
+absent nothing is blocked: the kit's own CLI (`npx shadcn@latest add
+<component>`) does the adding, and the token mapping above binds either way. Do
+not restate their component docs here.
 
 ## Optional — Figma (design ↔ code)
 

package/plugins/sheleg-design/skills/sheleg-design/SURFACE_COMPOSITION.md

@@ -53,9 +53,15 @@ A pack that bans grain and blur leaves the slot empty rather than filling it —
 
 ## Charts and data — hand the pack to `dataviz`
 
-Do not restyle charts from the pack by hand, and do not let a chart library pick
-its own colours. The `dataviz` skill already owns chart form, colour roles and
-the runnable palette validation; a pack is the *parameter set* it consumes.
+Do not let a chart library pick its own colours. Where a `dataviz` skill is
+installed, it owns chart form, colour roles and the runnable palette validation,
+and a pack is the *parameter set* it consumes — hand it the values mapped below.
+That skill is an **optional neighbour**: this skill declares it in its
+`compatibility` front-matter and does not ship it, so its absence is an ordinary
+state, not a broken install. **Where no dataviz skill is installed, the role
+table below is the contract** — resolve each role from the chosen pack's token
+layer by hand, and the status map and the two rules at the end of this section
+bind exactly the same, with nobody to hand them to.
 
 **Read the chosen pack's own token names before you write a single `var()`.**
 This table is by *role*, not by token, because the names are not uniform across