@madebywild/wvk 0.0.2 → 0.1.0

package/AGENTS.md

@@ -0,0 +1,81 @@
+# wvk — agent rules
+
+These rules apply to every wvk (wild vibeframe kit) project. They are absolute. When a request conflicts with them, raise the conflict — do not silently work around them.
+
+## The kit is the source of truth
+
+wvk projects are wireframes built from a fixed kit: a closed set of components, tokens, and typography styles. The kit is the vocabulary. If the kit does not have a word for it, the wireframe does not say it.
+
+- **Components** live in `src/components/ui/*` and `src/components/icons/*`. Always import from there.
+- **Tokens** are defined globally (CSS variables, Tailwind config). Color, spacing, radius, sizing, and icon size all come from kit tokens.
+- **Typography** uses the kit's existing text styles only.
+
+## No new tokens. No new styles. Ever.
+
+There is **no scenario** in a wireframe where you introduce a new color, spacing value, radius, font size, line height, or font weight.
+
+- **Color**: only semantic tokens (`foreground`, `muted-foreground`, `border`, `--wvk-surface-*`, etc.). No one-off hex, no arbitrary Tailwind color scales (`bg-blue-500`, `text-red-600`), no `text-destructive` for emphasis. Signal destructive intent with an icon (e.g. trash), not a non-token accent.
+- **Spacing**: only `var(--wvk-px-*)`, `var(--wvk-gap-*)`, `var(--wvk-size-*)` and the kit's Tailwind spacing scale. No arbitrary values like `p-[13px]` or `gap-[7px]`.
+- **Radius**: only `var(--radius-*)` (`-md`, `-lg`, `-full`, etc.). No `rounded-[6px]`.
+- **Typography**: only the existing text styles already used in the kit (the same Tailwind utilities the kit's components use — e.g. `text-sm`, `text-xs`, `font-bold`, `leading-5`). Do **not** invent a new size, weight, tracking, or leading. No `text-[15px]`, no `font-[450]`, no `leading-[1.35]`. If a reference implies a size that isn't in the kit, pick the closest existing style.
+- **Shadows**: the kit is flat. No `shadow-*` on cards, panels, or chrome. Use `border border-border` for separation.
+
+If a design genuinely cannot be expressed within the existing tokens, **stop and surface it**. Do not patch around it with arbitrary values.
+
+## Reference adaptation — strict translation, not mimicry
+
+When the user provides a reference (screenshot, URL, prompt, Figma, competitor product), the job is to **translate the structure and information into the kit**, not to reproduce the reference's visual identity.
+
+**Always use the kit's component as the base, even if it doesn't match the reference 1:1.** A more elaborate search field in the reference still maps to our `TextInput`. A custom-styled segmented control still maps to `SegmentedControl`. A bespoke card still uses our spacing, radius, and border.
+
+**When the kit lacks a piece of the reference's UI:**
+
+1. Use the closest existing kit component as the base.
+2. Implement what the kit can express cleanly.
+3. **Surface the gap** in your reply — name the missing primitive, pattern, or interaction (e.g. "the reference's search field has an inline filter chip row inside the input — the kit's `TextInput` has no slot for that, so I omitted it; this is a candidate for a new component or an extension"). Be specific about what was dropped and why.
+
+Do **not**:
+
+- Build a one-off component to match the reference more closely.
+- Add custom styling, icons, or chrome to fake a missing primitive.
+- Adopt the reference's color palette, typography, spacing rhythm, or shadow language.
+- Default to dark mode because the reference is dark — keep the kit's light theme unless the user explicitly asks for dark.
+
+Do:
+
+- **Keep the reference's information and actions.** Labels, copy, headings, helper text, buttons, links, tabs, table content — all should survive the kit pass. Visual translation is not a license to strip the UI for a "cleaner" wireframe. Drop content only when the user explicitly asks.
+- **Preserve affordances**, not chrome. If the reference shows an action, keep an equivalent action with the kit's button/link variants.
+- **Match dominant layout patterns** (sidebar shape, header placement, content hierarchy) using kit spacing.
+- **Only reproduce UI that appears in the reference.** Don't add extra widgets to "use more components."
+
+For multi-screen flows (onboarding, API explorer, checkout): build a real prototype driven by user actions and timed state transitions, not a stepper with "next/back" dev buttons. Mock data is fine; canonical strings belong in fixed slots.
+
+## Components — prefer kit, prefer semantic
+
+Always reach for an existing kit component before writing markup. Two-option mode switch → `SegmentedControl`, not a button group. Status row → plain typography, not `Tag` unless the reference clearly shows a pill. Single primary action → `Button`, not `SplitButton`.
+
+Pair controls with kit icons from `@/components/icons`. Dark mode chrome (`Tabs`, `SegmentedControl`, nav) must remain readable against the themed background — use semantic surface and border tokens (`--wvk-surface-*`, `--wvk-border-bold`, `--wvk-foreground-*`) so both light and `.dark` contrast correctly. Don't hard-code `--wvk-primitive-dark` for selected states when it can blend into a dark page fill.
+
+## Icons
+
+Icons in `src/components/icons/*.svg` are imported as React components via `@svgr/webpack`. The SVGR config strips fixed `width`/`height` and adds `100%`/`100%` plus `preserveAspectRatio="xMidYMid meet"` so glyphs scale inside kit slots (`[&_svg]:size-full`, `--wvk-icon-sm`/`md`/`lg`). New icons must define a correct `viewBox` and must not rely on fixed `width`/`height` for layout.
+
+Do **not** add `feDropShadow` or other shadow treatments to UI kit icons or other elements (unless asked). Drop shadows are reserved for `/public/cursors/*.svg` (cursor images can't use CSS shadow).
+
+**Never use unicode arrow characters** (`→`, `←`, `↑`, `↓`) in UI text. Use the kit icon component (`<ArrowRight />`, `<ArrowLeft />`, etc.), sized with `className="size-[var(--wvk-icon-sm)]"` and `aria-hidden` (the surrounding text carries the meaning).
+
+## Motion
+
+The kit ships with `framer-motion`. When something needs to animate (transitions, hover and tap feedback, list reveals, modal or drawer entrances, content swaps), reach for `motion` first. Don't roll a CSS keyframe or hand-spring a transform when the library already covers it cleanly.
+
+Use small microinteractions to add a moment of delight: a subtle bounce on a successful action, a tilt on a hovered card, a soft fade-and-slide on content change, a gentle scale on press. Keep them quick (typically under ~300ms), purposeful, and tied to real user feedback.
+
+Don't overdo it. Motion is seasoning, not the meal. If every element animates, nothing reads as special, and the page starts to feel busy instead of alive. Reserve animation for moments that benefit from it, and respect `prefers-reduced-motion` so users on that setting get a calm, near-static experience.
+
+## Responsiveness
+
+Always make sure that pages are overall **responsive** (unless specified). This includes making sure that sections, components and type scales properly in small increments, but also when changing the viewport drastically (like going from Desktop to Mobile) that the page still works. Like moving nav items into a burger menu to make sure they're accessible.
+
+## When you're stuck
+
+If a request can't be done within these rules — a reference needs a primitive the kit doesn't have, a layout needs a token that doesn't exist, a typographic hierarchy isn't expressible in the existing styles — **stop and ask**. Describe the gap, propose the closest kit-compliant alternative, and let the user decide whether to extend the kit or accept the wireframe-faithful version. Never resolve the gap by introducing new tokens, sizes, or one-off styling.

package/README.md

@@ -73,6 +73,53 @@ export default function RootLayout({ children }) {
 
 `ThemeProvider` also installs a small cursor fallback stylesheet when the full package stylesheet is not present yet. For full component styling and design tokens, still import `@madebywild/wvk/styles.css` from your global stylesheet.
 
+### Whimsy cursor (on by default)
+
+`ThemeProvider` auto-mounts `WhimsyCursor` — a DOM-rendered pointer that tilts on hover over interactive elements. It only activates on `(pointer: fine)` devices, so it's a no-op on touch.
+
+```tsx
+// Disable
+<ThemeProvider whimsyCursor={false}>{children}</ThemeProvider>
+
+// Customize the hover tilt
+<ThemeProvider whimsyCursor={{ hoverRotateDeg: -10 }}>{children}</ThemeProvider>
+```
+
+You can still render `<WhimsyCursor />` yourself if you'd rather mount it outside `ThemeProvider`; in that case pass `whimsyCursor={false}` to avoid double-mounting.
+
+### Cursor style variants
+
+The kit ships two default-cursor sprites:
+
+- `"default"` (default) — the chunky kit signature pointer, paired with `WhimsyCursor`
+- `"arrow"` — a slim classic arrow; `WhimsyCursor` auto-suppresses so the native cursor stays visible
+
+Set the initial style on `ThemeProvider`, or flip it at runtime via the `useCursorStyle()` hook (persisted to `localStorage` under `wvk-cursor-style`). The kit doesn't ship a UI for this — wire your own toggle if you want to expose it to users.
+
+```tsx
+import { ThemeProvider, useCursorStyle } from "@madebywild/wvk";
+
+<ThemeProvider cursorStyle="arrow">{children}</ThemeProvider>;
+
+// Anywhere inside the provider:
+const { cursorStyle, setCursorStyle } = useCursorStyle();
+```
+
+For SSR without a flash, mirror the value in the anti-flash inline script your app already uses for theme:
+
+```html
+<script>
+(function(){
+  try {
+    var c = localStorage.getItem('wvk-cursor-style');
+    if (c === 'arrow') document.documentElement.classList.add('wvk-cursor-style-arrow');
+  } catch (e) {}
+})();
+</script>
+```
+
+Other cursor tokens — `--wvk-cursor-pointer`, `--wvk-cursor-move`, `--wvk-cursor-grabbing`, `--wvk-cursor-text` — are independent of the variant. Tailwind utilities `cursor-pointer`, `cursor-move`, `cursor-grabbing`, and `cursor-text` are wired to them. `cursor-grab` aliases to the move sprite (no open-hand variant ships yet).
+
 ## Design-token philosophy
 
 Tokens are organized in three tiers:
@@ -82,3 +129,23 @@ Tokens are organized in three tiers:
 - **Shadcn-compatible** (`--background`, `--foreground`, `--primary`, …) — driven by the semantic tier so any shadcn-style components keep working.
 
 Always prefer semantic tokens in product code; reach for primitives only for one-off accents.
+
+## Agent rules
+
+The package ships an `AGENTS.md` describing the strict authoring contract for wvk wireframes (kit-only tokens, components, typography, icons). Drop it into your project so your agent harness picks it up:
+
+```bash
+# write ./AGENTS.md (refuses to overwrite an existing file)
+npx @madebywild/wvk copy-harness
+
+# overwrite an existing AGENTS.md
+npx @madebywild/wvk copy-harness --force
+
+# merge into an existing AGENTS.md as an idempotent, delimited block
+npx @madebywild/wvk copy-harness --append
+
+# write to a custom path (parent dirs are created)
+npx @madebywild/wvk copy-harness --out .claude/AGENTS.md
+```
+
+`--append` wraps the rules in `<!-- BEGIN @madebywild/wvk AGENTS.md ... -->` / `<!-- END ... -->` markers. Re-running replaces the block in place, so the file never grows duplicate copies and stays safe to call from a postinstall or CI step.

package/bin/wvk.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PKG_NAME = "@madebywild/wvk";
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(SCRIPT_DIR, "..");
+const SOURCE = resolve(PKG_ROOT, "AGENTS.md");
+const PKG_JSON = JSON.parse(
+  readFileSync(resolve(PKG_ROOT, "package.json"), "utf8"),
+);
+const VERSION = PKG_JSON.version;
+
+const BEGIN_RE = new RegExp(
+  `<!-- BEGIN ${escapeRegex(PKG_NAME)} AGENTS\\.md \\(v[^,]+, sha256:([a-f0-9]+)\\) -->`,
+  "g",
+);
+const END_MARK = `<!-- END ${PKG_NAME} AGENTS.md -->`;
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function usage() {
+  return `wvk — ${PKG_NAME} CLI
+
+Usage:
+  wvk copy-harness [--force] [--append] [--out <path>]
+  wvk --help
+  wvk --version
+
+Commands:
+  copy-harness    Copy this package's AGENTS.md into your project so your
+                  agent harness picks up the wvk authoring rules.
+
+Options:
+  --out <path>    Destination path (default: ./AGENTS.md). Parent dirs are created.
+  --force         Overwrite the destination if it exists. Mutually exclusive with --append.
+  --append        Merge the rules into the destination as a delimited, idempotent block.
+                  Re-running is safe: the block is replaced in place, never duplicated.
+`;
+}
+
+function fail(msg, code = 1) {
+  process.stderr.write(`wvk: ${msg}\n`);
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const args = { _: [], force: false, append: false, out: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--force") args.force = true;
+    else if (a === "--append") args.append = true;
+    else if (a === "--out") {
+      const v = argv[++i];
+      if (!v) fail("--out requires a path");
+      args.out = v;
+    } else if (a === "--help" || a === "-h") args.help = true;
+    else if (a === "--version" || a === "-v") args.version = true;
+    else if (a.startsWith("--")) fail(`unknown option: ${a}`);
+    else args._.push(a);
+  }
+  return args;
+}
+
+function shortHash(buf) {
+  return createHash("sha256").update(buf).digest("hex").slice(0, 12);
+}
+
+function buildBlock(body, hash) {
+  const begin = `<!-- BEGIN ${PKG_NAME} AGENTS.md (v${VERSION}, sha256:${hash}) -->`;
+  const trimmed = body.replace(/\s+$/, "");
+  return `${begin}\n${trimmed}\n${END_MARK}\n`;
+}
+
+function findBlocks(text) {
+  const blocks = [];
+  let m;
+  BEGIN_RE.lastIndex = 0;
+  while ((m = BEGIN_RE.exec(text)) !== null) {
+    const beginStart = m.index;
+    const beginEnd = m.index + m[0].length;
+    const endIdx = text.indexOf(END_MARK, beginEnd);
+    if (endIdx === -1) {
+      fail(
+        `corrupted AGENTS.md block: BEGIN marker without matching END at offset ${beginStart}`,
+      );
+    }
+    blocks.push({
+      hash: m[1],
+      start: beginStart,
+      end: endIdx + END_MARK.length,
+    });
+  }
+  return blocks;
+}
+
+function copyHarness(args) {
+  if (args.append && args.force) {
+    fail("--append and --force are mutually exclusive");
+  }
+  if (!existsSync(SOURCE)) {
+    fail(`source AGENTS.md missing in package at ${SOURCE}`);
+  }
+  const body = readFileSync(SOURCE, "utf8");
+  const hash = shortHash(body);
+  const dest = resolve(process.cwd(), args.out ?? "AGENTS.md");
+  const destRel = relative(process.cwd(), dest) || dest;
+  mkdirSync(dirname(dest), { recursive: true });
+
+  const exists = existsSync(dest) && statSync(dest).isFile();
+
+  if (args.append) {
+    const block = buildBlock(body, hash);
+    if (!exists) {
+      writeFileSync(dest, block);
+      report(destRel, "appended");
+      return;
+    }
+    const current = readFileSync(dest, "utf8");
+    const blocks = findBlocks(current);
+    if (blocks.length > 1) {
+      fail(
+        `${destRel} contains ${blocks.length} ${PKG_NAME} blocks; remove duplicates and retry`,
+      );
+    }
+    if (blocks.length === 1) {
+      const [b] = blocks;
+      if (b.hash === hash) {
+        report(destRel, "unchanged");
+        return;
+      }
+      const before = current.slice(0, b.start);
+      const after = current.slice(b.end);
+      const next =
+        before + block.replace(/\n$/, "") + (after.startsWith("\n") ? "" : "\n") + after;
+      writeFileSync(dest, next);
+      report(destRel, "updated");
+      return;
+    }
+    const sep = current.length === 0 || current.endsWith("\n") ? "" : "\n";
+    const gap = current.length === 0 ? "" : "\n";
+    writeFileSync(dest, current + sep + gap + block);
+    report(destRel, "appended");
+    return;
+  }
+
+  if (exists && !args.force) {
+    fail(
+      `${destRel} already exists. Re-run with --force to overwrite, or --append to merge.`,
+    );
+  }
+  writeFileSync(dest, body);
+  report(destRel, exists ? "overwritten" : "written");
+}
+
+function report(destRel, mode) {
+  process.stdout.write(`wvk: ${mode} ${destRel}\n`);
+  if (mode !== "unchanged") {
+    process.stdout.write(
+      `wvk: your agent harness should now pick up the ${PKG_NAME} rules.\n`,
+    );
+  }
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    process.stdout.write(usage());
+    return;
+  }
+  if (args.version) {
+    process.stdout.write(`${VERSION}\n`);
+    return;
+  }
+  const cmd = args._[0];
+  if (!cmd) {
+    process.stdout.write(usage());
+    return;
+  }
+  if (cmd === "copy-harness") {
+    copyHarness(args);
+    return;
+  }
+  process.stderr.write(`wvk: unknown command: ${cmd}\n\n${usage()}`);
+  process.exit(1);
+}
+
+main();