sheleg-design-skill 0.2.0 → 0.4.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,17 +64,39 @@ 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, 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" |
+| `styles/*.md` | Style packs — the visual identity layer: `instrument-console` (near-black console, electric-blue signal) and `editorial-luxury` (warm cream/espresso/sage, dossier motifs). Each locks palette, type, texture, motion tokens, motifs, and bans; the pack contract lets you author new styles |
 
 After installing, a Cursor or Claude agent in that project can discover the
 skill and use it when you ask it to build or upgrade a cinematic,
 scroll-driven, particle-backed page.
 
+## Style-agnostic motion, pluggable identity
+
+The motion methodology (one clock, layered responses, degrade-to-calm) is
+independent of the visual style. The look comes from a **style pack** the
+agent picks per project — dark instrument console or warm editorial luxury
+out of the box, or a new pack authored against the same contract.
+
 ## Stack-agnostic
 
 The skill teaches **principles and architecture**, not a fixed dependency set.
@@ -83,6 +109,14 @@ 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.
+
 ## License
 
 MIT © ssheleg

package/bin/cli.js

@@ -14,9 +14,21 @@
 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"];
+const FILES = [
+  "SKILL.md",
+  "SHELEG_DESIGN.md",
+  "styles/instrument-console.md",
+  "styles/editorial-luxury.md",
+];
 
 const pkg = require(path.join(__dirname, "..", "package.json"));
 
@@ -79,6 +91,7 @@ ${c("bold", "Default")}
 ${c("bold", "What it installs")}
   SKILL.md           the agent-facing skill (discovery + principles)
   SHELEG_DESIGN.md   the full reference (architecture, recipes, why it works)
+  styles/*.md        style packs (instrument-console, editorial-luxury)
 `);
 }
 
@@ -135,14 +148,17 @@ function main() {
 
   fs.mkdirSync(targetDir, { recursive: true });
   for (const f of FILES) {
-    fs.copyFileSync(path.join(SKILL_DIR, f), path.join(targetDir, f));
+    const dest = path.join(targetDir, f);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(path.join(SKILL_DIR, f), dest);
   }
 
   const rel = path.relative(cwd, targetDir) || ".";
   console.log(
     `\n${c("green", "✓")} ${c("bold", "SHELEG Design")} installed to ${c("blue", rel + "/")}\n` +
       `  ${c("dim", "SKILL.md")}          the agent skill\n` +
-      `  ${c("dim", "SHELEG_DESIGN.md")}  the full reference\n\n` +
+      `  ${c("dim", "SHELEG_DESIGN.md")}  the full reference\n` +
+      `  ${c("dim", "styles/")}           style packs (console / editorial)\n\n` +
       `Your Cursor / Claude agent can now discover the skill and build\n` +
       `cinematic, scroll-driven, particle-backed pages on its principles.\n\n` +
       `${c("dim", "Docs: " + pkg.homepage)}\n`,

package/cursor/rules/sheleg-design.mdc

@@ -0,0 +1,50 @@
+---
+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`, `SHELEG_DESIGN.md`,
+and the chosen style pack in `styles/` (instrument-console — dark console;
+editorial-luxury — warm editorial) 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.4.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.4.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
@@ -41,9 +41,26 @@ system or copy isn't finished yet. Fix those first; motion amplifies weakness.
 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.
 
+## Style packs
+
+The motion methodology is style-agnostic; the visual identity comes from a
+style pack in [`styles/`](./styles/):
+
+| Pack | Look | Choose for |
+|---|---|---|
+| [`instrument-console`](./styles/instrument-console.md) | near-black aerospace console, one electric-blue signal, mono telemetry | technical / systems / infra products |
+| [`editorial-luxury`](./styles/editorial-luxury.md) | warm cream + espresso ink, sage accent, Fraunces/Newsreader, dossier motifs | editorial / research / premium B2B |
+
+Read the chosen pack in full before styling anything — it supplies the
+palette, type, texture, motion-token values, signature motifs, and bans.
+For a new style, author a new pack file with the same headings (Register /
+Palette / Type / Texture & surface / Motion tokens / Signature motifs /
+Micro-interactions / Bans); never invent token values ad hoc.
+
 ## How to Apply
 
-1. Visual system first (color, type, spacing, components).
+1. Visual system first: pick (or author) a style pack, apply its tokens as
+   the site-wide design tokens (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.

package/plugins/sheleg-design/skills/sheleg-design/styles/editorial-luxury.md

@@ -0,0 +1,99 @@
+# Style pack — Editorial Luxury
+
+Origin: prowl.chat (production). Warm cream field, espresso ink, one
+functional sage-green accent, terracotta as a rare editorial highlight,
+classified-red reserved for negatives only. "Design *is* the product" on
+public pages; quiet and fast inside the app. Dossier/editorial DNA:
+hairline rules, eyebrow labels, stamp/seal motifs, mono data, authored
+artifact previews instead of icon cards.
+
+## Register
+
+Choose this pack for warm, editorial, print-inspired products: research /
+intelligence tools, content products, premium B2B. Two registers:
+**brand** (landing, use-case, legal, shared pages — cinematic, editorial)
+and **product** (authenticated app — quiet micro-interactions only, never
+cinematic noise).
+
+## Palette
+
+| Token | Value | Role |
+|---|---|---|
+| `--paper` | `#fbf6ec` | primary cream field |
+| `--paper-2` | `#f3ead9` | raised card on cream |
+| `--paper-3` | `#ece0cb` | deeper inset |
+| `--espresso` | `#1b150e` | dark section field |
+| `--espresso-2` | `#241c12` | raised card on espresso |
+| `--cream` | `#f4ecdc` | ink on espresso |
+| `--ink` / `-soft` / `-faint` | `#241c14` / `#5b4f3d` / `#8a7c64` | text ramp on cream |
+| `--accent` (sage) / `-deep` | `#3f7d5f` / `#2f5e47` | THE single functional accent (links, CTA, "signal") |
+| `--terra` | `#b5623f` | rare editorial highlight only |
+| `--red` | `#a83a2b` | negatives ONLY (comparison "without") |
+| `--hair` / `-strong` | `rgba(36,28,20,0.13)` / `rgba(36,28,20,0.22)` | hairline rules |
+
+Contrast: body on cream must clear 4.5:1 — `--ink` / `--ink-soft`, never
+`--ink-faint` for sustained reading. On espresso, text is `--cream` and the
+sage accent brightens to `#9fd9bc`.
+
+## Type
+
+- Display: **Fraunces** — oversized, optical, tracked `-0.02…-0.03em`, hero
+  ceiling ~7rem via clamp.
+- Body: **Newsreader** — relaxed, measure ≤66ch.
+- Mono: **JetBrains Mono** — eyebrows, labels, numbers, code, "signal" tags.
+- Three families, no more; hierarchy through scale + weight.
+
+## Texture & surface
+
+- Fixed warm radial field + ~4% film-grain multiply overlay (cheap, no blur).
+- Squircle radii 14 / 22 / 30px; double-bezel cards
+  (`inset 0 1px 0 rgba(255,251,242,0.7)` highlight).
+- Soft ambient elevation only (`0 18px 50px -28px rgba(36,28,20,0.30)`
+  scale); no harsh dark drops, no outer glows on buttons.
+
+## Motion tokens
+
+- Ease `cubic-bezier(0.22, 1, 0.36, 1)` (ease-out-expo feel) — the one
+  site-wide curve for the SHELEG token set.
+- Spring `cubic-bezier(0.32, 0.72, 0, 1)` — press/magnetic feedback only.
+- Base duration `0.7s` for brand-register reveals; product register stays in
+  the SHELEG fast/base range (≤0.32s).
+
+## Signature motifs
+
+- A recurring sage **"signal"** motif travels the narrative: raw inputs →
+  pipeline → synthesized deliverable. One story, one color.
+- **Authored artifact previews** instead of flat icon cards: composed mock
+  report/infographic/PDF/PPTX/video frames that assemble on scroll.
+- Dossier primitives: `.dossier-card`, hairline `.rule`, `.eyebrow`,
+  `.stamp`, `.data-table`, tabular-nums data, footnote captions.
+- Visualization rule (key contract): all data-viz animation is **CSS-driven
+  off a `.revealed` ancestor** (bars `scaleX/Y`, sparklines/donuts via
+  `stroke-dashoffset`) — identical in plain and cinematic reveal paths,
+  correct static final state under reduced-motion, **fail-open** if JS/CDN
+  dies (content always visible).
+
+## Micro-interactions
+
+- Buttons: tactile `translateY(-2px)` + spring; no glow.
+- Magnetic primary CTAs and a small sage cursor-ring accent — desktop +
+  fine pointer only, gated with the SHELEG degrade rules.
+- Focus-visible: 2px sage outline, offset 3px (brightened on espresso).
+- Cards lift + border warms on hover; never nested-card-in-card.
+
+## Bans
+
+- No gradient text, no side-stripe accent borders, no glassmorphism, no
+  neon/outer-glow shadows, no purple.
+- No emojis in product UI; no Inter/system display fonts (Fraunces owns
+  display).
+- Never flatten the cream identity into generic white; never let motion
+  gate content visibility.
+
+## Gotchas
+
+- Token-first re-skin: override the token layer in `:root`, map legacy
+  token names onto it — do NOT restyle components one by one.
+- After any theme/token migration, **sweep hardcoded literals** (hex/rgba
+  left in CSS/JS keep the old palette and read as inverted on the new
+  theme).

package/plugins/sheleg-design/skills/sheleg-design/styles/instrument-console.md

@@ -0,0 +1,89 @@
+# Style pack — Instrument Console
+
+Origin: Nicegram Business OS landing (the SHELEG reference implementation).
+A near-black aerospace console: deep layered surfaces, hairline seams, one
+electric-blue signal accent, mono telemetry labels. The particle field and
+every instrument read as one precision device responding to the hand.
+
+## Register
+
+Choose this pack for technical, systems, infra, or "operating system"
+products where the aesthetic is calm precision hardware. Single dark
+register across landing and app; brightness (energy) varies per scene, hue
+does not.
+
+## Palette
+
+| Token | Value | Role |
+|---|---|---|
+| `--base` | `#05070a` | page field (near-black) |
+| `--surface-1/2/3` | `#0a0e14` / `#10151d` / `#161c26` | ascending raised panels |
+| `--hairline` / `-strong` | `#1e2630` / `#2b3542` | panel seams, rules |
+| `--ink` | `#eef2f7` | primary text |
+| `--ink-muted` / `-faint` | `#9aa7b6` / `#5f6b7a` | secondary / captions |
+| `--accent` | `#3392ff` | THE electric-blue signal (CTA, links, particles) |
+| `--accent-dim` / `-bright` | `#1f5fb0` / `#6bb3ff` | pressed / highlighted signal |
+| `--accent-glow` | `rgba(51,146,255,0.18)` | the only permitted glow |
+| `--ok` / `--warn` | `#46d39a` / `#e0a030` | status semantics only |
+
+The particle field, progress rail, and all instruments are tinted with
+`--accent` only — energy per scene changes brightness, never hue.
+
+## Type
+
+- Display + body: **Geist Sans** (or an equivalent neutral grotesk) —
+  weight 600 headlines, clamp-scaled (hero ~5.25rem ceiling), tight but
+  not tracked-negative.
+- Data: **Geist Mono** (or ui-monospace) — telemetry eyebrows, numeric
+  readouts, section indices ("02 / CONTROL"), code.
+- Two families; mono is a signature, not a garnish — every label that
+  narrates system state is mono.
+
+## Texture & surface
+
+- Flat panels separated by 1px hairlines; radii 4 / 8 / 14px (+ pill) —
+  machined, not squircle.
+- Elevation via surface steps (`--surface-1..3`), not shadows; the single
+  glow `0 0 0 1px rgba(51,146,255,0.4), 0 8px 30px rgba(51,146,255,0.18)`
+  is reserved for the active signal element.
+- No grain, no blur; darkness itself is the texture.
+
+## Motion tokens
+
+- Ease `cubic-bezier(0.16, 1, 0.3, 1)` — the one site-wide curve
+  (the SHELEG default token set: 0.18 / 0.32 / 0.55 / 0.8s, stagger 0.07).
+- Section rhythm `clamp(9rem, 24vh, 20rem)` vertical padding.
+
+## Signature motifs
+
+- WebGL particle formations as the narrative backdrop (SCENES registry),
+  electric-blue, hold-then-redeploy per the SHELEG core.
+- Right-edge progress rail with act markers; nav act badge ("02 /
+  CONTROL") driven by the coarse store subscription.
+- Frame/HUD chrome: thin viewport frame, corner ticks, scan/dim of
+  off-band sections (attention spotlight).
+- Scrubbed SVG instruments (charts, step flows) drawn hairline-thin with
+  mono annotations.
+
+## Micro-interactions
+
+- Buttons: surface-step + accent fill on primary; press = 1 shade dimmer
+  (`--accent-dim`), no bounce.
+- Reveal primitives themed per act: Scatter (drift+blur resolve), Lock
+  (snap into slot), Clip (mechanical wipe), Pulse (lock acquired).
+- Focus-visible: 1px `--accent` ring + `--accent-glow` halo.
+
+## Bans
+
+- One accent hue — no second color except `--ok`/`--warn` status semantics.
+- No gradient text, no glassmorphism/backdrop blur, no purple/neon
+  rainbow, no colored shadows besides `--accent-glow`.
+- No light sections — contrast comes from surface steps, not inversion.
+- No decorative serif/display fonts; the console voice is grotesk + mono.
+
+## Gotchas
+
+- Glow discipline: `--accent-glow` on more than one element per viewport
+  destroys the "single signal" read — the page becomes a christmas tree.
+- Dark UIs hide low-contrast text: `--ink-faint` is for captions only,
+  never sustained reading (fails 4.5:1 on `--surface-1`).