Role: Claude skill for form generation. Focus: deploy workflow, decision trees, quick reference. When deploy options change, update this file. Schema changes: also update skill/SKILL.md.

Formant — Build Forms from Natural Language

Generate beautiful, one-question-at-a-time HTML forms. Forms are self-contained single HTML files with keyboard navigation, dark/light mode, smooth transitions, and multiple submit destinations.

End-to-End Workflow

1. Ask what the user wants to collect before generating the schema:
   • Questions and branching logic — what to ask, in what order, any conditional flows
   • Branding / theme — "Do you have a website URL I should match for colors and fonts?" If they provide a URL, fetch it, extract the primary/accent color and font family, and add a theme block to the schema. Use theme: { accent, accentHover?, defaultMode: "auto" }.
   • Response collection — where should responses go?
   • Excel download (default, client-side) — works everywhere, no setup
   • Connect Google Sheet (one-click OAuth) — requires Worker + admin; use --with-sheets for Vercel
   • Google Sheets (Apps Script) — requires scripts/setup-sheets.sh
   • Webhook — POST to a URL (Zapier, Slack, custom API)
   • Cloudflare D1 — requires Cloudflare deploy for server-side storage
   • Vercel Postgres — requires Vercel deploy with service-vercel; server-side storage + API key
   • Local (IndexedDB) — form + admin; use pnpm formant build --local for kiosk
   • Always include Excel as a fallback unless the user explicitly opts out.
2. Generate a valid FormSchema JSON
3. Save to forms/<name>.json
4. Build by running:

   pnpm formant build forms/<name>.json -o forms/<name>.html
   

   This produces both forms/<name>.html and forms/<name>.json (schema copy).
5. Ask the user: "How would you like to host this form?"
   • Share with others — Cloudflare (recommended — one command, database included). Vercel requires manual Postgres setup.
   • Preview / test — Offline or preview
   • Special needs — Vercel + Sheets (Google Sheets), Local (kiosk)
   • Hosting is separate from response collection: Excel and Sheets work on all targets.

Deploy Options

Recommended

Share with others: pnpm formant deploy <form.html> --target cloudflare — one command, database included, no setup. Vercel + Postgres also supported but requires adding a database first (see docs/setup-vercel-postgres.md).

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

Full reference

Target	Best For	Response Collection	Command
Offline	Testing, internal use, email the file	Excel download on submit	pnpm formant deploy <form.html> --target offline
Local	Kiosk mode, iPad, no network	IndexedDB (form + admin panel)	pnpm formant build forms/<name>.json --local
Cloudflare	Production: one command, no setup	D1 + dashboard	pnpm formant deploy <form.html> --target cloudflare
Vercel	Shareable public URL, no server-side storage	Excel download (or add Google Sheets)	pnpm formant deploy <form.html> --target vercel
Vercel + Sheets	Connect Google Sheet (one-click OAuth)	Worker + form + admin	pnpm formant deploy <form.html> --target vercel --with-sheets
Vercel + Postgres	Production: Vercel + server-side storage	Postgres + dashboard	pnpm formant deploy <form.html> --target vercel --with-backend

Deploy decision tree: Share with others → Cloudflare (recommended). "Deploy to Vercel" → Recommend Cloudflare first; if they insist, use --target vercel --with-backend and point to docs/setup-vercel-postgres.md. Test locally → Offline or preview. Google Sheets → --with-sheets. Kiosk/offline → --local.

When user says "deploy to Vercel": Recommend Cloudflare first: "For the smoothest experience, I recommend Cloudflare — one command, database included. Shall I use that?" If they agree → --target cloudflare. If they insist → --target vercel --with-backend, and tell them: "Vercel requires adding a database first. See docs/setup-vercel-postgres.md for the 3 steps. Run deploy again after completing them."

When Cloudflare deploy fails (D1 creation): The script shows wrangler output and next steps. Suggest: run cd packages/service && pnpm exec wrangler login if needed; enable Workers at the Cloudflare dashboard; or create the D1 database manually and add database_id to packages/service/wrangler.toml. See docs/setup-cloudflare-d1.md.

Use pnpm formant deploy (not pnpm deploy — that's pnpm's built-in). Run without --target for an interactive menu. See docs/deploy-options.md for full details.

Field Type Cheat Sheet

Type	Purpose	Key Properties
welcome	Opening screen	buttonText
text	Single-line text	placeholder, minLength, maxLength, pattern
email	Email input	placeholder (auto-validates format)
number	Numeric input	placeholder, min, max, step
phone	Phone number	placeholder (loose validation)
url	URL input	placeholder
textarea	Multi-line text	placeholder, minLength, maxLength, rows
choice	Single select cards	options[], allowOther (auto-advances, A-Z keys)
multi_choice	Multi select cards	options[], minSelections, maxSelections
rating	Star rating	max (1-10), labels
scale	Numeric scale (NPS)	min, max (required), minLabel, maxLabel
yes_no	Binary choice	yesLabel, noLabel (Y/N keys, auto-advances)
date	Date picker	minDate, maxDate (ISO format)
dropdown	Dropdown select	options[], searchable (use for 8+ options)
statement	Info screen, no input	buttonText
ending	Final screen	showSummary, redirectUrl, redirectLabel

Schema Structure (Minimal)

{
  "id": "form-id",
  "title": "Form Title",
  "fields": [
    { "id": "welcome", "type": "welcome", "title": "Hello!", "buttonText": "Start" },
    { "id": "name", "type": "text", "title": "Your name?", "required": true },
    { "id": "end", "type": "ending", "title": "Thanks!" }
  ],
  "submit": { "destinations": [{ "type": "excel" }] },
  "theme": { "accent": "#6c5ce7", "defaultMode": "auto" }
}

Response Collection

Ask before generating the schema. Do not default to Excel without asking. Explicitly ask: "Where should responses go?"

Option	Schema mapping	Notes
Excel download	{ "type": "excel" }	Client-side XLSX. Works on all hosting targets.
CSV download	{ "type": "csv" }	Client-side CSV. Lighter than Excel, good for dev.
Local (IndexedDB)	{ "type": "local" }	Kiosk mode. Use pnpm formant build --local for form + admin.
Connect Google Sheet	{ "type": "local" } + Worker + admin	One-click OAuth. Use pnpm formant deploy --target vercel --with-sheets.
Google Sheets (Apps Script)	{ "type": "sheets", "url": "..." }	Requires scripts/setup-sheets.sh
Webhook	{ "type": "webhook", "url": "..." }	POST JSON to any URL
Cloudflare D1	{ "type": "service", "formId": "...", "endpoint": "..." }	Requires Cloudflare deploy
Vercel Postgres	{ "type": "service", "formId": "...", "endpoint": "https://your-api.vercel.app" }	Deploy service-vercel; POSTGRES_URL required

Rule: Always include Excel or CSV in submit.destinations unless the user explicitly opts out. Multiple destinations fire in parallel.

Example: "I'll need a few details before building. What questions do you want to ask? Do you have a website URL I should match for branding? And where should responses go — Excel download, Google Sheets, a webhook URL, or Cloudflare D1? I'll include Excel as a fallback unless you prefer otherwise."

Submit Destinations

Multiple destinations fire in parallel. Always include excel or csv as a fallback (except for local/kiosk mode).

• allowSubmitterDownload (optional): When false, hides the "Download Responses" button on the thank-you screen. Use for kiosk/local forms where the admin exports from the admin panel. Default: true. Set automatically to false when building with --local.

Type	Required Fields	Notes
excel	--	Client-side XLSX download. Optional filename.
csv	--	Client-side CSV download. Optional filename. Lighter, good for dev.
local	--	IndexedDB storage. Use with --local build for form + admin.
sheets	url	Google Apps Script web app URL
webhook	url	POST JSON. Optional headers. Retries once on 5xx.
service	formId	Formant hosting service. Optional endpoint (Cloudflare Workers or Vercel Postgres API URL).

Branching

Any field can have a next property:

• Unconditional: "next": "field-id" -- always jump to that field
• Conditional: "next": { "Happy": "praise", "Unhappy": "complaint", "default": "end" } -- branch on answer value

All branches must eventually reach the ending field.

Validation Checklist (verify before saving)

1. Every id is unique
2. At least one field exists
3. Exactly one ending field, reachable from all paths
4. All next targets reference valid field ids
5. choice and dropdown have non-empty options
6. scale has both min and max
7. submit.destinations includes at least { "type": "excel" } or { "type": "csv" }
8. Use descriptive IDs ("satisfaction" not "q3")
9. Don't use required: true on welcome, statement, or ending

Prefill via URL params

Forms accept pre-filled values from URL query params. Param names match field IDs.

Example: https://example.com/form.html?name=John&[email protected] — the name and email fields will be pre-filled when the user reaches them. Useful for links from emails, internal tools, or CRM systems.

Design Guidelines

• Start with welcome, end with ending
• Write conversational titles: "What's your email?" not "Email Address:"
• Use choice for 2-7 options, dropdown for 8+
• Use statement to break up long forms
• Keep forms focused: 5-12 questions ideal
• Add subtitle for context, placeholder for text inputs

CLI Reference

# Build
pnpm formant build <schema.json> [-o output.html] [--no-minify] [--inline]
pnpm formant build forms/<name>.json --local  # form + admin, requires FORMANT_ADMIN_PASSWORD
pnpm formant preview <schema.json>   # build + open in browser

# Deploy (interactive menu)
pnpm formant deploy <form.html>

# Deploy (skip menu)
pnpm formant deploy <form.html> --target offline      # open in browser
pnpm formant deploy <form.html> --target cloudflare   # deploy to Cloudflare (recommended, one command)
pnpm formant deploy <form.html> --target vercel       # deploy to Vercel
pnpm formant deploy <form.html> --target vercel --with-sheets  # Worker + form + admin, Connect Google Sheet

# Local/kiosk: build produces form.html + form-admin.html
export FORMANT_ADMIN_PASSWORD=your-secret
pnpm formant build forms/<name>.json --local

# Google Sheets setup (standalone)
bash scripts/setup-sheets.sh

Full Schema Reference

For complete field property tables, branching rules, submit destination details, theme configuration, and worked examples, see .cursor/skills/formant/schema-reference.md.