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

{
  "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:

#### welcome — Opening screen

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

#### text — Single-line text input

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

#### email — Email input

Validates email format automatically.

#### number — Numeric input

#### phone — Phone number input

Loose validation — accepts international formats.

#### url — URL input

#### textarea — Multi-line text

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

#### choice — Single select from options

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

#### multi_choice — Multiple select

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

#### rating — Star rating

Number keys 1–N select the rating.

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

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

#### yes_no — Binary choice

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

#### date — Date picker

Native date input styled to match the theme.

#### dropdown — Dropdown select

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

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

Displays a message without collecting input. No question number.

#### ending — Final screen

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:

{ "id": "q1", "type": "text", "title": "...", "next": "q5" }

Conditional branching — go to different fields based on the answer:

{
  "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 ids 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.

"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" }
  ]
}

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:

{
  "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

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

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.

1. 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 ids
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:

~~~

{
  "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

{
  "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": "[email protected]",
      "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

{
  "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

{
  "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

{
  "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": "[email protected]" },
    { "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

{
  "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:

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:

"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:

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