@madebywild/wvk
v0.1.2
Published
Wireframe kit — components, icons, and design tokens
Readme
@madebywild/wvk
Wireframe kit — accessible React components, 183 icons, and design tokens that map 1:1 to the wild Wireframe Kit Figma library.
Quick start (new project)
Scaffold a fresh Next.js 16 / React 19 / Tailwind v4 app that ships with @madebywild/wvk already wired up — ThemeProvider, design tokens, the package stylesheet, and a small Header composition:
npx @madebywild/wvk create-next-app my-wvk-app
cd my-wvk-app
npm install
npm run devThen open http://localhost:3000. The scaffold also writes an AGENTS.md so your agent harness (Claude Code, Cursor, Copilot, etc.) picks up the wvk authoring rules — pass --no-agents to skip that, or --force to scaffold into a non-empty directory.
Install
pnpm add @madebywild/wvk
# peers
pnpm add react react-domThe kit assumes Tailwind CSS v4 in your app.
Use components
import { Button, TextInput, Tag } from "@madebywild/wvk";
export function Example() {
return (
<div>
<TextInput placeholder="Search" />
<Button>Save</Button>
<Tag>New</Tag>
</div>
);
}Use icons
Icons ship as pre-compiled React components — no SVGR setup required in your app. Import only what you use; the rest tree-shakes away.
import { MagnifyingGlass, ArrowRight } from "@madebywild/wvk/icons";
<MagnifyingGlass className="h-4 w-4" />;Paths use currentColor, so the icon inherits the parent's text color.
Use the design tokens
In your global stylesheet (after @import "tailwindcss";):
@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));
@import "@madebywild/wvk/styles.css";This registers the wvk-* color, surface, foreground, border, transparency, primitive, radius, size, and cursor tokens, plus light/dark theme values (toggle by adding class="dark" to <html>).
Custom cursors are self-contained. The cursor tokens embed the SVG artwork as data URLs, so consumers do not need to copy files into public/ or configure asset hosting. If a browser does not support SVG cursors, the tokens still end with system keyword fallbacks.
Theme switching
Wrap your app in ThemeProvider and drop the prebuilt switcher anywhere:
import { ThemeProvider, ThemeSwitcher } from "@madebywild/wvk";
export default function RootLayout({ children }) {
return (
<ThemeProvider>
<ThemeSwitcher />
{children}
</ThemeProvider>
);
}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.
// 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 withWhimsyCursor"arrow"— a slim classic arrow;WhimsyCursorauto-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.
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:
<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:
- Primitives (
--wvk-primitive-*) — fixed palette swatches (Dark, Medium, Soft, …) matching the Figma Colors frame. - Semantic (
--wvk-surface-*,--wvk-foreground-*,--wvk-border-*,--wvk-transparency-*) — role-based tokens that flip between light and dark themes. - 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:
# 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.