Skip to content

Commit 9c18bfe

Browse files
hotlongclaude
hotlong
and
claude
committed
docs(design): switch mockups to annotated HTML, drop SVG
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>
1 parent da0e098 commit 9c18bfe

4 files changed

Lines changed: 284 additions & 140 deletions

File tree

‎docs/design/builder-ui.md‎

Lines changed: 58 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,11 @@ does **not** re-specify the per-item config panels: those are Studio's existing
1111
protocol-generated metadata forms, reused as-is (§1.4). What the builder actually
1212
builds is the composition; the panels are dropped in.
1313

14+
Each surface has an **HTML mockup** under [`builder-ui/`](./builder-ui/) — the precise
15+
visual target and, because its DOM maps to the component tree and its regions are
16+
tagged `data-build` / `data-reuse`, the implementation blueprint (see
17+
[Mockups](#mockups)). The ASCII sketches inline below are for quick reading.
18+
1419
---
1520

1621
## 1. Core constraints — AI-first, human-confirmable, reuse-first
@@ -56,16 +61,29 @@ shrink the novel surface to almost nothing:
5661
config panel in the inspector (Studio protocol-generated forms). These are
5762
referenced by name; the builder composes them, it does not reimplement them.
5863

59-
Solid vs. dashed in the wireframes marks this boundary.
64+
In every mockup this boundary is explicit: regions carry `data-build="shell"` or
65+
`data-reuse="<component>"`, and reused blocks are drawn with a dashed outline.
6066

6167
---
6268

6369
## 2. The shell (every pillar shares it)
6470

65-
![Data pillar shell — rail, facet tabs, grid, inspector](./builder-ui/data-pillar.svg)
66-
67-
*Solid frame = shell/composition built in the builder; dashed frame = existing Studio
68-
component (grid = ListView; inspector = protocol-generated form) reused as-is.*
71+
```
72+
┌───────────────────────────────────────────────────────────────────┐
73+
│ app ▾ Data · Automation · Interface · Access ⚙ Save · Publish │ ← top bar
74+
├─────────┬───────────────────────────────────────────┬──────────────┤
75+
│ left │ main (the work surface) │ right │
76+
│ rail │ + a per-entity facet tab bar (see Data) │ inspector │
77+
│ entities │ grid / canvas / builder / matrix │ = selected │
78+
│ + search │ ───────────────────────────────────── │ item's │
79+
│ + new │ [ reused renderer, e.g. ListView ] │ config │
80+
│ │ │ [reused form] │
81+
├─────────┴───────────────────────────────────────────┴──────────────┤
82+
│ legend: solid = built (shell) · dashed = reused (Studio component) │
83+
└───────────────────────────────────────────────────────────────────┘
84+
```
85+
86+
Mockup: [`builder-ui/data-pillar.html`](./builder-ui/data-pillar.html) (open in a browser).
6987

7088
- **Top bar** — the four pillar tabs (Data / Automation / Interface / Access), the
7189
⚙ Settings entry, the app switcher, and the draft indicator + Save draft /
@@ -115,6 +133,18 @@ and validations, and work with records. Data owns the *data layer and the field
115133
designer*; runtime presentation surfaces (saved grid views, kanban, calendar, pages,
116134
dashboards) belong to Interface.
117135

136+
Mockup: [`builder-ui/data-pillar.html`](./builder-ui/data-pillar.html).
137+
138+
```
139+
┌ objects ─┬ Task ┈ Records · Fields · Validations │ Actions · Hooks · ⋯ ┬ inspector ┐
140+
│ Account │ ┌ filter · sort · hide ─────────────────────────────────┐ │ Edit field │
141+
│ Task ◄ │ │ # Title Status [Priority ▾] + │ │ Priority │
142+
│ Project │ │ 1 Audit IA In review ● Medium │ │ type: select│
143+
│ Invoice │ │ 2 Design system In progress ● High │ │ options … │
144+
│ + New │ │ + New record │ │ required │
145+
└──────────┴─┴───────────────────────────────────────────────────────┴─┴────────────┘
146+
```
147+
118148
### Left rail
119149
The app's objects (v1: owned objects only), with search + New object.
120150

@@ -216,10 +246,27 @@ union of six declarative rule types (`packages/spec/src/data/validation.zod.ts`)
216246

217247
---
218248

219-
## Wireframes
220-
- [`builder-ui/data-pillar.svg`](./builder-ui/data-pillar.svg) — the Data pillar shell
221-
(rail · facet tabs · Records grid · field inspector), with the solid/dashed
222-
build-boundary legend.
249+
## Mockups
250+
251+
Mockups live under [`builder-ui/`](./builder-ui/) as **HTML**, not images — HTML is
252+
the better artifact for an AI to build against and it scales to the many surfaces
253+
still to design:
254+
255+
- **DOM ≈ component tree.** The markup maps almost 1:1 to the React components to
256+
build, so there is little to infer or get wrong.
257+
- **The build boundary is machine-readable.** Every region is tagged
258+
`data-build="shell"` (built in the builder) or `data-reuse="<component>"` (an
259+
existing Studio/objectui component — e.g. `ListView`, `protocol-form:field` — to
260+
drop in unchanged). Reused blocks render with a dashed outline.
261+
- **One shared look.** [`shell.css`](./builder-ui/shell.css) holds the tokens and
262+
layout primitives (top bar, rail, facet tabs, grid, inspector, form rows, toggles);
263+
each pillar mockup composes them, so a new surface is a small file and stays
264+
visually consistent for free.
265+
266+
Open any `*.html` in a browser to view it. Current mockups:
267+
268+
| Surface | Mockup |
269+
|---|---|
270+
| Data pillar | [`data-pillar.html`](./builder-ui/data-pillar.html) |
223271

224-
Wireframes are committed as SVG so they render on GitHub and stay the unambiguous
225-
visual target for implementation. More are added per pillar as they are designed.
272+
More are added per pillar as they are designed.

‎docs/design/builder-ui/data-pillar.html‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8">
5+
<title>Builder — Data pillar</title>
6+
<link rel="stylesheet" href="shell.css">
7+
</head>
8+
<body>
9+
<!-- Data pillar: object model workbench. Object "Task" selected, Records tab active,
10+
Priority column selected -> field editor in the inspector.
11+
data-build="shell" = built in the builder (composition/chrome)
12+
data-reuse="<comp>" = existing Studio/objectui component, dropped in unchanged -->
13+
<div class="builder">
14+
15+
<!-- ===== top bar (built) ===== -->
16+
<div class="topbar" data-build="shell">
17+
<span class="app">app &#9662;</span>
18+
<nav class="pilltabs">
19+
<a class="active" href="#">Data</a>
20+
<a href="#">Automation</a>
21+
<a href="#">Interface</a>
22+
<a href="#">Access</a>
23+
</nav>
24+
<div class="right">
25+
<span>&#9881;</span>
26+
<span>Save draft</span>
27+
<button class="btn-publish">Publish</button>
28+
</div>
29+
</div>
30+
31+
<div class="body">
32+
33+
<!-- ===== left rail: objects (built) ===== -->
34+
<aside class="rail" data-build="shell">
35+
<div class="label">OBJECTS</div>
36+
<div class="search">Search</div>
37+
<ul>
38+
<li>Account</li>
39+
<li class="active">Task</li>
40+
<li>Project</li>
41+
<li>Invoice</li>
42+
</ul>
43+
<div class="new">+ New object</div>
44+
</aside>
45+
46+
<!-- ===== main: facet tabs + Records grid ===== -->
47+
<main class="main">
48+
49+
<!-- object facet tabs (built) -->
50+
<nav class="facettabs" data-build="shell">
51+
<a class="active" href="#">Records</a>
52+
<a href="#">Fields</a>
53+
<a href="#">Validations</a>
54+
<span class="sep"></span>
55+
<a href="#">Actions <span class="tag">auto</span></a>
56+
<a href="#">Hooks <span class="tag">adv</span></a>
57+
<a href="#">&#8943;</a>
58+
</nav>
59+
60+
<!-- ephemeral view toolbar (built) -->
61+
<div class="toolbar" data-build="shell">
62+
<span>&#9906; Filter</span>
63+
<span>&#8597; Sort</span>
64+
<span>&#9640; Hide</span>
65+
<span>&#9638; Group</span>
66+
<span class="spacer"></span>
67+
<span class="add">+ New record</span>
68+
</div>
69+
70+
<!-- data grid = reused ListView renderer -->
71+
<div class="workarea">
72+
<div class="reuse" data-reuse="ListView">
73+
<table class="grid">
74+
<thead>
75+
<tr>
76+
<th class="muted">#</th>
77+
<th>Title</th>
78+
<th>Status</th>
79+
<th class="col-selected">Priority &#9662;</th>
80+
<th class="muted">+</th>
81+
</tr>
82+
</thead>
83+
<tbody>
84+
<tr><td class="muted">1</td><td>Audit IA</td><td class="muted">In review</td><td class="col-selected">&#9679; Medium</td><td></td></tr>
85+
<tr><td class="muted">2</td><td>Design system</td><td class="muted">In progress</td><td class="col-selected">&#9679; High</td><td></td></tr>
86+
<tr><td class="muted">3</td><td>API surface</td><td class="muted">Todo</td><td class="col-selected">&#9679; Low</td><td></td></tr>
87+
<tr><td class="muted">4</td><td>Release notes</td><td class="muted">Done</td><td class="col-selected">&#9679; Medium</td><td></td></tr>
88+
</tbody>
89+
</table>
90+
<div class="grid-add">+ New record</div>
91+
<span class="reuse-tag">grid = existing ListView renderer (reused)</span>
92+
</div>
93+
</div>
94+
</main>
95+
96+
<!-- ===== right inspector: field editor = reused protocol form ===== -->
97+
<aside class="inspector" data-build="shell">
98+
<div class="eyebrow">EDIT FIELD</div>
99+
<h3>Priority</h3>
100+
<hr>
101+
<div class="reuse form" data-reuse="protocol-form:field">
102+
<div class="flabel">Label</div>
103+
<div class="field">Priority</div>
104+
<div class="flabel">Type</div>
105+
<div class="field">Select &#9662;</div>
106+
<div class="flabel">Options</div>
107+
<div class="chips">
108+
<span class="chip">Low</span>
109+
<span class="chip">Medium</span>
110+
<span class="chip">High</span>
111+
<span class="add">+ add</span>
112+
</div>
113+
<div class="toggle-row"><span>Required</span><span class="toggle"></span></div>
114+
<div class="toggle-row"><span>Unique</span><span class="toggle"></span></div>
115+
<span class="reuse-tag">protocol-generated field form (reused)</span>
116+
</div>
117+
</aside>
118+
</div>
119+
120+
<!-- ===== legend ===== -->
121+
<div class="legend">
122+
<span><span class="sw built"></span>solid = shell / composition (built in the builder)</span>
123+
<span><span class="sw reused"></span>dashed = existing Studio component (reused, not rebuilt)</span>
124+
</div>
125+
</div>
126+
</body>
127+
</html>

‎docs/design/builder-ui/data-pillar.svg‎

Lines changed: 0 additions & 129 deletions
This file was deleted.

0 commit comments

Comments
 (0)