◉ wisp

The component explorer built by the design team at literal.
Built for teams using AI to write frontend code.

---

Why we built this

AI writes a lot of our frontend code. That's fast — until you need to actually see what was generated, inspect its layout, tweak a prop, or check how it behaves at different sizes. The feedback loop between AI output and visual confirmation matters.

The tools that existed were too slow. A component explorer that takes 30 seconds to start doesn't fit inside an AI-assisted workflow. We needed something that opened instantly, showed the component exactly as it renders, and got out of the way.

So the design team at literal built wisp for ourselves. We're open-sourcing it because the workflow is universal — if you're using AI to build UI, you have the same problem.

---

What it does

wisp is a local component explorer for React + TypeScript. Point it at a folder of *.stories.tsx files and it runs — no build config, no plugin ecosystem. Files hot-reload the moment they're saved, which means the loop between AI generating a component and you seeing it is as short as it can be.

npx wisp --dir ../my-app/src/components

Inspired by Storybook's CSF3 story format — existing story files work without changes.

---

Features

• Component preview — hierarchical sidebar built from your folder structure
• Live controls — auto-generated from argTypes: text, boolean, select, number, range, color
• Resizable canvas — drag the frame edges to test responsive behavior; viewport presets for mobile, tablet, and desktop
• Element inspector — click any element to read its box model, spacing, borders, and typography directly from the DOM
• Code view — JSX usage snippet with syntax highlighting and one-click copy
• Docs — editable markdown documentation per component, rendered inline
• Hot reload — new .stories.tsx files appear the moment they're saved
• Fullscreen — press F to expand any component to full viewport

---

Getting started

git clone https://github.com/CodeByAshton/wisp
cd wisp
npm install
npm run dev

Opens at http://localhost:5174 with the built-in demo stories.

---

Pointing at your own project

Edit wisp.config.ts:

import { defineConfig } from './src/config'

export default defineConfig({
  storiesDir: '../my-app/src/components',
  storiesGlob: '**/*.stories.tsx',
})

Or use the CLI:

npx wisp --dir ../my-app/src/components --port 3000

Or use the settings panel — click the gear icon, enter a path, hit Apply. wisp rewrites the config and reloads.

---

Story format

// Button.stories.tsx
import type { Meta, StoryObj } from 'wisp'
import { Button } from './Button'

const meta: Meta<typeof Button> = {
  component: Button,
  argTypes: {
    variant: { control: 'select', options: ['primary', 'secondary', 'ghost'] },
    label:   { control: 'text' },
    disabled:{ control: 'boolean' },
  },
}

export default meta
type Story = StoryObj<typeof Button>

export const Primary:   Story = { args: { variant: 'primary',   label: 'Continue' } }
export const Secondary: Story = { args: { variant: 'secondary', label: 'Cancel'   } }

Folder structure determines sidebar navigation — no title strings needed:

src/components/
  Inputs/
    Button.stories.tsx      →  Inputs › Button
    InputField.stories.tsx  →  Inputs › Input Field
  DataDisplay/
    Badge.stories.tsx       →  Data Display › Badge
  Overlays/
    Modal.stories.tsx       →  Overlays › Modal

---

Keyboard shortcuts

Key	Action
⌘K	Focus search
F	Toggle fullscreen
R	Reset controls
← →	Previous / next variant

---

Tech stack

• Vite 5 — dev server, HMR, virtual module plugin
• React 18 — UI
• TypeScript 5 — end-to-end types
• Lucide React — icons
• CSS Modules — scoped styles, Apple HIG design tokens

---

Claude Code skill

This repo ships a Claude Code skill that turns any component request into a production-ready wisp story in one shot.

/wisp build a status badge with variants: success, warning, error

The skill enforces CDD methodology — story first, one component per file, TypeScript strict, WCAG AA touch targets, and useReducedMotion() on every animated component. Three reference files live in .claude/references/ and are loaded on demand:

File	When Claude reads it
story-template.md	Canonical story shape, arg types, import paths
animation.md	react-spring patterns, gesture patterns, reduced-motion guard
component-examples.md	Worked examples: Badge, BottomSheet, PageTransition

To use the skill, open Claude Code in your project and type /wisp followed by a description or attach a screenshot.

---

License

MIT © literal