sheleg-design-skill 0.7.0 → 1.2.0

package/CHANGELOG.md

@@ -4,6 +4,234 @@ All notable changes to this project are documented in this file. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions
 follow [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-07-29
+
+Worked through Figma's *State of the Designer 2026* (NewtonX, 906 digital
+designers across five regions, surveyed September–October 2025). It is a survey
+of the profession — AI adoption, what designers mean by craft, satisfaction,
+regional outlook — **not** a visual-trends report, so nothing here is a "trend"
+invented from it. Two findings were actionable, and one was a gap in this skill.
+
+### Added
+
+- **`AI_PRODUCT_PATTERNS.md`** — the surfaces a model drives, which the skill
+  had nothing to say about while the survey ranks *designing AI-driven
+  products* the **third most in-demand skill (37%)**, ahead of motion design
+  (29%) and information architecture (19%). Organizing rule: **honest state**.
+
+  Contents: the five states of a model call (idle · working · complete ·
+  refused/needs-a-human · failed — a refusal is not an error and a rate limit
+  is not a crash); streaming instead of spinners, with a stop control from the
+  first frame, a reserved container and no fake typing delay; latency as two
+  numbers (time-to-first-token is the one users feel); provenance and
+  uncertainty (cite or don't claim, no confidence theater, show the context the
+  model actually used); agent actions where the confirmation *is* the design —
+  the diff/recipient/query shown before it runs, explicit consent for anything
+  irreversible or outward-facing, undo for what's cheap; empty states that
+  carry the capability; chat as a shape rather than the shape; cost and scope
+  as visible state; and a ban list. Pairs with `workbench` and reuses its
+  status tokens.
+- **The craft bar** in `SKILL.md` — a definition of done ordered by what
+  designers actually mean by craft in that survey: visual polish (58%),
+  thoughtful problem solving (47%), clear intuitive UX (36%), emotion and
+  delight (35%), consistency (15%). Item 3 is explicitly *not* this skill's
+  half — if flows and states aren't decided, the honest move is to stop.
+- Discovery, the Cursor rule, the README and both installers cover the AI-UI
+  direction; `scenarios.md` gains T9.
+
+### Fixed
+
+- **The validator enforced five of the nine required pack headings** while the
+  0.9.0 entry, `CONTRIBUTING.md`, the README and the wiki all claimed the full
+  contract was gated. Exactly the promise-without-a-check defect this repo
+  keeps hunting, living inside the checker itself. All nine are now enforced
+  (`Motion flavor` stays conditional — `workbench` is standalone and has no
+  motion layer to flavor), which is also why the check count jumps to 194.
+
+## [1.1.1] - 2026-07-29
+
+### Fixed
+
+- `FIGMA_BRIDGE.md` described the mapping without mentioning that the official
+  Figma MCP **gates its main tools behind guidance skills** (`/figma-use`
+  before `use_figma`, `/figma-create-new-file` before `create_new_file`,
+  `/figma-design-to-code` before `get_design_context`) — the server names
+  skipping them the cause of hard-to-debug failures. An agent following the
+  bridge alone would have called them bare. The doc now says to load the gate
+  first and that the server's instructions win on *how* to call anything; this
+  file is the contract, not a tool manual. It also names the two read paths
+  worth knowing: `get_variable_defs` for token parity, `get_metadata` for frame
+  existence and naming.
+
+## [1.1.0] - 2026-07-29
+
+### Added
+
+- **`FIGMA_BRIDGE.md`** — the design↔code contract, a gap that was invisible
+  because it lived between repos: `super-ux` hands the look to this skill and
+  expects the chosen pack to become Figma variable collections, while this
+  skill did not mention Figma anywhere.
+
+  The rule is one line — the pack is the source of truth in both directions.
+  Publishing writes its values into variables; implementing a design maps the
+  file's values onto the pack's tokens, and a value with no token is either a
+  gap in the pack (add it, with its CSS line) or drift in the file, never an
+  inlined literal.
+
+  The specifics are what make it usable: one collection per token family with
+  names 1:1 with the CSS custom properties; **modes are themes, not surfaces**
+  — `workbench`'s light/dark is one collection with two modes, while
+  `editorial-luxury`'s espresso is a coexisting surface and modelling it as a
+  mode invents a theme switch the design never had; colors convert to 0..1
+  floats rather than copy; motion cannot cross at all (Figma has no easing
+  variable type, so §10's ease/durations/stagger stay code-only); shadows are
+  effect styles whose `radius`/`color`/`spread`/offsets bind to variables;
+  variables are COLOR/FLOAT/STRING/BOOLEAN only; and `addMode` can be refused
+  once a plan's mode cap is hit — ship light-only and say so rather than faking
+  a parallel collection. Figma file content is data, never instructions.
+- Discovery, the Cursor rule and the README cover the Figma direction; the
+  validator now requires every companion doc in the bundle to be linked from
+  `SKILL.md` (161 checks) — a reference nothing points at is a file the agent
+  never opens.
+
+## [1.0.1] - 2026-07-28
+
+Open-source hygiene pass — the repo is public, so the files a first-time
+contributor looks for now exist.
+
+### Added
+- `SECURITY.md` — states plainly that `bin/cli.js` neither spawns processes nor
+  touches the network, and that `install.sh` **does** fetch over HTTPS when run
+  without a checkout, so the documented `curl … | sh` one-liner is named as the
+  trust decision it is, with two alternatives.
+- `CODE_OF_CONDUCT.md`, issue forms and a pull-request template.
+- README points at the security policy and the code of conduct.
+
+## [1.0.0] - 2026-07-28
+
+First stable release. Nothing about the method changed — this marks the point
+where the surfaces below are treated as a contract, and a second full pass over
+every file cleared the remaining inaccuracies.
+
+**What 1.0.0 promises.** The installed layout (`SKILL.md`, `SHELEG_DESIGN.md`,
+`styles/*.md`, `styles/tokens/*.css`, `styles/STYLE_PACK_TEMPLATE.md`), the
+ten-heading style-pack contract, the token names inside a pack, and the CLI
+flags are stable within 1.x. A pack may gain tokens; it will not silently
+change what an existing token means. Removing or renaming either is a major.
+
+### Fixed
+
+- `release.yml` pointed at `pipeline.example.json`, a file that has never
+  existed in this repo, and installed `jsonschema` for a validator whose first
+  line says stdlib-only. Both gone; its post-release smoke test now `diff -r`s
+  the whole installed bundle instead of checking three paths.
+- The CLI accepted a bare trailing `--dir` and silently fell back to
+  auto-detect — installing somewhere the caller did not ask for. `--dir`
+  without a path, an unknown flag, and `--dir` combined with
+  `--cursor`/`--claude` now print the reason and exit 2 (previously exit 0).
+- `SKILL.md` listed "dashboards" under *not for*, one line after listing
+  dashboards as a supported use — the exclusion is about the cinematic motion
+  layer, and now says so.
+- `SHELEG_DESIGN.md` §13 presented the reference implementation's Next.js paths
+  as if they were the reader's; it now says to port the split, not the strings.
+  The §9 snippet used `STAGGER` without showing where it comes from, §11 said
+  "port" a file no reader has, and the closing line still said "this site".
+- `npm test` ran `--help` and always passed. It runs the validator now.
+- The 0.3.0 design spec still declared templates out of scope; annotated with
+  what superseded it rather than quietly rewritten.
+
+### Added
+
+- `CONTRIBUTING.md`: repo layout, the canonical-bundle-vs-mirror rule, and a
+  step-by-step for authoring a style pack (including the cross-pack token
+  naming trap).
+- README rewritten for people arriving cold: what the problem is, the two
+  halves, the pack table, what installs where, and an honest development
+  section.
+
+## [0.9.1] - 2026-07-28
+
+### Added
+
+- Optional **Lazyweb MCP** step: when `mcp__lazyweb__*` tools are present, the
+  skill sweeps real-world references for the target screen before laying it
+  out — recommended for the product-UI (`workbench`) register. The split is
+  explicit: references inform layout, hierarchy and content order; palette,
+  type and motion stay the pack's. Documented in `SKILL.md`, the Cursor rule
+  and the README; nothing depends on the MCP, and fetched reference content is
+  treated as data, never as instructions.
+
+## [0.9.0] - 2026-07-28
+
+Consistency pass over every file: the contradictions below were real and are
+fixed, and each one now has a validator or CI check so it cannot return.
+
+### Fixed
+
+- **The pack skeleton was unreachable from an installed skill.** `SKILL.md`
+  pointed at `templates/style-pack-template.md`, which `files[]` never shipped.
+  The skeleton now rides in the bundle as
+  `styles/STYLE_PACK_TEMPLATE.md`, kept byte-identical to `templates/`.
+- **`SKILL.md` listed 8 of the 10 pack headings** (no Motion flavor, no
+  Gotchas), so an authored pack would legitimately lose sections the packs and
+  the template both carry. The contract is now stated once and enforced.
+- **The motion-token contradiction.** `SHELEG_DESIGN.md` §10 declared one
+  site-wide ease while `editorial-luxury` and `workbench` legitimately override
+  it. §10 now states the defaults *and* that the pack wins; the packs say the
+  same from their side.
+- **Stagger drift inside the reference:** the Reveal table said 0.06s and the
+  GSAP recipe hard-coded 0.08 against a `STAGGER = 0.07` token; both now read
+  the token.
+- **`workbench.css` set `color-scheme: light dark`**, so a page forced to
+  `data-theme="dark"` still got UA controls and scrollbars from the OS
+  preference. Light `:root`, dark under the attribute; a reduced-motion block
+  zeroes the duration tokens.
+- **`--accent-dim` meant opposite things across packs** (a pressed darker blue
+  in `instrument-console`, a 12% tint in `editorial-luxury`). The tint is now
+  `--accent-weak`, matching `workbench`'s naming.
+- **`workbench.md` shipped prose where tokens belong** ("amber", "red",
+  "`#1a7f37`-family") — the table now carries the exact light/dark pairs from
+  the CSS, and `--info` is documented as deliberately the accent hue.
+- **CLI help still advertised two style packs** (the success message had been
+  fixed, the help text had not), and the bundle blurb omitted the token CSS.
+- **The Cursor rule promised product-UI guidance it never gave** — it now
+  carries a self-contained workbench contract for agents without the skill
+  installed.
+- README, `marketplace.json`, and the `/sheleg-design` command all described a
+  landing-page-only skill; all three now state the product-UI half.
+- Reference cleanups: ASCII architecture diagram re-aligned (the fan-out
+  connector was one column off the store box), `bias` added to the store
+  fields it lists, the `936 = 24 × 13 × 3` factorization disambiguated from
+  scene indices, and a product-specific closing-line example genericized.
+
+### Added
+
+- Validator (146 checks, was 101): the **whole** `.cursor/` mirror is compared
+  against the plugin bundle file-by-file in both directions (previously only
+  `SKILL.md`), the full ten-heading pack contract is enforced on every pack and
+  on the template, the shipped template must match `templates/`, and every pack
+  must be routed from the `SKILL.md` table and named in the CLI output.
+- CI installs through both channels and `diff -r`s the result against the
+  bundle, so a file that reaches one installer and not the other fails the run.
+- `test/scenarios.md` gains T7 (authoring a new pack against the contract).
+
+## [0.8.0] - 2026-07-28
+
+### Fixed
+- The Cursor channel copy of `SKILL.md` could drift from the plugin copy without
+  anything noticing. The validator now compares them and fails on drift.
+
+### Changed
+- `RU triggers - …` replaced with English-first pairs
+  (`"design tokens" / "дизайн-токены"`), so the description reads as English
+  with localized aliases.
+- README is English-only, with a plain statement of what the skill gives you and
+  an author/links block.
+
+### Added
+- Validator enforces the description canon: `Use when` opening, Russian trigger
+  aliases present, front-matter under 1024 characters.
+
 ## [0.7.0] - 2026-07-25
 
 Review pass.

package/README.md

@@ -1,36 +1,53 @@
-# SHELEG Design — agent skill
+# SHELEG Design — design taste as an 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.
+An agent can generate a landing page in under a minute, and it will look like
+every other generated landing page: three cards, a gradient, a hero that does
+nothing. Ask it for a dashboard and you get a different flavor of the same
+problem — invented colors, six accent hues, dark mode retrofitted later.
 
-Install it into any project with one command:
+This skill is the taste layer. It gives a coding agent **one motion
+methodology** for cinematic, scroll-driven pages and **three locked style
+packs** with ready-made design tokens, so what it builds reads as one system
+instead of a pile of effects.
 
 ```bash
 npx sheleg-design-skill
 ```
 
-That drops a `SKILL.md` + `SHELEG_DESIGN.md` bundle into your project so your
-coding agent can discover the skill and build sites on its principles.
+That drops the bundle — `SKILL.md`, the `SHELEG_DESIGN.md` reference, the style
+packs and their token CSS — into `.cursor/skills/` or `.claude/skills/`, where
+your agent discovers it on its own.
 
-## What is SHELEG Design?
+---
 
-A page feels *alive* not from many animations, but from a **single source of
-truth** (scroll position) driving **many cheap, layered responses** that are
-individually quiet and collectively cinematic. One scroll "clock" feeds a WebGL
-particle field, a 2D fallback, attention dimming, parallax, scrubbed
-instruments, and a progress rail — each an independent, degrade-to-calm layer.
-Nothing crossfades; things *redeploy*. The result reads as one precision
-instrument responding to your hand.
+## The two halves
 
-It was reverse-engineered from a production landing page (a 14-scene particle
-narrative that morphs through formations and culminates in a brand "N" that
-charges and bursts). The skill distills the architecture and the principles so
-an agent can rebuild that level on a new site.
+**Motion** — for landings, heroes, scroll narratives. A page feels *alive* not
+from many animations but from a **single source of truth** (measured scroll
+position) driving **many cheap, layered responses** that are individually quiet
+and collectively cinematic. One scroll "clock" feeds a WebGL particle field, a
+2D fallback, attention dimming, parallax, scrubbed instruments and a progress
+rail — each an independent, degrade-to-calm layer. Nothing crossfades; things
+*redeploy*.
+
+**Style packs** — the visual identity, pluggable per project. The `workbench`
+pack is meant to be used **standalone**, with none of the motion layer: quiet
+light/dark product UI for dashboards, admin panels, internal and dev tools.
+
+| Pack | Look | Choose for |
+|---|---|---|
+| `instrument-console` | near-black aerospace console, one electric-blue signal, mono telemetry | technical / systems / infra |
+| `editorial-luxury` | warm cream + espresso ink, sage accent, Fraunces/Newsreader, dossier motifs | editorial / research / premium B2B |
+| `workbench` | neutral grays, borders as elevation, one blue accent, mono data, light + dark twins | dashboards, admin, internal & dev tools |
+
+Each pack locks palette, type, texture, motion tokens, signature motifs and
+bans — and ships a `tokens/<pack>.css` to copy verbatim, so the agent never
+invents a hex. Where a pack sets its own ease and durations, the pack wins; the
+motion layer never hard-codes a palette.
 
 ### The five principles
 
@@ -44,91 +61,163 @@ an agent can rebuild that level on a new site.
 5. **Degrade to calm.** Reduced-motion / coarse pointer / no-WebGL collapse to a
    static, fully-legible page.
 
-## Usage
+The method was reverse-engineered from a production landing page — a 14-scene
+particle narrative that morphs through formations and ends in a brand glyph that
+charges and bursts — then generalized so an agent can rebuild that level
+anywhere.
+
+## Install
+
+Requires Node ≥ 16 for the installer. Nothing is added to your dependencies:
+the skill is documentation an agent reads.
 
 ```bash
-# Auto-detect (.cursor/ or .claude/), default to .cursor/skills/sheleg-design/
+# Auto-detect (.cursor/ or .claude/), default .cursor/skills/sheleg-design/
 npx sheleg-design-skill
 
-# Force a flavor
+# Pick the target explicitly
 npx sheleg-design-skill --cursor
 npx sheleg-design-skill --claude
-
-# Custom location
 npx sheleg-design-skill --dir docs/skills/sheleg-design
 
-# Overwrite an existing install
+# Overwrite an existing install / see all options
 npx sheleg-design-skill --force
-
-# Help
 npx sheleg-design-skill --help
 ```
 
-### Other install paths
+Other channels:
 
 ```bash
-# Claude Code plugin (adds the /sheleg-design command too)
+# 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)
+# vercel-labs skills CLI
 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
 ```
 
+Cursor rules users: `cursor/rules/sheleg-design.mdc` is a self-contained
+condensed version — copy it into `.cursor/rules/` if you prefer rules over
+skills.
+
 ### 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), `editorial-luxury` (warm cream/espresso/sage, dossier motifs), and `workbench` (quiet light/dark product UI for dashboards & tools, standalone). Each locks palette, type, texture, motion tokens, motifs, and bans; the pack contract lets you author new styles |
+| `SKILL.md` | The agent-facing skill: discovery triggers, 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 why each piece works |
+| `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 |
+| `styles/*.md` | The three style packs — palette, type, texture, motion tokens, motifs, bans, and the traps each one carries |
+| `styles/tokens/*.css` | The ready-made token layer per pack, copied verbatim instead of transcribed (workbench ships a light `:root` plus a `data-theme="dark"` twin) |
+| `styles/STYLE_PACK_TEMPLATE.md` | The pack contract as a skeleton, so a new style is authored against the same headings rather than improvised |
+
+## What you get out of it
+
+- **A motion methodology, not a component dump.** Scroll-linked animation,
+  particle and WebGL backgrounds, parallax layers that stay in phase instead of
+  drifting apart as the page grows.
+- **Product UI with the boring parts already decided** — tokens, light/dark,
+  elevation, state colors, data typography — up front rather than retrofitted.
+- **A diagnosis for pages that feel busy or janky**, naming which layer to cut
+  instead of telling you to "simplify".
+- **Stack-agnostic and dependency-free.** The reference implementation happens
+  to use Next.js + React + three / react-three-fiber + GSAP ScrollTrigger +
+  Lenis, but the method applies to any stack that can render to a canvas and
+  read scroll. It is a way of building, not a framework you now depend on.
+
+## AI product surfaces
+
+Chat, agent runs, streaming output and generated content are the surfaces most
+design systems were written before — and the ones everyone is now building.
+`AI_PRODUCT_PATTERNS.md` covers them with one organizing rule, **honest state**:
+a model's output is slow, uncertain, occasionally refused and sometimes wrong,
+and an interface that hides any of that is not calmer, it is lying.
+
+Concretely: five states per call, not two (idle · working · complete · refused ·
+failed — a refusal is not an error and a rate limit is not a crash); streaming
+instead of spinners, with a stop control from the first frame and no reflow; the
+context the model actually used, because most "wrong answer" reports are
+wrong-context reports; an agent's action shown in the shape it will take before
+it runs; and no confidence number with nothing behind it.
+
+This is where the skill's positioning is externally measured rather than
+asserted: in Figma's *State of the Designer 2026* (NewtonX, 906 designers,
+Sept–Oct 2025), designing AI-driven products is the **third most in-demand
+skill (37%)** — ahead of motion design and information architecture — while
+**visual polish tops the list at 58%**, and craft is named the differentiator
+now that anyone can prompt their way to a prototype.
+
+## Figma, in both directions
+
+Design files and design tokens are two encodings of one system, and the usual
+outcome is that they drift until nobody trusts either. The skill's rule is that
+**the pack is the source of truth on both sides**: publishing writes a pack's
+values into Figma variable collections; implementing a design maps the file's
+values *onto* the pack's tokens instead of inlining hexes.
+
+The bridge is specific because the traps are: `workbench`'s light and dark are
+two **modes of one collection**, while `editorial-luxury`'s espresso sections
+are surfaces and not a mode at all; Figma colors are 0..1 floats, not hex; and
+motion never crosses — Figma has no easing variable type, so the ease, durations
+and stagger stay code-only, and shadows are effect styles whose parts bind to
+variables. A value in a file with no matching token is either a gap in the pack
+or drift in the file — the one thing it is never is a literal in a component.
+
+## Optional: Lazyweb MCP
+
+A style pack locks *how it looks*. It says nothing about what a good version of
+the screen you're about to build actually **contains**. If the
+[Lazyweb](https://www.lazyweb.com) MCP server is connected, the skill sweeps
+real-world references for the target screen (signup, onboarding, paywall,
+pricing, checkout, dashboard, settings) before laying anything out.
+
+The division of labor keeps the result one system: references inform **layout,
+hierarchy and content order**; palette, type and motion stay the pack's. Setup
+is a Streamable HTTP MCP server plus a per-user token — keep it out of your
+repo. Entirely optional; without it the skill works from the pack alone.
 
-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.
+## Development
 
-## Stack-agnostic
+```bash
+python3 test/validate.py   # or: npm test
+```
 
-The skill teaches **principles and architecture**, not a fixed dependency set.
-The reference implementation happens to use Next.js + React + three /
-react-three-fiber + GSAP ScrollTrigger + Lenis + Framer Motion, but the method
-applies to any stack that can render to a canvas/WebGL surface and read scroll.
+The validator is the repo's contract, not a formality — it checks manifests and
+four-way version sync, skill/command/rule front-matter and description canon,
+the full style-pack section contract, pack ↔ `SKILL.md` ↔ CLI-help agreement,
+the bundled template against `templates/`, both installers' file lists, the
+entire `.cursor/` mirror against the plugin copy, and every relative link. CI
+runs it on each push and PR alongside a negative self-test (the validator must
+fail on a corrupted version) and installs the bundle through **both** installers,
+diffing the result against the source.
 
-## Zero dependencies
+`test/scenarios.md` (T1–T7) is the behavioral harness: fresh subagents given a
+task, checking that the skill is discovered, applied and quoted correctly.
+Re-run the affected scenarios after any edit to `SKILL.md`, a pack or the
+reference.
 
-The installer is a single zero-dependency Node script, so `npx` runs instantly
-with no install step and no supply-chain surface.
+Adding a style pack, or anything else: see [CONTRIBUTING.md](./CONTRIBUTING.md)
+and the [Code of Conduct](./CODE_OF_CONDUCT.md). To report a vulnerability, see
+[SECURITY.md](./SECURITY.md).
 
-## Development
+## Author
 
-`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.
+Built by ssheleg — [sshlg.me](https://sshlg.me)
 
-## По-русски
+- X / Twitter — [@fuck_this_year](https://x.com/fuck_this_year)
+- Telegram — [@sshlg](https://t.me/sshlg)
 
-**sheleg-design** — методология SHELEG: кинематографичные скролл-лендинги (единые
-часы анимации, слоистая композиция, «degrade to calm» при снижении ресурсов) плюс
-**style packs** для продуктового UI. Метод — style-agnostic; визуальную систему
-задаёт выбранный пак (`styles/<pack>.md` + `styles/tokens/<pack>.css`):
-`instrument-console` (тёмная приборная панель), `editorial-luxury` (тёплая
-издательская), `workbench` (светлый рабочий интерфейс).
+Part of the [ssheleg skill family](https://github.com/ssheleg/sshlg-skills):
+`super-ux`, `task-pipeline`, `make-skill`, `sheleg-design`, `seo-aeo-audit`.
+One command installs all five for every agent you use:
 
-Триггеры: «кинематографичный лендинг», «скролл-анимация», «лендинг с частицами»,
-«стиль дашборда», «дизайн-токены», «светлая/тёмная тема». Запуск — `/sheleg-design
-<что построить или улучшить>`. Установка — см. раздел Install выше.
+```bash
+npx sshlg-skills install
+```
 
 ## License
 

package/bin/cli.js

@@ -4,8 +4,9 @@
 /**
  * sheleg-design-skill installer.
  *
- * Copies the SHELEG Design skill bundle (SKILL.md + SHELEG_DESIGN.md) into the
- * current project so a Cursor / Claude agent can discover and apply it.
+ * Copies the SHELEG Design skill bundle (SKILL.md, SHELEG_DESIGN.md, the style
+ * packs and their token CSS) into the current project so a Cursor / Claude
+ * agent can discover and apply it.
  *
  * Zero dependencies on purpose: it must run instantly via `npx` with no install
  * step and no supply-chain surface.
@@ -60,6 +61,7 @@ function parseArgs(argv) {
     force: false,
     help: false,
     version: false,
+    error: null, // set → print help and exit non-zero
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -68,13 +70,23 @@ function parseArgs(argv) {
     else if (a === "--force" || a === "-f") opts.force = true;
     else if (a === "--cursor") opts.flavor = "cursor";
     else if (a === "--claude") opts.flavor = "claude";
-    else if (a === "--dir") opts.target = argv[++i];
-    else if (a.startsWith("--dir=")) opts.target = a.slice("--dir=".length);
-    else {
-      console.error(c("yellow", `Unknown argument: ${a}`));
-      opts.help = true;
+    else if (a === "--dir") {
+      // A bare trailing --dir must fail loudly: silently falling back to
+      // auto-detect would install somewhere the caller did not ask for.
+      const value = argv[++i];
+      if (!value || value.startsWith("-")) opts.error = "--dir needs a path";
+      else opts.target = value;
+    } else if (a.startsWith("--dir=")) {
+      const value = a.slice("--dir=".length);
+      if (!value) opts.error = "--dir needs a path";
+      else opts.target = value;
+    } else {
+      opts.error = `unknown argument: ${a}`;
     }
   }
+  if (opts.flavor && opts.target) {
+    opts.error = "--dir cannot be combined with --cursor / --claude";
+  }
   return opts;
 }
 
@@ -99,9 +111,14 @@ ${c("bold", "Default")}
   otherwise creates .cursor/skills/${SKILL_SLUG}/.
 
 ${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)
+  SKILL.md             the agent-facing skill (discovery + principles)
+  SHELEG_DESIGN.md     the full reference (architecture, recipes, why it works)
+  FIGMA_BRIDGE.md      the design↔code contract (tokens ⇄ Figma variables)
+  AI_PRODUCT_PATTERNS.md  chat / agent / streaming surfaces (honest state)
+  styles/              three style packs — instrument-console (dark console),
+                       editorial-luxury (warm editorial), workbench (light/dark
+                       product UI, standalone) — plus a ready-made token CSS
+                       per pack and STYLE_PACK_TEMPLATE.md for authoring more
 `);
 }
 
@@ -122,6 +139,11 @@ function resolveTargetDir(opts, cwd) {
 function main() {
   const opts = parseArgs(process.argv.slice(2));
 
+  if (opts.error) {
+    console.error(c("yellow", `sheleg-design-skill: ${opts.error}`));
+    printHelp();
+    process.exit(2);
+  }
   if (opts.version) {
     console.log(pkg.version);
     return;
@@ -169,9 +191,10 @@ function main() {
     `\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` +
-      `  ${c("dim", "styles/")}           style packs (instrument-console / editorial-luxury / workbench)\n\n` +
+      `  ${c("dim", "styles/")}           style packs + token CSS (instrument-console / editorial-luxury / workbench)\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` +
+      `cinematic, scroll-driven pages — or style product UI (dashboards,\n` +
+      `admin, internal tools) from the workbench pack — on its principles.\n\n` +
       `${c("dim", "Docs: " + pkg.homepage)}\n`,
   );
 }