sheleg-design-skill 1.53.0 → 1.54.1

package/CHANGELOG.md

@@ -6,6 +6,109 @@ follow [SemVer](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [1.54.1] - 2026-08-29
+
+### The installer refuses the shadow it documents
+
+Both installers write a plain skill copy on request, and on a machine where
+`sheleg-design` is installed as a Claude Code plugin, a write to that home's
+`~/.claude/skills/sheleg-design` is a copy that shadows the plugin and serves
+this frozen version forever. Neither installer checked the plugin channel at
+all, and CI tested a fresh HOME only, so the plugin-present case had never run
+anywhere. Canon: make-skill v0.25.0, `references/distribution.md` §"The
+installer must refuse the shadow it documents"; family audit SHD-07/UM-03.
+
+### Added
+
+- `bin/cli.js` and `install.sh` now consult the **target home's**
+  `~/.claude/plugins/installed_plugins.json` before any write to that home's
+  `~/.claude/skills/sheleg-design`, and refuse with **exit 3** when the plugin
+  channel owns the skill. The refusal names the real spec read from the JSON
+  (`sheleg-design@<marketplace>` — the marketplace name differs from the
+  plugin name here, and a remedy that guesses it sends the operator to a
+  marketplace that does not exist), prints the plugin-channel remedy
+  (`claude plugin marketplace update` + `claude plugin update <spec>`, plus
+  the family launcher line), and offers `--force` as the deliberate override.
+  The `plugins/marketplaces/` directory is read only as the fallback signal —
+  it under-reports (a `directory`-sourced marketplace has no dir there), which
+  is the fail-open class the canon names. A missing or unparsable JSON reads
+  as "no plugin": fail open, never crash. Only the Claude Code channel is
+  gated — `.cursor/` and every other agent's install are untouched, and a
+  project-level `.claude/` falls open naturally because a project holds no
+  plugin registry.
+- `install.sh` accepts `--force` (the override for the gate above) and refuses
+  unknown flags with exit 2 instead of treating them as a target directory.
+- `test/installer_test.js` — thirteen cases against throwaway HOMEs, wired
+  into `npm test` and CI: plugin-present (exit 3 + remedy + nothing written,
+  all three asserted), the differently-named marketplace spec carried into the
+  remedy, `--force` installing, corrupt JSON installing, a prefix-collider
+  (`sheleg-design-extra@x`) not falsely refused, marketplaces-dir-only still
+  refusing, fresh HOME still installing, the `.cursor` channel untouched by
+  the gate, and the install.sh mirrors of the same. Watched failing first: run
+  against the pre-fix installers, 7 cases red.
+
+### Changed
+
+- Both installers now end a successful install by saying how the next version
+  arrives (`npx sheleg-design-skill@latest --force`, or the family launcher) —
+  an installer that never mentions updates has still chosen an update model:
+  never.
+- `bin/cli.js --help` documents the exit-code contract, including the new
+  exit 3.
+- CONTRIBUTING: release tags must be **annotated** (`git tag -a`) — v1.53.0
+  and v1.54.0 were lightweight, and `git submodule status` describes a pinned
+  commit with `git describe`, which ignores lightweight tags, so the family
+  umbrella misreported the member's version (SHD-07/UM-03). Applies from this
+  release forward; the old tags are not re-cut.
+
+## [1.54.0] - 2026-08-29
+
+### The thirty-eighth pack — the terrain is mapped
+
+**`surveyor`**, extracted from an AI-visibility tracker's front page and named per
+ADR-0001 for the register it encodes: a page that sells a survey of terrain the
+buyer cannot see — contour lines for texture, counted stat slabs for readings, and
+the product appearing only as flat portraits.
+
+### Added
+
+- `styles/surveyor.md` — widened, all thirteen headings; `Themes: light only`;
+  `Rank: unordered — 3 status role(s)`, and the missing warn is a stated decision
+  rather than a gap: the authored palette ships no amber, and one invented from the
+  WordPress vendor presets would be the exact rule-7 trap. Two forks written from
+  both sides: against `test-drive` (a flat portrait against a running machine on
+  the same warm paper) and against `showroom` (a field survey pinned flat against
+  one lit museum specimen).
+- `styles/tokens/surveyor.css` — the authored layer dug out of a WordPress site:
+  SE Ranking's own `se-uikit` tokens verified against the render, with the vendor
+  preset `:root` (a full palette that paints nothing) left behind. The corrections
+  climb the reference's own ladder: its CTA label measures `#ffffff` on `#0d9488`
+  at 3.74:1, so the hover step `#0a7269` becomes the text-bearing `--action` and
+  the brand teal keeps large-only jobs; the pink that answers (`#ff91da`, 1.84:1)
+  gains a speaking step `--pink-deep` `#a83f88` at 5.32:1. The page's elevation
+  model is recorded as measured: box-shadow none everywhere except the nav after
+  it detaches on scroll.
+- `kits/surveyor/` — the six-name spine plus `StatSlab`, `Delta`, `Portrait`,
+  `TintPanel`, `Closer`, `Dialogue`, `Pulse`, `Field`, `NavBar`, `Empty`. The
+  contour terrain ships as a CSS technique (`repeating-radial-gradient` rings)
+  over the three measured line inks, because a PNG asset cannot live in a token
+  layer.
+- `test/scenarios.md` T36 — `surveyor` against `test-drive`, the warm-paper
+  analytics-landing fork, with its negative branch per standing instruction 4.
+- ADR-0001 gains its fifteenth application: `surveyor`, with `contour`, `atlas`,
+  `heatmap`/`benchmark` and `field-survey` weighed and rejected.
+
+### Changed
+
+- `test-drive` and `showroom` each gain the reciprocal fork clause naming
+  `surveyor`.
+- Counted claims moved with the tree: thirty-eight packs and kits across
+  `SKILL.md`, the index (six core / thirty-two widened), `SURFACE_COMPOSITION.md`
+  (the accent is `--accent` in 35 of the 38; twenty-five layers carry a
+  non-text role), `FIGMA_BRIDGE.md` (twelve of the thirty-eight ship a twin),
+  the template's theme split (12/17/9), README, DOCMAP, both installers and all
+  three manifests.
+
 ## [1.53.0] - 2026-08-27
 
 ### The thirty-seventh pack — the visitor is handed the keys

package/README.md

@@ -31,7 +31,7 @@ problem — invented colors, six accent hues, dark mode retrofitted later.
 
 This skill is the taste layer. It gives a coding agent **one motion
 methodology** for cinematic, scroll-driven pages, **a motion doctrine** that
-decides whether to animate before it decides how, and **thirty-seven locked style
+decides whether to animate before it decides how, and **thirty-eight locked style
 packs** with ready-made design tokens, so what it builds reads as one system
 instead of a pile of effects.
 
@@ -77,6 +77,7 @@ into the cinematic layer, and says so in its own *Motion flavor* section.
 | `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 through a navy that is never a word, so there is no grey ramp at all. A dot grid, dashed hairlines, three faces with one job each, and an **11px working size** | **developer and AI infrastructure whose front page is a working document** — memory and context engines, retrieval services, agent runtimes, evaluation and observability surfaces (standalone) |
 | `deskmate` | a warm beige working day lit from **one source above the top edge** — every gradient origin in the reference sits at or above `y=0` — where a single four-stop ramp (peach, lilac, violet, deep navy) washes the field, fills a panel and fills one word of a heading, and everything a hand touches is a 56px pill against 32px slabs | **products sold as a colleague rather than a tool** — AI employees and chat-native agents, assistants living in Slack or Teams, delegation and approval surfaces (standalone) |
 | `test-drive` | warm paper and white cards where **the live product runs inside drawn browser chrome** — traffic-light dots, a real address, the engine on — one coral in two tokens (the brand hue lights, fills and blinks; a darker step carries every body-size word), every control lit by a four-layer shadow in its own hue, a handwritten face and a yellow marker annotating from the margin | **self-serve SaaS sold by handing over the running product** — analytics, dashboards, developer tools with a visible console, indie SaaS (standalone) |
+| `surveyor` | peach paper where **an unseen terrain is mapped** — fine contour lines as the one texture, flat white and tinted cards with no shadow anywhere, a teal whose text-bearing steps are the reference's own hover ladder, a pink that answers but may not speak, and the product appearing only as flat portraits | **visibility, monitoring and benchmark tools** — AI-search and SEO trackers, share-of-voice and brand-listening platforms sold to marketing teams (standalone) |
 | `outrank` | white field with one violet that carries text in both directions, a 5px light ring standing in for a button shadow, and two type families split by how long a thing is read | SEO and growth SaaS, agent-run back-office — the pack for a product that ships a landing and a dashboard at once |
 | `orchard` | warm oat field of rounded slabs, sage brand + one candy-orange action, rounded geometric display, soft-3D pills built from inset light | friendly consumer biotech, DTC wellness, testing kits & supplements |
 | `field-notes` | warm green-cast paper ruled by hairlines, one rust accent, a hero that dissolves into the page instead of ending, numbered mono eyebrows, crop marks, colour that encodes how a claim is known | open-source & developer tools sold on auditability — code intelligence, provenance, evals, agent memory |
@@ -177,7 +178,7 @@ skills.
 | `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 |
-| `styles/*.md` | The thirty-seven style packs — palette, type, texture, motion tokens, motifs, bans, and the traps each one carries |
+| `styles/*.md` | The thirty-eight 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` and `field-notes` each ship 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 |
 
@@ -248,7 +249,7 @@ cd ./ds-workbench && npm install && npm run build
 then `/design-sync` in that directory, from Claude Code. Three layers cross: the
 pack's **bans** as the design system's own README, `styles.css` built from
 `tokens/<pack>.css` verbatim, and the components — a six-name spine that is
-identical in all thirty-seven kits, so switching packs swaps identity rather than API,
+identical in all thirty-eight kits, so switching packs swaps identity rather than API,
 plus each pack's signature parts. **Motion does not cross**, exactly as it does
 not cross into Figma: a kit is the static half of a pack, and saying so is what
 stops an agent inventing motion to fill the silence.
@@ -298,7 +299,7 @@ a pack's four widened sections used to make two gates *quieter* and still green.
 One honest limit: the npx installer is checked by asserting its runtime bundle
 walker exists, not by reading a file list — it has none by design. What proves
 it ships the right files is CI, which installs the bundle through **both**
-installers and `diff -r`s the result against the source, then builds all thirty-seven
+installers and `diff -r`s the result against the source, then builds all thirty-eight
 kits.
 
 `test/scenarios.md` (T1–T34) is the behavioral harness: fresh subagents given a

package/bin/cli.js

@@ -225,6 +225,13 @@ ${c("bold", "Default")}
   Auto-detects: uses .cursor/ if present, else .claude/ if present,
   otherwise creates .cursor/skills/${SKILL_SLUG}/.
 
+${c("bold", "Exit codes")}
+  0 installed or skipped    2 usage error
+  1 packaging bug, or       3 refused: the sheleg-design PLUGIN is installed
+    overwrite refused         in the target home — a plain copy in
+                              ~/.claude/skills would shadow it and serve this
+                              frozen version forever (--force overrides)
+
 ${c("bold", "What it installs")}
   SKILL.md             the agent-facing skill (discovery + principles)
   SHELEG_DESIGN.md     the full reference (architecture, recipes, why it works)
@@ -234,7 +241,7 @@ ${c("bold", "What it installs")}
   DESIGN_SYNC_BRIDGE.md   the Claude Design contract (what a pack sends, and
                        what does not cross)
   AI_PRODUCT_PATTERNS.md  chat / agent / streaming surfaces (honest state)
-  styles/              thirty-seven style packs — instrument-console (dark console),
+  styles/              thirty-eight style packs — instrument-console (dark console),
                        editorial-luxury (warm editorial), workbench (light/dark
                        product UI), briefing-room (dark 16:9 presentation deck),
                        atrium (warm cream consumer health), patchbay (dark live
@@ -254,6 +261,10 @@ ${c("bold", "What it installs")}
                        inside drawn browser chrome, controls lit by a
                        four-layer shadow in their own hue, and a
                        handwritten hand annotating the tour),
+                       surveyor (peach paper mapping unseen terrain in
+                       contour lines, flat shadowless cards, a teal that
+                       states and a pink that answers, and the product
+                       shown only as portraits),
                        babylove (white +
                           one orange, seven tokens over Tailwind defaults),
                           outrank (white +
@@ -324,6 +335,112 @@ function resolveTargetDir(opts, cwd) {
   return path.join(cwd, ".cursor", "skills", SKILL_SLUG);
 }
 
+// Exit codes are the contract: 0 installed or skipped, 1 packaging bug or
+// overwrite refusal, 2 usage error, 3 refused — the plugin channel owns the
+// target home's Claude Code install (--force overrides).
+const EXIT_PLUGIN_PRESENT = 3;
+
+/**
+ * The home whose Claude Code channel this write would land in, or null.
+ *
+ * Only the Claude Code channel is gated: a write to `<H>/.claude/skills/
+ * sheleg-design` is the shape that can shadow a plugin installed in `<H>`.
+ * `.cursor/` and every other agent's skill directory have no plugin channel,
+ * so installs there are untouched by the check. A project-level `.claude/`
+ * matches this shape too, and falls open naturally: a project holds no
+ * `plugins/installed_plugins.json`, so the gate reads "no plugin" and the
+ * install proceeds.
+ */
+function claudeHomeOf(targetDir) {
+  const parts = path.resolve(targetDir).split(path.sep);
+  const tail = parts.slice(-3).join("/");
+  if (tail !== `.claude/skills/${SKILL_SLUG}`) return null;
+  return parts.slice(0, -3).join(path.sep) || path.sep;
+}
+
+/**
+ * The plugin spec (`<name>@<marketplace>`) installed for sheleg-design in
+ * this home, or null.
+ *
+ * `installed_plugins.json` is the record of what is actually installed. The
+ * `plugins/marketplaces/<name>` directory under-reports: a marketplace added
+ * from a local `directory` source has no dir there at all, and plugin names
+ * differ from marketplace names — this very plugin is `sheleg-design` shipped
+ * from the `sheleg-design-skill` marketplace — so a check keyed on the dir
+ * alone stays green while the shadow lands. Absence and corruption both read
+ * as "no plugin": the fresh HOME is the common case, and an installer that
+ * crashes on a parse error refuses the machines that need it most.
+ */
+function installedPluginSpec(home) {
+  try {
+    const raw = fs.readFileSync(
+      path.join(home, ".claude", "plugins", "installed_plugins.json"),
+      "utf8",
+    );
+    const parsed = JSON.parse(raw);
+    const plugins =
+      parsed &&
+      typeof parsed === "object" &&
+      parsed.plugins &&
+      typeof parsed.plugins === "object"
+        ? parsed.plugins
+        : parsed;
+    if (!plugins || typeof plugins !== "object") return null;
+    for (const spec of Object.keys(plugins)) {
+      if (spec === SKILL_SLUG) return `${SKILL_SLUG}@${SKILL_SLUG}`;
+      if (spec.startsWith(SKILL_SLUG + "@")) return spec;
+    }
+  } catch {
+    // missing or corrupt = no plugin — fail open on absence, never crash
+  }
+  return null;
+}
+
+/**
+ * One channel per agent. A plain `<H>/.claude/skills/sheleg-design` beside an
+ * installed plugin is two listings of the same skill, and the stale copy wins
+ * — the exact shadow the family canon forbids (make-skill
+ * references/distribution.md §"The installer must refuse the shadow it
+ * documents"). Refuse rather than create it, and refuse LOUDLY: a refusal
+ * that exits 0 reads as success to every script above it. Reproduced live
+ * 2026-08-29: a bare `npx @ssheleg/telegram-dev` shipped three shadows past a
+ * marketplace-dir-only check while the plugin was enabled.
+ */
+function refuseIfPluginOwnsChannel(targetDir, force) {
+  const home = claudeHomeOf(targetDir);
+  if (!home || force) return;
+  const spec = installedPluginSpec(home);
+  const marketplaces = path.join(home, ".claude", "plugins", "marketplaces");
+  const mktDir = [SKILL_SLUG, "sheleg-design-skill"]
+    .map((n) => path.join(marketplaces, n))
+    .find((p) => fs.existsSync(p));
+  if (!spec && !mktDir) return;
+
+  const remedySpec = spec || "sheleg-design@sheleg-design-skill";
+  const remedyMarketplace = remedySpec.split("@")[1];
+  const found = spec
+    ? `installed as the Claude Code plugin ${spec}\n` +
+      `         (declared in ${path.join(home, ".claude", "plugins", "installed_plugins.json")})`
+    : `registered as a Claude Code marketplace\n         (${mktDir})`;
+  console.error(
+    c("yellow", `refused: ${SKILL_SLUG} is already ${found}.`) +
+      `\n         A plain copy in ${path.join(home, ".claude", "skills", SKILL_SLUG)}\n` +
+      `         would shadow the plugin and serve this frozen version forever.\n` +
+      `         Update the plugin channel instead:\n` +
+      `           ${c("bold", `claude plugin marketplace update ${remedyMarketplace}`)}\n` +
+      `           ${c("bold", `claude plugin update ${remedySpec}`)}\n` +
+      `         Family launcher (updates every member, prunes shadow copies):\n` +
+      `           ${c("bold", "npx --yes sshlg-skills@latest update")}\n` +
+      `         Pass --force to write the plain copy anyway — a deliberate choice\n` +
+      `         to run two channels, where the stale one wins.`,
+  );
+  // Offered on the refusal path too: the skill IS present on this machine —
+  // as the plugin — so the routing block is exactly as wanted as on the
+  // install path.
+  offerRouters();
+  process.exit(EXIT_PLUGIN_PRESENT);
+}
+
 function main() {
   const opts = parseArgs(process.argv.slice(2));
 
@@ -350,6 +467,10 @@ function main() {
 
   const targetDir = resolveTargetDir(opts, cwd);
 
+  // Before any write to a home's ~/.claude/skills/sheleg-design: if that
+  // home's plugin channel already owns this skill, refuse (exit 3).
+  refuseIfPluginOwnsChannel(targetDir, opts.force);
+
   // Verify the bundle is intact before touching the filesystem.
   for (const f of CORE_FILES) {
     if (!fs.existsSync(path.join(SKILL_DIR, f))) {
@@ -394,6 +515,16 @@ function main() {
   );
 
   offerRouters();
+
+  // The last line says how the next version arrives — "installed" is not a
+  // complete sentence. Auto-update is off on purpose: this member composes
+  // with its family, and per-marketplace autoUpdate moves each member on its
+  // own clock, into combinations nobody tested together.
+  console.log(
+    `Updates: rerun ${c("bold", "npx sheleg-design-skill@latest --force")}, or refresh the\n` +
+      `whole family with ${c("bold", "npx --yes sshlg-skills@latest update")} (every channel,\n` +
+      `and it prunes plain copies that would shadow a plugin).\n`,
+  );
 }
 
 /**

package/cursor/rules/sheleg-design.mdc

@@ -132,6 +132,12 @@ every control lit by a four-layer shadow in its own hue, a handwritten face and
 yellow marker annotating from the margin, machine surfaces quarantined in their own
 dark ladder that ignores the theme, for self-serve SaaS sold by handing over the
 running product;
+surveyor — warm peach paper where an unseen terrain is mapped: fine contour lines as
+the single texture, flat white and tinted cards with no shadow anywhere but the
+detached nav, one teal whose text-bearing steps climb the reference's own hover
+ladder, a pink that answers but may not speak, TT Fors at a 600 ceiling with tabular
+numerals, and the product shown only as flat portraits, for visibility, monitoring
+and benchmark tools sold to marketing teams;
 otherwise follow the contract below (self-contained on purpose).
 
 ## Whether to animate at all — before how

package/kits/surveyor/.design-sync/config.json

@@ -0,0 +1,14 @@
+{
+  "pkg": "@sheleg-design/surveyor",
+  "globalName": "ShelegSurveyor",
+  "shape": "package",
+  "buildCmd": "npm run build",
+  "srcDir": "src",
+  "tsconfig": "tsconfig.json",
+  "cssEntry": "src/styles.css",
+  "docsDir": "src",
+  "readmeHeader": ".design-sync/conventions.md",
+  "guidelinesGlob": [
+    "guidelines/*.md"
+  ]
+}

package/kits/surveyor/.design-sync/conventions.md

@@ -0,0 +1,35 @@
+# Surveyor — conventions for a design agent
+
+This kit is the built form of the Surveyor style pack. Read these before generating
+anything with it; they are the pack's bans, stated where a design tool will see them.
+
+## Colour
+
+- **The teal is a ladder and the roles are shifted one step down**: `--action`
+  (#0a7269) carries every word and text-bearing fill; `--accent` (#0d9488) is
+  large-only — stat figures, marks, the Q glyph. White body copy on #0d9488 (3.74:1)
+  is the reference's recorded failure; do not restore it.
+- **The pink never speaks at `--pink`** (1.84:1 on the field): glyphs, series and
+  tints only. A pink word is `--pink-deep`.
+- **Tense as tint**: mint = shipping, pink = coming. Swapping them lies.
+- **Three statuses, no warn** — an amber here would be an invented value.
+
+## Geometry
+
+- Controls 10px, cards 24px, panels 32px, badges 6px, pill 99px. The corpus's 20
+  and 12 are nested instances (24−4, 20−8), never free values.
+- Nothing is bolder than 600, and the heading tracking RELAXES at narrow widths.
+
+## Elevation
+
+- Flat. White/mint/pink tints on peach are the whole depth. The one shadow is the
+  detached nav's, toggled on scroll.
+
+## Proof
+
+- The product appears as `Portrait` — a flat still. No browser chrome, no
+  spotlight, no animation inside the image.
+
+## Motion
+
+- One 0.2s clock and one pulse ring. Nothing moves, lifts, scales or scrolls.

package/kits/surveyor/README.md

@@ -0,0 +1,33 @@
+# @sheleg-design/surveyor
+
+The React reference kit for the **Surveyor** style pack — warm peach paper where an
+unseen terrain is mapped: contour lines for texture, flat portraits for proof, a teal
+that states and a pink that answers.
+
+The pack document is the source of truth for every value here:
+`plugins/sheleg-design/skills/sheleg-design/styles/surveyor.md`. This kit is what
+those values look like when they are built, and `src/styles.css` opens with the
+pack's token layer copied byte for byte — never transcribed.
+
+```bash
+npm install && npm run build   # tsc only; there is no bundler in this kit
+```
+
+## What ships
+
+**The spine**, identical in name, props and types across every SHELEG kit: `Button`,
+`Card`, `Chip`, `Stat`, `Heading`, `Rule`.
+
+**The signature**: `StatSlab` (the counted reading in the working hue), `Delta` (a
+reading's movement, arrow included), `Portrait` (the flat still), `TintPanel` (tense
+as tint), `Closer` (the one dark slab — the signature element), `Dialogue` (the
+teal-Q/pink-A pair), `Pulse` (the one loop), `Field`, `NavBar`, `Empty`.
+
+## The three rules a generator loses first
+
+1. The page is flat: no shadow on anything but the detached nav, and elevation is a
+   tint. A `shadow-md` is a foreign object.
+2. The teal ladder is shifted for AA: `--action` `#0a7269` writes and fills;
+   `--accent` `#0d9488` is large-only (`#ffffff` on it is 3.74:1).
+3. The pink answers, it does not speak: `--pink` for glyphs and tints beside
+   readable ink, `--pink-deep` when pink must carry a word.

package/kits/surveyor/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@sheleg-design/surveyor",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/react": "^18.3.0"
+  }
+}

package/kits/surveyor/src/Button.md

@@ -0,0 +1,17 @@
+---
+category: Actions
+---
+
+One height (`--control-h`, 48px: 12×24 padding on 16px/500) at `--r-control`, and a
+fill that only ever changes colour — no shadow, no scale, no travel. `primary` rests
+on `--action` (the reference's own hover step, promoted for AA: `#ffffff` on
+`#0a7269` is 5.79:1) and hovers to `--action-hover`. `secondary` is the measured
+outline: transparent on the field with a 1px `--ink` border. `ghost` tints `--mint`
+on hover. Disabled keeps the reference's own literal pair.
+
+Focus is the pack's correction: the fill step **and** a 2px `--focus-color` outline.
+
+```tsx
+<Button>Start free trial</Button>
+<Button variant="secondary">Book a demo</Button>
+```

package/kits/surveyor/src/Button.tsx

@@ -0,0 +1,33 @@
+import type { ReactNode } from 'react';
+
+export interface ButtonProps {
+  /** `primary` is the accent fill — at most one per view. */
+  variant?: 'primary' | 'secondary' | 'ghost';
+  size?: 'sm' | 'md' | 'lg';
+  disabled?: boolean;
+  onClick?: () => void;
+  children: ReactNode;
+  className?: string;
+}
+
+export function Button({
+  variant = 'primary',
+  size = 'md',
+  disabled = false,
+  onClick,
+  children,
+  className,
+}: ButtonProps) {
+  return (
+    <button
+      type="button"
+      className={['sv-btn', `sv-btn--${variant}`, `sv-btn--${size}`, className]
+        .filter(Boolean)
+        .join(' ')}
+      disabled={disabled}
+      onClick={onClick}
+    >
+      {children}
+    </button>
+  );
+}

package/kits/surveyor/src/Card.md

@@ -0,0 +1,11 @@
+---
+category: Surfaces
+---
+
+A card is `--surface` at `--r-card` (24px) with 24px padding and **nothing else** —
+no border, no shadow, no hover. Elevation on this page is a tint, and the one drop
+shadow belongs to the detached nav.
+
+```tsx
+<Card title="Business owners">…</Card>
+```

package/kits/surveyor/src/Card.tsx

@@ -0,0 +1,24 @@
+import type { ReactNode } from 'react';
+
+export interface CardProps {
+  title?: string;
+  /** Right-aligned metadata on the title row: a count, an id, a timestamp. */
+  meta?: string;
+  children: ReactNode;
+  className?: string;
+}
+
+export function Card({ title, meta, children, className }: CardProps) {
+  const head = title !== undefined || meta !== undefined;
+  return (
+    <section className={['sv-card', className].filter(Boolean).join(' ')}>
+      {head && (
+        <div className="sv-card__head">
+          {title !== undefined && <h3 className="sv-card__title">{title}</h3>}
+          {meta !== undefined && <span className="sv-card__meta">{meta}</span>}
+        </div>
+      )}
+      <div className="sv-card__body">{children}</div>
+    </section>
+  );
+}

package/kits/surveyor/src/Chip.md

@@ -0,0 +1,11 @@
+---
+category: Data
+---
+
+A 6px-radius badge in a tense tint: default is `--mint` with `--action` text
+("Coming soon" ships mint in the reference), `accent` is `--pink-wash` with
+`--pink-deep`. A chip never carries a status alone — `Delta` does states.
+
+```tsx
+<Chip>Coming soon</Chip>
+```

package/kits/surveyor/src/Chip.tsx

@@ -0,0 +1,25 @@
+import type { ReactNode } from 'react';
+
+export interface ChipProps {
+  children: ReactNode;
+  selected?: boolean;
+  tone?: 'neutral' | 'accent';
+  className?: string;
+}
+
+export function Chip({ children, selected = false, tone = 'neutral', className }: ChipProps) {
+  return (
+    <span
+      className={[
+        'sv-chip',
+        `sv-chip--${tone}`,
+        selected ? 'sv-chip--selected' : undefined,
+        className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+    >
+      {children}
+    </span>
+  );
+}

package/kits/surveyor/src/Closer.md

@@ -0,0 +1,14 @@
+---
+category: Signature
+---
+
+**The signature element.** The page's only dark object: an `--accent` slab at
+`--r-panel` with two white contour origins bleeding off its edges, a white heading
+(3.74:1 — legal at heading sizes only, which is why `support` renders at the
+24px question size and never body), and one white outline control. One per page;
+a second closer has spent the device twice and broken it both times.
+
+```tsx
+<Closer title="Need a custom plan?" support="Contact our team."
+  action={<Button variant="secondary">Book a demo</Button>} />
+```

package/kits/surveyor/src/Closer.tsx

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+
+export interface CloserProps {
+  /** The heading — white on the brand teal is legal at heading sizes only. */
+  title: string;
+  /** One line of support copy, kept at heading scale. */
+  support?: string;
+  /** One white outline control. */
+  action: ReactNode;
+  className?: string;
+}
+
+export function Closer({ title, support, action, className }: CloserProps) {
+  return (
+    <section className={['sv-closer', className].filter(Boolean).join(' ')}>
+      <h2 className="sv-closer__title">{title}</h2>
+      {support !== undefined && <p className="sv-closer__support">{support}</p>}
+      <span className="sv-closer__action">{action}</span>
+    </section>
+  );
+}

package/kits/surveyor/src/Delta.md

@@ -0,0 +1,12 @@
+---
+category: Signature
+---
+
+A reading's movement: number first, arrow second, hue third. Rising takes the
+action family; falling takes `--pink-deep` — the *speaking* pink at 5.32:1, never
+the glyph pink. The arrow ships inside the component because status is never
+colour alone.
+
+```tsx
+<Delta direction="down">1,3</Delta>
+```