sheleg-design-skill 0.1.0 → 0.3.0

package/README.md

@@ -1,5 +1,9 @@
 # SHELEG Design — agent skill
 
+[![npm version](https://img.shields.io/npm/v/sheleg-design-skill)](https://www.npmjs.com/package/sheleg-design-skill)
+[![CI](https://github.com/ssheleg/sheleg-design-skill/actions/workflows/validate.yml/badge.svg)](https://github.com/ssheleg/sheleg-design-skill/actions/workflows/validate.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
 > A motion + particle interface methodology for building cinematic,
 > scroll-driven landing pages — packaged as an installable agent skill for
 > Cursor and Claude.
@@ -60,11 +64,25 @@ npx sheleg-design-skill --force
 npx sheleg-design-skill --help
 ```
 
+### Other install paths
+
+```bash
+# Claude Code plugin (adds the /sheleg-design command too)
+/plugin marketplace add ssheleg/sheleg-design-skill
+/plugin install sheleg-design@sheleg-design-skill
+
+# vercel-labs skills CLI (70+ agents)
+npx skills add ssheleg/sheleg-design-skill
+
+# POSIX fallback, no Node
+curl -fsSL https://raw.githubusercontent.com/ssheleg/sheleg-design-skill/main/install.sh | sh
+```
+
 ### What gets installed
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | Agent-facing skill: discovery trigger + the principles + how to apply them |
+| `SKILL.md` | Agent-facing skill: discovery trigger, the principles, how to apply them, quick-reference rules, common mistakes |
 | `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 the "why it works" |
 
 After installing, a Cursor or Claude agent in that project can discover the
@@ -83,6 +101,27 @@ applies to any stack that can render to a canvas/WebGL surface and read scroll.
 The installer is a single zero-dependency Node script, so `npx` runs instantly
 with no install step and no supply-chain surface.
 
+## Development
+
+`python3 test/validate.py` checks repo consistency (manifests, version sync,
+skill/command/rule front-matter, relative links); CI runs it plus a CLI smoke
+test on every push and PR. Versioning is semver; bump `marketplace.json` +
+`plugin.json` + `package.json` + `CHANGELOG.md` together — the validator
+enforces the sync.
+
+## По-русски (коротко)
+
+SHELEG Design — методология кинематографичных скролл-лендингов: один
+scroll-«клок» питает много дешёвых независимых слоёв (WebGL-частицы,
+2D-фоллбек, параллакс, scrub-инструменты, прогресс-рейл), каждый деградирует
+до спокойной статики. Ничего не кроссфейдится — формации «передислоцируются».
+Установка: `npx sheleg-design-skill` (авто-детект `.cursor`/`.claude`), либо
+плагин Claude Code — `/plugin marketplace add ssheleg/sheleg-design-skill`,
+затем `/plugin install sheleg-design@sheleg-design-skill` (даст команду
+`/sheleg-design`). Агент получает SKILL.md (принципы и порядок работы) и
+SHELEG_DESIGN.md (полный референс: архитектура, точная математика морфа,
+DOM↔WebGL-мост, рецепт сборки с нуля).
+
 ## License
 
 MIT © ssheleg

package/bin/cli.js

@@ -14,7 +14,14 @@
 const fs = require("fs");
 const path = require("path");
 
-const SKILL_DIR = path.join(__dirname, "..", "skill");
+const SKILL_DIR = path.join(
+  __dirname,
+  "..",
+  "plugins",
+  "sheleg-design",
+  "skills",
+  "sheleg-design",
+);
 const SKILL_SLUG = "sheleg-design";
 const FILES = ["SKILL.md", "SHELEG_DESIGN.md"];
 

package/cursor/rules/sheleg-design.mdc

@@ -0,0 +1,48 @@
+---
+description: Apply SHELEG Design when building or upgrading a cinematic scroll-driven landing page, hero, or particle/WebGL scroll experience — or when scroll motion feels busy, janky, or out of sync
+alwaysApply: false
+---
+
+# SHELEG Design — single-clock scroll motion
+
+A page feels cinematic from a **single source of truth** (measured scroll
+position) driving **many cheap, layered, independently-degradable responses** —
+not from many animations. If the project has the full skill installed
+(`.cursor/skills/sheleg-design/`), read its `SKILL.md` and `SHELEG_DESIGN.md`
+first; otherwise follow the contract below (self-contained on purpose).
+
+## Five principles, in order
+
+1. **One clock.** All motion derives from one measured scroll state in one
+   store; no layer measures scroll itself, so layers never drift out of phase.
+2. **Read per frame, notify rarely.** Hot consumers (WebGL/canvas/progress
+   rail) read the store imperatively with zero framework renders; only coarse
+   act/section changes notify the framework.
+3. **Hold, then redeploy.** Hold a formation ~80% of a section, then morph in
+   a short, phase-staggered, arc-curved wave. Crossfades between point sets
+   are banned.
+4. **Earned motion.** Scrub only for instruments that narrate state over time
+   (charts, step flows); hover/entrance motion stays sub-500ms and never
+   gates content visibility.
+5. **Degrade to calm.** `prefers-reduced-motion` / coarse pointer / no-WebGL
+   collapse to a static, fully-legible page. The effect is a bonus, never a
+   dependency.
+
+## Non-negotiables
+
+- One scroll store, two read paths: live getter for per-frame readers,
+  coarse subscription for framework-rendered UI.
+- Storyboard in data: a `SCENES` registry (`{ anchor, formation, focusX,
+  energy }` per section); iterate on data before render loops.
+- Smooth scroll (e.g. Lenis) driven from the animation library's ticker so
+  scrubbed instruments and the particle field share one inertia.
+- Lazy-load GSAP/WebGL out of the initial bundle; mount WebGL one frame
+  after hydration paints.
+- One ease + one small duration/stagger token set site-wide.
+- Scrubbed SVG: `ease: 'none'`, `pathLength={1}`, always kill timelines and
+  triggers on cleanup.
+- Animate only `transform` and `opacity`.
+- Every layer ships its reduced-motion/fallback branch in the same commit.
+- At most one parallax figure per viewport; no scrub on hero/entrances.
+- Visual system (color, type, spacing, components) is finished before any
+  motion work starts.

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "sheleg-design-skill",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "SHELEG Design — an agent skill for building cinematic, scroll-driven, particle-backed landing pages. Installs a SKILL.md + reference doc into your project so Cursor/Claude agents can build sites with a single-clock motion system, a scene-formation particle engine, and degrade-to-calm fallbacks.",
   "bin": {
     "sheleg-design-skill": "bin/cli.js"
   },
   "files": [
     "bin/",
-    "skill/",
+    "plugins/",
+    "cursor/",
     "README.md",
     "LICENSE"
   ],

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

@@ -0,0 +1,21 @@
+{
+  "name": "sheleg-design",
+  "description": "SHELEG Design methodology for cinematic scroll-driven landing pages: a single scroll clock driving layered, degrade-to-calm motion (WebGL particle formations, 2D fallback, parallax, scrubbed instruments, progress rail). Ships the sheleg-design skill, the full architecture reference, and the /sheleg-design command.",
+  "version": "0.3.0",
+  "author": {
+    "name": "ssheleg"
+  },
+  "homepage": "https://github.com/ssheleg/sheleg-design-skill",
+  "repository": "https://github.com/ssheleg/sheleg-design-skill",
+  "license": "MIT",
+  "keywords": [
+    "design",
+    "motion",
+    "animation",
+    "particles",
+    "webgl",
+    "scroll",
+    "landing-page",
+    "claude-code"
+  ]
+}

package/plugins/sheleg-design/commands/sheleg-design.md

@@ -0,0 +1,13 @@
+---
+description: Apply the SHELEG Design methodology (single-clock, layered, degrade-to-calm motion) to the current landing-page / hero / scroll-animation task
+argument-hint: [what to build or upgrade]
+---
+
+Invoke the `sheleg-design` skill and apply it to the current request.
+
+- Read the skill's SKILL.md, then its full reference `SHELEG_DESIGN.md`
+  (same directory) before designing anything.
+- Task: $ARGUMENTS — if empty, ask what page or section to build/upgrade,
+  then proceed per the skill's "How to Apply" order.
+- Follow the skill's non-negotiables (Quick Reference table) and ship every
+  layer's reduced-motion/fallback branch in the same commit.

package/{skill → plugins/sheleg-design/skills/sheleg-design}/SHELEG_DESIGN.md

@@ -158,7 +158,7 @@ to you" signal.
 
 ## 3. Layer 2 — Smooth scroll (one position per frame)
 
-**File:** `src/components/v2/motion/SmoothScroll.tsx`
+**File:** `src/components/motion/SmoothScroll.tsx`
 
 Lenis provides inertial scrolling, but the important move is **driving Lenis
 from the GSAP ticker** rather than its own rAF:
@@ -183,7 +183,7 @@ and keep native scroll. The store still runs, so the rail and nav stay in sync.
 
 ## 4. Layer 3 — The particle field (the scene-formation engine)
 
-**File:** `src/components/v2/webgl/SignalField.tsx`
+**File:** `src/components/webgl/SignalField.tsx`
 
 This is the showpiece: ~936 points (`24 × 13 × 3`) that narrate the page section
 by section. It is a single `THREE.Points` cloud whose target positions change
@@ -326,7 +326,7 @@ scrubbed scalar, scrolling back up rewinds the whole explosion frame-for-frame.
 
 ## 5. Layer 4 — The 2D fallback (SignalMesh)
 
-**File:** `src/components/v2/atmosphere/SignalMesh.tsx`
+**File:** `src/components/atmosphere/SignalMesh.tsx`
 
 Touch and no-WebGL clients get a canvas mesh: two depth layers of grid nodes
 with hairline links and traveling pulses, plus **stroke overlays** that fade in
@@ -399,18 +399,18 @@ particle "head" runs exactly where the line tip is being drawn.
 
 Three small components, one mechanism each, all reading the same clock.
 
-### FocalSpotlight — `src/components/v2/motion/FocalSpotlight.tsx`
+### FocalSpotlight — `src/components/motion/FocalSpotlight.tsx`
 An `IntersectionObserver` with a generous center band (`rootMargin: -22% 0 -22% 0`)
 toggles a `data-dim` attribute on sections outside the band. CSS dims them to
 62% opacity. The reader's eye is always pulled to the active section. The finale
 section is excluded (`:not(#finale)`) because it runs its own fade.
 
-### ParallaxDrift — `src/components/v2/motion/ParallaxDrift.tsx`
+### ParallaxDrift — `src/components/motion/ParallaxDrift.tsx`
 Wraps **at most one figure per viewport** in a GSAP `yPercent` scrub for a few
 percent of depth drift. Restraint is the rule: parallax on everything is nausea;
 parallax on the one hero figure is depth.
 
-### ScrollRail — `src/components/v2/atmosphere/ScrollRail.tsx`
+### ScrollRail — `src/components/atmosphere/ScrollRail.tsx`
 A right-edge hairline whose fill is scaled imperatively (`scaleY(global)`) and
 brightened by `velocity` — a live mission timeline, updated per frame with zero
 React renders. Act markers deep-link to their anchor sections and use the coarse
@@ -420,7 +420,7 @@ React renders. Act markers deep-link to their anchor sections and use the coarse
 
 ## 8. Layer 7 — Reveal primitives (act-themed entrances)
 
-**File:** `src/components/v2/design/Reveal.tsx`
+**File:** `src/components/design/Reveal.tsx`
 
 Entrances are not generic. Each narrative act has a reveal whose *physics* match
 its meaning — this is Disney's "staging" applied to a scroll page:
@@ -487,7 +487,7 @@ The non-negotiables (each learned from a real bug here):
 No component invents its own curve. Everything uses:
 
 - **`EASE = cubic-bezier(0.16, 1, 0.3, 1)`** (an easeOutExpo-like signature),
-  mirrored in CSS as `--v2-ease`.
+  mirrored in CSS as `--motion-ease`.
 - **`DUR`** — `fast 0.18` / `base 0.32` / `slow 0.55` / `epic 0.8` seconds.
 - **`STAGGER = 0.07`** — the standard interval between sibling reveals.
 
@@ -622,18 +622,18 @@ A pragmatic order that front-loads the parts everything else depends on.
 | Lazy GSAP + reduced-motion gate | `src/lib/motion/gsap-client.ts` |
 | DOM↔WebGL bridge | `src/lib/motion/field-sync.ts` |
 | Interactive field gestures | `src/lib/motion/use-section-field.ts` |
-| WebGL particle field | `src/components/v2/webgl/SignalField.tsx` |
-| 2D fallback field | `src/components/v2/atmosphere/SignalMesh.tsx` |
-| Field/fallback mode switch | `src/components/v2/atmosphere/AtmosphereField.tsx` |
-| Constellation SVG overlay | `src/components/v2/atmosphere/ConstellationOverlay.tsx` |
-| Progress rail | `src/components/v2/atmosphere/ScrollRail.tsx` |
-| Smooth scroll | `src/components/v2/motion/SmoothScroll.tsx` |
-| Attention dimming | `src/components/v2/motion/FocalSpotlight.tsx` |
-| Figure parallax | `src/components/v2/motion/ParallaxDrift.tsx` |
-| Reveal primitives | `src/components/v2/design/Reveal.tsx` |
-| Epilogue runway | `src/components/v2/sections/FinaleSectionV2.tsx` |
+| WebGL particle field | `src/components/webgl/SignalField.tsx` |
+| 2D fallback field | `src/components/atmosphere/SignalMesh.tsx` |
+| Field/fallback mode switch | `src/components/atmosphere/AtmosphereField.tsx` |
+| Constellation SVG overlay | `src/components/atmosphere/ConstellationOverlay.tsx` |
+| Progress rail | `src/components/atmosphere/ScrollRail.tsx` |
+| Smooth scroll | `src/components/motion/SmoothScroll.tsx` |
+| Attention dimming | `src/components/motion/FocalSpotlight.tsx` |
+| Figure parallax | `src/components/motion/ParallaxDrift.tsx` |
+| Reveal primitives | `src/components/design/Reveal.tsx` |
+| Epilogue runway | `src/components/sections/FinaleSection.tsx` |
 | Scrubbed instruments (examples) | `WhyNowChart.tsx`, `EcosystemDiagram.tsx`, `PinnedSteps.tsx` |
-| CSS tokens + all `v2-*` styles | `src/app/v2.css` |
+| CSS tokens + motion styles | `src/app/motion.css` |
 
 ---
 

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

@@ -0,0 +1,74 @@
+---
+name: sheleg-design
+description: Use when building or upgrading a cinematic scroll-driven landing page, marketing site, or hero experience — a particle/WebGL background, scroll-linked animation, parallax, pinned or scrubbed sections, formation-morphing scenes — or when such a page feels busy or janky, or its motion layers drift out of sync. RU triggers - кинематографичный лендинг, скролл-анимация, лендинг с частицами. Pairs with an existing visual system, does not replace one.
+---
+
+# SHELEG Design
+
+## Overview
+
+A page feels cinematic not from many animations, but from a **single source of
+truth** (measured scroll position) driving **many cheap, layered,
+independently-degradable responses**. Centralize scroll into one store; layers
+read it per frame and react in their own language. Nothing crossfades — things
+*redeploy*. Every layer degrades to a calm static state.
+
+**REQUIRED REFERENCE:** read [`SHELEG_DESIGN.md`](./SHELEG_DESIGN.md) (same
+directory) before implementing — it holds the architecture, exact morph math,
+the DOM↔WebGL bridge, the build recipe (§11), and the file map.
+
+## When to Use
+
+- Landing/marketing/hero pages where motion is a stated goal
+- Particle or WebGL backgrounds tied to scroll; scenes that morph per section
+- Scroll-linked charts, step flows, progress rails, parallax
+- Existing scroll site that feels nervous, janky, or out of phase
+
+**Not for:** docs, dashboards, static content sites — or any page whose visual
+system or copy isn't finished yet. Fix those first; motion amplifies weakness.
+
+## Core Pattern — five principles, in order
+
+1. **One clock.** All motion derives from one measured scroll state; no layer
+   measures scroll itself, so layers can never drift out of phase.
+2. **Read per frame, notify rarely.** Hot consumers (WebGL/canvas/rail) read
+   the store imperatively, zero framework renders; only coarse act/section
+   changes notify the framework.
+3. **Hold, then redeploy.** Hold a formation ~80% of a section, then morph in a
+   short, phase-staggered, arc-curved wave. Crossfades are banned.
+4. **Earned motion.** Scrub only for instruments that narrate state over time;
+   hover/entrance motion stays sub-500ms and never gates content.
+5. **Degrade to calm.** Reduced-motion / coarse pointer / no-WebGL collapse to
+   a static, fully-legible page. The effect is a bonus, never a dependency.
+
+## How to Apply
+
+1. Visual system first (color, type, spacing, components).
+2. Build bottom-up in the §11 layer order: scroll clock → smooth scroll →
+   particle field → 2D fallback → DOM choreography → reveals → scrubbed
+   instruments → optional DOM↔WebGL bridge. One small file per layer.
+3. Storyboard in data: a `SCENES` registry (`{ anchor, formation, focusX,
+   energy }` per section); iterate on the data before touching render loops.
+4. Ship each layer's reduced-motion/fallback branch in the same commit.
+5. Verify: typecheck/lint/build; screenshot each scene mid-hold and mid-morph;
+   reduced-motion pass; narrow-viewport pass.
+
+## Quick Reference
+
+| Rule | Prevents |
+|---|---|
+| One scroll store, two read paths (live getter + coarse subscription) | layers drifting out of phase; render storms |
+| Long hold, short smoothstepped morph tail | nervous, constantly-moving page |
+| Per-point phase-staggered, perpendicular-arc migration | "screensaver" particle look |
+| Smooth scroll driven from the animation library's ticker | scrub and field on different inertia |
+| Lazy-load GSAP/WebGL; mount WebGL one frame after hydration | heavy initial bundle, hydration jank |
+| One ease + tiny duration/stagger token set site-wide | motion reading as many systems, not one |
+| Scrubbed SVG: `ease: 'none'`, `pathLength={1}`, kill timelines on cleanup | easing fighting scrub; leaked triggers |
+| Animate only `transform`/`opacity` | layout thrash |
+
+## Common Mistakes
+
+- Paying the fallback/a11y tax "at the end" → it never ships. Same commit.
+- Parallax on everything → nausea. At most one drifting figure per viewport.
+- Scrub on hero/entrances → motion feels unearned; reserve scrub for
+  instruments.

package/skill/SKILL.md

@@ -1,85 +0,0 @@
----
-name: sheleg-design
-description: Use when building or upgrading a cinematic, scroll-driven landing page, marketing site, or hero experience — especially one with a particle/WebGL background, scroll-linked animation, parallax, pinned/scrubbed sections, or formation-changing motion. SHELEG Design is a motion + systems methodology: one scroll "clock" drives many cheap, layered, independently-degradable responses (a particle field, a 2D fallback, attention dimming, parallax, scrubbed instruments, a progress rail) so the page reads as a single precision instrument. Read this before designing the motion architecture of such a site; it pairs with a visual system, not replaces one.
----
-
-# SHELEG Design
-
-A methodology for landing pages that feel *alive* without feeling busy. Full
-reference (architecture, code-level mechanics, build-from-scratch recipe, file
-map, and the deeper "why") lives in [`SHELEG_DESIGN.md`](./SHELEG_DESIGN.md) next
-to this file — read it before implementing.
-
-## The thesis
-
-A page feels cinematic not from many animations, but from a **single source of
-truth** (scroll position) driving **many cheap, layered responses** that are
-individually quiet and collectively rich. Centralize scroll into one external
-store; let independent layers read it per frame and react in their own language.
-Nothing crossfades — things *redeploy*. Every layer degrades to a calm static
-state.
-
-## The five principles (apply in order)
-
-1. **One clock.** All motion derives from one measured scroll state. Layers never
-   measure scroll independently, so they can never drift out of phase.
-2. **Read per frame, notify rarely.** Hot consumers (WebGL/canvas/rail) read the
-   store imperatively each frame and cause zero React renders. Only coarse,
-   human-visible changes (the current "act"/section) notify the framework.
-3. **Hold, then redeploy.** Hold a formation steady for ~80% of a section, then
-   morph in a short, phase-staggered, arc-curved wave. Ban crossfades.
-4. **Earned motion.** Scrub belongs to instruments that narrate state over time
-   (charts, step flows). Hover/entrance motion stays sub-500ms and never gates
-   content visibility.
-5. **Degrade to calm.** `prefers-reduced-motion` / coarse pointer / no-WebGL all
-   collapse to a static, fully-legible page. The effect is a bonus, never a
-   dependency.
-
-## How to use this skill
-
-When asked to build or upgrade such a site:
-
-1. **Lay the visual system first** (color, type, spacing, components). Motion on
-   top of a weak visual system amplifies the weakness. SHELEG Design is the
-   motion layer — it assumes a visual foundation exists.
-2. **Build bottom-up following the layer order** in `SHELEG_DESIGN.md` §11:
-   the scroll clock → smooth scroll → particle field → 2D fallback → DOM
-   choreography → reveal primitives → scrubbed instruments → (optional) DOM↔WebGL
-   bridge. Each layer is a small, single-responsibility file reading the one clock.
-3. **Storyboard in data.** Express the narrative as a `SCENES` registry (one
-   `{ anchor, formation, focusX, energy }` per section). Iterate on the data
-   before touching render loops.
-4. **Pay the fallback + a11y tax in the same commit** as each layer, never at the
-   end. Every animated component ships its reduced-motion branch immediately.
-5. **Verify** with typecheck/lint/build, screenshots of each scene mid-hold and
-   mid-morph, a reduced-motion pass, and a narrow-viewport pass.
-
-## Non-negotiables (each prevents a real failure mode)
-
-- Centralize scroll in ONE store with two read paths: a live getter for
-  per-frame readers and a coarse subscription for framework-rendered UI.
-- Hold-then-morph (long hold, short smoothstepped tail) — constant morphing
-  reads as nervous; this is the single biggest "calm" lever.
-- Redeploy with a per-point phase-staggered, perpendicular-arc migration — this
-  is what makes a particle field read as premium rather than a screensaver.
-- Drive smooth scroll (e.g. Lenis) from the animation library's ticker so
-  scrubbed instruments and the particle field share one inertia.
-- Lazy-load heavy libs (GSAP/WebGL) out of the initial bundle; WebGL mounts one
-  frame after hydration paints.
-- One ease + a tiny duration/stagger token set for the whole site; no component
-  invents its own curve.
-- For scrubbed SVG: `ease: 'none'`, `pathLength={1}` to normalize paths, and
-  always kill timelines + triggers on cleanup.
-- Animate only `transform` and `opacity`; reserve scrub for genuine instruments.
-
-## When NOT to use it
-
-Skip for static content sites, docs, dashboards, or anything where motion is not
-a goal. Do not bolt the particle field onto a page whose visual system or copy
-isn't finished — fix those first.
-
----
-
-Read [`SHELEG_DESIGN.md`](./SHELEG_DESIGN.md) for the full architecture, code
-mechanics, the exact morph math, the DOM↔WebGL projection bridge, the
-build-from-scratch recipe, and the file map.