docs: polish root README and add per-package READMEs (#18)

ignsm · web-flow · commit 2166f2f3b1f1 · 2026-04-11T00:51:41.000+09:00
* docs: polish root README and add per-package READMEs

* docs: mention /formhaus-create-form and /formhaus-figma-connect skills
diff --git a/README.md b/README.md
@@ -6,8 +6,8 @@
 [![bundlephobia](https://img.shields.io/bundlephobia/minzip/@formhaus/core?label=core%20size)](https://bundlephobia.com/package/@formhaus/core)
 [![license](https://img.shields.io/github/license/ignsm/formhaus)](LICENSE)
 
-Framework-agnostic form engine with its own compact JSON-based definition format.
-Define a form once — fields, validation, conditions, steps — in a single file. Render it in React, Vue, Figma, or any framework via the core engine. No JSON Schema spec, no separate UI schema, no boilerplate.
+Framework-agnostic form engine with a compact JSON definition format.
+Define a form once (fields, validation, conditions, steps) in a single file. Render it in React, Vue, Figma, or anything via the core engine. No JSON Schema spec, no separate UI schema, no boilerplate.
 
 ## Packages
 
@@ -17,9 +17,9 @@ Define a form once — fields, validation, conditions, steps — in a single fil
 | `@formhaus/react` | React adapter with native HTML defaults and custom component support | `npm i @formhaus/react` |
 | `@formhaus/vue` | Vue 3 adapter with native HTML defaults and custom component support | `npm i @formhaus/vue` |
 
-There is also a Figma plugin (`@formhaus/figma`) that generates form mockups from form definitions. Available via `manifest.json` for now.
+`@formhaus/figma` generates form mockups on the Figma canvas from a form definition. Not on Figma Community yet, install as a local plugin via `packages/figma/manifest.json`.
 
-Svelte, Solid, or anything else: use `@formhaus/core` directly. See the [playground](https://formhaus.dev/playground) for an example.
+Svelte, Solid, or anything else: use `@formhaus/core` directly. The [playground](https://formhaus.dev/playground.html) has a Svelte example.
 
 ## Install
 
@@ -34,13 +34,13 @@ npm install @formhaus/react   # React
 npm install @formhaus/vue     # Vue
 ```
 
-Or use `@formhaus/core` directly with any framework. See the [Svelte example in the playground](/playground).
+Or use `@formhaus/core` directly with any framework. See the [Svelte example](https://formhaus.dev/playground.html).
 
 ## Quick Start
 
 ### Define a form
 
-You can write the JSON by hand or use the [Claude skill](.claude/skills/formhaus-create-form/SKILL.md) to generate it from a text description.
+Write the JSON by hand, or use the [`/formhaus-create-form`](https://formhaus.dev/guide/formhaus-create-form.html) Claude Code skill to generate it from a text description, a CSV table, or a screenshot of an existing form.
 
 ```json
 {
@@ -191,7 +191,7 @@ Each field component receives the full `FormField` descriptor, the current value
 
 ## Figma Plugin
 
-`@formhaus/figma` is a Figma plugin that takes a formhaus form definition and generates a styled form mockup directly on the canvas. Useful for rapid prototyping and design handoff.
+`@formhaus/figma` generates styled form mockups on the Figma canvas from a form definition. Map your design system components to field types via a `componentMap` that the [`/formhaus-figma-connect`](https://formhaus.dev/guide/formhaus-figma-connect.html) Claude Code skill can generate for you by scanning your Figma file. Not on Figma Community yet, install as a local plugin via `packages/figma/manifest.json`.
 
 ## Contributing
 
diff --git a/packages/core/README.md b/packages/core/README.md
@@ -0,0 +1,65 @@
+# @formhaus/core
+
+Framework-agnostic form engine. Types, validation, visibility, multi-step navigation, async step validation. Zero runtime dependencies, ESM-only.
+
+Part of [Formhaus](https://github.com/ignsm/formhaus). For React, use `@formhaus/react`. For Vue, use `@formhaus/vue`.
+
+## Install
+
+```bash
+npm install @formhaus/core
+```
+
+Requires Node ≥18.
+
+## Generating a definition
+
+Write the JSON by hand, or use the [`/formhaus-create-form`](https://formhaus.dev/guide/formhaus-create-form.html) Claude Code skill to generate it from a text description, a CSV table, or a screenshot of an existing form.
+
+## Usage
+
+```ts
+import { FormEngine, type FormDefinition } from '@formhaus/core';
+
+const definition: FormDefinition = {
+  id: 'contact',
+  title: 'Contact Us',
+  submit: { label: 'Send' },
+  fields: [
+    { key: 'name', type: 'text', label: 'Name', validation: { required: true } },
+    { key: 'email', type: 'email', label: 'Email', validation: { required: true } },
+  ],
+};
+
+const engine = new FormEngine(definition);
+
+engine.setValue('name', 'Jane');
+const errors = engine.validate();
+// { email: 'This field is required' }
+
+engine.setValue('email', 'jane@example.com');
+engine.validate();
+// {}
+
+engine.getSubmitValues();
+// { name: 'Jane', email: 'jane@example.com' }
+```
+
+## What it covers
+
+- Form state with reactive `subscribe()` / `getSnapshot()` for adapters
+- Field validation (required, min/max, pattern, matchField, custom validators)
+- Visibility conditions (`show` / `showAny`) with cascade-clearing of hidden values
+- Multi-step forms with conditional steps and per-step validation
+- Async step validation via `onStepValidate` + `nextStepAsync()`
+- Definition validation (duplicate keys, invalid regex, circular show conditions)
+
+## Docs
+
+- Full guide and API reference: https://formhaus.dev
+- Live playground: https://formhaus.dev/playground.html
+- Source and issues: https://github.com/ignsm/formhaus
+
+## License
+
+MIT
diff --git a/packages/figma/README.md b/packages/figma/README.md
@@ -0,0 +1,39 @@
+# @formhaus/figma
+
+Figma plugin that generates styled form mockups on the canvas from a [Formhaus](https://github.com/ignsm/formhaus) form definition. Maps your design system components to field types via a `componentMap`.
+
+Not published to the Figma Community yet. Install as a local plugin.
+
+## Install (local plugin)
+
+1. Clone the repo: `git clone https://github.com/ignsm/formhaus.git`
+2. Build the plugin: `cd formhaus && pnpm install && pnpm --filter @formhaus/figma build`
+3. In Figma desktop: **Plugins → Development → Import plugin from manifest...**
+4. Pick `packages/figma/manifest.json`
+
+## Usage
+
+1. Open a Figma file
+2. **Plugins → Development → Formhaus**
+3. Paste a Formhaus form definition JSON into the plugin UI
+4. Click **Generate**
+
+The plugin creates a frame per step with all fields rendered as instances of your mapped design system components. Buttons, step counters, and layout are set up automatically.
+
+## Component map
+
+The plugin ships with a default component map. To make it use your own design system, you need a JSON that maps each form field type (`text`, `select`, `checkbox`, etc.) to a Figma component key in your library.
+
+Writing that map by hand means digging through the Figma API for component keys. Instead, use the **[`/formhaus-figma-connect`](https://formhaus.dev/guide/formhaus-figma-connect.html) Claude skill**: it scans your Figma design system via MCP, auto-detects form components, shows screenshots for confirmation, and generates the full `componentMap` JSON. Copy the output, open the plugin's **Component Map** tab, paste, save. The plugin remembers the map across runs.
+
+If you don't use Claude Code, the full `ComponentMap` TypeScript interface lives in [`packages/figma/src/constants.ts`](https://github.com/ignsm/formhaus/blob/main/packages/figma/src/constants.ts). Paste a JSON that conforms to it.
+
+## Docs
+
+- Full Formhaus guide: https://formhaus.dev
+- Plugin guide: https://formhaus.dev/guide/figma.html
+- Source and issues: https://github.com/ignsm/formhaus
+
+## License
+
+MIT
diff --git a/packages/react/README.md b/packages/react/README.md
@@ -0,0 +1,71 @@
+# @formhaus/react
+
+React adapter for [Formhaus](https://github.com/ignsm/formhaus). Renders forms from a JSON definition with native HTML inputs by default. Drop in your own components via a `components` prop.
+
+## Install
+
+```bash
+npm install @formhaus/core @formhaus/react
+```
+
+Requires React ≥18 and Node ≥18.
+
+## Generating a definition
+
+Write the form JSON by hand, or use the [`/formhaus-create-form`](https://formhaus.dev/guide/formhaus-create-form.html) Claude Code skill to generate it from a text description, a CSV table, or a screenshot of an existing form.
+
+## Usage
+
+```tsx
+import { FormRenderer } from '@formhaus/react';
+import definition from './contact-form.json';
+
+export function ContactPage() {
+  async function handleSubmit(values: Record<string, unknown>) {
+    await fetch('/api/contact', {
+      method: 'POST',
+      body: JSON.stringify(values),
+    });
+  }
+
+  return <FormRenderer definition={definition} onSubmit={handleSubmit} />;
+}
+```
+
+## Custom components
+
+Swap native HTML for your own UI kit:
+
+```tsx
+import type { FieldComponentMap, FieldComponentProps } from '@formhaus/react';
+
+function MyInput({ field, value, error, onChange, onBlur }: FieldComponentProps) {
+  return (
+    <div>
+      <label>{field.label}</label>
+      <input
+        value={value as string}
+        onChange={(e) => onChange(e.target.value)}
+        onBlur={onBlur}
+      />
+      {error && <span className="error">{error}</span>}
+    </div>
+  );
+}
+
+const components: FieldComponentMap = { text: MyInput, email: MyInput };
+
+<FormRenderer definition={definition} onSubmit={handleSubmit} components={components} />;
+```
+
+Unmapped field types fall back to native HTML.
+
+## Docs
+
+- Full guide and API reference: https://formhaus.dev
+- Live playground: https://formhaus.dev/playground.html
+- Source and issues: https://github.com/ignsm/formhaus
+
+## License
+
+MIT
diff --git a/packages/vue/README.md b/packages/vue/README.md
@@ -0,0 +1,80 @@
+# @formhaus/vue
+
+Vue 3 adapter for [Formhaus](https://github.com/ignsm/formhaus). Renders forms from a JSON definition with native HTML inputs by default. Drop in your own components via a `components` prop.
+
+## Install
+
+```bash
+npm install @formhaus/core @formhaus/vue
+```
+
+Requires Vue ≥3.3 and Node ≥18.
+
+## Generating a definition
+
+Write the form JSON by hand, or use the [`/formhaus-create-form`](https://formhaus.dev/guide/formhaus-create-form.html) Claude Code skill to generate it from a text description, a CSV table, or a screenshot of an existing form.
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import { FormRenderer } from '@formhaus/vue';
+import definition from './contact-form.json';
+
+async function handleSubmit(values: Record<string, unknown>) {
+  await fetch('/api/contact', {
+    method: 'POST',
+    body: JSON.stringify(values),
+  });
+}
+</script>
+
+<template>
+  <FormRenderer :definition="definition" @submit="handleSubmit" />
+</template>
+```
+
+## Custom components
+
+Swap native HTML for your own UI kit:
+
+```vue
+<!-- MyInput.vue -->
+<script setup lang="ts">
+import type { FormFieldProps } from '@formhaus/vue';
+
+defineProps<FormFieldProps>();
+defineEmits<{ (e: 'update:value', value: unknown): void }>();
+</script>
+
+<template>
+  <div>
+    <label>{{ field.label }}</label>
+    <input
+      :value="value"
+      @input="$emit('update:value', ($event.target as HTMLInputElement).value)"
+    />
+    <span v-if="error">{{ error }}</span>
+  </div>
+</template>
+```
+
+```vue
+<FormRenderer
+  :definition="definition"
+  :components="{ text: MyInput, email: MyInput }"
+  @submit="handleSubmit"
+/>
+```
+
+Unmapped field types fall back to native HTML.
+
+## Docs
+
+- Full guide and API reference: https://formhaus.dev
+- Live playground: https://formhaus.dev/playground.html
+- Source and issues: https://github.com/ignsm/formhaus
+
+## License
+
+MIT
