docs(studio): add design handoff for original Studio redesign#9
Open
mikewolfd wants to merge 8 commits into
Open
docs(studio): add design handoff for original Studio redesign#9mikewolfd wants to merge 8 commits into
mikewolfd wants to merge 8 commits into
Conversation
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.
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.
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 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.
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.
… 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.
…demos 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.
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
mikewolfd
added a commit
that referenced
this pull request
Apr 27, 2026
Points to Trellis main at 374248c. Two new decision documents: - thoughts/adr/0007-certificate-of-completion-composition.md — ADR 0007 (human-readable signed-artifact binding; unblocks sequence item #9) - thoughts/specs/2026-04-24-hpke-crate-spike.md — HPKE crate selection (picks rozbb/rust-hpke; unblocks sequence item #6) Both TODO sequence items now reference their design anchor inline instead of naming execution work without a pinned decision. Co-Authored-By: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.