Skip to content
FileKindSize
SKILL.mdskill md24.5 KB
examples/.gitkeepother0 B
examples/product-feedback.htmlother48.1 KB
examples/product-feedback.jsonconfig2.4 KB
# Formant — Form Generation Skill

> **Role:** Full schema reference. Used by Claude Artifacts, docs, or other tools needing detailed FormSchema info. When schema/field types change, update this file. Deploy changes: also update `.cursor/skills/formant/SKILL.md`.

> Generate beautiful, interactive single-file HTML forms from natural language descriptions.

## What This Skill Does

You help users create forms by generating a **FormSchema** JSON object. The schema is then compiled into a self-contained `.html` file using the Formant build tool. The generated forms have a modern Typeform/Vercel aesthetic — minimal, clean, one-question-at-a-time flow with keyboard navigation, dark/light mode, and smooth transitions.

## Workflow

1. **Understand** what the user wants to collect (questions, branching logic, branding URL if any, where responses should go). Ask: *"Do you have a website URL I should match for colors and fonts?"* If provided, fetch the URL and extract primary color + font for the `theme` block.
2. **Generate** a valid FormSchema JSON
3. **Output** the schema in a fenced JSON code block

The user runs the schema through `buildFormHTML(schema)` (from `@formant/html-builder`) to produce a standalone HTML file.

---

## FormSchema Reference

### Top-Level Structure

```json
{
  "id": "unique-form-id",
  "title": "Human-readable form title",
  "fields": [ /* ordered array of Field objects */ ],
  "submit": {
    "destinations": [ /* where responses are sent */ ],
    "successMessage": "Optional override for the ending screen"
  },
  "theme": {
    "accent": "#6c5ce7",
    "accentHover": "#5a4bd1",
    "radius": "10px",
    "defaultMode": "auto"
  },
  "meta": {
    "createdAt": "2026-02-14T00:00:00Z",
    "createdBy": "claude",
    "version": 1
  }
}
```

**Required:** `id`, `fields`
**Optional:** `title`, `submit`, `theme`, `meta`

### Field Types

Every field has these base properties:

| Property   | Type                              | Required | Description |
|------------|-----------------------------------|----------|-------------|
| `id`       | `string`                          | yes      | Unique identifier, used as the answer key |
| `type`     | `FieldType`                       | yes      | One of the types below |
| `title`    | `string`                          | yes      | The question text shown to the user |
| `subtitle` | `string`                          | no       | Helper text below the title |
| `required` | `boolean`                         | no       | Default `false`. If `true`, user must answer before advancing |
| `next`     | `string \| Record<string, string>` | no       | Branching — see Branching Logic section |

#### `welcome` — Opening screen

| Property     | Type     | Default      |
|--------------|----------|--------------|
| `buttonText` | `string` | `"Start"`    |

No question number shown. Large centered title + subtitle + CTA button.

#### `text` — Single-line text input

| Property      | Type     | Description |
|---------------|----------|-------------|
| `placeholder` | `string` | Input placeholder text |
| `minLength`   | `number` | Minimum character count |
| `maxLength`   | `number` | Maximum character count |
| `pattern`     | `string` | Regex validation pattern |

Also used as the base for `email`, `phone`, and `url` inputs which share the same UI.

#### `email` — Email input

| Property      | Type     | Description |
|---------------|----------|-------------|
| `placeholder` | `string` | e.g. `"you@example.com"` |

Validates email format automatically.

#### `number` — Numeric input

| Property      | Type     | Description |
|---------------|----------|-------------|
| `placeholder` | `string` | Input placeholder |
| `min`         | `number` | Minimum value |
| `max`         | `number` | Maximum value |
| `step`        | `number` | Step increment |

#### `phone` — Phone number input

| Property      | Type     | Description |
|---------------|----------|-------------|
| `placeholder` | `string` | e.g. `"+1 (555) 000-0000"` |

Loose validation — accepts international formats.

#### `url` — URL input

| Property      | Type     | Description |
|---------------|----------|-------------|
| `placeholder` | `string` | e.g. `"https://example.com"` |

#### `textarea` — Multi-line text

| Property      | Type     | Description |
|---------------|----------|-------------|
| `placeholder` | `string` | Placeholder text |
| `minLength`   | `number` | Minimum character count |
| `maxLength`   | `number` | Maximum character count |
| `rows`        | `number` | Visible row count |

Shows an "OK" button since Enter creates newlines in textareas.

#### `choice` — Single select from options

| Property     | Type       | Description |
|--------------|------------|-------------|
| `options`    | `string[]` | **Required.** List of choices |
| `allowOther` | `boolean`  | Allow free-text "Other" option |

Cards with letter-key shortcuts (A, B, C...). Auto-advances 300ms after selection. Best for branching.

#### `multi_choice` — Multiple select

| Property        | Type       | Description |
|-----------------|------------|-------------|
| `options`       | `string[]` | **Required.** List of choices |
| `minSelections` | `number`   | Minimum selections required |
| `maxSelections` | `number`   | Maximum selections allowed |

Checkbox-style cards. No auto-advance — shows a "Continue" button.

#### `rating` — Star rating

| Property | Type                    | Description |
|----------|-------------------------|-------------|
| `max`    | `number`                | Number of stars (1–10, default `5`) |
| `labels` | `Record<number, string>` | Labels for specific values, e.g. `{ "1": "Poor", "5": "Excellent" }` |

Number keys 1–N select the rating.

#### `scale` — Numeric scale (e.g. NPS)

| Property   | Type     | Description |
|------------|----------|-------------|
| `min`      | `number` | **Required.** Scale minimum (usually `0` or `1`) |
| `max`      | `number` | **Required.** Scale maximum (usually `5` or `10`) |
| `minLabel` | `string` | Label at the low end |
| `maxLabel` | `string` | Label at the high end |

Number buttons in a horizontal row. Keys 0–9 select values.

#### `yes_no` — Binary choice

| Property   | Type     | Default   |
|------------|----------|-----------|
| `yesLabel` | `string` | `"Yes"`   |
| `noLabel`  | `string` | `"No"`    |

Two large side-by-side cards. Y/N keyboard shortcuts. Auto-advances after selection.

#### `date` — Date picker

| Property  | Type     | Description |
|-----------|----------|-------------|
| `minDate` | `string` | Earliest allowed date (ISO format) |
| `maxDate` | `string` | Latest allowed date (ISO format) |

Native date input styled to match the theme.

#### `dropdown` — Dropdown select

| Property     | Type       | Description |
|--------------|------------|-------------|
| `options`    | `string[]` | **Required.** List of options |
| `searchable` | `boolean`  | Enable type-to-filter |

Use when there are too many options for choice cards (roughly > 7 options).

#### `statement` — Informational screen (no input)

| Property     | Type     | Default        |
|--------------|----------|----------------|
| `buttonText` | `string` | `"Continue →"` |

Displays a message without collecting input. No question number.

#### `ending` — Final screen

| Property        | Type      | Description |
|-----------------|-----------|-------------|
| `showSummary`   | `boolean` | Show a summary of all answers |
| `redirectUrl`   | `string`  | URL to redirect to |
| `redirectLabel` | `string`  | Text for the redirect link |

**Every form must have exactly one `ending` field as the last reachable field.** It displays a checkmark animation, the title/subtitle, and optionally a summary of responses.

---

### Branching Logic

The `next` property on any field controls where the form goes after that question.

**Unconditional jump** — always go to a specific field:
```json
{ "id": "q1", "type": "text", "title": "...", "next": "q5" }
```

**Conditional branching** — go to different fields based on the answer:
```json
{
  "id": "satisfaction",
  "type": "choice",
  "title": "How satisfied are you?",
  "options": ["Happy", "Neutral", "Unhappy"],
  "next": {
    "Happy": "praise-detail",
    "Neutral": "suggestion",
    "Unhappy": "complaint-detail",
    "default": "end"
  }
}
```

The `"default"` key is the fallback if the answer doesn't match any key. If `next` is omitted entirely, the form advances to the next field in array order.

**Rules:**
- All `next` target values must be valid `id`s of other fields in the schema
- Branching targets should eventually reach an `ending` field
- Back navigation follows the user's actual path (history stack), not the array order

---

### Submit Destinations

Configure where form responses are sent. **Multiple destinations fire in parallel** using `Promise.allSettled` — one destination failing does not block others. The ending screen shows status feedback:

- **All succeed:** Green "Responses submitted successfully" message
- **Some fail:** Warning "Some destinations were unreachable" with details
- **All fail:** Error state with "Download Responses" as a prominent fallback

A **"Download Responses"** button is always visible on the ending screen regardless of success/failure.

```json
"submit": {
  "destinations": [
    { "type": "excel", "filename": "my-responses" },
    { "type": "sheets", "url": "https://script.google.com/macros/s/.../exec" },
    { "type": "webhook", "url": "https://hooks.example.com/abc", "headers": { "Authorization": "Bearer token" } },
    { "type": "service", "formId": "abc123" }
  ]
}
```

| Type      | Required Fields | Description |
|-----------|-----------------|-------------|
| `excel`   | —               | Client-side XLSX download. `filename` is optional. |
| `sheets`  | `url`           | POST to a Google Apps Script web app URL |
| `webhook` | `url`           | POST JSON to any URL. Optional `headers`. Retries once on 5xx with 1s delay. 10s timeout. |
| `service` | `formId`        | POST to the Formant hosting service. Optional `endpoint` for Cloudflare Workers or Vercel Postgres API. |

**Default recommendation:** Always include `{ "type": "excel" }` as a fallback so the user can always download their responses even if other destinations fail.

#### Webhook Details

The `webhook` destination sends a `POST` request with the full `FormResponse` JSON:

```json
{
  "formId": "my-form",
  "status": "completed",
  "submittedAt": "2026-02-14T12:00:00.000Z",
  "answers": { "name": "Alice", "rating": 5 },
  "metadata": { "userAgent": "...", "duration": 120, "completionRate": 100 }
}
```

- **Custom headers:** Use `headers` to add authentication tokens, API keys, or any custom headers
- **Retry:** Automatically retries once with a 1-second delay on 5xx server errors
- **Timeout:** 10-second fetch timeout per attempt
- **Use cases:** Zapier, Make.com, Slack incoming webhooks, custom APIs, n8n, Pipedream

---

### Theme Configuration

```json
"theme": {
  "accent": "#6c5ce7",
  "accentHover": "#5a4bd1",
  "radius": "10px",
  "defaultMode": "auto"
}
```

| Property      | Default     | Description |
|---------------|-------------|-------------|
| `accent`      | `#6c5ce7`   | Primary accent color (buttons, selections, progress bar) |
| `accentHover` | `#5a4bd1`   | Hover state for accent. Auto-derived if omitted. |
| `radius`      | `10px`      | Border radius for cards and inputs |
| `defaultMode` | `auto`      | `"auto"` (system preference), `"dark"`, or `"light"` |

All forms include a manual dark/light toggle regardless of `defaultMode`.

---

## How to Generate a Form

### Step 1 — Ask Clarifying Questions

Before generating, make sure you understand:

1. **Purpose** — What is this form for? (feedback, survey, registration, quiz, etc.)
2. **Fields** — What information to collect? What question types fit best?
3. **Logic** — Any conditional branching? ("If they answer X, ask Y")
4. **Branding** — *"Do you have a website URL I should match for colors and fonts?"* If provided, fetch the URL, extract primary/accent color and font, and add a `theme` block.
5. **Destinations** — Where should responses go? Ask: *"Where should responses be sent?"*
   - **Excel download** (always include as fallback) — works offline, no setup
   - **Google Sheets** — requires a deployed Apps Script URL (see SETUP.md)
   - **Webhook** — any URL that accepts POST JSON. Supports custom headers for auth. Great for Zapier, Slack, Make.com, n8n, or custom APIs.
   - **Formant service** — hosted collection with export. Requires API key + deployment (Cloudflare D1 or Vercel Postgres).
   - Users can pick **multiple destinations** — all fire in parallel.
6. **Tone** — Formal or casual? This affects title/subtitle wording.

If the user gives a vague request like "make me a feedback form", use sensible defaults (at minimum `excel`) and explain your choices.

### Step 2 — Design the Schema

Follow these guidelines:

- **Start with a `welcome` field** — sets the tone and gives context
- **End with an `ending` field** — provides closure and optionally shows a summary
- **Use `required: true`** for essential fields; leave optional fields without it
- **Use `choice` for 2–7 options**, `dropdown` for 8+ options
- **Use `statement` fields** to break up long forms with context or encouragement
- **Keep forms focused** — 5–12 questions is ideal. Longer forms should use branching to skip irrelevant sections.
- **Use descriptive `id` values** — e.g. `"satisfaction-rating"` not `"q3"`. These become answer keys.
- **Write conversational titles** — "What's your email?" not "Email Address:"
- **Add `subtitle`** for context on complex questions
- **Add `placeholder`** for text inputs to guide the expected format

### Step 3 — Validate Your Schema

Before outputting, mentally verify:

1. Every `id` is unique across all fields
2. At least one field exists
3. Exactly one `ending` field exists and is reachable
4. All `next` targets reference valid field `id`s
5. All branching paths eventually reach the `ending`
6. `choice` and `dropdown` fields have non-empty `options` arrays
7. `scale` fields have both `min` and `max`
8. `submit.destinations` array is present (include at least `excel`)

### Step 4 — Output the Schema

Output the complete FormSchema as a JSON code block:

~~~
```json
{
  "id": "my-form",
  "title": "My Form Title",
  "fields": [ ... ],
  "submit": { "destinations": [{ "type": "excel" }] }
}
```
~~~

Then tell the user:
> Save this as a `.json` file and run it through the Formant builder to generate your HTML form:
> ```ts
> import { buildFormHTML } from "@formant/html-builder";
> import schema from "./my-form.json";
> const html = buildFormHTML(schema);
> ```

---

## Complete Example — Product Feedback Form

```json
{
  "id": "product-feedback",
  "title": "Product Feedback",
  "fields": [
    {
      "id": "welcome",
      "type": "welcome",
      "title": "We'd love your feedback",
      "subtitle": "Takes about 2 minutes. Your responses help us improve.",
      "buttonText": "Get Started"
    },
    {
      "id": "name",
      "type": "text",
      "title": "What's your name?",
      "placeholder": "Type your name...",
      "required": true
    },
    {
      "id": "email",
      "type": "email",
      "title": "What's your email?",
      "subtitle": "We'll only use this to follow up if needed.",
      "placeholder": "you@example.com",
      "required": true
    },
    {
      "id": "role",
      "type": "choice",
      "title": "What best describes your role?",
      "options": ["Developer", "Designer", "Product Manager", "Executive", "Other"],
      "allowOther": true
    },
    {
      "id": "satisfaction",
      "type": "rating",
      "title": "How satisfied are you with the product?",
      "required": true,
      "max": 5,
      "labels": { "1": "Very poor", "3": "Okay", "5": "Excellent" }
    },
    {
      "id": "recommend",
      "type": "scale",
      "title": "How likely are you to recommend us?",
      "min": 0,
      "max": 10,
      "minLabel": "Not at all likely",
      "maxLabel": "Extremely likely"
    },
    {
      "id": "favorite-feature",
      "type": "choice",
      "title": "What's your favorite feature?",
      "options": ["Speed", "Design", "Reliability", "Integrations", "Support"],
      "next": {
        "Support": "support-detail",
        "default": "improvements"
      }
    },
    {
      "id": "support-detail",
      "type": "textarea",
      "title": "Tell us about your support experience",
      "subtitle": "What went well? What could be better?",
      "placeholder": "Share your experience...",
      "next": "improvements"
    },
    {
      "id": "improvements",
      "type": "textarea",
      "title": "What would you most like us to improve?",
      "placeholder": "Your suggestions..."
    },
    {
      "id": "use-again",
      "type": "yes_no",
      "title": "Would you use this product again?"
    },
    {
      "id": "end",
      "type": "ending",
      "title": "Thank you!",
      "subtitle": "Your feedback is incredibly valuable to us.",
      "showSummary": true
    }
  ],
  "submit": {
    "destinations": [
      { "type": "excel", "filename": "product-feedback" }
    ]
  },
  "theme": {
    "accent": "#6c5ce7"
  }
}
```

This form:
- Starts with a friendly welcome screen
- Collects identity (name, email) and role
- Gets quantitative feedback (rating, NPS scale)
- Branches to a support-specific question if the user picks "Support"
- Collects open-ended improvement suggestions
- Ends with a summary of all answers
- Downloads responses as an Excel file

---

## Common Patterns

### Quick 3-Question Survey
```json
{
  "id": "quick-survey",
  "title": "Quick Survey",
  "fields": [
    { "id": "welcome", "type": "welcome", "title": "Quick question for you", "buttonText": "Sure" },
    { "id": "rating", "type": "rating", "title": "How's your experience so far?", "max": 5, "required": true },
    { "id": "comment", "type": "textarea", "title": "Anything else?", "placeholder": "Optional..." },
    { "id": "end", "type": "ending", "title": "Thanks!", "subtitle": "Appreciate your time." }
  ],
  "submit": { "destinations": [{ "type": "excel" }] }
}
```

### NPS Survey with Branching
```json
{
  "id": "nps",
  "title": "NPS Survey",
  "fields": [
    { "id": "welcome", "type": "welcome", "title": "One quick question" },
    {
      "id": "score", "type": "scale", "title": "How likely are you to recommend us to a friend?",
      "min": 0, "max": 10, "minLabel": "Not likely", "maxLabel": "Very likely", "required": true
    },
    { "id": "why", "type": "textarea", "title": "What's the main reason for your score?", "placeholder": "Tell us more..." },
    { "id": "end", "type": "ending", "title": "Thank you!", "showSummary": true }
  ],
  "submit": { "destinations": [{ "type": "excel", "filename": "nps-responses" }] }
}
```

### Event Registration
```json
{
  "id": "event-registration",
  "title": "Event Registration",
  "fields": [
    { "id": "welcome", "type": "welcome", "title": "Register for TechConf 2026", "subtitle": "March 15 · San Francisco", "buttonText": "Register" },
    { "id": "name", "type": "text", "title": "Full name", "required": true, "placeholder": "Jane Smith" },
    { "id": "email", "type": "email", "title": "Email address", "required": true, "placeholder": "jane@company.com" },
    { "id": "company", "type": "text", "title": "Company", "placeholder": "Acme Inc." },
    { "id": "role", "type": "dropdown", "title": "Your role", "options": ["Engineer", "Designer", "PM", "Executive", "Student", "Other"], "searchable": false },
    { "id": "dietary", "type": "choice", "title": "Dietary preference", "options": ["No restrictions", "Vegetarian", "Vegan", "Gluten-free", "Other"], "allowOther": true },
    { "id": "sessions", "type": "multi_choice", "title": "Which sessions interest you?", "options": ["Keynote", "AI Workshop", "Design Systems", "DevOps Deep Dive", "Networking Lunch"], "minSelections": 1 },
    { "id": "end", "type": "ending", "title": "You're registered!", "subtitle": "We'll send confirmation to your email.", "showSummary": true }
  ],
  "submit": { "destinations": [{ "type": "excel", "filename": "event-registrations" }] }
}
```

### Multi-Destination Feedback with Webhook + Sheets

```json
{
  "id": "multi-dest-feedback",
  "title": "Customer Feedback",
  "fields": [
    { "id": "welcome", "type": "welcome", "title": "Quick feedback?", "buttonText": "Sure" },
    { "id": "satisfaction", "type": "rating", "title": "How satisfied are you?", "max": 5, "required": true },
    { "id": "comment", "type": "textarea", "title": "Anything you'd like to share?", "placeholder": "Optional..." },
    { "id": "end", "type": "ending", "title": "Thank you!", "subtitle": "Your feedback has been recorded." }
  ],
  "submit": {
    "destinations": [
      { "type": "sheets", "url": "https://script.google.com/macros/s/.../exec" },
      { "type": "webhook", "url": "https://hooks.zapier.com/hooks/catch/123/abc/", "headers": { "X-Source": "formant" } },
      { "type": "excel", "filename": "customer-feedback" }
    ]
  }
}
```

This form sends responses to Google Sheets and Zapier simultaneously, with Excel download as a fallback. If Zapier is down, Sheets still receives the data (and vice versa).

---

## CLI Deploy (Quick Reference)

**Share with others:** `pnpm formant deploy <form.html> --target vercel --with-backend` or `--target cloudflare` — shareable URL, server-side storage, dashboard.

**Preview locally:** `pnpm formant deploy <form.html> --target offline` or `pnpm formant preview <schema.json>`.

**Other options:** Vercel + Sheets (Connect Google Sheet), Local (kiosk). See `docs/deploy-options.md` for full reference.

---

## Deploying to the Formant Service

After generating a form, you can offer to deploy it to a live URL using the Formant hosting service.

### How Deployment Works

1. The user provides an **API key** (any string — recommend a UUID v4). This key is used to manage the form and access responses.
2. You generate the HTML using `buildFormHTML(schema)`.
3. POST the HTML and schema to the Formant service API.
4. The service returns a **live URL** where the form is publicly accessible.
5. Responses submitted through the form are automatically collected by the service.

### Deployment Flow

```
After generating a form, ask the user:

"Would you like me to deploy this to a live URL?
You'll need an API key — any secret string will do (I recommend a UUID like `a1b2c3d4-e5f6-7890-abcd-ef1234567890`)."
```

Once the user provides their API key and the Formant service endpoint:

```ts
import { buildFormHTML } from "@formant/html-builder";

// 1. Build the HTML
const html = buildFormHTML(schema);

// 2. Deploy to the service
const response = await fetch("https://<formant-service-url>/api/forms", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <user-api-key>"
  },
  body: JSON.stringify({ html, schema })
});

const { id, url } = await response.json();
// url is "/f/<id>" — the live form URL
```

Then present:
> **Your form is live at:** `https://<formant-service-url>/f/<id>`
>
> Responses are being collected automatically. To view or export them, use the same API key.

### Including Service as a Submit Destination

When deploying, add the service as a submit destination so responses are collected automatically:

```json
"submit": {
  "destinations": [
    {
      "type": "service",
      "formId": "<generated-form-id>",
      "endpoint": "https://<formant-service-url>"
    },
    { "type": "excel", "filename": "my-responses" }
  ]
}
```

**Note:** Always keep `excel` as a fallback destination, so users can download responses even if the service is unreachable.

### Managing Deployed Forms

All management endpoints require the same API key used to create the form:

| Action | Method | Endpoint |
|--------|--------|----------|
| View responses | `GET` | `/api/responses/<formId>?limit=100&offset=0` |
| Export as Excel | `GET` | `/api/responses/<formId>/xlsx` |
| Delete form | `DELETE` | `/api/forms/<formId>` |

All requests need `Authorization: Bearer <api-key>` header.

---

## Do NOT

- **Generate field IDs like `q1`, `q2`** — use descriptive names (`"satisfaction"`, `"email"`, `"favorite-feature"`)
- **Forget the `ending` field** — every form must end with one
- **Use `choice` for long lists** — switch to `dropdown` for 8+ options
- **Hardcode colors** — use the `theme.accent` property instead
- **Skip `submit.destinations`** — always include at least `{ "type": "excel" }`
- **Create orphan branches** — every path through the form must reach the `ending`
- **Use `required: true` on `welcome`, `statement`, or `ending`** — these have no input to validate
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall