sheleg-design-skill 0.2.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,6 +64,20 @@ 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 |
@@ -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.2.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}/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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 with each other. Read before designing the motion architecture; pairs with an existing visual system, does not replace one.
+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