docs: ADR-0084 app-builder IA + builder UI design doc - #2503
Merged
Merged
Conversation
Records the builder IA converged on over an extended design pass: the app builder is for BUILDING AN APP only. Four visual content pillars — Data · Automation · Interface · Access (Airtable's three plus the one it lacks) — each with an editor matched to its natural shape (grid / canvas / builder / matrix). Dashboards live in Interface (Analytics splits out later, gated on the dataset layer). A Settings area holds General (the app's basic info) and Advanced — the technical tier unified by audience (developers), holding both Code (hooks now; functions, custom components later) and Connections (datasources, connectors, webhooks) — so there is no separate Integration tier. Operate (ship/run) and Platform (AI, i18n, templates, plugins) are out of the builder entirely — different personas, different surfaces. v1 ships the four pillars + Settings (General + Advanced/Hooks). Refines ADR-0083 for the builder surface (AI is a platform capability, not a pillar; Integration folds into Advanced). Records the alternatives rejected along the way (6 flat pillars, Analytics-in-v1, Integration-as-tier, AI-as-pillar, Operate/Platform-in-builder, implicit auto datasets). Related: #2501, #2502. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
size/s
documentation
ADR-0083 (metadata-type taxonomy) was voided (#2499 closed); 0084 subsumes the builder-relevant taxonomy. Remove the Builds-on citation and the Relationship section — their content (AI is a platform capability not a pillar; Integration folds into Advanced) already lives in the TL;DR and Alternatives. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Living companion to ADR-0084. Captures the shared 3-zone shell (pillar tabs / left rail / main work surface / right inspector / draft-publish), the design principles (facet=tab item=inspector, grid-primary via default tab, small-config→inspector big-designer→main, two-doors, same-renderer, no-modal), and the Data pillar in detail (object facet tabs with Records grid default, field manager, Validations grounded in the real 6-type ValidationRuleSchema, v1 scope). TODO placeholders for the other pillars. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
os-zhuang
changed the title
Correct the Data pillar: Records = grid/list-style field designer (preview data, add columns, select column → configure field), Fields = form-style field designer (drag-reorder, section grouping, field-property config). Both design the same fields and share the right-hand field editor. Drop the earlier claim that grouping lives only in Interface — the object's default field layout (order + grouping) is authored in the Fields form designer. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add §1 north star: every layout decision is judged by whether AI can generate the artifact in one shot, whether the design prevents AI mistakes, and whether a human can confirm it in one pass. Ties these to the concrete mechanisms already in the shell (same-renderer, declarative/constrained surfaces, os validate gates, draft diff per ADR-0033, no-modal). Also record the rationale for keeping the Records/Fields tab names over Grid/Form. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add the fourth core constraint — reuse Studio's protocol-generated metadata forms, never hand-roll config UI — and a Build-boundary section that answers how code written against this doc stays correct: the novel surface is only the shell/composition; the grid (ListView) and every inspector panel (protocol forms) are reused by reference. Commit an SVG wireframe of the Data pillar shell (rail/tabs/grid/inspector) with a solid=built / dashed=reused legend, embedded in the doc as the visual target. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
HTML is the better artifact for AI to build against and scales to the many surfaces still to design: the DOM maps ~1:1 to the component tree, and each region is tagged data-build="shell" (built) or data-reuse="<component>" (existing Studio/objectui component to drop in), making the build boundary machine-readable. shell.css holds shared tokens + layout primitives so each new pillar mockup is a small, consistent file. Data pillar mockup added; inline ASCII kept for quick reading. No committed PNGs — open the .html. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…s caption Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This branch was successfully deployed
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.
What
Two companion docs for the application builder:
ADR-0084 — the information architecture (the decisions): 4 content pillars
Data / Automation / Interface / Access + Settings (General + Advanced),
AI as a platform capability (not a pillar), Integration folded into Advanced,
Operate/Platform out of the builder. Records what was chosen and what was rejected.
docs/design/builder-ui.md— the UI design (a living doc, the how-it-looks):the shared 3-zone shell (pillar tabs · left rail · main work surface · right
inspector · draft/publish), the design principles (facet=tab / item=inspector,
grid-primary via a default
Recordstab, small-config→inspector /big-designer→main, two-doors, same-renderer, no-modal), and the Data pillar in
detail (object facet tabs, field manager, Validations grounded in the real 6-type
ValidationRuleSchema, v1 scope). TODO placeholders for Automation / Interface /Access / Settings — it grows as those are designed.
Why the split
ADR = why it's decided this way, what's excluded (bound, stable). Design doc =
what it looks like, how it's used (living, iterated). Keeping them separate lets the
UI evolve without re-opening the IA decision.
Scope
Docs only. No code.