From cdfdcebe24e3a0f71822b02ffa8300534b2ee6fa Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 20 Apr 2026 10:49:46 +0000 Subject: [PATCH 1/8] docs(studio): add design handoff for original Studio redesign Non-leading handoff document that explains Formspec Studio as a product ("ChatGPT for forms" conceptual frame), its audiences, and the full capability surface without prescribing layout, screens, or interaction patterns. Written for a designer producing a net-new design from first principles. --- .../2026-04-20-studio-design-handoff.md | 405 ++++++++++++++++++ 1 file changed, 405 insertions(+) create mode 100644 thoughts/studio/2026-04-20-studio-design-handoff.md diff --git a/thoughts/studio/2026-04-20-studio-design-handoff.md b/thoughts/studio/2026-04-20-studio-design-handoff.md new file mode 100644 index 00000000..fe048cc5 --- /dev/null +++ b/thoughts/studio/2026-04-20-studio-design-handoff.md @@ -0,0 +1,405 @@ +# Formspec Studio — Design Handoff + +**Date:** 2026-04-20 +**Status:** Handoff for an original design pass — no current-design constraints +**Audience:** Designer producing a net-new Studio design from first principles + +--- + +## 0. Read this first + +This document explains what Formspec Studio is, who uses it, and what it has to do. It does **not** tell you how to design it. Every screen layout, panel arrangement, nav pattern, and interaction model is yours to invent. The current Studio codebase shipped a working design — that design is a reference point for *what the product does*, not a constraint on *how it should look or feel*. Assume you are designing from zero. + +The goal is an original design that fits the product described below. If after reading this you think the product should be structured differently from how today's Studio structures it, say so — the conceptual frame ("ChatGPT for forms") is new enough that the right IA is an open question. + +--- + +## 1. What Formspec is (30-second version) + +Formspec is a **JSON-native specification for complex forms** — tax returns, grant applications, clinical intake, insurance claims, regulatory filings, safety inspections. Not contact forms. Not surveys. Forms with hundreds of fields, conditional sections, cascading calculations, cross-field validation, multi-format output, and offline requirements. + +A Formspec form is a set of JSON documents: + +- **Definition** — the data model: fields, types, structure, validation rules, calculations, conditional logic +- **Theme** — presentation tokens, widget catalog, page layout +- **Component** — interaction widgets, slot binding, responsive design +- **Mapping** — bidirectional transforms to JSON / XML / CSV for downstream systems + +Plus optional sidecars (Locale, References, Ontology, Registry, Changelog, Assist) that most authors will never touch directly. + +The same JSON definition renders identically on web, React, iOS, and server. The same validation runs in the browser and on the backend. The same calculations produce the same decimal-exact numbers offline on a tablet and on a cloud server. + +Formspec is a **specification**, not a platform. There is no hosted service. Form definitions are JSON files that authors own. + +--- + +## 2. What Studio is + +Studio is the **authoring environment** for Formspec. It is where someone sits down to build a form and leaves with a valid set of JSON documents. It is a single-page web application; it is not a SaaS; it is the reference implementation of what authoring should feel like. + +Studio has to serve two overlapping jobs: + +1. **Visual authoring** — direct manipulation of every tier: definition, component, theme, mapping. Every structural change, rule, token, and transform is editable. Undo, redo, import, export are table stakes. Every mutation flows through a typed command catalog so the edit history is auditable and reversible. + +2. **AI-assisted authoring** — a conversational collaborator that can build, modify, refine, and reason about the form alongside the author. The AI calls into the same typed command catalog as the human. Nothing the AI does is unreviewable, un-undoable, or magical. + +Studio is not a form-filling tool. End users of the form never see Studio. Studio's output is the JSON documents; those get deployed into any runtime (web component, React, iOS, server) for end users to fill. + +### The conceptual frame: "ChatGPT for forms" + +The short internal pitch for Studio is **"ChatGPT for forms"**. Take that seriously as a framing device, not as a literal UI pattern: + +- A non-technical author describes the form they need in plain language. The system produces a validated first draft. +- The author reviews, refines, and corrects — through conversation, through direct manipulation, or both. +- The author's role is **oversight and judgement**, not line-by-line construction. +- Every AI action is reviewable. The author can always see what changed, why, and undo it. +- The underlying artifacts (JSON documents) stay human-readable. There is no black box. + +The frame implies a product where *conversation is a first-class authoring surface*, not a side panel bolted onto a traditional form builder. How strongly you lean into that is a design decision. You could design Studio as "chat is the whole interface, with a live preview", or "chat and visual editing are equal peers", or "visual editing is primary with chat as an accelerator". Any of those are defensible — the current implementation leans toward the third, but nothing forces that choice. + +Note: the current codebase ships **two separate chat surfaces** — one embedded in the editor (refines the live project via tool calls), one standalone (conversational intake that scaffolds a form, then hands off to the editor). The fact that there are two is an implementation artifact, not a product requirement. A unified design is welcome. + +--- + +## 3. Who uses Studio + +The primary audience is **non-technical form authors** — the people who today file tickets with IT to get a form built, or spend months going back and forth with developers. They understand their domain (grants, eligibility, clinical intake, inspections, compliance) deeply. They do not write code. Many have used Google Forms, Typeform, SurveyMonkey, or REDCap; fewer have used ODK or a real expression language. + +A secondary audience is **developers and form engineers** who will edit the JSON directly, tune FEL expressions, write mapping rules, and integrate the output into their stack. Studio should stay legible to them, but the primary reader of the screen is the domain expert, not the engineer. + +The authors typically work in these settings: + +- **Government program staff** — benefits eligibility, permitting, tax, licensing. Risk-averse, compliance-sensitive, long procurement cycles, Section 508 / WCAG expectations. +- **Nonprofit and grant operations** — grant applications, reports, compliance submissions. Often small teams; one person wears many hats. +- **Clinical and health intake** — patient questionnaires, screening tools, referrals. Coded vocabularies (ICD-10, SNOMED, LOINC) matter. +- **Insurance and financial services** — claims, applications, underwriting. Calculation correctness and audit trails are non-negotiable. +- **Field inspection and compliance** — safety checklists, site surveys. Offline is not optional. + +These authors share a few traits that shape the design: + +- They are accountable for the form being correct. A calculation error is their problem. +- They iterate a lot. Rules change mid-cycle. Wording gets tweaked. New sections appear. +- They do not read docs. They expect the tool to teach them by being legible. +- They are used to forms being second-class citizens in whatever tool they have. They will be surprised by good tooling. +- They do not think in terms of "definition vs. theme vs. component" — they think in terms of "the form". + +That last point is important. Formspec separates concerns across four tiers (Definition, Theme, Component, Mapping) because that separation is architecturally valuable. Whether the author has to *see* that separation is a design call. Today's Studio exposes all four as top-level tabs. That is one answer; it is not the only answer. + +--- + +## 4. What Studio must be able to do + +This section enumerates the capability surface — what the tool has to support. It does not prescribe screens, panels, or flows. Think of this as the complete list of verbs an author needs. How you group them, surface them, and sequence them is the design. + +### 4.1 Create and seed a form + +- Start from nothing (blank form). +- Start from a conversation ("I need a grant budget form with personnel, travel, and equipment sections and a $500k cap"). +- Start from a template (built-in archetypes: housing intake, grant application, patient intake, compliance checklist, employee onboarding). +- Start from an uploaded file (PDF, Word, CSV, screenshot — the AI extracts structure). +- Start from an existing JSON bundle (paste, drag-drop, or import). + +### 4.2 Edit the data model (Definition tier) + +- Add, remove, rename, reorder, move, duplicate, and wrap items. +- Items come in three kinds: **fields** (collect a value), **groups** (nest other items), **content** (headings, paragraphs, banners, dividers — display only). +- Field types: text, integer, decimal, boolean, date, datetime, choice, multi-choice, currency, email, phone, file, signature, rating, slider, URL. +- Mark groups as **repeatable** (min/max instances, add/remove labels). +- Define **named option sets** (reusable choice lists with usage tracking). +- Define **variables** (named FEL expressions the form can reference). +- Define **instances** (external data sources the form can reference). +- Edit per-field metadata: label, hint, placeholder, default value, concept URI (for ontology), help text, references. + +### 4.3 Express logic (Binds and Shapes) + +Formspec has two logic mechanisms; the author needs access to both: + +- **Binds** attach behavior to a single field: `required`, `relevant` (show/hide), `readonly`, `constraint`, `calculate`, `default`. +- **Shapes** attach cross-field or form-level rules with severity (error / warning / info), timing (continuous / deferred / disabled), and activation conditions. + +Binds and shapes are expressed in **FEL** — the Formspec Expression Language. FEL is Excel-like: `$personnel + $travel`, `if($income > 50000, 'A', 'B')`, `sum(items[*].amount)`. Authors will write FEL. The editor has to help them: + +- Autocomplete for field names, function names, variables. +- Real-time parse error feedback. +- Dependency visualization (what does this field depend on? what depends on this field?). +- Static error surfacing (circular references, type mismatches, undefined names). +- A human-readable rendering of expressions ("Show this field when income is greater than $50,000") for authors who prefer prose. + +### 4.4 Organize into pages and flows + +- Multi-page forms (wizard mode, tabs mode, single-page mode). +- Assign items to pages; pages have order, title, description. +- **Screener routing** — an upfront mini-form that routes users into different branches based on their answers. (Think: "Are you a resident? Employee? Contractor?" → different downstream form.) + +### 4.5 Shape presentation (Theme tier) + +- Design tokens: colors, spacing, typography, radii. +- Theme defaults: label position, density, help text style. +- Selector cascade: match items by type / concept / path and apply styling overrides. +- Per-item overrides for one-off adjustments. +- Breakpoints and responsive behavior. + +### 4.6 Shape layout (Component tier) + +- Visual layout of the form: which fields go where, how they cluster. +- Layout containers: stacks, cards, collapsibles, columns (2/3/4), sidebars, inline groups. +- Drag-and-drop arrangement on a canvas. +- Widget selection per field (which of the 33 built-in components renders this field). +- Multi-page composition. + +### 4.7 Shape output (Mapping tier) + +- Define transforms from form response → target format (JSON, XML, CSV). +- Field-level rules: source path → target path, with coercion and value maps. +- Preview the mapping result against a test response. + +### 4.8 Preview and test + +- Live preview of the form as an end-user would see it. +- Viewport switcher (mobile / tablet / desktop). +- Test with scenario data — pre-fill answers and watch conditional logic, calculations, and validation react. +- **Behavior lab** — a panel where the author sees bind states (relevance, required, readonly, calculations) update in real time as scenario values change. +- Inspect generated JSON documents (Definition, Component, Theme, Mapping) at any point. +- Validate a response — check whether a set of answers is complete and correct against the rules. + +### 4.9 Conversational authoring + +Two distinct conversational flows exist today; the design may keep them separate or unify them: + +- **Scaffolding conversation** — the AI interviews the author, gathers requirements, and produces a first-draft form. Works from plain language, templates, or uploaded files. The author watches the form materialize. +- **Refinement conversation** — once a form exists, the author talks to the AI to modify it. ("Add an email field with validation." "Make the budget section only appear for large grants." "Split the address into street, city, state, ZIP.") The AI calls typed tools that mutate the live project, producing reviewable changesets. + +Characteristics the conversational surface has to support: + +- Streaming responses. +- Source tracing — every element the AI created should be traceable back to the conversation turn or upload that produced it. +- Issue tracking — contradictions, low-confidence choices, and missing config surface as a reviewable queue. +- Regeneration — discard and re-scaffold from the full conversation. +- Message truncation — "go back to here and try again." +- Diff view — after a refinement, show what changed. +- Tool-call transparency — the author can see which operations the AI invoked. + +### 4.10 History and collaboration primitives + +- Undo / redo at the command level. +- Command history as a visible log (who did what, when). +- Import / export of the full bundle. +- Save / restore / list sessions (for conversational state). + +### 4.11 Cross-cutting: selection, navigation, search + +- A persistent notion of "the selected item" (a field, a group, a rule, a variable) that drives contextual panels. +- Fast navigation across all entities: items, binds, shapes, variables, option sets, mappings, pages. +- Full-text / command-palette search. +- Entity counts at a glance (how many fields, how many rules, how many unresolved issues). + +### 4.12 Settings and metadata + +- Form metadata: title, description, version, status, page mode, density, label position. +- Extension registry configuration (which extensions are loaded). +- Presentation defaults. + +--- + +## 5. Unpacking the "ChatGPT for forms" frame + +The frame is intentionally provocative. "ChatGPT for forms" is shorthand for a cluster of ideas worth spelling out so the design can decide how much of each to adopt. + +**What "ChatGPT for X" products share:** + +- The primary input is natural language intent, not direct manipulation of artifacts. +- The system produces a first draft the user reviews, rather than requiring the user to produce the first draft themselves. +- Iteration happens in conversation: "make it shorter", "add a section about X", "change the tone". +- The user's artifacts (a document, an image, a slide deck) exist alongside the conversation — they are the subject of the conversation, not its output. +- The user can edit the artifacts directly when conversation is too slow or imprecise. +- Nothing is hidden. The user sees what the system produced and can modify or reject it. + +**What is different for Formspec:** + +- Forms are **structured artifacts with rules**. The AI cannot ship something invalid — it has to pass JSON Schema validation, FEL static analysis, and cross-tier consistency checks. Every AI action flows through typed tool calls that the engine can reject. +- Forms have a **behavior dimension**, not just a content dimension. "Add a field" is trivial; "make the total update when any line item changes" is the actual work. Conversation has to be able to express logic, not just structure. +- Forms have **end users who are not the author**. The author is designing an experience for someone else. The preview / testing surface matters as much as the authoring surface — the author is constantly asking "what does the respondent see?" +- Forms have **multiple correct answers**. There is no single "good" budget form. The design has to leave room for the author's judgement and domain expertise — the AI is a collaborator, not an oracle. +- Forms are **long-lived**. A form shipped this year may run for five years and collect thousands of responses. Revision, versioning, and the ability to audit every change matter more than in a chat-to-produce-a-document product. + +**What this means for the design:** + +These are observations, not directives: + +- Conversation is not the only surface, but it should feel native — not a support chat widget in the corner. A first-time author should be able to go from empty state to a working first draft entirely through conversation. +- Direct manipulation has to be seamless with conversation. If the author fixes something by hand, the AI should pick up where they left off. If the AI changes something, the author should see it in the direct-manipulation surface immediately. +- The system's trustworthiness comes from the author being able to see and undo anything. Design should expose, not hide, what the AI did. +- Preview is not a separate mode you enter — it is part of the authoring loop. The author should see the form-as-respondent as they build. +- The AI is most valuable for the tedious parts: initial scaffolding, writing FEL expressions, suggesting validation rules, extracting structure from documents, naming things, translating. The direct manipulation is most valuable for the structural decisions only the author can make. The design should make the handoff between the two frictionless. + +--- + +## 6. Constraints the design must respect + +These are things the design cannot change, because they are downstream of the specification or the architecture. + +### 6.1 The four tiers are real + +Definition, Theme, Component, and Mapping are separate JSON documents with separate schemas. They are authored, reviewed, and versioned separately. Studio can hide that separation from a non-technical author, but it cannot collapse it — when the author exports, they get four files. The design needs a coherent story for each tier, even if the author never thinks of them that way. + +### 6.2 Every mutation is a typed command + +All edits flow through a command catalog (`definition.addItem`, `theme.setToken`, `component.addNode`, `mapping.mapField`, etc.). This is what makes undo/redo, audit logging, and AI tool calls work uniformly. The design does not have to expose commands as a concept, but it cannot invent ad-hoc edit paths that bypass them. + +### 6.3 FEL is the logic language + +Calculations and conditions are FEL expressions. The design must provide a way to author, read, and debug FEL. Authors of complex forms will write non-trivial expressions — `sum(items[*].amount)`, `if($income > 50000, $rate_a, $rate_b)`, nested `let`-bindings, etc. The design can offer a visual/prose abstraction over FEL, but the raw expression has to be reachable. + +### 6.4 Validation has two mechanisms + +**Binds** (per-field) and **shapes** (cross-field) are structurally different. Shapes have severity levels (error / warning / info) and timing (continuous / deferred / disabled). The design needs to make the distinction legible — authors will want to express "this field is required" (a bind) and "the budget total must balance" (a shape) and will conflate them unless the UI helps. + +### 6.5 Preview is a real form runtime + +The preview surface runs the actual `FormEngine` against the live definition. It is not a mock or an approximation. Reactive updates, conditional visibility, calculations, and validation all run through the same engine an end user would hit. The design can rely on this being accurate. + +### 6.6 The AI runs through typed tools, not freeform generation + +The scaffold step produces a `FormDefinition` through structured output against a JSON schema. The refinement step calls tools from a catalog (the MCP server exposes ~48 typed tools). The AI cannot produce invalid state because the tools reject invalid inputs. This is an asset, not a limitation — the design can promise "the AI cannot break your form" and mean it. + +### 6.7 Offline-first authoring is not required, but runtime offline-first is + +Studio itself runs in a browser with a network connection. The *forms Studio produces* must work offline, which affects what Studio has to show the author (calculation correctness, on-device validation semantics) but not how Studio itself is architected. + +### 6.8 The output must be portable JSON + +Nothing Studio produces can require Studio to run. An author must be able to export, hand the JSON to a developer, and have it work in any runtime (web component, React, iOS, server). The design should not invent Studio-specific concepts that have no representation in the underlying JSON. + +### 6.9 Accessibility is a first-class requirement + +Studio targets government, clinical, and nonprofit authors. Many work in organizations with WCAG 2.2 AA requirements. Studio itself must meet accessibility standards (keyboard operability, screen reader support, focus management, sufficient contrast). The forms Studio produces must also meet accessibility standards — Studio should teach the author to do the right thing (e.g., surfacing when a field is missing a label). + +### 6.10 Session persistence and recovery + +Authors walk away and come back. They close tabs. They crash. The design needs a session model — sessions persist, can be listed, can be resumed. Both the project state and any active conversation must be restorable. + +### 6.11 Scale + +A realistic form is 50–300 fields with dozens of binds, several shapes, multiple repeat groups, and a few pages. The design has to work at that scale without becoming unusable — searching, filtering, and navigating large forms matters. A design that looks beautiful at 5 fields and breaks at 150 is not acceptable. + +--- + +## 7. What a good design answers + +This section is not a brief. It is a list of questions the design has to have an answer to. How it answers them is open. + +**Framing and identity** + +- What does a first-time author see in the first ten seconds? What does the product look like it is for? +- What does an author who has built forms before recognize? What is the closest mental-model anchor — IDE, design tool, word processor, notebook, document editor, agent interface? +- Does conversation feel like a peer to direct manipulation, a front door to it, a supporting surface, or something else entirely? + +**Core authoring loop** + +- How does an author go from "I need a form" to "I have a first draft"? +- Once a draft exists, how do they see what's there, what's missing, and what's wrong? +- When they want to change something, what's the fastest path — conversation, direct edit, keyboard, search? +- How does the author move between thinking about the structure (what fields exist), the behavior (what rules apply), the presentation (how it looks), and the output (what systems consume it)? + +**Trust and review** + +- When the AI does something, how does the author see what changed? +- How does the author accept, reject, or modify an AI action? +- What does the history of the form look like? Can the author read it? +- How does the author know the form is correct — no broken rules, no undefined references, no unreachable fields? + +**Complexity management** + +- Where do logic, validation, and calculations live? How does an author with 40 rules not get lost? +- How does the author see the dependency graph — what depends on this field? what does this field depend on? +- How does search and navigation work at 200 fields? +- How does the author work on one part of the form without losing context on the rest? + +**Preview and testing** + +- When and where does the author see the form-as-respondent? Is it a separate mode, a constant companion, an on-demand overlay? +- How does the author test behavior — conditional visibility, calculations, validation — with sample data? +- How does the author switch between author-view and respondent-view mentally? + +**Tier legibility** + +- Does the author ever need to know the difference between Definition, Component, Theme, and Mapping? If yes, how is it framed? If no, how are the concerns still separable under the hood? +- Where does layout (drag-drop arrangement) live relative to structure (the item tree)? +- Where does theming live — as a separate surface, inline with items, globally, or something else? + +**Conversation as a surface** + +- Is there one conversation or many? Per-form, per-session, per-topic? +- Does the conversation remember context across sessions? +- How does the author see what tools the AI is calling, and at what granularity? +- How does the author redirect, correct, or roll back an AI action? +- How does conversation surface issues, suggestions, and warnings the AI has surfaced? + +**Empty states, error states, edge cases** + +- What does the first-run experience look like? +- What does a broken form (invalid FEL, dangling reference, circular calculation) look like? +- What does a large, production-scale form look like three months into its life? +- What does a form imported from a file look like before the author has cleaned it up? + +A complete design answers all of the above, consistently, without resorting to "it's in a settings menu somewhere." + +--- + +## 8. What the current Studio has, for reference + +The existing implementation is not the design to match — it is a working reference for the capability surface. Treat it like a feature catalog, not a layout proposal. Look at it to understand what has to be supported; do not copy its structure. + +Quick summary of what ships today: + +- **Tabbed workspace**: Editor (item tree), Logic (variables, binds, shapes), Data (schema, instances, option sets), Layout (visual canvas), Theme (tokens, cascades), Mapping (rules, preview), Preview (live form + behavior lab). +- **Blueprint sidebar** with nine sections: Structure, Component Tree, Theme, Screener, Variables, Data Sources, Option Sets, Mappings, Settings. +- **Right-hand properties panel** driven by the current selection. +- **Header** with tab navigation, undo/redo, import/export, command palette (⌘K). +- **Two chat entry points**: an embedded sidebar panel (refinement via MCP tools) and a standalone conversational intake page (scaffolds a form, hands off to the editor). +- **Preview** with viewport switcher, scenario data editor, and a diagnostics panel. +- **Source tracing**: every AI-created element links back to the conversation turn that produced it. +- **Issue queue**: contradictions, low-confidence choices, and missing config surface as a reviewable list. + +This is *an* answer to the product described in this document. Your job is to produce a new answer. + +--- + +## 9. Source material + +For deeper context, the following are canonical: + +- `context.md` (repo root) — Formspec project context, audiences, positioning. +- `packages/formspec-studio/README.md` — current Studio architecture and workspace inventory. +- `packages/formspec-studio-core/README.md` — the authoring API the UI is a surface over (51+ helpers, the vocabulary of things Studio can do). +- `packages/formspec-chat/README.md` — the conversational authoring core (sessions, adapters, scaffolding, refinement, source tracing, issues). +- `specs/core/spec.llm.md` — Formspec core specification. +- `specs/fel/fel-grammar.llm.md` — FEL expression language grammar and semantics. +- `specs/theme/theme-spec.llm.md` — Theme specification. +- `specs/component/component-spec.llm.md` — Component specification, including the 33 built-in components. +- `specs/mapping/mapping-spec.llm.md` — Mapping DSL specification. +- `thoughts/studio/` — prior Studio design reviews, visual specs, product requirements docs (historical, not binding). + +You do not need to read all of this to design. Start with this handoff, `context.md`, and the Studio README. Reach for the specs when you need to understand a specific capability in depth. + +--- + +## 10. The ask + +Produce an original design for Formspec Studio that: + +- Fits the product described in sections 1–6. +- Answers the questions in section 7. +- Takes the "ChatGPT for forms" frame seriously without being bound to any existing ChatGPT-like layout. +- Is grounded in the real audiences (non-technical domain experts in government, nonprofit, clinical, and compliance settings). +- Does not assume the current Studio structure is correct. + +Nothing about tabs, sidebars, canvases, panels, or modes is load-bearing in this document. If the right design has none of those things, that's a valid answer. If the right design has all of them but arranged differently, that's a valid answer. If the right design looks like a notebook, a document, a chat, a spreadsheet, or something that doesn't have a common name yet — those are all valid answers. + +What is load-bearing: the product has to let a non-technical domain expert build, review, refine, and ship a complex, correct form, alongside an AI collaborator, while keeping the author in control of everything that ends up in the final JSON. + + + + + + From efc803e9242565a8710c5aef5d821076cec4d919 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 20 Apr 2026 10:54:08 +0000 Subject: [PATCH 2/8] docs(studio): add spec/studio design philosophy to handoff Weave in the core framing: the spec is simple enough for humans and structured enough for AI to compose unlimited complexity; Studio's job is to make that full power range feel approachable. JSON is always reachable, never required. The benefits of tier separation (theme swaps, layout reuse, retargetable output) should come through in the product; the mechanics should be invisible. --- .../2026-04-20-studio-design-handoff.md | 37 +++++++++++++++++-- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/thoughts/studio/2026-04-20-studio-design-handoff.md b/thoughts/studio/2026-04-20-studio-design-handoff.md index fe048cc5..89072377 100644 --- a/thoughts/studio/2026-04-20-studio-design-handoff.md +++ b/thoughts/studio/2026-04-20-studio-design-handoff.md @@ -59,6 +59,26 @@ The frame implies a product where *conversation is a first-class authoring surfa Note: the current codebase ships **two separate chat surfaces** — one embedded in the editor (refines the live project via tool calls), one standalone (conversational intake that scaffolds a form, then hands off to the editor). The fact that there are two is an implementation artifact, not a product requirement. A unified design is welcome. +### The design philosophy behind the spec and Studio's role in it + +One idea sits under everything in this document; the design should internalize it. + +**Formspec the specification was designed to be simple enough for a human to create by hand and structured enough for AI to create forms of effectively unlimited complexity.** A grant budget form is a few dozen lines of JSON a domain expert can read and edit. A 300-field tax return with cascading calculations, conditional branches, multi-format output, and version-locked change history is the same shape — just more of it. Nothing about the spec gets heavier as the form gets harder. The tools scale, the JSON scales, the reader scales. + +**Studio's job is to give authors access to that full range of power without it feeling overwhelming at any point on the curve.** A first-time author building their first intake form should feel like they are using a simple, approachable tool. A program director rebuilding a tax package for the next regulatory cycle should feel like they are using a tool that can handle what they are asking of it. The underlying capability surface is the same; the experience of using it should stretch without snapping. + +**The JSON is present, never hidden, never primary.** The author can always see, export, and if they want, edit the underlying JSON documents. But they should never *have to*. The complexity of authoring JSON — getting the schema right, writing FEL by hand, keeping Definition / Theme / Component / Mapping consistent with each other — should be invisible. The author works with concepts (fields, rules, pages, styles, outputs); the tool produces correct JSON. When the author opens the JSON panel, they see a readable, sensible document — one they could have written themselves if they had to. + +**The conceptual benefits of the spec's separation of concerns should come through in the design, even if the mechanics don't.** The author does not need to know they are editing four separate documents. They *should* come away with an intuitive understanding of three ideas: + +- **The data model is separate from how it looks.** Changing the theme does not change what the form collects. Two forms can share data structure and have completely different presentations. +- **The layout is separate from the data model.** The field "total" can appear in a card, a sidebar, or on its own page — the data it collects is the same. +- **The output is separate from the input.** The same response can flow out as JSON to one system, XML to another, and CSV to a third, declared once in the mapping — not re-implemented for every destination. + +These separations pay off the first time an author changes a theme without touching their logic, or reuses a data model across two visual layouts, or re-targets their output to a new downstream system. The design should make those moments feel like natural consequences of the product, not special tricks. + +**AI is how the complexity curve stays flat.** The spec is simple enough to author by hand at the low end and rich enough that an AI can compose arbitrarily complex forms at the high end. Studio is where those two meet. The author stays in conceptual mode ("add a section for household members that repeats"); the AI handles the structural and logical machinery; the JSON stays correct and legible the whole time. + --- ## 3. Who uses Studio @@ -83,7 +103,7 @@ These authors share a few traits that shape the design: - They are used to forms being second-class citizens in whatever tool they have. They will be surprised by good tooling. - They do not think in terms of "definition vs. theme vs. component" — they think in terms of "the form". -That last point is important. Formspec separates concerns across four tiers (Definition, Theme, Component, Mapping) because that separation is architecturally valuable. Whether the author has to *see* that separation is a design call. Today's Studio exposes all four as top-level tabs. That is one answer; it is not the only answer. +That last point is important. Formspec separates concerns across four tiers (Definition, Theme, Component, Mapping) because that separation is architecturally valuable — and the *benefits* of that separation (change theme without touching logic; reuse data model across layouts; retarget output without rebuilding the form) should be something the author feels in how the product behaves. The *mechanics* of the separation (four JSON documents, four schemas, cross-document consistency) are authoring overhead the tool should absorb. Today's Studio exposes all four as top-level tabs; that is one answer, and it is not necessarily the right one. --- @@ -238,9 +258,9 @@ These are observations, not directives: These are things the design cannot change, because they are downstream of the specification or the architecture. -### 6.1 The four tiers are real +### 6.1 The four tiers are real, but the author shouldn't feel four tools -Definition, Theme, Component, and Mapping are separate JSON documents with separate schemas. They are authored, reviewed, and versioned separately. Studio can hide that separation from a non-technical author, but it cannot collapse it — when the author exports, they get four files. The design needs a coherent story for each tier, even if the author never thinks of them that way. +Definition, Theme, Component, and Mapping are separate JSON documents with separate schemas. They are authored, reviewed, and versioned separately. The *benefits* of this separation should come through in the product (theme swaps don't affect logic; layout is editable without touching data; output retargets without rebuilding the form). The *mechanics* of this separation (four documents, four schemas, keeping them consistent) should be invisible. When the author exports, they get four files — but getting there should not have felt like running four editors in a trench coat. ### 6.2 Every mutation is a typed command @@ -270,6 +290,10 @@ Studio itself runs in a browser with a network connection. The *forms Studio pro Nothing Studio produces can require Studio to run. An author must be able to export, hand the JSON to a developer, and have it work in any runtime (web component, React, iOS, server). The design should not invent Studio-specific concepts that have no representation in the underlying JSON. +### 6.8.1 The JSON is always reachable, never required + +The author can always open, read, copy, and edit the underlying JSON documents. This is a first-class capability, not a hidden developer escape hatch — domain experts sometimes want to look under the hood, and developers will want to live there. But the author must never *need* to edit JSON to do their job. Every authoring path has a non-JSON expression. The JSON is the artifact; it is not the interface. + ### 6.9 Accessibility is a first-class requirement Studio targets government, clinical, and nonprofit authors. Many work in organizations with WCAG 2.2 AA requirements. Studio itself must meet accessibility standards (keyboard operability, screen reader support, focus management, sufficient contrast). The forms Studio produces must also meet accessibility standards — Studio should teach the author to do the right thing (e.g., surfacing when a field is missing a label). @@ -326,6 +350,13 @@ This section is not a brief. It is a list of questions the design has to have an - Does the author ever need to know the difference between Definition, Component, Theme, and Mapping? If yes, how is it framed? If no, how are the concerns still separable under the hood? - Where does layout (drag-drop arrangement) live relative to structure (the item tree)? - Where does theming live — as a separate surface, inline with items, globally, or something else? +- How do the *benefits* of tier separation (theme swaps, reusable data models, retargetable output) surface as natural moments in the product rather than as things the author has to go hunt for? + +**JSON and transparency** + +- How does an author see the underlying JSON when they want to? Where does that surface live? +- How does the product avoid ever making the author *need* to touch JSON to accomplish a task? +- How do the JSON documents look when the author opens them — are they readable, organized, commented, or dense? **Conversation as a surface** From 8ce76c915bb73fcd0fbf7898e2174740ebd56989 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 20 Apr 2026 10:55:37 +0000 Subject: [PATCH 3/8] docs(studio): dial back JSON prominence; sharpen primary audience MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The primary Studio user is a non-technical program manager or analyst, not a developer. JSON should not be a featured authoring surface or a fallback path — it is a downstream artifact of authoring, available for export and transparency but not promoted. Strengthen audience framing so the designer keeps this user in mind throughout. --- .../studio/2026-04-20-studio-design-handoff.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/thoughts/studio/2026-04-20-studio-design-handoff.md b/thoughts/studio/2026-04-20-studio-design-handoff.md index 89072377..5b3a100c 100644 --- a/thoughts/studio/2026-04-20-studio-design-handoff.md +++ b/thoughts/studio/2026-04-20-studio-design-handoff.md @@ -67,7 +67,7 @@ One idea sits under everything in this document; the design should internalize i **Studio's job is to give authors access to that full range of power without it feeling overwhelming at any point on the curve.** A first-time author building their first intake form should feel like they are using a simple, approachable tool. A program director rebuilding a tax package for the next regulatory cycle should feel like they are using a tool that can handle what they are asking of it. The underlying capability surface is the same; the experience of using it should stretch without snapping. -**The JSON is present, never hidden, never primary.** The author can always see, export, and if they want, edit the underlying JSON documents. But they should never *have to*. The complexity of authoring JSON — getting the schema right, writing FEL by hand, keeping Definition / Theme / Component / Mapping consistent with each other — should be invisible. The author works with concepts (fields, rules, pages, styles, outputs); the tool produces correct JSON. When the author opens the JSON panel, they see a readable, sensible document — one they could have written themselves if they had to. +**The JSON exists, but the author does not work in it.** The audience is program managers, operations leads, and analysts — people who know their domain cold but do not write code, do not read schemas, and will not hand-edit JSON to get their form out the door. The complexity of authoring JSON — keeping schemas valid, writing FEL by hand, keeping Definition / Theme / Component / Mapping consistent with each other — should be fully absorbed by the tool. The author works in concepts (fields, rules, pages, styles, outputs) and the JSON is a downstream artifact, like a compiler's output. Export is available when they need to hand the files to a developer or put them in a repository. A "view source" capability is reasonable for transparency and for the occasional developer who will want it. Neither needs to be a featured surface, and neither should be positioned as a path the primary user is expected to take. **The conceptual benefits of the spec's separation of concerns should come through in the design, even if the mechanics don't.** The author does not need to know they are editing four separate documents. They *should* come away with an intuitive understanding of three ideas: @@ -83,9 +83,9 @@ These separations pay off the first time an author changes a theme without touch ## 3. Who uses Studio -The primary audience is **non-technical form authors** — the people who today file tickets with IT to get a form built, or spend months going back and forth with developers. They understand their domain (grants, eligibility, clinical intake, inspections, compliance) deeply. They do not write code. Many have used Google Forms, Typeform, SurveyMonkey, or REDCap; fewer have used ODK or a real expression language. +The primary audience is **non-technical program managers and analysts** — the people who today file tickets with IT to get a form built, or spend months going back and forth with developers. They understand their domain (grants, eligibility, clinical intake, inspections, compliance) deeply. They do not write code. They do not read JSON. They do not want to learn a schema, a query language, or a markup format. Many have used Google Forms, Typeform, SurveyMonkey, or REDCap; fewer have used ODK or a real expression language. Design for this audience first. -A secondary audience is **developers and form engineers** who will edit the JSON directly, tune FEL expressions, write mapping rules, and integrate the output into their stack. Studio should stay legible to them, but the primary reader of the screen is the domain expert, not the engineer. +A secondary audience is **developers and form engineers** who will occasionally crack open the bundle, tune FEL expressions, write mapping rules, and integrate the output into their stack. They should not be blocked by the product — they can inspect, export, and extend. But the screen is not for them. If a design decision trades clarity for the program manager against convenience for the engineer, the program manager wins. The authors typically work in these settings: @@ -290,9 +290,9 @@ Studio itself runs in a browser with a network connection. The *forms Studio pro Nothing Studio produces can require Studio to run. An author must be able to export, hand the JSON to a developer, and have it work in any runtime (web component, React, iOS, server). The design should not invent Studio-specific concepts that have no representation in the underlying JSON. -### 6.8.1 The JSON is always reachable, never required +### 6.8.1 JSON is the artifact, not the interface -The author can always open, read, copy, and edit the underlying JSON documents. This is a first-class capability, not a hidden developer escape hatch — domain experts sometimes want to look under the hood, and developers will want to live there. But the author must never *need* to edit JSON to do their job. Every authoring path has a non-JSON expression. The JSON is the artifact; it is not the interface. +The primary author is non-technical and should never encounter JSON in the course of authoring. Every authoring path has a non-JSON expression; the tool absorbs schema validity, FEL syntax, and cross-document consistency on the author's behalf. JSON is reachable — authors can export the bundle, and a transparency / "view source" affordance exists for the occasional developer or curious domain expert — but it is not a featured surface, not a workflow the product promotes, and not a fallback the author is ever expected to depend on. ### 6.9 Accessibility is a first-class requirement @@ -354,9 +354,9 @@ This section is not a brief. It is a list of questions the design has to have an **JSON and transparency** -- How does an author see the underlying JSON when they want to? Where does that surface live? -- How does the product avoid ever making the author *need* to touch JSON to accomplish a task? -- How do the JSON documents look when the author opens them — are they readable, organized, commented, or dense? +- How does the product ensure the primary author never has to touch JSON to accomplish anything? +- Where does the "export" / "hand this to a developer" capability live, and how is it framed so non-technical authors are not confused or intimidated by it? +- If a curious domain expert or a developer wants to see the underlying documents, how is that surfaced without promoting it as a path the primary audience should take? **Conversation as a surface** From 38d2437e6fa517e56ca66acfb2a56bf1fb690340 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 20 Apr 2026 10:57:42 +0000 Subject: [PATCH 4/8] docs(studio): add design-carries-the-pitch section to handoff Studio is the project's most visible artifact; the design has to both work as a serious authoring tool and carry the vision in a single screenshot or short demo. Explicit targets: visibly distinct from existing form builders, professional enough for government and clinical audiences, AI collaboration legible at a glance, opinionated rather than generic-SaaS. Matched questions added to section 7. --- .../2026-04-20-studio-design-handoff.md | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/thoughts/studio/2026-04-20-studio-design-handoff.md b/thoughts/studio/2026-04-20-studio-design-handoff.md index 5b3a100c..495b0418 100644 --- a/thoughts/studio/2026-04-20-studio-design-handoff.md +++ b/thoughts/studio/2026-04-20-studio-design-handoff.md @@ -79,6 +79,25 @@ These separations pay off the first time an author changes a theme without touch **AI is how the complexity curve stays flat.** The spec is simple enough to author by hand at the low end and rich enough that an AI can compose arbitrarily complex forms at the high end. Studio is where those two meet. The author stays in conceptual mode ("add a section for household members that repeats"); the AI handles the structural and logical machinery; the JSON stays correct and legible the whole time. +### The design carries the pitch + +Studio is the most visible artifact in the Formspec project. Before anyone reads the spec, the schemas, or a single README, they will see a screenshot. Before they try the product, they will watch a demo video, or skim a tweet, or scroll past a post on a feed. The design is what tells them — in under three seconds — whether Formspec is a serious piece of work that deserves their attention or yet another form builder that can be skipped. + +This is a real requirement, not an afterthought. The product has to be *visibly* different from the tools it replaces — Google Forms, Typeform, REDCap, ODK, SurveyJS, JSON Forms. A design that looks like a nicer version of an existing form builder will be read as a nicer version of an existing form builder. A design that looks like its own thing — a tool that couldn't have existed five years ago, built for a kind of work the old tools can't do — gets a second look. + +Concretely, the design has to: + +- **Make someone stop scrolling.** A single screenshot should communicate that something meaningfully different is happening here. Not "prettier form builder" — something whose category is not immediately obvious, in the way that Linear did not look like a Jira skin and Figma did not look like a faster Illustrator. +- **Look like a professional tool, not a hobby project.** The audience — government, nonprofit, clinical, insurance — is serious. Procurement officers and program directors do not adopt tools that look like weekend projects. Craft, polish, typographic discipline, and restraint matter. This is a tool that people will use for hours a day to do work that matters; it should look like it. +- **Make the AI collaboration legible at a glance.** The "ChatGPT for forms" frame is the headline. A person looking at a screenshot should immediately see that conversation and direct manipulation are first-class peers, not that chat is bolted onto an existing form builder. The AI's presence in the product should be obvious from the first frame, not something you have to discover in a side panel. +- **Demo well.** A 90-second video of someone describing a form and watching it materialize, then refining it through a mix of conversation and direct edits, should be compelling on its own — no voiceover required to explain what is happening. The transitions, the reactivity, the moments where the AI proposes something and the author accepts or modifies it, should read cleanly at demo speed. +- **Photograph well at multiple crops.** Full-window hero shots, tight detail shots of the editing surface, sequence shots showing conversation → form materializing. The design has to hold up as marketing imagery without requiring a caption to explain what the reader is looking at. +- **Carry a point of view.** Formspec's positioning is that complex forms deserve a serious tool, and that AI + a good spec can change what form authoring looks like. The visual design should have that opinion in it. Neutral, corporate, "safe SaaS" design will undersell the project. The design should feel authored — like someone made deliberate choices — without being gimmicky or trend-chasing. + +None of this is a license for form over function. A design that is beautiful to look at and miserable to use will not survive contact with the 200-field tax form. The bar is both: it has to work for a program manager iterating on a real form for hours, and it has to make someone on the outside — a potential adopter, a government CIO, a clinical informaticist, a technical decision-maker — stop and think "I want to know more about this." + +If the design achieves both, the vision sells itself. If it achieves only the working part, the project stays a well-built tool nobody hears about. + --- ## 3. Who uses Studio @@ -317,6 +336,8 @@ This section is not a brief. It is a list of questions the design has to have an - What does a first-time author see in the first ten seconds? What does the product look like it is for? - What does an author who has built forms before recognize? What is the closest mental-model anchor — IDE, design tool, word processor, notebook, document editor, agent interface? - Does conversation feel like a peer to direct manipulation, a front door to it, a supporting surface, or something else entirely? +- Does a single hero screenshot communicate, without explanation, that this is not a skin on an existing form builder? What is the one frame that sells the product? +- Does a 90-second demo — conversation, form materializing, a few refinements, a moment of preview — land without a voiceover? **Core authoring loop** From f5828459e4509c7f6033393b0a8676a291363dfb Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 20 Apr 2026 11:11:24 +0000 Subject: [PATCH 5/8] docs(studio): rewrite handoff to address review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Structural rewrite in response to three parallel reviews: - Merge the redundant "ChatGPT for forms" sections into one place in §3; state the chat-vs-direct-manipulation question as genuinely open rather than covertly leading toward "peers." - Replace the "design carries the pitch" section with §10 "The real tension" — the honest version: tool for hours of use AND visible enough to earn a second look, without the Linear/Figma name-drops or photograph-well framing. - Fix the audience contradiction: program managers don't write code or read JSON but they can read/write Excel-like FEL; the AI writes most expressions and the human reads and tweaks them. - Propagate the JSON-is-artifact stance consistently across §4, §6, §7. Drop the inspect-JSON capability bullet from the verb list. - Rewrite the capability surface (§6) in verbs grouped by authoring activity, not in tier-named headings that contradict §7.1. - Add technical realities the prior draft omitted: scaffold vs refinement are architecturally different (wholesale swap vs command dispatch); changesets are the refinement primitive; bootstrap vs authoring two-phase import lifecycle; sidecars exist beyond the four tiers. - Fix factual errors: ~48 tools across ~28 families (not just 48); renameVariable is blocked; source tracing only populates in the standalone scaffold path today; command history is data not UI; upload extraction is generic (no per-format pipelines yet); field type list now includes single-line vs multi-line text and url. - Add §11 Deliverables and inputs — what the designer returns and what they get (canonical form, current Studio instance access, brand assets). - Trim §9 design questions from 35 to 10. - Drop the anxious "notebook / document / chat / spreadsheet" list and the performative "don't copy today's Studio" disclaimers. Length: 223 lines, down from 405. --- .../2026-04-20-studio-design-handoff.md | 474 +++++------------- 1 file changed, 120 insertions(+), 354 deletions(-) diff --git a/thoughts/studio/2026-04-20-studio-design-handoff.md b/thoughts/studio/2026-04-20-studio-design-handoff.md index 495b0418..bde9fe4e 100644 --- a/thoughts/studio/2026-04-20-studio-design-handoff.md +++ b/thoughts/studio/2026-04-20-studio-design-handoff.md @@ -1,456 +1,222 @@ # Formspec Studio — Design Handoff -**Date:** 2026-04-20 -**Status:** Handoff for an original design pass — no current-design constraints -**Audience:** Designer producing a net-new Studio design from first principles +**Date:** 2026-04-20 (rewritten after review) +**Status:** Handoff for an original design pass +**Audience:** Designer producing a net-new Studio design --- -## 0. Read this first +## 1. How to use this document -This document explains what Formspec Studio is, who uses it, and what it has to do. It does **not** tell you how to design it. Every screen layout, panel arrangement, nav pattern, and interaction model is yours to invent. The current Studio codebase shipped a working design — that design is a reference point for *what the product does*, not a constraint on *how it should look or feel*. Assume you are designing from zero. +This explains what Formspec Studio is, who uses it, what it has to do, and what can't change. It does not specify screens, panels, nav patterns, or interaction models. Those are yours. -The goal is an original design that fits the product described below. If after reading this you think the product should be structured differently from how today's Studio structures it, say so — the conceptual frame ("ChatGPT for forms") is new enough that the right IA is an open question. +The current Studio has shipped; a quick summary is in §8. Treat it as a reference for the capability surface, not as a template. If you think the product should be structured differently than it is today, that's a valid outcome. --- -## 1. What Formspec is (30-second version) +## 2. What Formspec is -Formspec is a **JSON-native specification for complex forms** — tax returns, grant applications, clinical intake, insurance claims, regulatory filings, safety inspections. Not contact forms. Not surveys. Forms with hundreds of fields, conditional sections, cascading calculations, cross-field validation, multi-format output, and offline requirements. +Formspec is a **JSON-native specification for complex forms** — tax returns, grant applications, clinical intake, insurance claims, regulatory filings, safety inspections. Not contact forms or surveys. Forms with hundreds of fields, conditional sections, cascading calculations, cross-field validation, multi-format output, and offline requirements. -A Formspec form is a set of JSON documents: +A Formspec form is a set of JSON documents — a Definition (the data model and its rules), plus optional Theme, Component, and Mapping documents, plus additional sidecars (Locale, References, Ontology, Registry, Changelog, Assist) that most authors never touch. -- **Definition** — the data model: fields, types, structure, validation rules, calculations, conditional logic -- **Theme** — presentation tokens, widget catalog, page layout -- **Component** — interaction widgets, slot binding, responsive design -- **Mapping** — bidirectional transforms to JSON / XML / CSV for downstream systems +The same JSON renders identically on web, React, iOS, and server. The same validation runs in the browser and on the backend. The same calculations produce the same decimal-exact numbers offline on a tablet and on a cloud server. -Plus optional sidecars (Locale, References, Ontology, Registry, Changelog, Assist) that most authors will never touch directly. - -The same JSON definition renders identically on web, React, iOS, and server. The same validation runs in the browser and on the backend. The same calculations produce the same decimal-exact numbers offline on a tablet and on a cloud server. - -Formspec is a **specification**, not a platform. There is no hosted service. Form definitions are JSON files that authors own. +Formspec is a specification, not a platform. There is no hosted service. --- -## 2. What Studio is - -Studio is the **authoring environment** for Formspec. It is where someone sits down to build a form and leaves with a valid set of JSON documents. It is a single-page web application; it is not a SaaS; it is the reference implementation of what authoring should feel like. - -Studio has to serve two overlapping jobs: - -1. **Visual authoring** — direct manipulation of every tier: definition, component, theme, mapping. Every structural change, rule, token, and transform is editable. Undo, redo, import, export are table stakes. Every mutation flows through a typed command catalog so the edit history is auditable and reversible. - -2. **AI-assisted authoring** — a conversational collaborator that can build, modify, refine, and reason about the form alongside the author. The AI calls into the same typed command catalog as the human. Nothing the AI does is unreviewable, un-undoable, or magical. - -Studio is not a form-filling tool. End users of the form never see Studio. Studio's output is the JSON documents; those get deployed into any runtime (web component, React, iOS, server) for end users to fill. - -### The conceptual frame: "ChatGPT for forms" - -The short internal pitch for Studio is **"ChatGPT for forms"**. Take that seriously as a framing device, not as a literal UI pattern: - -- A non-technical author describes the form they need in plain language. The system produces a validated first draft. -- The author reviews, refines, and corrects — through conversation, through direct manipulation, or both. -- The author's role is **oversight and judgement**, not line-by-line construction. -- Every AI action is reviewable. The author can always see what changed, why, and undo it. -- The underlying artifacts (JSON documents) stay human-readable. There is no black box. - -The frame implies a product where *conversation is a first-class authoring surface*, not a side panel bolted onto a traditional form builder. How strongly you lean into that is a design decision. You could design Studio as "chat is the whole interface, with a live preview", or "chat and visual editing are equal peers", or "visual editing is primary with chat as an accelerator". Any of those are defensible — the current implementation leans toward the third, but nothing forces that choice. +## 3. What Studio is -Note: the current codebase ships **two separate chat surfaces** — one embedded in the editor (refines the live project via tool calls), one standalone (conversational intake that scaffolds a form, then hands off to the editor). The fact that there are two is an implementation artifact, not a product requirement. A unified design is welcome. +Studio is the authoring environment for Formspec — where someone sits down to build a form and leaves with a valid set of documents. It is a single-page web application, the reference implementation of what authoring should feel like. End users filling out the form never see Studio. -### The design philosophy behind the spec and Studio's role in it +Studio has one job with two halves. Authors should be able to build and modify forms by **direct manipulation** of the form itself — items, rules, pages, styles, outputs. Authors should also be able to build and modify forms by **conversation with an AI collaborator** that understands the form and can mutate it through the same typed operations a human would. Neither half is a side panel on the other. Both are first-class. How they relate visually and interactively is open. -One idea sits under everything in this document; the design should internalize it. +The short internal pitch is **"ChatGPT for forms"** — a non-technical author describes what they need in plain language, reviews what the system produces, refines through conversation and direct edits, and ends up with a working form without ever having written code. Take that frame seriously, but not literally: the question of whether conversation dominates the interface, shares it equally with direct manipulation, or lives alongside it is a design decision. -**Formspec the specification was designed to be simple enough for a human to create by hand and structured enough for AI to create forms of effectively unlimited complexity.** A grant budget form is a few dozen lines of JSON a domain expert can read and edit. A 300-field tax return with cascading calculations, conditional branches, multi-format output, and version-locked change history is the same shape — just more of it. Nothing about the spec gets heavier as the form gets harder. The tools scale, the JSON scales, the reader scales. +The AI is not freeform. It mutates the form through typed tool calls against a command catalog, constrained by JSON Schema, static analysis, and FEL validity. Nothing the AI produces can be structurally invalid; nothing it does is unreviewable or un-undoable. That is an asset the design can lean on — the product can truthfully promise that the AI cannot break the form. -**Studio's job is to give authors access to that full range of power without it feeling overwhelming at any point on the curve.** A first-time author building their first intake form should feel like they are using a simple, approachable tool. A program director rebuilding a tax package for the next regulatory cycle should feel like they are using a tool that can handle what they are asking of it. The underlying capability surface is the same; the experience of using it should stretch without snapping. - -**The JSON exists, but the author does not work in it.** The audience is program managers, operations leads, and analysts — people who know their domain cold but do not write code, do not read schemas, and will not hand-edit JSON to get their form out the door. The complexity of authoring JSON — keeping schemas valid, writing FEL by hand, keeping Definition / Theme / Component / Mapping consistent with each other — should be fully absorbed by the tool. The author works in concepts (fields, rules, pages, styles, outputs) and the JSON is a downstream artifact, like a compiler's output. Export is available when they need to hand the files to a developer or put them in a repository. A "view source" capability is reasonable for transparency and for the occasional developer who will want it. Neither needs to be a featured surface, and neither should be positioned as a path the primary user is expected to take. - -**The conceptual benefits of the spec's separation of concerns should come through in the design, even if the mechanics don't.** The author does not need to know they are editing four separate documents. They *should* come away with an intuitive understanding of three ideas: - -- **The data model is separate from how it looks.** Changing the theme does not change what the form collects. Two forms can share data structure and have completely different presentations. -- **The layout is separate from the data model.** The field "total" can appear in a card, a sidebar, or on its own page — the data it collects is the same. -- **The output is separate from the input.** The same response can flow out as JSON to one system, XML to another, and CSV to a third, declared once in the mapping — not re-implemented for every destination. - -These separations pay off the first time an author changes a theme without touching their logic, or reuses a data model across two visual layouts, or re-targets their output to a new downstream system. The design should make those moments feel like natural consequences of the product, not special tricks. - -**AI is how the complexity curve stays flat.** The spec is simple enough to author by hand at the low end and rich enough that an AI can compose arbitrarily complex forms at the high end. Studio is where those two meet. The author stays in conceptual mode ("add a section for household members that repeats"); the AI handles the structural and logical machinery; the JSON stays correct and legible the whole time. - -### The design carries the pitch - -Studio is the most visible artifact in the Formspec project. Before anyone reads the spec, the schemas, or a single README, they will see a screenshot. Before they try the product, they will watch a demo video, or skim a tweet, or scroll past a post on a feed. The design is what tells them — in under three seconds — whether Formspec is a serious piece of work that deserves their attention or yet another form builder that can be skipped. - -This is a real requirement, not an afterthought. The product has to be *visibly* different from the tools it replaces — Google Forms, Typeform, REDCap, ODK, SurveyJS, JSON Forms. A design that looks like a nicer version of an existing form builder will be read as a nicer version of an existing form builder. A design that looks like its own thing — a tool that couldn't have existed five years ago, built for a kind of work the old tools can't do — gets a second look. +--- -Concretely, the design has to: +## 4. Design philosophy -- **Make someone stop scrolling.** A single screenshot should communicate that something meaningfully different is happening here. Not "prettier form builder" — something whose category is not immediately obvious, in the way that Linear did not look like a Jira skin and Figma did not look like a faster Illustrator. -- **Look like a professional tool, not a hobby project.** The audience — government, nonprofit, clinical, insurance — is serious. Procurement officers and program directors do not adopt tools that look like weekend projects. Craft, polish, typographic discipline, and restraint matter. This is a tool that people will use for hours a day to do work that matters; it should look like it. -- **Make the AI collaboration legible at a glance.** The "ChatGPT for forms" frame is the headline. A person looking at a screenshot should immediately see that conversation and direct manipulation are first-class peers, not that chat is bolted onto an existing form builder. The AI's presence in the product should be obvious from the first frame, not something you have to discover in a side panel. -- **Demo well.** A 90-second video of someone describing a form and watching it materialize, then refining it through a mix of conversation and direct edits, should be compelling on its own — no voiceover required to explain what is happening. The transitions, the reactivity, the moments where the AI proposes something and the author accepts or modifies it, should read cleanly at demo speed. -- **Photograph well at multiple crops.** Full-window hero shots, tight detail shots of the editing surface, sequence shots showing conversation → form materializing. The design has to hold up as marketing imagery without requiring a caption to explain what the reader is looking at. -- **Carry a point of view.** Formspec's positioning is that complex forms deserve a serious tool, and that AI + a good spec can change what form authoring looks like. The visual design should have that opinion in it. Neutral, corporate, "safe SaaS" design will undersell the project. The design should feel authored — like someone made deliberate choices — without being gimmicky or trend-chasing. +The specification was designed to be simple enough for a human to create by hand and structured enough for AI to compose forms of effectively unlimited complexity. A grant budget form is a few dozen lines of JSON a domain expert can read. A 300-field tax return with cascading calculations and multi-format output is the same shape — just more of it. Nothing about the spec gets heavier as the form gets harder. Studio's job is to give authors access to that full range of power without it feeling overwhelming at any point on the curve. -None of this is a license for form over function. A design that is beautiful to look at and miserable to use will not survive contact with the 200-field tax form. The bar is both: it has to work for a program manager iterating on a real form for hours, and it has to make someone on the outside — a potential adopter, a government CIO, a clinical informaticist, a technical decision-maker — stop and think "I want to know more about this." +The spec separates concerns across several documents — data model, presentation, layout, output transforms, translations, references, ontology. That separation is architecturally valuable. The *benefits* should come through in the product: change the theme without touching logic, reuse a data model across layouts, retarget output to a new system by editing one document. The *mechanics* — four schemas, cross-document consistency, the coordination that separation requires — are authoring overhead the tool should absorb. -If the design achieves both, the vision sells itself. If it achieves only the working part, the project stays a well-built tool nobody hears about. +The JSON is the artifact, not the interface. The author works in concepts — fields, rules, pages, styles, outputs — and the tool produces correct JSON. Export exists so the author can hand the files to a developer or check them into a repository. A view-source affordance is reasonable for transparency. Neither needs to be prominent, and the primary user is never expected to edit JSON to accomplish a task. --- -## 3. Who uses Studio +## 5. Who uses Studio -The primary audience is **non-technical program managers and analysts** — the people who today file tickets with IT to get a form built, or spend months going back and forth with developers. They understand their domain (grants, eligibility, clinical intake, inspections, compliance) deeply. They do not write code. They do not read JSON. They do not want to learn a schema, a query language, or a markup format. Many have used Google Forms, Typeform, SurveyMonkey, or REDCap; fewer have used ODK or a real expression language. Design for this audience first. +The primary user is a **non-technical program manager or analyst** — the person who today files tickets with IT to get a form built, or spends months going back and forth with developers. They know their domain cold (grants, eligibility, clinical intake, inspections, compliance). They do not write code. They do not read schemas. They will not hand-edit JSON. -A secondary audience is **developers and form engineers** who will occasionally crack open the bundle, tune FEL expressions, write mapping rules, and integrate the output into their stack. They should not be blocked by the product — they can inspect, export, and extend. But the screen is not for them. If a design decision trades clarity for the program manager against convenience for the engineer, the program manager wins. +They can, however, read and write **FEL expressions**. FEL (the Formspec Expression Language) is deliberately Excel-like: `$personnel + $travel`, `if($income > 50000, $rate_a, $rate_b)`, `sum(items[*].amount)`. Someone who has written a formula in Excel or a calculated column in a spreadsheet can read and write the common cases. The AI will write most expressions for them; they will read what it produced and tweak it. For unusual expressions the AI struggles with, the author can edit directly. FEL is not a language this user is afraid of — treat it like a spreadsheet formula, not like code. -The authors typically work in these settings: +Typical settings: -- **Government program staff** — benefits eligibility, permitting, tax, licensing. Risk-averse, compliance-sensitive, long procurement cycles, Section 508 / WCAG expectations. -- **Nonprofit and grant operations** — grant applications, reports, compliance submissions. Often small teams; one person wears many hats. -- **Clinical and health intake** — patient questionnaires, screening tools, referrals. Coded vocabularies (ICD-10, SNOMED, LOINC) matter. +- **Government program staff** — benefits, permitting, tax, licensing. Compliance-sensitive, Section 508 / WCAG expectations. +- **Nonprofit and grant operations** — grant applications, reports, submissions. Small teams, one person wearing many hats. +- **Clinical and health intake** — questionnaires, screening, referrals. Coded vocabularies (ICD-10, SNOMED, LOINC) matter. - **Insurance and financial services** — claims, applications, underwriting. Calculation correctness and audit trails are non-negotiable. -- **Field inspection and compliance** — safety checklists, site surveys. Offline is not optional. +- **Field inspection and compliance** — checklists, site surveys. Offline is not optional for the forms they produce. -These authors share a few traits that shape the design: +Shared traits: -- They are accountable for the form being correct. A calculation error is their problem. -- They iterate a lot. Rules change mid-cycle. Wording gets tweaked. New sections appear. -- They do not read docs. They expect the tool to teach them by being legible. -- They are used to forms being second-class citizens in whatever tool they have. They will be surprised by good tooling. -- They do not think in terms of "definition vs. theme vs. component" — they think in terms of "the form". +- Accountable for the form being correct. A bad calculation is their problem. +- Iterate constantly. Rules change mid-cycle, wording gets tweaked, sections come and go. +- Do not read docs. Expect the tool to teach them by being legible. +- Used to forms being second-class citizens in every tool they have. -That last point is important. Formspec separates concerns across four tiers (Definition, Theme, Component, Mapping) because that separation is architecturally valuable — and the *benefits* of that separation (change theme without touching logic; reuse data model across layouts; retarget output without rebuilding the form) should be something the author feels in how the product behaves. The *mechanics* of the separation (four JSON documents, four schemas, cross-document consistency) are authoring overhead the tool should absorb. Today's Studio exposes all four as top-level tabs; that is one answer, and it is not necessarily the right one. +A secondary user is the **developer or form engineer** who will inspect the bundle, integrate it into a stack, write mapping rules against an unusual target system, or extend the registry. They are not blocked — they can export, view source, and edit files in their own editor. But the screen is not for them. When a decision trades clarity for the program manager against convenience for the engineer, the program manager wins. --- -## 4. What Studio must be able to do - -This section enumerates the capability surface — what the tool has to support. It does not prescribe screens, panels, or flows. Think of this as the complete list of verbs an author needs. How you group them, surface them, and sequence them is the design. - -### 4.1 Create and seed a form +## 6. What Studio must be able to do -- Start from nothing (blank form). -- Start from a conversation ("I need a grant budget form with personnel, travel, and equipment sections and a $500k cap"). -- Start from a template (built-in archetypes: housing intake, grant application, patient intake, compliance checklist, employee onboarding). -- Start from an uploaded file (PDF, Word, CSV, screenshot — the AI extracts structure). -- Start from an existing JSON bundle (paste, drag-drop, or import). +A list of verbs, not screens. How you group, surface, sequence, or collapse them is the design. -### 4.2 Edit the data model (Definition tier) +**Start a form.** From nothing, from conversation, from a built-in template (housing intake, grant application, patient intake, compliance checklist, employee onboarding), from an uploaded file (the AI adapter accepts file attachments today; only generic extraction exists — no per-format pipelines yet), from an existing JSON bundle (paste, drop, or import). -- Add, remove, rename, reorder, move, duplicate, and wrap items. -- Items come in three kinds: **fields** (collect a value), **groups** (nest other items), **content** (headings, paragraphs, banners, dividers — display only). -- Field types: text, integer, decimal, boolean, date, datetime, choice, multi-choice, currency, email, phone, file, signature, rating, slider, URL. -- Mark groups as **repeatable** (min/max instances, add/remove labels). -- Define **named option sets** (reusable choice lists with usage tracking). -- Define **variables** (named FEL expressions the form can reference). -- Define **instances** (external data sources the form can reference). -- Edit per-field metadata: label, hint, placeholder, default value, concept URI (for ontology), help text, references. +**Shape the data model.** Add, remove, rename, reorder, move, duplicate, and wrap items. Items are fields (collect a value), groups (nest items), or content (headings, paragraphs, banners, dividers — display only). Field types include single-line text, multi-line text, integer, decimal, boolean, date, datetime, time, choice, multi-choice, currency, email, phone, URL, file, signature, rating, and slider. Groups can be made repeatable with min/max cardinality. Authors also define named option sets (reusable choice lists), named variables (FEL expressions other logic can reference), and named instances (external data sources). Per-item metadata includes label, hint, placeholder, default, concept URI, help text, and references. -### 4.3 Express logic (Binds and Shapes) +**Express logic.** Formspec has two mechanisms and the author needs both. **Binds** attach behavior to a single field: required, relevant (show/hide), readonly, constraint, calculate, default. **Shapes** attach cross-field or form-level rules with severity (error / warning / info), timing (continuous / deferred / disabled), and activation conditions. Both are written in FEL. The editor must help the author read and write FEL — autocomplete for field and function names, real-time parse feedback, dependency visualization (what does this field depend on; what depends on it), and static-error surfacing (circular references, undefined names, type mismatches). The AI will write most expressions; the human will read and tweak them. -Formspec has two logic mechanisms; the author needs access to both: +**Organize into pages and flows.** Multi-page forms in wizard, tabs, or single-page modes. Assign items to pages; pages have order, title, description. **Screener routing** — an upfront mini-form that routes users into different branches based on their answers — is a first-class feature. -- **Binds** attach behavior to a single field: `required`, `relevant` (show/hide), `readonly`, `constraint`, `calculate`, `default`. -- **Shapes** attach cross-field or form-level rules with severity (error / warning / info), timing (continuous / deferred / disabled), and activation conditions. +**Shape presentation.** Design tokens (colors, spacing, typography, radii), global defaults (label position, density, help text), a selector cascade that targets items by type, concept, or path, and per-item overrides. Breakpoints and responsive behavior. -Binds and shapes are expressed in **FEL** — the Formspec Expression Language. FEL is Excel-like: `$personnel + $travel`, `if($income > 50000, 'A', 'B')`, `sum(items[*].amount)`. Authors will write FEL. The editor has to help them: +**Shape layout.** Visual arrangement: which fields go where, how they cluster. Layout containers (stacks, cards, collapsibles, columns, sidebars, inline groups), drag-and-drop on a canvas, widget selection per field (which of the built-in components renders it), multi-page composition. -- Autocomplete for field names, function names, variables. -- Real-time parse error feedback. -- Dependency visualization (what does this field depend on? what depends on this field?). -- Static error surfacing (circular references, type mismatches, undefined names). -- A human-readable rendering of expressions ("Show this field when income is greater than $50,000") for authors who prefer prose. +**Shape output.** Transforms from form response to target format — JSON, XML, CSV. Field-level rules with coercion and value maps. Preview the mapped result against a test response. -### 4.4 Organize into pages and flows +**Preview and test.** A live preview of the form as an end user would see it. Viewport switcher (mobile / tablet / desktop). Scenario data — pre-fill answers and watch conditional logic, calculations, and validation react. A **behavior view** that surfaces bind states (relevance, required, readonly, calculations) and diagnostics as scenario values change. Validate a response against the rules without leaving Studio. Headless evaluation is available (the underlying API exposes `previewForm` and `validateResponse` that run a form engine without a browser), which means preview and behavior views can be scenario-driven without full DOM rendering. -- Multi-page forms (wizard mode, tabs mode, single-page mode). -- Assign items to pages; pages have order, title, description. -- **Screener routing** — an upfront mini-form that routes users into different branches based on their answers. (Think: "Are you a resident? Employee? Contractor?" → different downstream form.) +**Converse with the AI.** Two conversational flows exist in the product today and the design may unify or separate them: +- **Scaffolding** — the AI interviews the author, gathers requirements (from plain language, a template, or an uploaded file), and produces a first-draft form. The scaffold step produces a complete `FormDefinition` and swaps it in wholesale — it does not go through the incremental command catalog. +- **Refinement** — once a form exists, the author talks to the AI to modify it. Refinement goes through typed tool calls against the command catalog; every change is the same kind of operation a human would make and is therefore undoable and auditable. Refinement operations are grouped into **changesets** the author can open, review, accept, or reject as a unit. +Both flows stream, produce structural diffs, and support regenerating or truncating the conversation. Source tracing — linking elements back to the conversation turn that produced them — is populated today only in the standalone scaffold path; parity across both surfaces is a design/implementation question, not a given. -### 4.5 Shape presentation (Theme tier) +**Track issues.** Contradictions, low-confidence AI choices, missing configuration, and validation problems surface as a reviewable queue with severities and categories. Issues can be resolved, deferred, or reopened. -- Design tokens: colors, spacing, typography, radii. -- Theme defaults: label position, density, help text style. -- Selector cascade: match items by type / concept / path and apply styling overrides. -- Per-item overrides for one-off adjustments. -- Breakpoints and responsive behavior. +**Undo, redo, and look back.** Every human or AI mutation is a typed command. Undo and redo work across both. The underlying command history is available as data; whether Studio exposes it as a visible log is a design call (today it doesn't). -### 4.6 Shape layout (Component tier) +**Save, restore, hand off.** Session persistence — authors close tabs, crash, walk away, come back. Sessions list, open, resume. Export and import of the full bundle. Import from a partial bundle is undoable like any other operation. -- Visual layout of the form: which fields go where, how they cluster. -- Layout containers: stacks, cards, collapsibles, columns (2/3/4), sidebars, inline groups. -- Drag-and-drop arrangement on a canvas. -- Widget selection per field (which of the 33 built-in components renders this field). -- Multi-page composition. +**Navigate a large form.** A persistent notion of the selected item (field, group, rule, variable, mapping rule) that drives contextual panels. Fast navigation across all entities. Full-text / command-palette search. Entity counts at a glance. Filtering and scoped views at real form sizes (50–300 fields is typical; hundreds of binds, dozens of shapes, multiple repeat groups). -### 4.7 Shape output (Mapping tier) - -- Define transforms from form response → target format (JSON, XML, CSV). -- Field-level rules: source path → target path, with coercion and value maps. -- Preview the mapping result against a test response. - -### 4.8 Preview and test - -- Live preview of the form as an end-user would see it. -- Viewport switcher (mobile / tablet / desktop). -- Test with scenario data — pre-fill answers and watch conditional logic, calculations, and validation react. -- **Behavior lab** — a panel where the author sees bind states (relevance, required, readonly, calculations) update in real time as scenario values change. -- Inspect generated JSON documents (Definition, Component, Theme, Mapping) at any point. -- Validate a response — check whether a set of answers is complete and correct against the rules. - -### 4.9 Conversational authoring - -Two distinct conversational flows exist today; the design may keep them separate or unify them: - -- **Scaffolding conversation** — the AI interviews the author, gathers requirements, and produces a first-draft form. Works from plain language, templates, or uploaded files. The author watches the form materialize. -- **Refinement conversation** — once a form exists, the author talks to the AI to modify it. ("Add an email field with validation." "Make the budget section only appear for large grants." "Split the address into street, city, state, ZIP.") The AI calls typed tools that mutate the live project, producing reviewable changesets. - -Characteristics the conversational surface has to support: - -- Streaming responses. -- Source tracing — every element the AI created should be traceable back to the conversation turn or upload that produced it. -- Issue tracking — contradictions, low-confidence choices, and missing config surface as a reviewable queue. -- Regeneration — discard and re-scaffold from the full conversation. -- Message truncation — "go back to here and try again." -- Diff view — after a refinement, show what changed. -- Tool-call transparency — the author can see which operations the AI invoked. - -### 4.10 History and collaboration primitives - -- Undo / redo at the command level. -- Command history as a visible log (who did what, when). -- Import / export of the full bundle. -- Save / restore / list sessions (for conversational state). - -### 4.11 Cross-cutting: selection, navigation, search - -- A persistent notion of "the selected item" (a field, a group, a rule, a variable) that drives contextual panels. -- Fast navigation across all entities: items, binds, shapes, variables, option sets, mappings, pages. -- Full-text / command-palette search. -- Entity counts at a glance (how many fields, how many rules, how many unresolved issues). - -### 4.12 Settings and metadata - -- Form metadata: title, description, version, status, page mode, density, label position. -- Extension registry configuration (which extensions are loaded). -- Presentation defaults. +**Configure metadata and extensions.** Form title, description, version, status, page mode, density, label position. Extension registry configuration — which extensions are loaded, how they resolve. Authors of forms in regulated domains will also touch sidecars beyond the four main tiers (Locale for translations, References for citations and help text, Ontology for concept URIs, Changelog for versioned change logs, Assist for filling-side tooling). These are optional for most authors and rarely edited in-band; their authoring surface is a real scope question, not a given. --- -## 5. Unpacking the "ChatGPT for forms" frame - -The frame is intentionally provocative. "ChatGPT for forms" is shorthand for a cluster of ideas worth spelling out so the design can decide how much of each to adopt. - -**What "ChatGPT for X" products share:** +## 7. Constraints and technical realities -- The primary input is natural language intent, not direct manipulation of artifacts. -- The system produces a first draft the user reviews, rather than requiring the user to produce the first draft themselves. -- Iteration happens in conversation: "make it shorter", "add a section about X", "change the tone". -- The user's artifacts (a document, an image, a slide deck) exist alongside the conversation — they are the subject of the conversation, not its output. -- The user can edit the artifacts directly when conversation is too slow or imprecise. -- Nothing is hidden. The user sees what the system produced and can modify or reject it. +Things the design cannot change and things it should know about before making IA decisions. -**What is different for Formspec:** +**The four tiers are real, but the author shouldn't feel four tools.** Definition, Theme, Component, and Mapping are separate JSON documents with separate schemas, separately versioned. The benefits of that separation should come through in product behavior (theme swaps don't touch logic; layouts are editable without touching data; output retargets without rebuilding). The mechanics should be absorbed. -- Forms are **structured artifacts with rules**. The AI cannot ship something invalid — it has to pass JSON Schema validation, FEL static analysis, and cross-tier consistency checks. Every AI action flows through typed tool calls that the engine can reject. -- Forms have a **behavior dimension**, not just a content dimension. "Add a field" is trivial; "make the total update when any line item changes" is the actual work. Conversation has to be able to express logic, not just structure. -- Forms have **end users who are not the author**. The author is designing an experience for someone else. The preview / testing surface matters as much as the authoring surface — the author is constantly asking "what does the respondent see?" -- Forms have **multiple correct answers**. There is no single "good" budget form. The design has to leave room for the author's judgement and domain expertise — the AI is a collaborator, not an oracle. -- Forms are **long-lived**. A form shipped this year may run for five years and collect thousands of responses. Revision, versioning, and the ability to audit every change matter more than in a chat-to-produce-a-document product. - -**What this means for the design:** - -These are observations, not directives: - -- Conversation is not the only surface, but it should feel native — not a support chat widget in the corner. A first-time author should be able to go from empty state to a working first draft entirely through conversation. -- Direct manipulation has to be seamless with conversation. If the author fixes something by hand, the AI should pick up where they left off. If the AI changes something, the author should see it in the direct-manipulation surface immediately. -- The system's trustworthiness comes from the author being able to see and undo anything. Design should expose, not hide, what the AI did. -- Preview is not a separate mode you enter — it is part of the authoring loop. The author should see the form-as-respondent as they build. -- The AI is most valuable for the tedious parts: initial scaffolding, writing FEL expressions, suggesting validation rules, extracting structure from documents, naming things, translating. The direct manipulation is most valuable for the structural decisions only the author can make. The design should make the handoff between the two frictionless. - ---- +**Sidecars exist.** Beyond the four main tiers there are Locale, References, Ontology, Registry, Changelog, and Assist documents. Most authors won't touch them; regulated / multilingual / ontology-bound forms will. The design should have an answer for how a sidecar-authoring user reaches those surfaces without cluttering the primary experience. -## 6. Constraints the design must respect +**Every mutation is a typed command.** All edits — human or AI — flow through a command catalog. This is what makes undo/redo, audit logging, and AI tool-calling work uniformly. The design does not expose commands as a concept, but it cannot invent ad-hoc edit paths that bypass them. -These are things the design cannot change, because they are downstream of the specification or the architecture. +**The AI's two paths are architecturally different.** Scaffolding produces a complete `FormDefinition` via structured output and swaps it in wholesale — it does not go through the command catalog, it replaces the definition. Refinement goes through the command catalog (the MCP server exposes roughly 48 tools, organized into around 28 consolidated families). This asymmetry matters for the design: an AI scaffold feels like a reset; an AI refinement feels like an edit. Today the two live in separate surfaces (integrated sidebar for refinement, standalone page for scaffolding). That split is implementation-driven, not product-required — a unified conversational experience is welcome. -### 6.1 The four tiers are real, but the author shouldn't feel four tools +**Changesets are the refinement primitive.** When the AI modifies an existing form, it opens a changeset, makes a batch of edits, and leaves it for the author to accept or reject as a unit. This is the mechanism behind "reviewable AI actions" — the design should assume it exists and build its review UX around it. -Definition, Theme, Component, and Mapping are separate JSON documents with separate schemas. They are authored, reviewed, and versioned separately. The *benefits* of this separation should come through in the product (theme swaps don't affect logic; layout is editable without touching data; output retargets without rebuilding the form). The *mechanics* of this separation (four documents, four schemas, keeping them consistent) should be invisible. When the author exports, they get four files — but getting there should not have felt like running four editors in a trench coat. +**Imports go through a two-phase lifecycle.** When a file is uploaded or a bundle is imported, the system first enters a **bootstrap** phase where the draft accumulates schema errors, then transitions to an **authoring** phase against a live project. This directly shapes empty-state, broken-import, and recovery UX. -### 6.2 Every mutation is a typed command +**FEL is the logic language.** Excel-like syntax, statically analyzable, deterministic, side-effect-free. The AI writes most expressions; humans read and tweak them. The design needs authoring, reading, and debugging surfaces for FEL — the raw expression must be reachable even if a prose or visual rendering is offered alongside. -All edits flow through a command catalog (`definition.addItem`, `theme.setToken`, `component.addNode`, `mapping.mapField`, etc.). This is what makes undo/redo, audit logging, and AI tool calls work uniformly. The design does not have to expose commands as a concept, but it cannot invent ad-hoc edit paths that bypass them. +**Validation is two mechanisms, not one.** Binds (per-field) and shapes (cross-field, with severity and timing) are structurally different. The distinction should be legible — authors will conflate "this field is required" (bind) with "the budget must balance" (shape) unless the product helps them see the difference. -### 6.3 FEL is the logic language +**Preview is the real engine.** The preview surface runs the actual `FormEngine` against the live definition. It is not a mock. Reactive updates, conditional visibility, calculations, and validation all execute through the same engine an end user would hit. The design can trust that what preview shows is what respondents will see. -Calculations and conditions are FEL expressions. The design must provide a way to author, read, and debug FEL. Authors of complex forms will write non-trivial expressions — `sum(items[*].amount)`, `if($income > 50000, $rate_a, $rate_b)`, nested `let`-bindings, etc. The design can offer a visual/prose abstraction over FEL, but the raw expression has to be reachable. +**JSON is the artifact, not the interface.** The primary user never encounters JSON in the normal flow. Export exists. A view-source affordance exists for transparency. Neither is featured. No authoring path requires touching JSON. -### 6.4 Validation has two mechanisms +**The output must be portable.** Nothing Studio produces can require Studio to run. An exported bundle has to work in any runtime (web component, React, iOS, server). The design should not invent Studio-only concepts with no representation in the JSON. -**Binds** (per-field) and **shapes** (cross-field) are structurally different. Shapes have severity levels (error / warning / info) and timing (continuous / deferred / disabled). The design needs to make the distinction legible — authors will want to express "this field is required" (a bind) and "the budget total must balance" (a shape) and will conflate them unless the UI helps. +**Accessibility is first-class.** Studio targets government, nonprofit, and clinical audiences — many with WCAG 2.2 AA requirements. Studio itself must meet accessibility standards. Studio should also help authors produce accessible forms (for example, surfacing when a field is missing a label). -### 6.5 Preview is a real form runtime +**Session persistence and recovery.** Authors close tabs, crash, walk away. Sessions persist, list, and resume. Both project state and conversational state must be restorable. -The preview surface runs the actual `FormEngine` against the live definition. It is not a mock or an approximation. Reactive updates, conditional visibility, calculations, and validation all run through the same engine an end user would hit. The design can rely on this being accurate. +**Known gaps the designer should not design around as if they work today:** +- **`renameVariable` is not implemented.** Renaming a named variable is blocked at the core; the helper throws. The design can plan for variable renames, but if variable rename flows are critical path to an early demo, they are not wireable today. +- **Upload-to-scaffold is generic.** The AI adapter accepts file attachments and passes them to the model; there is no per-format extraction (no "drop a CSV and see columns map to fields"). Designs assuming format-specific upload UX are ahead of the implementation. +- **Source tracing is partial.** Links from form elements back to the conversation turn that produced them populate in the standalone scaffold path; the integrated refinement path does not feed them back today. Parity is a design question, not a given. +- **Command history is data, not yet UI.** The command log is queryable; no visible audit panel ships. -### 6.6 The AI runs through typed tools, not freeform generation - -The scaffold step produces a `FormDefinition` through structured output against a JSON schema. The refinement step calls tools from a catalog (the MCP server exposes ~48 typed tools). The AI cannot produce invalid state because the tools reject invalid inputs. This is an asset, not a limitation — the design can promise "the AI cannot break your form" and mean it. - -### 6.7 Offline-first authoring is not required, but runtime offline-first is - -Studio itself runs in a browser with a network connection. The *forms Studio produces* must work offline, which affects what Studio has to show the author (calculation correctness, on-device validation semantics) but not how Studio itself is architected. - -### 6.8 The output must be portable JSON - -Nothing Studio produces can require Studio to run. An author must be able to export, hand the JSON to a developer, and have it work in any runtime (web component, React, iOS, server). The design should not invent Studio-specific concepts that have no representation in the underlying JSON. - -### 6.8.1 JSON is the artifact, not the interface - -The primary author is non-technical and should never encounter JSON in the course of authoring. Every authoring path has a non-JSON expression; the tool absorbs schema validity, FEL syntax, and cross-document consistency on the author's behalf. JSON is reachable — authors can export the bundle, and a transparency / "view source" affordance exists for the occasional developer or curious domain expert — but it is not a featured surface, not a workflow the product promotes, and not a fallback the author is ever expected to depend on. - -### 6.9 Accessibility is a first-class requirement - -Studio targets government, clinical, and nonprofit authors. Many work in organizations with WCAG 2.2 AA requirements. Studio itself must meet accessibility standards (keyboard operability, screen reader support, focus management, sufficient contrast). The forms Studio produces must also meet accessibility standards — Studio should teach the author to do the right thing (e.g., surfacing when a field is missing a label). - -### 6.10 Session persistence and recovery - -Authors walk away and come back. They close tabs. They crash. The design needs a session model — sessions persist, can be listed, can be resumed. Both the project state and any active conversation must be restorable. - -### 6.11 Scale - -A realistic form is 50–300 fields with dozens of binds, several shapes, multiple repeat groups, and a few pages. The design has to work at that scale without becoming unusable — searching, filtering, and navigating large forms matters. A design that looks beautiful at 5 fields and breaks at 150 is not acceptable. +**Scale.** Realistic forms are 50–300 fields with dozens of binds, several shapes, multiple repeat groups, and several pages. A design that looks clean at 5 fields and breaks at 150 is not viable. Search, filter, navigation, and scoping at real form sizes are first-order concerns. --- -## 7. What a good design answers - -This section is not a brief. It is a list of questions the design has to have an answer to. How it answers them is open. - -**Framing and identity** - -- What does a first-time author see in the first ten seconds? What does the product look like it is for? -- What does an author who has built forms before recognize? What is the closest mental-model anchor — IDE, design tool, word processor, notebook, document editor, agent interface? -- Does conversation feel like a peer to direct manipulation, a front door to it, a supporting surface, or something else entirely? -- Does a single hero screenshot communicate, without explanation, that this is not a skin on an existing form builder? What is the one frame that sells the product? -- Does a 90-second demo — conversation, form materializing, a few refinements, a moment of preview — land without a voiceover? - -**Core authoring loop** - -- How does an author go from "I need a form" to "I have a first draft"? -- Once a draft exists, how do they see what's there, what's missing, and what's wrong? -- When they want to change something, what's the fastest path — conversation, direct edit, keyboard, search? -- How does the author move between thinking about the structure (what fields exist), the behavior (what rules apply), the presentation (how it looks), and the output (what systems consume it)? - -**Trust and review** - -- When the AI does something, how does the author see what changed? -- How does the author accept, reject, or modify an AI action? -- What does the history of the form look like? Can the author read it? -- How does the author know the form is correct — no broken rules, no undefined references, no unreachable fields? - -**Complexity management** +## 8. Today's Studio, for reference -- Where do logic, validation, and calculations live? How does an author with 40 rules not get lost? -- How does the author see the dependency graph — what depends on this field? what does this field depend on? -- How does search and navigation work at 200 fields? -- How does the author work on one part of the form without losing context on the rest? +A brief factual summary of what ships now. Use it to understand the capability surface; do not use it as a layout proposal. -**Preview and testing** - -- When and where does the author see the form-as-respondent? Is it a separate mode, a constant companion, an on-demand overlay? -- How does the author test behavior — conditional visibility, calculations, validation — with sample data? -- How does the author switch between author-view and respondent-view mentally? - -**Tier legibility** - -- Does the author ever need to know the difference between Definition, Component, Theme, and Mapping? If yes, how is it framed? If no, how are the concerns still separable under the hood? -- Where does layout (drag-drop arrangement) live relative to structure (the item tree)? -- Where does theming live — as a separate surface, inline with items, globally, or something else? -- How do the *benefits* of tier separation (theme swaps, reusable data models, retargetable output) surface as natural moments in the product rather than as things the author has to go hunt for? - -**JSON and transparency** - -- How does the product ensure the primary author never has to touch JSON to accomplish anything? -- Where does the "export" / "hand this to a developer" capability live, and how is it framed so non-technical authors are not confused or intimidated by it? -- If a curious domain expert or a developer wants to see the underlying documents, how is that surfaced without promoting it as a path the primary audience should take? - -**Conversation as a surface** - -- Is there one conversation or many? Per-form, per-session, per-topic? -- Does the conversation remember context across sessions? -- How does the author see what tools the AI is calling, and at what granularity? -- How does the author redirect, correct, or roll back an AI action? -- How does conversation surface issues, suggestions, and warnings the AI has surfaced? - -**Empty states, error states, edge cases** - -- What does the first-run experience look like? -- What does a broken form (invalid FEL, dangling reference, circular calculation) look like? -- What does a large, production-scale form look like three months into its life? -- What does a form imported from a file look like before the author has cleaned it up? +- **Tabbed workspace** with Editor (item tree), Logic (variables, binds, shapes), Data (schema, instances, option sets), Layout (visual canvas), Theme (tokens, selector cascade), Mapping (rules, preview), and Preview (live form, behavior view, viewport switcher). +- **Blueprint sidebar** with nine sections (Structure, Component Tree, Theme, Screener, Variables, Data Sources, Option Sets, Mappings, Settings) and entity count badges. +- **Right-hand properties panel** driven by the current selection. +- **Header** with tab navigation, undo/redo, import/export, command palette (⌘K). +- **Two separate chat entry points** — an embedded sidebar that refines the live project via MCP tool calls (integrated refinement), and a standalone page that runs a conversational intake, scaffolds a definition, and hands off to the editor (standalone scaffolding). +- **Preview** with viewport switcher, scenario data editor, and a diagnostics panel. +- **Issue queue** for AI-surfaced contradictions, low-confidence choices, and missing config. -A complete design answers all of the above, consistently, without resorting to "it's in a settings menu somewhere." +This is one answer to the product described above. The rewrite ask is to produce a new one. --- -## 8. What the current Studio has, for reference - -The existing implementation is not the design to match — it is a working reference for the capability surface. Treat it like a feature catalog, not a layout proposal. Look at it to understand what has to be supported; do not copy its structure. - -Quick summary of what ships today: +## 9. Questions a good design answers -- **Tabbed workspace**: Editor (item tree), Logic (variables, binds, shapes), Data (schema, instances, option sets), Layout (visual canvas), Theme (tokens, cascades), Mapping (rules, preview), Preview (live form + behavior lab). -- **Blueprint sidebar** with nine sections: Structure, Component Tree, Theme, Screener, Variables, Data Sources, Option Sets, Mappings, Settings. -- **Right-hand properties panel** driven by the current selection. -- **Header** with tab navigation, undo/redo, import/export, command palette (⌘K). -- **Two chat entry points**: an embedded sidebar panel (refinement via MCP tools) and a standalone conversational intake page (scaffolds a form, hands off to the editor). -- **Preview** with viewport switcher, scenario data editor, and a diagnostics panel. -- **Source tracing**: every AI-created element links back to the conversation turn that produced it. -- **Issue queue**: contradictions, low-confidence choices, and missing config surface as a reviewable list. +The design has to have an answer to these. How is open. -This is *an* answer to the product described in this document. Your job is to produce a new answer. +1. What does a first-time author see in the first ten seconds, and what does the product look like it is for? +2. How does an author go from "I need a form" to "I have a first draft"? +3. How does conversation relate to direct manipulation — and how does the handoff between them feel when the author switches mid-task? +4. When the AI does something, how does the author see what changed, accept or reject it, and keep going? +5. Where do logic, validation, and calculations live, and how does the author not get lost in them at 40+ rules? +6. When and where does the author see the form-as-respondent? Is preview a mode, a companion, an overlay, or something else? +7. How do the benefits of tier separation (swap theme without touching logic; reuse data model across layouts; retarget output) surface as natural product moments? +8. How does search and navigation work at 200 fields? +9. What does a broken form look like — invalid FEL, dangling references, circular calculations, failed import? +10. What does this product look like three months into the life of a real form, when the author is maintaining it rather than building it? --- -## 9. Source material - -For deeper context, the following are canonical: +## 10. The real tension -- `context.md` (repo root) — Formspec project context, audiences, positioning. -- `packages/formspec-studio/README.md` — current Studio architecture and workspace inventory. -- `packages/formspec-studio-core/README.md` — the authoring API the UI is a surface over (51+ helpers, the vocabulary of things Studio can do). -- `packages/formspec-chat/README.md` — the conversational authoring core (sessions, adapters, scaffolding, refinement, source tracing, issues). -- `specs/core/spec.llm.md` — Formspec core specification. -- `specs/fel/fel-grammar.llm.md` — FEL expression language grammar and semantics. -- `specs/theme/theme-spec.llm.md` — Theme specification. -- `specs/component/component-spec.llm.md` — Component specification, including the 33 built-in components. -- `specs/mapping/mapping-spec.llm.md` — Mapping DSL specification. -- `thoughts/studio/` — prior Studio design reviews, visual specs, product requirements docs (historical, not binding). +Studio has to do two things at once. It has to be a tool a program manager uses for hours at a stretch to build and maintain a correct, complex, high-stakes form — craftwork, not spectacle. It also has to be the most visible surface of the Formspec project, the thing people see in a screenshot or a short demo before they decide whether any of this is worth their attention. Those two pressures can reinforce each other (a tool that is a genuine pleasure to use is also a tool that demos well), but they can also pull apart (flourishes that look good in a hero shot and get in the way at hour six; depth that takes a walkthrough to appreciate). -You do not need to read all of this to design. Start with this handoff, `context.md`, and the Studio README. Reach for the specs when you need to understand a specific capability in depth. +The ask is to hold both. A design that only serves the program manager will be competent and invisible. A design that only serves the screenshot will be beautiful and unusable. The design should look, at a single glance, like something meaningfully different from the form builders it competes with — because it is. It should also earn the second hour, the tenth hour, the hundredth. --- -## 10. The ask +## 11. Deliverables and inputs -Produce an original design for Formspec Studio that: +**What the designer returns:** high-fidelity designs for the primary authoring flows — empty state, scaffolding-by-conversation, direct editing of items and rules, preview, refinement-by-conversation, review of an AI changeset, navigation of a large form. Coverage of mobile is not required for authoring surfaces (authors work on desktop); preview must show how authored forms render across viewports. -- Fits the product described in sections 1–6. -- Answers the questions in section 7. -- Takes the "ChatGPT for forms" frame seriously without being bound to any existing ChatGPT-like layout. -- Is grounded in the real audiences (non-technical domain experts in government, nonprofit, clinical, and compliance settings). -- Does not assume the current Studio structure is correct. +**What the designer gets:** +- This document. +- `context.md` at the repo root for project-level positioning. +- `packages/formspec-studio/README.md` for the current Studio's architecture summary. +- `packages/formspec-studio-core/README.md` for the authoring API (the vocabulary of operations the product supports — 51+ helpers). +- `packages/formspec-chat/README.md` for the conversational layer (session lifecycle, adapters, scaffolding, refinement, changesets, issues). +- A canonical reference form will be provided separately (suggested: a grant budget form at the simple end, a patient intake form at the complex end). Design mockups should use real form content, not lorem ipsum. +- Access to a running instance of today's Studio, for reference. Open it to see the current answer; don't copy it. +- Formspec brand assets (logo, typography, palette) if and when they exist. If they don't, the designer is free to propose. -Nothing about tabs, sidebars, canvases, panels, or modes is load-bearing in this document. If the right design has none of those things, that's a valid answer. If the right design has all of them but arranged differently, that's a valid answer. If the right design looks like a notebook, a document, a chat, a spreadsheet, or something that doesn't have a common name yet — those are all valid answers. +--- -What is load-bearing: the product has to let a non-technical domain expert build, review, refine, and ship a complex, correct form, alongside an AI collaborator, while keeping the author in control of everything that ends up in the final JSON. +## 12. Source material for deeper context +- `specs/core/spec.llm.md` — Formspec core specification. +- `specs/fel/fel-grammar.llm.md` — FEL grammar and semantics. +- `specs/theme/theme-spec.llm.md` — theme specification. +- `specs/component/component-spec.llm.md` — component specification, including the built-in component catalog. +- `specs/mapping/mapping-spec.llm.md` — mapping DSL. +- `thoughts/studio/` — prior Studio design reviews and product requirements. Historical, not binding. +Start with this document, `context.md`, and the three package READMEs. Reach for the specs when you need to understand a specific capability in depth. From 69e4991ce452f6e86f8d33ffecb946529cd8da05 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 20 Apr 2026 11:43:55 +0000 Subject: [PATCH 6/8] docs(studio): rewrite handoff for non-technical designer, exploratory scope The audience is a non-technical designer with no code access doing exploratory design work, not an engineer-designer refining a single solution. The brief is rewritten to match: - Strip every code path, package name, internal identifier, and implementation detail (command catalog, MCP tool counts, FormEngine, changesets as primitive, bootstrap/authoring phase, renameVariable caveats, file paths, source-material links to repo). - Translate all constraints into product language a non-technical reader can act on. - Explain formula language via Excel analogy, with no syntax samples that would read as code to a non-technical reader. - Reframe as exploratory: three to five distinct directions, not one refined design. Explicitly invite divergence and disagreement with the brief. - Replace deliverables-for-an-engineer with deliverables-for-an- exploration (direction descriptions, key flows, hero frames). - Replace "Source material" section (pointed into the repo) with "What you'll be given" (brief, overview, running instance access, example form content, brand assets, access to SMEs). - Explicitly state no source or internal docs will be shared. Length: 218 lines. --- .../2026-04-20-studio-design-handoff.md | 223 +++++++++--------- 1 file changed, 109 insertions(+), 114 deletions(-) diff --git a/thoughts/studio/2026-04-20-studio-design-handoff.md b/thoughts/studio/2026-04-20-studio-design-handoff.md index bde9fe4e..f0d2eb10 100644 --- a/thoughts/studio/2026-04-20-studio-design-handoff.md +++ b/thoughts/studio/2026-04-20-studio-design-handoff.md @@ -1,222 +1,217 @@ -# Formspec Studio — Design Handoff +# Formspec Studio — Design Exploration Brief -**Date:** 2026-04-20 (rewritten after review) -**Status:** Handoff for an original design pass -**Audience:** Designer producing a net-new Studio design +**Date:** 2026-04-20 +**Status:** Exploratory design brief — multiple directions welcome +**Audience:** Designer producing exploratory concepts for Formspec Studio --- ## 1. How to use this document -This explains what Formspec Studio is, who uses it, what it has to do, and what can't change. It does not specify screens, panels, nav patterns, or interaction models. Those are yours. +This brief explains what Formspec Studio is, who uses it, what it has to do for them, and what about it can't change. It is deliberately **not** a list of screens to design. The goal of this engagement is to produce several **exploratory design directions** — different ways the same product could look, feel, and work — not to refine a single answer. -The current Studio has shipped; a quick summary is in §8. Treat it as a reference for the capability surface, not as a template. If you think the product should be structured differently than it is today, that's a valid outcome. +Read the brief, form your own opinions, and propose directions that you think fit. If two of your directions disagree with each other, good. If one of them disagrees with what's described here, tell us why — the brief captures our current thinking, not a contract. + +A version of Studio already exists; §8 describes it at a product level. Treat that as a reference for *what* the product does, not as a template for *how* it should be designed. Starting from zero is encouraged. --- ## 2. What Formspec is -Formspec is a **JSON-native specification for complex forms** — tax returns, grant applications, clinical intake, insurance claims, regulatory filings, safety inspections. Not contact forms or surveys. Forms with hundreds of fields, conditional sections, cascading calculations, cross-field validation, multi-format output, and offline requirements. - -A Formspec form is a set of JSON documents — a Definition (the data model and its rules), plus optional Theme, Component, and Mapping documents, plus additional sidecars (Locale, References, Ontology, Registry, Changelog, Assist) that most authors never touch. +Formspec is a way to define complex forms as portable, version-controlled documents — not to build them in a specific tool or run them on a specific service. It's aimed at the kind of forms where getting the behavior right is most of the work: tax returns, grant applications, clinical intake, insurance claims, regulatory filings, inspection checklists. Not contact forms, not surveys. -The same JSON renders identically on web, React, iOS, and server. The same validation runs in the browser and on the backend. The same calculations produce the same decimal-exact numbers offline on a tablet and on a cloud server. +A Formspec form knows its own rules. Conditional sections, calculations, cross-field validation, different output formats for different downstream systems, translations for different audiences, offline use when there's no connectivity — all of it is described inside the form itself. The same form definition can render on a web page, in a phone app, on a tablet at a remote clinic, and on a server re-checking the answers after submission. The rules behave identically everywhere. -Formspec is a specification, not a platform. There is no hosted service. +Formspec is a specification and a set of open-source tools, not a hosted service. The forms people create with it are their own — they can move them, version them, hand them to other systems, keep them forever. --- ## 3. What Studio is -Studio is the authoring environment for Formspec — where someone sits down to build a form and leaves with a valid set of documents. It is a single-page web application, the reference implementation of what authoring should feel like. End users filling out the form never see Studio. +Studio is where someone sits down to build a Formspec form. It's the authoring environment — the tool someone opens when they have a blank page and a job to do, and closes when they have a working form they can ship. The people who will eventually fill out the form never see Studio. + +Studio has one job with two halves. + +**Direct manipulation.** The author can build and modify the form by working on it directly — adding fields, writing rules, arranging pages, adjusting how it looks, defining how the answers map to their downstream systems. -Studio has one job with two halves. Authors should be able to build and modify forms by **direct manipulation** of the form itself — items, rules, pages, styles, outputs. Authors should also be able to build and modify forms by **conversation with an AI collaborator** that understands the form and can mutate it through the same typed operations a human would. Neither half is a side panel on the other. Both are first-class. How they relate visually and interactively is open. +**Conversation with an AI.** The author can also build and modify the form by talking to an AI that understands the form and can make the same kinds of changes the author would make. Anything the AI does is something the author could have done themselves; everything is reviewable and reversible. -The short internal pitch is **"ChatGPT for forms"** — a non-technical author describes what they need in plain language, reviews what the system produces, refines through conversation and direct edits, and ends up with a working form without ever having written code. Take that frame seriously, but not literally: the question of whether conversation dominates the interface, shares it equally with direct manipulation, or lives alongside it is a design decision. +Neither half is a side-panel on the other. Both are first-class. The short internal pitch is **"ChatGPT for forms"** — describe what you need, see the system produce a first draft, refine it in conversation or by hand, walk away with a working form. Take the frame seriously, but not literally. Whether conversation dominates the interface, shares it equally with direct manipulation, or lives alongside it, is genuinely open — different exploration directions can try different answers. -The AI is not freeform. It mutates the form through typed tool calls against a command catalog, constrained by JSON Schema, static analysis, and FEL validity. Nothing the AI produces can be structurally invalid; nothing it does is unreviewable or un-undoable. That is an asset the design can lean on — the product can truthfully promise that the AI cannot break the form. +One thing the design can truthfully promise: the AI cannot break the form. It works through the same controlled set of operations a human does, and the system won't accept structurally invalid changes from anyone, human or AI. --- ## 4. Design philosophy -The specification was designed to be simple enough for a human to create by hand and structured enough for AI to compose forms of effectively unlimited complexity. A grant budget form is a few dozen lines of JSON a domain expert can read. A 300-field tax return with cascading calculations and multi-format output is the same shape — just more of it. Nothing about the spec gets heavier as the form gets harder. Studio's job is to give authors access to that full range of power without it feeling overwhelming at any point on the curve. +Formspec was designed to be simple enough for a person to create a small form by hand and rich enough for an AI to compose an arbitrarily large and intricate form. A grant budget form might be a few dozen lines of plain, readable description. A 300-field tax return with conditional sections, cascading calculations, and multi-format output is the same shape — just more of it. The underlying specification doesn't get heavier as the form gets harder. Studio's job is to give authors access to that full range of power without it feeling overwhelming at any point on the curve. -The spec separates concerns across several documents — data model, presentation, layout, output transforms, translations, references, ontology. That separation is architecturally valuable. The *benefits* should come through in the product: change the theme without touching logic, reuse a data model across layouts, retarget output to a new system by editing one document. The *mechanics* — four schemas, cross-document consistency, the coordination that separation requires — are authoring overhead the tool should absorb. +Formspec keeps several concerns separate on purpose — what the form collects, how it looks, how it's laid out, how its data flows to downstream systems, what languages it speaks. That separation is valuable; the author shouldn't have to feel it as four or five different tools. The *benefits* should come through as natural product moments — swap the look without changing the logic; reuse the same data model in two different layouts; send the same answers to three different downstream systems by adjusting one thing. The *mechanics* of keeping those concerns separate should be invisible. -The JSON is the artifact, not the interface. The author works in concepts — fields, rules, pages, styles, outputs — and the tool produces correct JSON. Export exists so the author can hand the files to a developer or check them into a repository. A view-source affordance is reasonable for transparency. Neither needs to be prominent, and the primary user is never expected to edit JSON to accomplish a task. +The underlying form definition is just structured text — portable, versionable, readable, editable outside Studio if someone wants to. The author never has to touch it. Export is available; a "view source" affordance is reasonable for transparency. Neither needs to be prominent, and the primary user should never be expected to open the raw form to get their job done. --- ## 5. Who uses Studio -The primary user is a **non-technical program manager or analyst** — the person who today files tickets with IT to get a form built, or spends months going back and forth with developers. They know their domain cold (grants, eligibility, clinical intake, inspections, compliance). They do not write code. They do not read schemas. They will not hand-edit JSON. +The person you are designing for is a **non-technical program manager or analyst** — the person who today files tickets with IT to get a form built, or spends months going back and forth with developers. They know their domain cold: grants, eligibility, clinical intake, inspections, compliance, benefits, licensing, underwriting. They do not write code. They do not read schemas. They will not hand-edit structured text to get a form out the door. -They can, however, read and write **FEL expressions**. FEL (the Formspec Expression Language) is deliberately Excel-like: `$personnel + $travel`, `if($income > 50000, $rate_a, $rate_b)`, `sum(items[*].amount)`. Someone who has written a formula in Excel or a calculated column in a spreadsheet can read and write the common cases. The AI will write most expressions for them; they will read what it produced and tweak it. For unusual expressions the AI struggles with, the author can edit directly. FEL is not a language this user is afraid of — treat it like a spreadsheet formula, not like code. +They *can*, however, read and write simple formulas the way someone writes them in Excel or Google Sheets. The form's logic — "show this section if income is over $50,000", "the total is the sum of personnel, travel, and equipment", "flag this as a warning if the budget is over $500,000" — is written in an Excel-like formula language. Most of the time the AI will write the formula and the author will read it and maybe tweak a number or a comparison; for the occasional case the AI gets wrong, the author can edit the formula directly. Treat the formula language the way you'd treat a spreadsheet formula — something the user can read and adjust, not something scary. Typical settings: -- **Government program staff** — benefits, permitting, tax, licensing. Compliance-sensitive, Section 508 / WCAG expectations. -- **Nonprofit and grant operations** — grant applications, reports, submissions. Small teams, one person wearing many hats. -- **Clinical and health intake** — questionnaires, screening, referrals. Coded vocabularies (ICD-10, SNOMED, LOINC) matter. -- **Insurance and financial services** — claims, applications, underwriting. Calculation correctness and audit trails are non-negotiable. -- **Field inspection and compliance** — checklists, site surveys. Offline is not optional for the forms they produce. +- **Government program staff** — benefits, permitting, tax, licensing. Compliance-sensitive, often required to meet accessibility standards. +- **Nonprofit and grant operations** — applications, reports, submissions. Small teams; one person often wearing many hats. +- **Clinical and health intake** — patient questionnaires, screening, referrals. Coded medical vocabularies matter. +- **Insurance and financial services** — claims, applications, underwriting. Calculation correctness and audit trails matter. +- **Field inspection and compliance** — safety checklists, site surveys. The forms they produce must work offline. -Shared traits: +Shared traits to design for: -- Accountable for the form being correct. A bad calculation is their problem. -- Iterate constantly. Rules change mid-cycle, wording gets tweaked, sections come and go. -- Do not read docs. Expect the tool to teach them by being legible. -- Used to forms being second-class citizens in every tool they have. +- They're accountable for the form being correct. A calculation error is their problem. +- They iterate constantly. Rules change mid-cycle. Wording gets tweaked. Sections come and go. +- They don't read docs. They expect the tool to teach them by being legible. +- They're used to forms being a second-class citizen in every tool they have. A tool that treats this work seriously will surprise them. -A secondary user is the **developer or form engineer** who will inspect the bundle, integrate it into a stack, write mapping rules against an unusual target system, or extend the registry. They are not blocked — they can export, view source, and edit files in their own editor. But the screen is not for them. When a decision trades clarity for the program manager against convenience for the engineer, the program manager wins. +A secondary user is the developer or engineer who will help integrate the finished form into a larger system. They're not blocked by the design — they can export and work with the files in their own tools — but the screen is not for them. When a design choice trades clarity for the program manager against convenience for the engineer, the program manager wins. --- -## 6. What Studio must be able to do - -A list of verbs, not screens. How you group, surface, sequence, or collapse them is the design. - -**Start a form.** From nothing, from conversation, from a built-in template (housing intake, grant application, patient intake, compliance checklist, employee onboarding), from an uploaded file (the AI adapter accepts file attachments today; only generic extraction exists — no per-format pipelines yet), from an existing JSON bundle (paste, drop, or import). - -**Shape the data model.** Add, remove, rename, reorder, move, duplicate, and wrap items. Items are fields (collect a value), groups (nest items), or content (headings, paragraphs, banners, dividers — display only). Field types include single-line text, multi-line text, integer, decimal, boolean, date, datetime, time, choice, multi-choice, currency, email, phone, URL, file, signature, rating, and slider. Groups can be made repeatable with min/max cardinality. Authors also define named option sets (reusable choice lists), named variables (FEL expressions other logic can reference), and named instances (external data sources). Per-item metadata includes label, hint, placeholder, default, concept URI, help text, and references. +## 6. What the author needs to be able to do -**Express logic.** Formspec has two mechanisms and the author needs both. **Binds** attach behavior to a single field: required, relevant (show/hide), readonly, constraint, calculate, default. **Shapes** attach cross-field or form-level rules with severity (error / warning / info), timing (continuous / deferred / disabled), and activation conditions. Both are written in FEL. The editor must help the author read and write FEL — autocomplete for field and function names, real-time parse feedback, dependency visualization (what does this field depend on; what depends on it), and static-error surfacing (circular references, undefined names, type mismatches). The AI will write most expressions; the human will read and tweak them. +A list of things the product has to support, in verbs. How these are grouped, surfaced, or sequenced is the design. -**Organize into pages and flows.** Multi-page forms in wizard, tabs, or single-page modes. Assign items to pages; pages have order, title, description. **Screener routing** — an upfront mini-form that routes users into different branches based on their answers — is a first-class feature. +**Start a form.** From nothing. From a conversation with the AI. From a built-in template (things like a housing intake, a grant application, a patient intake form). From an uploaded document — someone drops in a PDF, a Word doc, or a screenshot of an existing form, and the AI tries to turn it into a starting draft. From pasting in an existing form someone else made. -**Shape presentation.** Design tokens (colors, spacing, typography, radii), global defaults (label position, density, help text), a selector cascade that targets items by type, concept, or path, and per-item overrides. Breakpoints and responsive behavior. +**Shape what the form collects.** Add, remove, rename, reorder, and move the parts of the form. The building blocks are fields (a place where a respondent enters a value), groups (a way to nest fields into sections), and content (headings, paragraphs, banners, dividers — visible but not collected). Fields come in common kinds — text, number, yes/no, date, a choice from a list, multiple choices from a list, money, email, phone, file upload, signature, rating, slider, and so on. Sections can be marked as repeatable with a minimum and maximum (think "household members" or "line items"). -**Shape layout.** Visual arrangement: which fields go where, how they cluster. Layout containers (stacks, cards, collapsibles, columns, sidebars, inline groups), drag-and-drop on a canvas, widget selection per field (which of the built-in components renders it), multi-page composition. +**Set up reusable building blocks.** Named lists of options (used in several places across the form, edited in one place). Named formulas (so a value computed once can be referenced from multiple places). External data sources (so a form can reference a list that lives somewhere outside the form). -**Shape output.** Transforms from form response to target format — JSON, XML, CSV. Field-level rules with coercion and value maps. Preview the mapped result against a test response. +**Express logic.** The author writes rules that say things like: "this field is required if the respondent selected 'yes' above", "this section is hidden unless they're applying for grant type A", "the total is the sum of these three line items", "warn if the budget exceeds $500,000 but don't block submission". There are two kinds: rules that attach to a single field (is this required? should it be hidden? should it be computed from other fields? is its value valid?) and rules that span the whole form (does the budget balance? does the start date come before the end date?). Cross-form rules also have a *severity* — is this a blocking error, a warning, or a note — and can fire continuously as the respondent types or only when they try to submit. The AI writes most of these rules; the author reads them and adjusts. -**Preview and test.** A live preview of the form as an end user would see it. Viewport switcher (mobile / tablet / desktop). Scenario data — pre-fill answers and watch conditional logic, calculations, and validation react. A **behavior view** that surfaces bind states (relevance, required, readonly, calculations) and diagnostics as scenario values change. Validate a response against the rules without leaving Studio. Headless evaluation is available (the underlying API exposes `previewForm` and `validateResponse` that run a form engine without a browser), which means preview and behavior views can be scenario-driven without full DOM rendering. +**Organize the respondent's journey.** Break a long form into pages. Multi-page forms can be wizards (one page at a time, next / back), tabs (free movement between pages), or a single long page. Authors can also set up an **upfront screener** — a quick set of questions at the start that routes the respondent into a different branch of the form based on their answers. -**Converse with the AI.** Two conversational flows exist in the product today and the design may unify or separate them: -- **Scaffolding** — the AI interviews the author, gathers requirements (from plain language, a template, or an uploaded file), and produces a first-draft form. The scaffold step produces a complete `FormDefinition` and swaps it in wholesale — it does not go through the incremental command catalog. -- **Refinement** — once a form exists, the author talks to the AI to modify it. Refinement goes through typed tool calls against the command catalog; every change is the same kind of operation a human would make and is therefore undoable and auditable. Refinement operations are grouped into **changesets** the author can open, review, accept, or reject as a unit. -Both flows stream, produce structural diffs, and support regenerating or truncating the conversation. Source tracing — linking elements back to the conversation turn that produced them — is populated today only in the standalone scaffold path; parity across both surfaces is a design/implementation question, not a given. +**Shape how the form looks.** Global choices — colors, type, spacing, density, label position. Overrides for specific kinds of fields or specific fields. Responsive behavior for mobile, tablet, and desktop. A theme is swappable without touching the form's logic or data model. -**Track issues.** Contradictions, low-confidence AI choices, missing configuration, and validation problems surface as a reviewable queue with severities and categories. Issues can be resolved, deferred, or reopened. +**Shape how the form is laid out.** Where each field sits on the page, how fields cluster into cards or columns, what widget is used for a given field (a dropdown vs. a radio group vs. a segmented control, for example). This is visual arrangement, separate from what the form collects. -**Undo, redo, and look back.** Every human or AI mutation is a typed command. Undo and redo work across both. The underlying command history is available as data; whether Studio exposes it as a visible log is a design call (today it doesn't). +**Shape where the answers go.** When a form is submitted, the answers usually need to feed one or more downstream systems — an API expecting JSON, a legacy system expecting XML, a spreadsheet expecting CSV. The author sets up how each field in the form maps to each downstream format, previews the result, and adjusts. The same submission can feed multiple downstream formats without the author re-entering anything. -**Save, restore, hand off.** Session persistence — authors close tabs, crash, walk away, come back. Sessions list, open, resume. Export and import of the full bundle. Import from a partial bundle is undoable like any other operation. +**Preview and test.** See the form as a respondent would see it — on a phone, a tablet, a desktop. Fill it in with sample answers and watch the conditional logic, calculations, and validation react in real time. Inspect which rules are firing and why. Feed a saved response in and check whether it would pass validation. -**Navigate a large form.** A persistent notion of the selected item (field, group, rule, variable, mapping rule) that drives contextual panels. Fast navigation across all entities. Full-text / command-palette search. Entity counts at a glance. Filtering and scoped views at real form sizes (50–300 fields is typical; hundreds of binds, dozens of shapes, multiple repeat groups). +**Converse with the AI.** Two moments: +- *When the form is empty or very early*, the AI interviews the author, asks what they're trying to build, and produces a first draft to work from. +- *Once a form exists*, the author can ask the AI to change it — "add an email field with validation", "split the address into street, city, state, zip", "make the budget section only appear for large grants". The AI makes the changes, shows what it did, and the author can accept, reject, or modify. +The two moments may be one surface or two, one mode or many. That's a design question. -**Configure metadata and extensions.** Form title, description, version, status, page mode, density, label position. Extension registry configuration — which extensions are loaded, how they resolve. Authors of forms in regulated domains will also touch sidecars beyond the four main tiers (Locale for translations, References for citations and help text, Ontology for concept URIs, Changelog for versioned change logs, Assist for filling-side tooling). These are optional for most authors and rarely edited in-band; their authoring surface is a real scope question, not a given. +**Review what the AI did.** When the AI proposes changes, the author needs to see what's changing before committing to it — a clear before/after, grouped into a coherent unit the author can accept or reject as a whole. After the changes are accepted, they're undoable like any other edit. ---- +**See problems that need attention.** Contradictions between rules, low-confidence choices the AI made, missing configuration, references to things that don't exist, rules that can never fire — these surface as a reviewable queue with severities. The author can resolve an issue, defer it, or reopen one they resolved. -## 7. Constraints and technical realities +**Undo and redo.** Every change — whether the author made it or the AI made it — is reversible. The author can walk back any number of steps. -Things the design cannot change and things it should know about before making IA decisions. +**Save, leave, come back.** Authors close tabs, walk away, crash their browser, and come back the next day. Their work is still there, the conversation with the AI is still there, and they can pick up where they left off. Authors can also have several forms in flight, list them, and switch between them. -**The four tiers are real, but the author shouldn't feel four tools.** Definition, Theme, Component, and Mapping are separate JSON documents with separate schemas, separately versioned. The benefits of that separation should come through in product behavior (theme swaps don't touch logic; layouts are editable without touching data; output retargets without rebuilding). The mechanics should be absorbed. +**Export and hand off.** At any point, the author can export the form as a set of files to hand to a developer, save to a shared drive, or check into version control. -**Sidecars exist.** Beyond the four main tiers there are Locale, References, Ontology, Registry, Changelog, and Assist documents. Most authors won't touch them; regulated / multilingual / ontology-bound forms will. The design should have an answer for how a sidecar-authoring user reaches those surfaces without cluttering the primary experience. +**Work at real form sizes.** Real forms are often 50–300 fields with dozens of rules, several pages, and multiple repeatable sections. Finding a specific field, filtering to the rules that apply to a given field, searching across the whole form — these stop being nice-to-haves once the form gets past about 30 fields. -**Every mutation is a typed command.** All edits — human or AI — flow through a command catalog. This is what makes undo/redo, audit logging, and AI tool-calling work uniformly. The design does not expose commands as a concept, but it cannot invent ad-hoc edit paths that bypass them. +**Set form-level metadata.** Title, description, version, status, page mode, density. There are also specialized sidecar documents — translations into other languages, citations to regulations, semantic tagging that ties fields to standard medical or legal concepts — that only certain kinds of authors (multilingual forms, regulated forms, clinical forms) will ever touch. Whether and how those surface in Studio is a scope question worth flagging. -**The AI's two paths are architecturally different.** Scaffolding produces a complete `FormDefinition` via structured output and swaps it in wholesale — it does not go through the command catalog, it replaces the definition. Refinement goes through the command catalog (the MCP server exposes roughly 48 tools, organized into around 28 consolidated families). This asymmetry matters for the design: an AI scaffold feels like a reset; an AI refinement feels like an edit. Today the two live in separate surfaces (integrated sidebar for refinement, standalone page for scaffolding). That split is implementation-driven, not product-required — a unified conversational experience is welcome. +--- -**Changesets are the refinement primitive.** When the AI modifies an existing form, it opens a changeset, makes a batch of edits, and leaves it for the author to accept or reject as a unit. This is the mechanism behind "reviewable AI actions" — the design should assume it exists and build its review UX around it. +## 7. What can't change -**Imports go through a two-phase lifecycle.** When a file is uploaded or a bundle is imported, the system first enters a **bootstrap** phase where the draft accumulates schema errors, then transitions to an **authoring** phase against a live project. This directly shapes empty-state, broken-import, and recovery UX. +A few things about the product are load-bearing — the design can express them in any form, but it can't work around them. -**FEL is the logic language.** Excel-like syntax, statically analyzable, deterministic, side-effect-free. The AI writes most expressions; humans read and tweak them. The design needs authoring, reading, and debugging surfaces for FEL — the raw expression must be reachable even if a prose or visual rendering is offered alongside. +**The author works in concepts, not code.** Program managers don't write code or read raw form files. The design cannot require them to. -**Validation is two mechanisms, not one.** Binds (per-field) and shapes (cross-field, with severity and timing) are structurally different. The distinction should be legible — authors will conflate "this field is required" (bind) with "the budget must balance" (shape) unless the product helps them see the difference. +**The form's logic is Excel-like formulas.** The author will occasionally read and tweak them, mostly with the AI's help. The design needs a place for formulas — writing, reading, debugging — that feels like editing a spreadsheet formula, not like editing code. -**Preview is the real engine.** The preview surface runs the actual `FormEngine` against the live definition. It is not a mock. Reactive updates, conditional visibility, calculations, and validation all execute through the same engine an end user would hit. The design can trust that what preview shows is what respondents will see. +**The AI is always reviewable and reversible.** Anything the AI does has to be visible, understandable, and undoable. The design has to answer: when the AI does something, how does the author see it, evaluate it, and keep or roll it back? -**JSON is the artifact, not the interface.** The primary user never encounters JSON in the normal flow. Export exists. A view-source affordance exists for transparency. Neither is featured. No authoring path requires touching JSON. +**There are two kinds of rules and the difference matters.** Rules that attach to a single field ("is this required?", "what's the computed value?") and rules that span the form ("does the budget balance?", "is the start date before the end date?") are structurally different — the cross-form ones also have severities and timing. The design should make the distinction legible or the author will conflate them. -**The output must be portable.** Nothing Studio produces can require Studio to run. An exported bundle has to work in any runtime (web component, React, iOS, server). The design should not invent Studio-only concepts with no representation in the JSON. +**Several concerns are separate on purpose.** The form's data model, its visual theme, its layout, and its downstream output are different things. Changing one doesn't and shouldn't change the others. The design can hide that separation from the author's attention, but the *benefits* (swap the theme, reuse the data model, re-target the output) should come through as natural moments in the product. -**Accessibility is first-class.** Studio targets government, nonprofit, and clinical audiences — many with WCAG 2.2 AA requirements. Studio itself must meet accessibility standards. Studio should also help authors produce accessible forms (for example, surfacing when a field is missing a label). +**Preview is real.** What the author sees in preview is exactly what a respondent will see — same logic, same calculations, same validation. The design can lean on this truthfully. -**Session persistence and recovery.** Authors close tabs, crash, walk away. Sessions persist, list, and resume. Both project state and conversational state must be restorable. +**The form must work at 200+ fields.** Not 20. The design should anticipate real forms, which means search, filter, scoping, and navigation at scale matter early. -**Known gaps the designer should not design around as if they work today:** -- **`renameVariable` is not implemented.** Renaming a named variable is blocked at the core; the helper throws. The design can plan for variable renames, but if variable rename flows are critical path to an early demo, they are not wireable today. -- **Upload-to-scaffold is generic.** The AI adapter accepts file attachments and passes them to the model; there is no per-format extraction (no "drop a CSV and see columns map to fields"). Designs assuming format-specific upload UX are ahead of the implementation. -- **Source tracing is partial.** Links from form elements back to the conversation turn that produced them populate in the standalone scaffold path; the integrated refinement path does not feed them back today. Parity is a design question, not a given. -- **Command history is data, not yet UI.** The command log is queryable; no visible audit panel ships. +**Accessibility is first-class.** Government, nonprofit, and clinical audiences often require accessibility conformance. Studio itself should meet accessibility standards, and Studio should help authors produce forms that meet them (for example, by surfacing when a field is missing a label). -**Scale.** Realistic forms are 50–300 fields with dozens of binds, several shapes, multiple repeat groups, and several pages. A design that looks clean at 5 fields and breaks at 150 is not viable. Search, filter, navigation, and scoping at real form sizes are first-order concerns. +**Authors walk away and come back.** Sessions persist. Both the form in progress and the conversation with the AI should still be there the next morning, in another tab, or after a crash. --- -## 8. Today's Studio, for reference +## 8. Today's Studio, at a product level -A brief factual summary of what ships now. Use it to understand the capability surface; do not use it as a layout proposal. +A brief description of what the current version of Studio does, so you know what exists to react to. You'll be given access to a running instance to look at. Use it to understand the capability surface; do not use it as a layout proposal. -- **Tabbed workspace** with Editor (item tree), Logic (variables, binds, shapes), Data (schema, instances, option sets), Layout (visual canvas), Theme (tokens, selector cascade), Mapping (rules, preview), and Preview (live form, behavior view, viewport switcher). -- **Blueprint sidebar** with nine sections (Structure, Component Tree, Theme, Screener, Variables, Data Sources, Option Sets, Mappings, Settings) and entity count badges. -- **Right-hand properties panel** driven by the current selection. -- **Header** with tab navigation, undo/redo, import/export, command palette (⌘K). -- **Two separate chat entry points** — an embedded sidebar that refines the live project via MCP tool calls (integrated refinement), and a standalone page that runs a conversational intake, scaffolds a definition, and hands off to the editor (standalone scaffolding). -- **Preview** with viewport switcher, scenario data editor, and a diagnostics panel. -- **Issue queue** for AI-surfaced contradictions, low-confidence choices, and missing config. +- The workspace is organized around a set of **tabs** — one for the form's structure, one for its logic, one for reference data (options, formulas, external sources), one for the visual layout, one for the theme, one for the downstream output mapping, and one for preview. +- There is a **sidebar** on one side that lets the author jump between views of the form — its structure, its variables, its options, its settings, and so on — with counts showing how many of each thing exist. +- There is a **properties panel** on the other side that changes based on whatever is currently selected. +- There is a **header** with the tab switcher, undo/redo, import/export, and a search palette. +- **Two separate AI surfaces** exist today — one embedded in the editor (for refining an existing form) and one standalone (for starting a form from a conversation). A single unified conversational experience would be welcome. +- **Preview** has a viewport switcher, a place to feed in sample answers, and a diagnostics panel that shows which rules are firing. +- An **issue queue** shows problems the AI or the system has flagged. -This is one answer to the product described above. The rewrite ask is to produce a new one. +That's one answer to what's described in this brief. The exercise is to explore different answers. --- -## 9. Questions a good design answers +## 9. Questions a good exploration answers -The design has to have an answer to these. How is open. +Any direction you propose should have a point of view on these. You don't need to answer all of them in words — your design should answer them by the way it's put together. 1. What does a first-time author see in the first ten seconds, and what does the product look like it is for? 2. How does an author go from "I need a form" to "I have a first draft"? -3. How does conversation relate to direct manipulation — and how does the handoff between them feel when the author switches mid-task? -4. When the AI does something, how does the author see what changed, accept or reject it, and keep going? -5. Where do logic, validation, and calculations live, and how does the author not get lost in them at 40+ rules? +3. How does conversation relate to direct manipulation — and what does it feel like when the author switches between them mid-task? +4. When the AI does something, how does the author see what changed and decide whether to keep it? +5. Where do the form's rules live, and how does the author not get lost in them at 40+ rules? 6. When and where does the author see the form-as-respondent? Is preview a mode, a companion, an overlay, or something else? -7. How do the benefits of tier separation (swap theme without touching logic; reuse data model across layouts; retarget output) surface as natural product moments? +7. How do the benefits of separation of concerns (swap the theme, reuse the data model, retarget the output) show up as natural moments in the product? 8. How does search and navigation work at 200 fields? -9. What does a broken form look like — invalid FEL, dangling references, circular calculations, failed import? -10. What does this product look like three months into the life of a real form, when the author is maintaining it rather than building it? +9. What does a broken form look like — a rule that can never fire, a reference to a field that doesn't exist, a failed import? +10. What does the product look like three months into the life of a real form, when the author is maintaining it rather than building it? --- ## 10. The real tension -Studio has to do two things at once. It has to be a tool a program manager uses for hours at a stretch to build and maintain a correct, complex, high-stakes form — craftwork, not spectacle. It also has to be the most visible surface of the Formspec project, the thing people see in a screenshot or a short demo before they decide whether any of this is worth their attention. Those two pressures can reinforce each other (a tool that is a genuine pleasure to use is also a tool that demos well), but they can also pull apart (flourishes that look good in a hero shot and get in the way at hour six; depth that takes a walkthrough to appreciate). +Studio has to do two things at once. + +It has to be a tool a program manager uses for hours at a stretch to build and maintain a correct, complex, high-stakes form. That's craft work — restrained, legible, forgiving, designed for the ninety-eighth minute of use, not the first. + +It *also* has to be the most visible surface of the Formspec project — the thing someone sees in a screenshot or a short demo before they decide whether any of this is worth their attention. That means the design has to look, at a single glance, like something meaningfully different from the form builders it competes with. Because it is. -The ask is to hold both. A design that only serves the program manager will be competent and invisible. A design that only serves the screenshot will be beautiful and unusable. The design should look, at a single glance, like something meaningfully different from the form builders it competes with — because it is. It should also earn the second hour, the tenth hour, the hundredth. +These two pressures reinforce each other when they can (a tool that's a pleasure to use for hours is also a tool that demos well) and pull apart when they can't (flourishes that look great in a hero shot get in the way at hour six; depth takes a walkthrough to appreciate). The brief is to hold both. A direction that only serves the program manager will be competent and invisible. A direction that only serves the screenshot will be beautiful and unusable. --- -## 11. Deliverables and inputs +## 11. What we're asking for -**What the designer returns:** high-fidelity designs for the primary authoring flows — empty state, scaffolding-by-conversation, direct editing of items and rules, preview, refinement-by-conversation, review of an AI changeset, navigation of a large form. Coverage of mobile is not required for authoring surfaces (authors work on desktop); preview must show how authored forms render across viewports. +**Multiple exploratory directions**, not one refined design. Ideally three to five distinct directions that take genuinely different positions on the open questions — different relationships between conversation and direct manipulation, different answers to where preview lives, different takes on how the author navigates a large form, different visual languages. Pick directions that you think have merit; the goal is to widen the space of what Studio could be before we narrow. -**What the designer gets:** -- This document. -- `context.md` at the repo root for project-level positioning. -- `packages/formspec-studio/README.md` for the current Studio's architecture summary. -- `packages/formspec-studio-core/README.md` for the authoring API (the vocabulary of operations the product supports — 51+ helpers). -- `packages/formspec-chat/README.md` for the conversational layer (session lifecycle, adapters, scaffolding, refinement, changesets, issues). -- A canonical reference form will be provided separately (suggested: a grant budget form at the simple end, a patient intake form at the complex end). Design mockups should use real form content, not lorem ipsum. -- Access to a running instance of today's Studio, for reference. Open it to see the current answer; don't copy it. -- Formspec brand assets (logo, typography, palette) if and when they exist. If they don't, the designer is free to propose. +For each direction, enough to evaluate it — a high-level description of the point of view, a few key flows (empty state, scaffolding-by-conversation, direct editing, review of an AI change, preview), and one "hero" frame that captures the direction's visual and conceptual identity. Fidelity and polish should be high enough to read the direction clearly; you don't need to mock every screen. + +Use real form content in your mockups — not lorem ipsum. We'll provide one or two canonical example forms you can work from. + +If you have strong opinions about what's wrong with the brief itself, say so. This is the first version. --- -## 12. Source material for deeper context +## 12. What you'll be given + +- This brief. +- A short written overview of the Formspec project (the "what and why" at a higher level than this brief goes into). +- Access to a running instance of today's Studio to look at. +- One or two canonical example forms (form content, as you'd see it on paper) to use in your mockups. +- Formspec brand assets — logo, typography, palette — if they exist. If they don't or are incomplete, you're welcome to propose. +- Access to subject-matter experts to answer questions as they come up, either synchronously or in writing. -- `specs/core/spec.llm.md` — Formspec core specification. -- `specs/fel/fel-grammar.llm.md` — FEL grammar and semantics. -- `specs/theme/theme-spec.llm.md` — theme specification. -- `specs/component/component-spec.llm.md` — component specification, including the built-in component catalog. -- `specs/mapping/mapping-spec.llm.md` — mapping DSL. -- `thoughts/studio/` — prior Studio design reviews and product requirements. Historical, not binding. +You do not need, and will not be given, access to the Formspec source code or internal documentation. This brief contains everything about the product you need to design against; if something is missing, ask. -Start with this document, `context.md`, and the three package READMEs. Reach for the specs when you need to understand a specific capability in depth. From 8b8e674795069eb3a2d9b0c633925aa417ff1a08 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 20 Apr 2026 11:47:36 +0000 Subject: [PATCH 7/8] docs(studio): reframe handoff for AI design team building functional demos MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The engagement is now functional-demo production by an AI design team, not mockup production by a human designer. Updated accordingly: - Header and §1 reframed: the output is runnable demos for a canonical end-to-end flow, not static figma frames. - §11 Deliverables rewritten for functional demos: coverage over polish, real interactions where possible, stubbed where needed with faithful captured behavior, ~2min walkthrough per direction plus written framing and trade-off summary. - §12 Resources rewritten: the Formspec runtime, authoring API, AI integration, and today's Studio source are all available. Preview should use the real engine. Explicit out-of-scope list (auth, storage, deployment, post-submission workflow). - Guidance on fidelity calibration (typography/motion/state transitions carry more than half the story; edge cases on the canonical flow only; no need to cover every field type or sidecar). - Dropped the "no source code access" disclaimer from the prior pass. Length: 238 lines. --- .../2026-04-20-studio-design-handoff.md | 54 +++++++++++++------ 1 file changed, 37 insertions(+), 17 deletions(-) diff --git a/thoughts/studio/2026-04-20-studio-design-handoff.md b/thoughts/studio/2026-04-20-studio-design-handoff.md index f0d2eb10..fec7f031 100644 --- a/thoughts/studio/2026-04-20-studio-design-handoff.md +++ b/thoughts/studio/2026-04-20-studio-design-handoff.md @@ -1,18 +1,20 @@ # Formspec Studio — Design Exploration Brief **Date:** 2026-04-20 -**Status:** Exploratory design brief — multiple directions welcome -**Audience:** Designer producing exploratory concepts for Formspec Studio +**Status:** Exploratory design brief — multiple directions, built as functional demos +**Audience:** AI design team building exploratory functional demos of Formspec Studio --- ## 1. How to use this document -This brief explains what Formspec Studio is, who uses it, what it has to do for them, and what about it can't change. It is deliberately **not** a list of screens to design. The goal of this engagement is to produce several **exploratory design directions** — different ways the same product could look, feel, and work — not to refine a single answer. +This brief explains what Formspec Studio is, who uses it, what it has to do for them, and what about it can't change. It is deliberately **not** a list of screens to build. The goal of this engagement is to produce several **exploratory design directions, each shipped as a functional demo** — different ways the same product could look, feel, and work, each running well enough to walk through end-to-end. -Read the brief, form your own opinions, and propose directions that you think fit. If two of your directions disagree with each other, good. If one of them disagrees with what's described here, tell us why — the brief captures our current thinking, not a contract. +Read the brief, form your own opinions, and build directions that you think fit. If two of your directions disagree with each other, good. If one of them disagrees with what's described here, tell us why in the demo — the brief captures our current thinking, not a contract. -A version of Studio already exists; §8 describes it at a product level. Treat that as a reference for *what* the product does, not as a template for *how* it should be designed. Starting from zero is encouraged. +A version of Studio already exists; §8 describes it at a product level, and the running instance is available to you as a reference. Treat it as a reference for *what* the product does, not as a template for *how* it should be designed. Starting from zero is encouraged. + +The bar is higher than usual because you're building, not mocking. A functional demo is more convincing than a figma file — and it's also more honest, because the moments that look good in a still image but fall apart in motion show up immediately. Lean into that. The goal isn't to ship a product; it's to get a direction far enough along that someone can use it for ten minutes and feel what it would be like. --- @@ -191,26 +193,44 @@ These two pressures reinforce each other when they can (a tool that's a pleasure ## 11. What we're asking for -**Multiple exploratory directions**, not one refined design. Ideally three to five distinct directions that take genuinely different positions on the open questions — different relationships between conversation and direct manipulation, different answers to where preview lives, different takes on how the author navigates a large form, different visual languages. Pick directions that you think have merit; the goal is to widen the space of what Studio could be before we narrow. +**Multiple exploratory directions, each a functional demo**, not one refined design. Ideally three to five distinct directions that take genuinely different positions on the open questions — different relationships between conversation and direct manipulation, different answers to where preview lives, different takes on how the author navigates a large form, different visual languages, different mental-model anchors. Pick directions that you think have merit; the goal is to widen the space of what Studio could be before we narrow. + +Each direction should be a runnable application that a person can sit down with, open, and use for at least one canonical end-to-end flow — opening an empty state, going from "I need a form" to a first draft through conversation, making at least one meaningful edit by direct manipulation, seeing the AI respond to a follow-up request with a visible and reviewable change, previewing the form as a respondent, and handing off the result. Real interactions beat mocked ones. If the demo requires stubbing somewhere (for example, using a scripted AI response rather than a live one), that's fine — mark it clearly and keep the stubbed behavior faithful to what the real thing would do. + +Fidelity guidance: + +- **High enough to read the direction.** Typography, spacing, rhythm, motion, and state transitions matter — they carry more than half of what a direction is trying to say. Rough sketches in code will read as rough sketches. +- **Coverage over polish.** Better to have the full end-to-end flow working at medium fidelity than one beautiful screen and dead links everywhere else. +- **Edge cases on the canonical flow only.** Empty state, loading state, AI-is-thinking state, error state, and "the author made a choice that needs confirmation" state should exist along the canonical flow. You do not need to cover every field type, every rule kind, every sidecar, or every import source. -For each direction, enough to evaluate it — a high-level description of the point of view, a few key flows (empty state, scaffolding-by-conversation, direct editing, review of an AI change, preview), and one "hero" frame that captures the direction's visual and conceptual identity. Fidelity and polish should be high enough to read the direction clearly; you don't need to mock every screen. +Use real form content throughout. We'll provide canonical example forms to work from. No lorem ipsum; it undermines the whole point. -Use real form content in your mockups — not lorem ipsum. We'll provide one or two canonical example forms you can work from. +Deliver each direction with: -If you have strong opinions about what's wrong with the brief itself, say so. This is the first version. +1. A short written framing — what this direction's point of view is and why you took it. +2. The running demo. +3. A ~2 minute walkthrough video demonstrating the canonical flow, with voiceover explaining what the direction is doing differently. +4. A summary of what the direction does better than the others and where it pays for it. + +If you have strong opinions about what's wrong with the brief itself, build them into the demos as counter-proposals rather than marginal comments. A direction that ignores part of the brief because you think we're wrong is welcome — just tell us which part and why. --- -## 12. What you'll be given +## 12. What you'll have access to + +**The Formspec stack is available to you.** You're building real demos, so you have real resources: + +- **The form runtime.** The engine that actually renders and runs Formspec forms — live preview, conditional logic, calculations, validation — is available as an open-source package you can drop into your demo. Preview should use the real engine; that's one of the few truthful promises the product can make. Don't mock it. +- **The authoring API.** Programmatic access to create, modify, and manipulate form definitions, themes, components, and mappings. Every mutation you make in a demo should go through it, so undo/redo, audit history, and AI tool-calling all just work. This also means the AI half of your demo has a real surface to call into — you don't need to simulate what the AI can do. +- **AI integration.** There is a working integration with a major model provider for both scaffolding (producing a first draft from a conversation) and refinement (modifying an existing form through a conversation). You can use the live integration or stub it for reliability in the demo. If stubbing, use real scripts captured from the live integration, not made-up dialog. +- **Example form content.** Two to three canonical example forms at different complexity levels — a small one (a grant budget), a medium one (a patient intake), and a large one (a regulatory application or tax form). Use them in every demo so the directions are directly comparable. +- **Today's Studio.** A running instance to look at. You have its source as a reference if you want to see how any of the capabilities above are used today. You do not need to match its structure; treat it as one possible answer. +- **Formspec brand assets** — logo, typography, palette — where they exist. Where they don't, or don't fit a direction, propose. +- **Subject-matter experts.** Access to people who know the product, the specification, and the audiences. Ask questions in writing or synchronously; don't guess in the dark on things that have known answers. -- This brief. -- A short written overview of the Formspec project (the "what and why" at a higher level than this brief goes into). -- Access to a running instance of today's Studio to look at. -- One or two canonical example forms (form content, as you'd see it on paper) to use in your mockups. -- Formspec brand assets — logo, typography, palette — if they exist. If they don't or are incomplete, you're welcome to propose. -- Access to subject-matter experts to answer questions as they come up, either synchronously or in writing. +**What you don't need to build.** Authentication, storage, deployment, billing, real-time collaboration, workflow after submission, or anything downstream of "the form is authored and ready to hand off." The demos end when the author hands off a finished form. What happens next is out of scope. -You do not need, and will not be given, access to the Formspec source code or internal documentation. This brief contains everything about the product you need to design against; if something is missing, ask. +**What the demos are not.** Not production software. Not a single shared system behind all the directions. Not responsive to every viewport. Not internationalized. Not instrumented. Not accessible-conformant (though the design should not obviously violate accessibility — keyboard operability, focus management, and sensible contrast are table stakes even at demo fidelity). Each direction is a disposable exploration built to answer "what could this feel like" and nothing more. From 02acb0ef354349a0626915f41f8e3a7b3953e3c3 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 20 Apr 2026 12:17:07 +0000 Subject: [PATCH 8/8] docs(studio): apply Strunk's Elements of Style to design handoff Tightens the handoff brief throughout: active voice, concrete language, parallel construction, positive form. Cuts throat-clearing and hedging qualifiers. Breaks long compound sentences. Preserves all content and argument structure. https://claude.ai/code/session_0197RsqEPiRTzKbMf7cL3JJA --- .../2026-04-20-studio-design-handoff.md | 197 +++++++++--------- 1 file changed, 99 insertions(+), 98 deletions(-) diff --git a/thoughts/studio/2026-04-20-studio-design-handoff.md b/thoughts/studio/2026-04-20-studio-design-handoff.md index fec7f031..2491f438 100644 --- a/thoughts/studio/2026-04-20-studio-design-handoff.md +++ b/thoughts/studio/2026-04-20-studio-design-handoff.md @@ -1,236 +1,237 @@ # Formspec Studio — Design Exploration Brief **Date:** 2026-04-20 -**Status:** Exploratory design brief — multiple directions, built as functional demos -**Audience:** AI design team building exploratory functional demos of Formspec Studio +**Status:** Exploratory brief. Multiple directions. Functional demos. +**Audience:** AI design team building functional demos of Formspec Studio. --- ## 1. How to use this document -This brief explains what Formspec Studio is, who uses it, what it has to do for them, and what about it can't change. It is deliberately **not** a list of screens to build. The goal of this engagement is to produce several **exploratory design directions, each shipped as a functional demo** — different ways the same product could look, feel, and work, each running well enough to walk through end-to-end. +This brief describes what Studio is, who uses it, what it must do, and what cannot change. It does not list screens to build. Produce **several exploratory directions, each a functional demo** — different takes on how Studio could look, feel, and work, each running well enough to walk through end-to-end. -Read the brief, form your own opinions, and build directions that you think fit. If two of your directions disagree with each other, good. If one of them disagrees with what's described here, tell us why in the demo — the brief captures our current thinking, not a contract. +Read the brief, form your own opinions, and build directions you believe in. If two of your directions contradict each other, good. If one contradicts the brief, say so in the demo. The brief is our current thinking, not a contract. -A version of Studio already exists; §8 describes it at a product level, and the running instance is available to you as a reference. Treat it as a reference for *what* the product does, not as a template for *how* it should be designed. Starting from zero is encouraged. +Studio already exists. §8 describes it at a product level, and a running instance is available as reference. Treat it as evidence of *what* the product does, not a template for *how* it should look. Start from zero. -The bar is higher than usual because you're building, not mocking. A functional demo is more convincing than a figma file — and it's also more honest, because the moments that look good in a still image but fall apart in motion show up immediately. Lean into that. The goal isn't to ship a product; it's to get a direction far enough along that someone can use it for ten minutes and feel what it would be like. +A functional demo convinces more than a Figma file, and tells the truth faster. Moments that look fine in a still image collapse in motion. Lean into that. The goal is not a shipped product — it is a direction a person can use for ten minutes and feel. --- ## 2. What Formspec is -Formspec is a way to define complex forms as portable, version-controlled documents — not to build them in a specific tool or run them on a specific service. It's aimed at the kind of forms where getting the behavior right is most of the work: tax returns, grant applications, clinical intake, insurance claims, regulatory filings, inspection checklists. Not contact forms, not surveys. +Formspec defines complex forms as portable, version-controlled documents. It is not a builder tool and not a hosted service. It is aimed at forms where behavior is most of the work: tax returns, grant applications, clinical intake, insurance claims, regulatory filings, inspection checklists. Not contact forms. Not surveys. -A Formspec form knows its own rules. Conditional sections, calculations, cross-field validation, different output formats for different downstream systems, translations for different audiences, offline use when there's no connectivity — all of it is described inside the form itself. The same form definition can render on a web page, in a phone app, on a tablet at a remote clinic, and on a server re-checking the answers after submission. The rules behave identically everywhere. +A Formspec form carries its own rules. Conditional sections, calculations, cross-field validation, output formats for downstream systems, translations, offline use — the form itself describes all of it. The same definition renders on a web page, a phone, a tablet at a remote clinic, and a server rechecking answers after submission. The rules behave identically everywhere. -Formspec is a specification and a set of open-source tools, not a hosted service. The forms people create with it are their own — they can move them, version them, hand them to other systems, keep them forever. +Formspec is a specification and a set of open-source tools. Authors own the forms they create — they can move them, version them, hand them off, keep them forever. --- ## 3. What Studio is -Studio is where someone sits down to build a Formspec form. It's the authoring environment — the tool someone opens when they have a blank page and a job to do, and closes when they have a working form they can ship. The people who will eventually fill out the form never see Studio. +Studio is where someone builds a Formspec form. Authors open it with a blank page and close it with a working form. Respondents — the people who fill the form out — never see Studio. Studio has one job with two halves. -**Direct manipulation.** The author can build and modify the form by working on it directly — adding fields, writing rules, arranging pages, adjusting how it looks, defining how the answers map to their downstream systems. +**Direct manipulation.** The author builds the form by working on it: adding fields, writing rules, arranging pages, adjusting the look, mapping answers to downstream systems. -**Conversation with an AI.** The author can also build and modify the form by talking to an AI that understands the form and can make the same kinds of changes the author would make. Anything the AI does is something the author could have done themselves; everything is reviewable and reversible. +**Conversation with an AI.** The author also builds the form by talking to an AI that understands it and makes the same kinds of changes the author would. The AI does nothing the author could not do. Everything it does is reviewable and reversible. -Neither half is a side-panel on the other. Both are first-class. The short internal pitch is **"ChatGPT for forms"** — describe what you need, see the system produce a first draft, refine it in conversation or by hand, walk away with a working form. Take the frame seriously, but not literally. Whether conversation dominates the interface, shares it equally with direct manipulation, or lives alongside it, is genuinely open — different exploration directions can try different answers. +Neither half is a side-panel on the other. Both are first-class. The internal pitch is **"ChatGPT for forms"**: describe what you need, watch a first draft appear, refine it in conversation or by hand, leave with a working form. Take the frame seriously, not literally. Whether conversation dominates, shares the canvas, or lives alongside direct manipulation is open. Different directions should try different answers. -One thing the design can truthfully promise: the AI cannot break the form. It works through the same controlled set of operations a human does, and the system won't accept structurally invalid changes from anyone, human or AI. +One promise the design can keep: the AI cannot break the form. It works through the same controlled operations a human uses, and the system rejects structurally invalid changes from anyone. --- ## 4. Design philosophy -Formspec was designed to be simple enough for a person to create a small form by hand and rich enough for an AI to compose an arbitrarily large and intricate form. A grant budget form might be a few dozen lines of plain, readable description. A 300-field tax return with conditional sections, cascading calculations, and multi-format output is the same shape — just more of it. The underlying specification doesn't get heavier as the form gets harder. Studio's job is to give authors access to that full range of power without it feeling overwhelming at any point on the curve. +Formspec is simple enough to hand-write a small form and rich enough for an AI to compose an enormous one. A grant budget form runs a few dozen lines of readable description. A 300-field tax return with conditional sections, cascading calculations, and multi-format output has the same shape, only larger. The specification does not grow heavier as the form grows harder. Studio's job is to open that full range to authors without overwhelming them at any point on the curve. -Formspec keeps several concerns separate on purpose — what the form collects, how it looks, how it's laid out, how its data flows to downstream systems, what languages it speaks. That separation is valuable; the author shouldn't have to feel it as four or five different tools. The *benefits* should come through as natural product moments — swap the look without changing the logic; reuse the same data model in two different layouts; send the same answers to three different downstream systems by adjusting one thing. The *mechanics* of keeping those concerns separate should be invisible. +Formspec separates several concerns on purpose: what the form collects, how it looks, how it is laid out, how its data flows to downstream systems, what languages it speaks. The separation is valuable. The author should not feel it as four or five tools. Let the *benefits* surface as natural product moments — swap the look without touching the logic, reuse one data model in two layouts, feed three downstream systems from a single mapping. Hide the *mechanics*. -The underlying form definition is just structured text — portable, versionable, readable, editable outside Studio if someone wants to. The author never has to touch it. Export is available; a "view source" affordance is reasonable for transparency. Neither needs to be prominent, and the primary user should never be expected to open the raw form to get their job done. +The form definition is structured text — portable, versionable, readable, editable outside Studio. The author never needs to touch it. Offer export. Offer "view source" for transparency. Neither belongs at the center. The primary user never opens the raw form to do their job. --- ## 5. Who uses Studio -The person you are designing for is a **non-technical program manager or analyst** — the person who today files tickets with IT to get a form built, or spends months going back and forth with developers. They know their domain cold: grants, eligibility, clinical intake, inspections, compliance, benefits, licensing, underwriting. They do not write code. They do not read schemas. They will not hand-edit structured text to get a form out the door. +Design for a **non-technical program manager or analyst** — the person who today files IT tickets to get a form built, or spends months trading drafts with developers. They know their domain cold: grants, eligibility, clinical intake, inspections, compliance, benefits, licensing, underwriting. They do not write code. They do not read schemas. They will not hand-edit structured text to ship a form. -They *can*, however, read and write simple formulas the way someone writes them in Excel or Google Sheets. The form's logic — "show this section if income is over $50,000", "the total is the sum of personnel, travel, and equipment", "flag this as a warning if the budget is over $500,000" — is written in an Excel-like formula language. Most of the time the AI will write the formula and the author will read it and maybe tweak a number or a comparison; for the occasional case the AI gets wrong, the author can edit the formula directly. Treat the formula language the way you'd treat a spreadsheet formula — something the user can read and adjust, not something scary. +They *can* read and write simple formulas, the way anyone uses Excel or Google Sheets. The form's logic — "show this section if income is over $50,000", "the total is the sum of personnel, travel, and equipment", "warn if the budget is over $500,000" — is written in an Excel-like formula language. The AI writes most formulas; the author reads them and tweaks a number or comparison. For the occasional case the AI gets wrong, the author edits the formula directly. Treat formulas like spreadsheet formulas — something the user reads and adjusts, not something scary. Typical settings: -- **Government program staff** — benefits, permitting, tax, licensing. Compliance-sensitive, often required to meet accessibility standards. -- **Nonprofit and grant operations** — applications, reports, submissions. Small teams; one person often wearing many hats. +- **Government program staff** — benefits, permitting, tax, licensing. Compliance-sensitive. Often required to meet accessibility standards. +- **Nonprofit and grant operations** — applications, reports, submissions. Small teams. One person wearing many hats. - **Clinical and health intake** — patient questionnaires, screening, referrals. Coded medical vocabularies matter. - **Insurance and financial services** — claims, applications, underwriting. Calculation correctness and audit trails matter. -- **Field inspection and compliance** — safety checklists, site surveys. The forms they produce must work offline. +- **Field inspection and compliance** — safety checklists, site surveys. Forms must work offline. -Shared traits to design for: +Shared traits: -- They're accountable for the form being correct. A calculation error is their problem. -- They iterate constantly. Rules change mid-cycle. Wording gets tweaked. Sections come and go. -- They don't read docs. They expect the tool to teach them by being legible. -- They're used to forms being a second-class citizen in every tool they have. A tool that treats this work seriously will surprise them. +- They are accountable for correctness. A calculation error is their problem. +- They iterate constantly. Rules change mid-cycle. Wording shifts. Sections come and go. +- They do not read docs. They expect the tool to teach them by being legible. +- They are used to forms being a second-class citizen in every tool they own. A tool that takes this work seriously will surprise them. -A secondary user is the developer or engineer who will help integrate the finished form into a larger system. They're not blocked by the design — they can export and work with the files in their own tools — but the screen is not for them. When a design choice trades clarity for the program manager against convenience for the engineer, the program manager wins. +A secondary user is the developer who integrates the finished form into a larger system. They are not blocked by the design — they can export and work in their own tools — but the screen is not for them. When a choice trades clarity for the program manager against convenience for the engineer, the program manager wins. --- -## 6. What the author needs to be able to do +## 6. What the author needs to do -A list of things the product has to support, in verbs. How these are grouped, surfaced, or sequenced is the design. +Verbs the product must support. How to group, surface, or sequence them is the design. -**Start a form.** From nothing. From a conversation with the AI. From a built-in template (things like a housing intake, a grant application, a patient intake form). From an uploaded document — someone drops in a PDF, a Word doc, or a screenshot of an existing form, and the AI tries to turn it into a starting draft. From pasting in an existing form someone else made. +**Start a form.** From nothing. From a conversation with the AI. From a built-in template — a housing intake, a grant application, a patient intake form. From an uploaded PDF, Word doc, or screenshot, which the AI converts to a starting draft. From a pasted form someone else made. -**Shape what the form collects.** Add, remove, rename, reorder, and move the parts of the form. The building blocks are fields (a place where a respondent enters a value), groups (a way to nest fields into sections), and content (headings, paragraphs, banners, dividers — visible but not collected). Fields come in common kinds — text, number, yes/no, date, a choice from a list, multiple choices from a list, money, email, phone, file upload, signature, rating, slider, and so on. Sections can be marked as repeatable with a minimum and maximum (think "household members" or "line items"). +**Shape what the form collects.** Add, remove, rename, reorder, and move the parts of the form. The building blocks are fields (where a respondent enters a value), groups (sections that nest fields), and content (headings, paragraphs, banners, dividers — visible, not collected). Fields come in common kinds: text, number, yes/no, date, single choice, multiple choice, money, email, phone, file upload, signature, rating, slider. Sections can repeat with a minimum and maximum — "household members," "line items." -**Set up reusable building blocks.** Named lists of options (used in several places across the form, edited in one place). Named formulas (so a value computed once can be referenced from multiple places). External data sources (so a form can reference a list that lives somewhere outside the form). +**Set up reusable building blocks.** Named option lists, edited in one place and used in several. Named formulas, computed once and referenced anywhere. External data sources, pointing to a list that lives outside the form. -**Express logic.** The author writes rules that say things like: "this field is required if the respondent selected 'yes' above", "this section is hidden unless they're applying for grant type A", "the total is the sum of these three line items", "warn if the budget exceeds $500,000 but don't block submission". There are two kinds: rules that attach to a single field (is this required? should it be hidden? should it be computed from other fields? is its value valid?) and rules that span the whole form (does the budget balance? does the start date come before the end date?). Cross-form rules also have a *severity* — is this a blocking error, a warning, or a note — and can fire continuously as the respondent types or only when they try to submit. The AI writes most of these rules; the author reads them and adjusts. +**Express logic.** The author writes rules like "this field is required if the respondent selected 'yes' above," "hide this section unless they're applying for grant type A," "the total is the sum of these three line items," "warn if the budget exceeds $500,000 but don't block submission." Rules come in two kinds. Field rules attach to one field: is it required? hidden? computed? valid? Form rules span the whole form: does the budget balance? does the start date come before the end date? Form rules also carry a *severity* — error, warning, or note — and fire continuously or only on submit. The AI writes most rules; the author reads and adjusts. -**Organize the respondent's journey.** Break a long form into pages. Multi-page forms can be wizards (one page at a time, next / back), tabs (free movement between pages), or a single long page. Authors can also set up an **upfront screener** — a quick set of questions at the start that routes the respondent into a different branch of the form based on their answers. +**Organize the respondent's journey.** Break a long form into pages. Multi-page forms run as wizards (one page at a time, next/back), tabs (free movement), or a single scrolling page. Authors can also set up a **screener** — a short set of questions up front that routes the respondent into a branch of the form based on their answers. -**Shape how the form looks.** Global choices — colors, type, spacing, density, label position. Overrides for specific kinds of fields or specific fields. Responsive behavior for mobile, tablet, and desktop. A theme is swappable without touching the form's logic or data model. +**Shape how the form looks.** Global choices — colors, type, spacing, density, label position. Overrides for field kinds or specific fields. Responsive behavior for mobile, tablet, desktop. Themes swap without touching logic or data. -**Shape how the form is laid out.** Where each field sits on the page, how fields cluster into cards or columns, what widget is used for a given field (a dropdown vs. a radio group vs. a segmented control, for example). This is visual arrangement, separate from what the form collects. +**Shape how the form is laid out.** Where each field sits, how fields cluster into cards or columns, what widget a field uses — dropdown, radio group, segmented control. Visual arrangement, separate from what the form collects. -**Shape where the answers go.** When a form is submitted, the answers usually need to feed one or more downstream systems — an API expecting JSON, a legacy system expecting XML, a spreadsheet expecting CSV. The author sets up how each field in the form maps to each downstream format, previews the result, and adjusts. The same submission can feed multiple downstream formats without the author re-entering anything. +**Shape where the answers go.** On submit, answers usually feed one or more downstream systems — a JSON API, a legacy XML system, a CSV spreadsheet. The author maps each field to each format, previews the result, adjusts. One submission can feed many formats without re-entry. -**Preview and test.** See the form as a respondent would see it — on a phone, a tablet, a desktop. Fill it in with sample answers and watch the conditional logic, calculations, and validation react in real time. Inspect which rules are firing and why. Feed a saved response in and check whether it would pass validation. +**Preview and test.** See the form as a respondent sees it — phone, tablet, desktop. Fill it with sample answers and watch the logic, calculations, and validation react live. Inspect which rules fire and why. Feed in a saved response and check whether it would pass validation. **Converse with the AI.** Two moments: -- *When the form is empty or very early*, the AI interviews the author, asks what they're trying to build, and produces a first draft to work from. -- *Once a form exists*, the author can ask the AI to change it — "add an email field with validation", "split the address into street, city, state, zip", "make the budget section only appear for large grants". The AI makes the changes, shows what it did, and the author can accept, reject, or modify. -The two moments may be one surface or two, one mode or many. That's a design question. +- *Empty or early form.* The AI interviews the author, asks what they're building, and produces a first draft. +- *Existing form.* The author asks the AI to change it: "add an email field with validation," "split the address into street, city, state, zip," "make the budget section appear only for large grants." The AI changes the form, shows what it did, and the author accepts, rejects, or modifies. -**Review what the AI did.** When the AI proposes changes, the author needs to see what's changing before committing to it — a clear before/after, grouped into a coherent unit the author can accept or reject as a whole. After the changes are accepted, they're undoable like any other edit. +The two moments may share one surface or split into two. That is a design question. -**See problems that need attention.** Contradictions between rules, low-confidence choices the AI made, missing configuration, references to things that don't exist, rules that can never fire — these surface as a reviewable queue with severities. The author can resolve an issue, defer it, or reopen one they resolved. +**Review what the AI did.** The author sees a clear before/after before accepting — changes grouped into one coherent unit, accepted or rejected as a whole. Once accepted, changes undo like any other edit. -**Undo and redo.** Every change — whether the author made it or the AI made it — is reversible. The author can walk back any number of steps. +**See problems.** A queue surfaces issues with severities: contradictions between rules, low-confidence AI choices, missing configuration, references to things that don't exist, rules that can never fire. The author resolves an issue, defers it, or reopens one they resolved. -**Save, leave, come back.** Authors close tabs, walk away, crash their browser, and come back the next day. Their work is still there, the conversation with the AI is still there, and they can pick up where they left off. Authors can also have several forms in flight, list them, and switch between them. +**Undo and redo.** Every change reverses — whether the author or the AI made it. The author walks back any number of steps. -**Export and hand off.** At any point, the author can export the form as a set of files to hand to a developer, save to a shared drive, or check into version control. +**Save, leave, come back.** Authors close tabs, walk away, crash, and return the next day. The form is still there. The conversation is still there. They pick up where they left off. Authors can also keep several forms in flight, list them, and switch between them. -**Work at real form sizes.** Real forms are often 50–300 fields with dozens of rules, several pages, and multiple repeatable sections. Finding a specific field, filtering to the rules that apply to a given field, searching across the whole form — these stop being nice-to-haves once the form gets past about 30 fields. +**Export and hand off.** At any point, the author exports the form as files — to a developer, a shared drive, or version control. -**Set form-level metadata.** Title, description, version, status, page mode, density. There are also specialized sidecar documents — translations into other languages, citations to regulations, semantic tagging that ties fields to standard medical or legal concepts — that only certain kinds of authors (multilingual forms, regulated forms, clinical forms) will ever touch. Whether and how those surface in Studio is a scope question worth flagging. +**Work at real form sizes.** Real forms run 50–300 fields with dozens of rules, several pages, and multiple repeatable sections. Finding a field, filtering rules by field, searching across the form — these stop being nice-to-haves past about 30 fields. + +**Set form metadata.** Title, description, version, status, page mode, density. Specialized sidecar documents also exist — translations, regulatory citations, semantic tagging for medical or legal concepts — that only some authors will touch. Whether and how those surface in Studio is a scope question worth flagging. --- ## 7. What can't change -A few things about the product are load-bearing — the design can express them in any form, but it can't work around them. +A few things are load-bearing. The design can express them any way, but not work around them. -**The author works in concepts, not code.** Program managers don't write code or read raw form files. The design cannot require them to. +**The author works in concepts, not code.** Program managers do not write code or read raw form files. The design cannot require them to. -**The form's logic is Excel-like formulas.** The author will occasionally read and tweak them, mostly with the AI's help. The design needs a place for formulas — writing, reading, debugging — that feels like editing a spreadsheet formula, not like editing code. +**The form's logic is Excel-like formulas.** The author occasionally reads and tweaks them, mostly with the AI's help. Give formulas a place — writing, reading, debugging — that feels like editing a spreadsheet formula, not like editing code. -**The AI is always reviewable and reversible.** Anything the AI does has to be visible, understandable, and undoable. The design has to answer: when the AI does something, how does the author see it, evaluate it, and keep or roll it back? +**The AI is always reviewable and reversible.** Everything the AI does must be visible, understandable, and undoable. Answer: when the AI acts, how does the author see it, evaluate it, and keep or roll it back? -**There are two kinds of rules and the difference matters.** Rules that attach to a single field ("is this required?", "what's the computed value?") and rules that span the form ("does the budget balance?", "is the start date before the end date?") are structurally different — the cross-form ones also have severities and timing. The design should make the distinction legible or the author will conflate them. +**Two kinds of rules. The difference matters.** Field rules ("is this required?", "what's the computed value?") and form rules ("does the budget balance?", "is the start date before the end date?") are structurally different. Form rules also carry severity and timing. Make the distinction legible or the author will conflate them. -**Several concerns are separate on purpose.** The form's data model, its visual theme, its layout, and its downstream output are different things. Changing one doesn't and shouldn't change the others. The design can hide that separation from the author's attention, but the *benefits* (swap the theme, reuse the data model, re-target the output) should come through as natural moments in the product. +**Several concerns are separate on purpose.** Data model, theme, layout, downstream output — different things. Changing one does not change the others. The design can hide the separation from the author's attention, but the *benefits* (swap the theme, reuse the data, retarget the output) should surface as natural product moments. -**Preview is real.** What the author sees in preview is exactly what a respondent will see — same logic, same calculations, same validation. The design can lean on this truthfully. +**Preview is real.** What the author sees in preview is what a respondent sees — same logic, same calculations, same validation. Lean on this truthfully. -**The form must work at 200+ fields.** Not 20. The design should anticipate real forms, which means search, filter, scoping, and navigation at scale matter early. +**The form must work at 200+ fields. Not 20.** Real forms are large. Search, filter, scoping, and navigation at scale matter from the start. -**Accessibility is first-class.** Government, nonprofit, and clinical audiences often require accessibility conformance. Studio itself should meet accessibility standards, and Studio should help authors produce forms that meet them (for example, by surfacing when a field is missing a label). +**Accessibility is first-class.** Government, nonprofit, and clinical audiences often require accessibility conformance. Studio itself must meet accessibility standards, and it must help authors produce forms that do — for instance, by flagging a field without a label. -**Authors walk away and come back.** Sessions persist. Both the form in progress and the conversation with the AI should still be there the next morning, in another tab, or after a crash. +**Authors walk away and come back.** Sessions persist. The form in progress and the AI conversation remain, in a new tab, the next morning, after a crash. --- ## 8. Today's Studio, at a product level -A brief description of what the current version of Studio does, so you know what exists to react to. You'll be given access to a running instance to look at. Use it to understand the capability surface; do not use it as a layout proposal. +A short description of what the current Studio does, so you know what exists to react to. A running instance is available. Use it to understand the capability surface. Do not treat it as a layout proposal. -- The workspace is organized around a set of **tabs** — one for the form's structure, one for its logic, one for reference data (options, formulas, external sources), one for the visual layout, one for the theme, one for the downstream output mapping, and one for preview. -- There is a **sidebar** on one side that lets the author jump between views of the form — its structure, its variables, its options, its settings, and so on — with counts showing how many of each thing exist. -- There is a **properties panel** on the other side that changes based on whatever is currently selected. -- There is a **header** with the tab switcher, undo/redo, import/export, and a search palette. -- **Two separate AI surfaces** exist today — one embedded in the editor (for refining an existing form) and one standalone (for starting a form from a conversation). A single unified conversational experience would be welcome. -- **Preview** has a viewport switcher, a place to feed in sample answers, and a diagnostics panel that shows which rules are firing. -- An **issue queue** shows problems the AI or the system has flagged. +- The workspace organizes around **tabs** — structure, logic, reference data (options, formulas, external sources), layout, theme, downstream mapping, and preview. +- A **sidebar** lets the author jump between views of the form — structure, variables, options, settings — with counts for each. +- A **properties panel** on the other side changes with whatever is selected. +- A **header** holds the tab switcher, undo/redo, import/export, and a search palette. +- **Two separate AI surfaces** exist today — one embedded in the editor for refining an existing form, one standalone for starting a form from a conversation. A single unified experience would be welcome. +- **Preview** has a viewport switcher, a place to feed in sample answers, and a diagnostics panel showing which rules fire. +- An **issue queue** surfaces problems the AI or the system has flagged. -That's one answer to what's described in this brief. The exercise is to explore different answers. +That is one answer to the brief. The exercise is to explore others. --- ## 9. Questions a good exploration answers -Any direction you propose should have a point of view on these. You don't need to answer all of them in words — your design should answer them by the way it's put together. +Every direction should have a point of view on these. The design should answer them by how it is put together, not in words. 1. What does a first-time author see in the first ten seconds, and what does the product look like it is for? 2. How does an author go from "I need a form" to "I have a first draft"? -3. How does conversation relate to direct manipulation — and what does it feel like when the author switches between them mid-task? -4. When the AI does something, how does the author see what changed and decide whether to keep it? -5. Where do the form's rules live, and how does the author not get lost in them at 40+ rules? +3. How does conversation relate to direct manipulation, and how does switching between them mid-task feel? +4. When the AI acts, how does the author see what changed and decide whether to keep it? +5. Where do the form's rules live, and how does the author stay oriented at 40+ rules? 6. When and where does the author see the form-as-respondent? Is preview a mode, a companion, an overlay, or something else? -7. How do the benefits of separation of concerns (swap the theme, reuse the data model, retarget the output) show up as natural moments in the product? +7. How do the benefits of separation — swap the theme, reuse the data model, retarget the output — surface as natural product moments? 8. How does search and navigation work at 200 fields? -9. What does a broken form look like — a rule that can never fire, a reference to a field that doesn't exist, a failed import? +9. What does a broken form look like — a rule that can never fire, a reference to a missing field, a failed import? 10. What does the product look like three months into the life of a real form, when the author is maintaining it rather than building it? --- ## 10. The real tension -Studio has to do two things at once. +Studio must do two things at once. -It has to be a tool a program manager uses for hours at a stretch to build and maintain a correct, complex, high-stakes form. That's craft work — restrained, legible, forgiving, designed for the ninety-eighth minute of use, not the first. +It must be a tool a program manager uses for hours to build and maintain a correct, complex, high-stakes form. That is craft work — restrained, legible, forgiving, built for the ninety-eighth minute of use, not the first. -It *also* has to be the most visible surface of the Formspec project — the thing someone sees in a screenshot or a short demo before they decide whether any of this is worth their attention. That means the design has to look, at a single glance, like something meaningfully different from the form builders it competes with. Because it is. +It must *also* be the most visible surface of the Formspec project — the thing someone sees in a screenshot or a short demo before deciding whether any of this is worth their attention. The design must look, at a glance, meaningfully different from the form builders it competes with. Because it is. -These two pressures reinforce each other when they can (a tool that's a pleasure to use for hours is also a tool that demos well) and pull apart when they can't (flourishes that look great in a hero shot get in the way at hour six; depth takes a walkthrough to appreciate). The brief is to hold both. A direction that only serves the program manager will be competent and invisible. A direction that only serves the screenshot will be beautiful and unusable. +The two pressures reinforce each other when they can: a tool that pleases for hours also demos well. They pull apart when they can't: hero-shot flourishes get in the way at hour six, and depth takes a walkthrough to appreciate. Hold both. A direction that serves only the program manager will be competent and invisible. A direction that serves only the screenshot will be beautiful and unusable. --- ## 11. What we're asking for -**Multiple exploratory directions, each a functional demo**, not one refined design. Ideally three to five distinct directions that take genuinely different positions on the open questions — different relationships between conversation and direct manipulation, different answers to where preview lives, different takes on how the author navigates a large form, different visual languages, different mental-model anchors. Pick directions that you think have merit; the goal is to widen the space of what Studio could be before we narrow. +**Multiple exploratory directions, each a functional demo.** Not one refined design. Ideally three to five distinct directions, each taking a different position on the open questions: different relationships between conversation and direct manipulation, different homes for preview, different takes on navigating a large form, different visual languages, different mental-model anchors. Pick directions you believe in. Widen the space before we narrow it. -Each direction should be a runnable application that a person can sit down with, open, and use for at least one canonical end-to-end flow — opening an empty state, going from "I need a form" to a first draft through conversation, making at least one meaningful edit by direct manipulation, seeing the AI respond to a follow-up request with a visible and reviewable change, previewing the form as a respondent, and handing off the result. Real interactions beat mocked ones. If the demo requires stubbing somewhere (for example, using a scripted AI response rather than a live one), that's fine — mark it clearly and keep the stubbed behavior faithful to what the real thing would do. +Each direction should be a runnable application that a person can open and use for one canonical end-to-end flow: land in an empty state, go from "I need a form" to a first draft through conversation, make at least one meaningful edit by direct manipulation, watch the AI respond to a follow-up with a visible and reviewable change, preview the form as a respondent, hand off the result. Real interactions beat mocked ones. Stubs are fine where necessary — a scripted AI response rather than a live one, for example — but mark them clearly and keep them faithful to what the real thing would do. Fidelity guidance: -- **High enough to read the direction.** Typography, spacing, rhythm, motion, and state transitions matter — they carry more than half of what a direction is trying to say. Rough sketches in code will read as rough sketches. -- **Coverage over polish.** Better to have the full end-to-end flow working at medium fidelity than one beautiful screen and dead links everywhere else. -- **Edge cases on the canonical flow only.** Empty state, loading state, AI-is-thinking state, error state, and "the author made a choice that needs confirmation" state should exist along the canonical flow. You do not need to cover every field type, every rule kind, every sidecar, or every import source. +- **High enough to read the direction.** Typography, spacing, rhythm, motion, and state transitions carry more than half of what a direction is saying. Rough sketches in code read as rough sketches. +- **Coverage over polish.** A full end-to-end flow at medium fidelity beats one beautiful screen with dead links around it. +- **Edge cases on the canonical flow only.** Empty state, loading state, AI-thinking state, error state, and "the author made a choice that needs confirmation" state should exist along the canonical flow. You do not need every field type, every rule kind, every sidecar, or every import source. -Use real form content throughout. We'll provide canonical example forms to work from. No lorem ipsum; it undermines the whole point. +Use real form content throughout. We will provide canonical example forms. No lorem ipsum. Deliver each direction with: -1. A short written framing — what this direction's point of view is and why you took it. +1. A short written framing: what this direction's point of view is and why you took it. 2. The running demo. -3. A ~2 minute walkthrough video demonstrating the canonical flow, with voiceover explaining what the direction is doing differently. -4. A summary of what the direction does better than the others and where it pays for it. +3. A ~2 minute walkthrough video of the canonical flow, with voiceover explaining what the direction does differently. +4. A summary: what this direction does better than the others, and where it pays for it. -If you have strong opinions about what's wrong with the brief itself, build them into the demos as counter-proposals rather than marginal comments. A direction that ignores part of the brief because you think we're wrong is welcome — just tell us which part and why. +If you have strong opinions about the brief, build them into the demos as counter-proposals. A direction that ignores part of the brief because you think we are wrong is welcome. Tell us which part, and why. --- ## 12. What you'll have access to -**The Formspec stack is available to you.** You're building real demos, so you have real resources: +**The Formspec stack is yours.** You are building real demos, so you have real resources. -- **The form runtime.** The engine that actually renders and runs Formspec forms — live preview, conditional logic, calculations, validation — is available as an open-source package you can drop into your demo. Preview should use the real engine; that's one of the few truthful promises the product can make. Don't mock it. -- **The authoring API.** Programmatic access to create, modify, and manipulate form definitions, themes, components, and mappings. Every mutation you make in a demo should go through it, so undo/redo, audit history, and AI tool-calling all just work. This also means the AI half of your demo has a real surface to call into — you don't need to simulate what the AI can do. -- **AI integration.** There is a working integration with a major model provider for both scaffolding (producing a first draft from a conversation) and refinement (modifying an existing form through a conversation). You can use the live integration or stub it for reliability in the demo. If stubbing, use real scripts captured from the live integration, not made-up dialog. -- **Example form content.** Two to three canonical example forms at different complexity levels — a small one (a grant budget), a medium one (a patient intake), and a large one (a regulatory application or tax form). Use them in every demo so the directions are directly comparable. -- **Today's Studio.** A running instance to look at. You have its source as a reference if you want to see how any of the capabilities above are used today. You do not need to match its structure; treat it as one possible answer. -- **Formspec brand assets** — logo, typography, palette — where they exist. Where they don't, or don't fit a direction, propose. -- **Subject-matter experts.** Access to people who know the product, the specification, and the audiences. Ask questions in writing or synchronously; don't guess in the dark on things that have known answers. +- **The form runtime.** An open-source package that renders and runs Formspec forms — live preview, conditional logic, calculations, validation. Preview should use the real engine. That is one of the few truthful promises the product can make. Do not mock it. +- **The authoring API.** Programmatic access to create and modify form definitions, themes, components, and mappings. Route every mutation through it. Undo/redo, audit history, and AI tool-calling then all work. The AI half of your demo has a real surface to call into. +- **AI integration.** A working integration with a major model provider, for both scaffolding (first draft from conversation) and refinement (modifying an existing form through conversation). Use the live integration, or stub for reliability. If stubbing, use real scripts captured from the live integration, not invented dialog. +- **Example form content.** Two or three canonical forms at different sizes — a small one (grant budget), a medium one (patient intake), a large one (regulatory application or tax form). Use them in every demo so the directions compare directly. +- **Today's Studio.** A running instance and its source, as reference. Do not match its structure. Treat it as one possible answer. +- **Formspec brand assets** — logo, typography, palette — where they exist. Where they do not, or where they do not fit a direction, propose. +- **Subject-matter experts.** People who know the product, the specification, and the audiences. Ask, in writing or synchronously. Do not guess in the dark on answerable questions. -**What you don't need to build.** Authentication, storage, deployment, billing, real-time collaboration, workflow after submission, or anything downstream of "the form is authored and ready to hand off." The demos end when the author hands off a finished form. What happens next is out of scope. +**What you do not need to build.** Authentication. Storage. Deployment. Billing. Real-time collaboration. Workflow after submission. Anything downstream of "the form is authored and ready to hand off." The demos end at hand-off. -**What the demos are not.** Not production software. Not a single shared system behind all the directions. Not responsive to every viewport. Not internationalized. Not instrumented. Not accessible-conformant (though the design should not obviously violate accessibility — keyboard operability, focus management, and sensible contrast are table stakes even at demo fidelity). Each direction is a disposable exploration built to answer "what could this feel like" and nothing more. +**What the demos are not.** Not production software. Not a single shared system behind all directions. Not responsive to every viewport. Not internationalized. Not instrumented. Not accessibility-conformant — though the design should not obviously violate accessibility. Keyboard operability, focus management, and sensible contrast are table stakes even at demo fidelity. Each direction is a disposable exploration, built to answer "what could this feel like," and nothing more.