@agent-native/core 0.203.0-nightly-20261007064822 → 0.203.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agent/engine/builder-engine.d.ts +1 -1
- package/dist/agent/model-config.d.ts +2 -2
- package/dist/agent/model-config.js +0 -2
- package/dist/agent/thread-data-builder.d.ts +6 -0
- package/dist/agent/thread-data-builder.js +747 -25
- package/dist/agent/thread-message-projection.d.ts +20 -0
- package/dist/agent/thread-message-projection.js +300 -0
- package/dist/automation/index.d.ts +1 -1
- package/dist/chat-threads/store.d.ts +4 -1
- package/dist/chat-threads/store.js +92 -17
- package/dist/cli/skills-content/turn-into-app-skill.d.ts +10 -4
- package/dist/cli/skills-content/turn-into-app-skill.js +2454 -705
- package/dist/cli/skills.d.ts +6 -0
- package/dist/cli/skills.js +8 -2
- package/dist/client/chat/agentkit-agent-native.js +839 -89
- package/dist/client/chat/agentkit-protocol.js +67 -17
- package/dist/collab/routes.d.ts +2 -2
- package/dist/jobs/actions/manage-recurring-job.d.ts +1 -1
- package/dist/mcp/build-server.d.ts +5 -1
- package/dist/mcp/build-server.js +56 -13
- package/dist/mcp/embed-app.js +6 -1
- package/dist/notifications/routes.d.ts +1 -1
- package/dist/observability/routes.d.ts +3 -3
- package/dist/org/index.d.ts +2 -2
- package/dist/provider-api/actions/provider-api.d.ts +4 -4
- package/dist/resources/handlers.d.ts +1 -1
- package/dist/server/agent-chat/mcp-options.d.ts +4 -0
- package/dist/server/agent-chat-plugin.js +97 -22
- package/dist/server/agent-engine-default-model-route.d.ts +2 -2
- package/dist/server/onboarding-html.js +1 -1
- package/dist/server/realtime-token.d.ts +1 -1
- package/dist/server/transcribe-voice.d.ts +1 -1
- package/dist/shared/embed-auth.js +5 -4
- package/dist/sharing/actions/list-resource-shares.d.ts +1 -1
- package/dist/templates/factory/.agents/skills/review-latest-feedback/SKILL.md +26 -24
- package/dist/templates/factory/.agents/skills/review-latest-feedback/references/deployment-recovery.md +53 -0
- package/dist/templates/factory/.agents/skills/review-latest-feedback/references/documentation-proof.md +7 -0
- package/dist/templates/workspace-core/.agents/skills/turn-into-app/SKILL.md +284 -461
- package/dist/templates/workspace-core/.agents/skills/turn-into-app/agents/openai.yaml +2 -2
- package/dist/templates/workspace-core/.agents/skills/turn-into-app/references/fresh-project.md +65 -90
- package/dist/templates/workspace-core/.agents/skills/turn-into-app/references/local-run-and-deploy.md +161 -0
- package/dist/templates/workspace-core/.agents/skills/turn-into-app/references/review-loop.md +384 -0
- package/dist/templates/workspace-core/.agents/skills/turn-into-app/references/source-brief.md +116 -0
- package/dist/templates/workspace-core/.agents/skills/turn-into-app/references/spreadsheet-source.md +206 -190
- package/dist/templates/workspace-core/.agents/skills/turn-into-app/references/ui-archetypes.md +381 -0
- package/dist/templates/workspace-core/.agents/skills/turn-into-app/references/ui-direction.md +323 -0
- package/dist/templates/workspace-core/.agents/skills/turn-into-app/references/ui-palettes.md +564 -0
- package/dist/triggers/actions/manage-automation.d.ts +7 -7
- package/docs/content/observability.mdx +136 -0
- package/package.json +4 -4
- package/src/templates/factory/.agents/skills/review-latest-feedback/SKILL.md +26 -24
- package/src/templates/factory/.agents/skills/review-latest-feedback/references/deployment-recovery.md +53 -0
- package/src/templates/factory/.agents/skills/review-latest-feedback/references/documentation-proof.md +7 -0
- package/src/templates/workspace-core/.agents/skills/turn-into-app/SKILL.md +284 -461
- package/src/templates/workspace-core/.agents/skills/turn-into-app/agents/openai.yaml +2 -2
- package/src/templates/workspace-core/.agents/skills/turn-into-app/references/fresh-project.md +65 -90
- package/src/templates/workspace-core/.agents/skills/turn-into-app/references/local-run-and-deploy.md +161 -0
- package/src/templates/workspace-core/.agents/skills/turn-into-app/references/review-loop.md +384 -0
- package/src/templates/workspace-core/.agents/skills/turn-into-app/references/source-brief.md +116 -0
- package/src/templates/workspace-core/.agents/skills/turn-into-app/references/spreadsheet-source.md +206 -190
- package/src/templates/workspace-core/.agents/skills/turn-into-app/references/ui-archetypes.md +381 -0
- package/src/templates/workspace-core/.agents/skills/turn-into-app/references/ui-direction.md +323 -0
- package/src/templates/workspace-core/.agents/skills/turn-into-app/references/ui-palettes.md +564 -0
|
@@ -0,0 +1,323 @@
|
|
|
1
|
+
# UI direction for generated apps
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
|
|
5
|
+
1. Precedence
|
|
6
|
+
2. The first viewport is the user's world
|
|
7
|
+
3. Pick the archetype
|
|
8
|
+
4. Pick the direction and record it
|
|
9
|
+
5. Shell and agent instructions
|
|
10
|
+
6. Sample data
|
|
11
|
+
7. Agent moments the user can watch
|
|
12
|
+
8. Craft floor
|
|
13
|
+
9. Anti-patterns
|
|
14
|
+
|
|
15
|
+
## 1. Precedence
|
|
16
|
+
|
|
17
|
+
- The user's explicit direction and an existing brand win over this guide.
|
|
18
|
+
- For the domain surface, this guide wins over any installed design skill,
|
|
19
|
+
including the scaffold's own `frontend-design` and `DESIGN.md`: it sets the
|
|
20
|
+
populated first viewport, per-object agent verbs, filters, and the
|
|
21
|
+
direction's token block (the scaffold's neutral tokens are the starting
|
|
22
|
+
point, not a theme to preserve). Keep those skills' shadcn, chrome,
|
|
23
|
+
accessibility, and polish rules.
|
|
24
|
+
- Chrome rules (titles, eyebrows, subtitles, stat strips, helper text) limit
|
|
25
|
+
decoration, never the amount of real data on screen.
|
|
26
|
+
- The source's stated context of use sets the viewport you design first (a
|
|
27
|
+
phone between calls, a wall display, print). Design that one first and
|
|
28
|
+
still pass the other. A one-page reading column is right inside a pane
|
|
29
|
+
layout when the user reads it on a phone; the no-centered-column rule is
|
|
30
|
+
about page chrome around the data.
|
|
31
|
+
|
|
32
|
+
## 2. The first viewport is the user's world
|
|
33
|
+
|
|
34
|
+
The app is a place, not a procedure. A source describes steps; the app shows
|
|
35
|
+
the objects those steps act on, and the steps become status on them (Draft,
|
|
36
|
+
Checked, Approved). At 1440x900 the domain object (grid, board, chart,
|
|
37
|
+
document, table) fills most of the viewport, populated, with one visible agent
|
|
38
|
+
verb. Names, dates, and numbers are content. Keep non-data text in the first
|
|
39
|
+
viewport under about 40 words (the review script ignores record text and
|
|
40
|
+
document body marked `data-content`); explanation goes in a tooltip, a
|
|
41
|
+
popover, or a secondary region's empty state.
|
|
42
|
+
|
|
43
|
+
A stepper fits only when order is enforced and the artifact does not exist
|
|
44
|
+
until the last step, which almost never holds for a proven workflow. `Tabs`
|
|
45
|
+
switch peer views of the same data (Board | List, Sheet | App), never sequence.
|
|
46
|
+
A form is a Dialog, Popover, Sheet, or inline row editor behind an Add verb,
|
|
47
|
+
unless the form is the work (A12) or the input is the work (A11); then it is
|
|
48
|
+
the first object on screen, filled with a realistic sample, beside what it
|
|
49
|
+
produces. The agent composer takes free text.
|
|
50
|
+
|
|
51
|
+
## 3. Pick the archetype
|
|
52
|
+
|
|
53
|
+
Finish the sentence "the user looks at a **_ and acts on its _**", then open
|
|
54
|
+
that section of [ui-archetypes.md](ui-archetypes.md). One archetype per
|
|
55
|
+
destination; a second job gets its own navigation destination.
|
|
56
|
+
|
|
57
|
+
| The source is about | Archetype |
|
|
58
|
+
| ------------------------------------------------------------- | ------------------------------------- |
|
|
59
|
+
| incoming items to sort, reply to, approve | A1 Triage queue |
|
|
60
|
+
| items moving through stages | A2 Pipeline board |
|
|
61
|
+
| numbers, scenarios, a spreadsheet model | A3 Live workbench |
|
|
62
|
+
| time: appointments, shifts, releases, trips | A4 Schedule grid |
|
|
63
|
+
| generated artifacts to compare and refine | A5 Gallery and stage |
|
|
64
|
+
| proposed changes to accept or reject | A6 Review diff |
|
|
65
|
+
| sources turned into a brief, report, or one-pager | A7 Research brief |
|
|
66
|
+
| signals, alerts, health, spend over time | A8 Monitor |
|
|
67
|
+
| a procedure with state, owners, and evidence | A9 Runbook |
|
|
68
|
+
| many records to browse, score, enrich | A10 Directory |
|
|
69
|
+
| one input becomes a result to judge and reuse | A11 Transform pane |
|
|
70
|
+
| structured records captured through a form | A12 Entry form |
|
|
71
|
+
| a dialogue whose value is the structure extracted from it | A13 Conversation and artifact |
|
|
72
|
+
| none of these, or the main object vanishes in the nearest one | Custom ("No fit" in ui-archetypes.md) |
|
|
73
|
+
|
|
74
|
+
Pairings are common (a queue whose selected item opens as a document, A1 with
|
|
75
|
+
A7; a directory with a board view, A10 with A2; a workbench with a drill-down
|
|
76
|
+
table, A3 with A10). The first archetype picks the direction; the second only
|
|
77
|
+
borrows components. If the source's main object disappears in the archetype
|
|
78
|
+
you picked, you picked wrong.
|
|
79
|
+
|
|
80
|
+
## 4. Pick the direction and record it
|
|
81
|
+
|
|
82
|
+
Take the directions whose Fits column lists the first archetype. Among them,
|
|
83
|
+
take the one whose Domain column names the source's domain. If none or several
|
|
84
|
+
match, number those candidates from 0 in table order and take the one at
|
|
85
|
+
(length of the app slug) mod (number of candidates). Never choose by taste. A
|
|
86
|
+
direction outside the Fits column needs a one-line reason in `DESIGN.md`.
|
|
87
|
+
|
|
88
|
+
| Direction | Fits | Domain | Type | Accent |
|
|
89
|
+
| ------------- | ----------------------- | -------------------------------------------------- | ----------------------------------- | ------ |
|
|
90
|
+
| ledger | A3 A8 A10 A12 | finance, planning, forecasting, analytics | Geist, tabular figures | pine |
|
|
91
|
+
| control-room | A8 A1 A9 A10 | engineering, code, ops, incidents, security | Inter Tight, JetBrains Mono | amber |
|
|
92
|
+
| paper-desk | A7 A6 A9 A11 A13 | writing, research, policy, legal, education | Figtree, Source Serif 4 body | plum |
|
|
93
|
+
| studio-canvas | A5 A2 A11 | creative, media, design, marketing | Bricolage Grotesque, Hanken Grotesk | lime |
|
|
94
|
+
| tidepool | A4 A10 A9 A1 A2 A12 A13 | people, recruiting, HR, scheduling, support | Onest | teal |
|
|
95
|
+
| signal-board | A2 A1 A9 | sales, customer accounts, delivery, project status | Schibsted Grotesk | cobalt |
|
|
96
|
+
|
|
97
|
+
A brand in the source wins: its color goes in `--primary` and `--ring`, the
|
|
98
|
+
neutrals stay, and you still append a direction block and the shared block.
|
|
99
|
+
Apply the tokens from [ui-palettes.md](ui-palettes.md); a first screen on the
|
|
100
|
+
scaffold's grey tokens, or on a near-black primary, fails review.
|
|
101
|
+
|
|
102
|
+
Before appending to `DESIGN.md`, rename the scaffold's `## Visual direction`
|
|
103
|
+
heading to `## Chat route direction` and change its "Preserve the scaffold's
|
|
104
|
+
semantic tokens" guardrail to name your direction, so the in-app agent reads
|
|
105
|
+
one direction per surface. Then append a block like this:
|
|
106
|
+
|
|
107
|
+
```md
|
|
108
|
+
## <Route> surface
|
|
109
|
+
|
|
110
|
+
- Archetype: A3 Live workbench, with an A10 drill-down
|
|
111
|
+
- Direction: ledger (Fits A3, domain finance); tokens from ui-palettes.md
|
|
112
|
+
- Composition: drivers rail left, hero chart and period table right, agent
|
|
113
|
+
findings pinned on the chart
|
|
114
|
+
- Agent moments: Pressure-test (header) writes findings through `add-finding`
|
|
115
|
+
- Sample data: the workbook's own values, labelled snapshot; cleared from the
|
|
116
|
+
Sample data menu
|
|
117
|
+
- Signature: the one element only this domain has (pins on the chart that
|
|
118
|
+
link back to the source cells)
|
|
119
|
+
- Refuses: the default look this domain usually gets, and what replaces it
|
|
120
|
+
("a KPI-card strip over the table" becomes "one hero output in the chart
|
|
121
|
+
header")
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
## 5. Shell and agent instructions
|
|
125
|
+
|
|
126
|
+
- Add the domain route and a domain-named sidebar link; keep the chat route
|
|
127
|
+
and the agent sidebar. The app must open on the domain surface: set
|
|
128
|
+
`app.homePath` to the domain route. A standalone app whose slug differs from
|
|
129
|
+
the template has `server/plugins/agent-native-email-branding.ts` with
|
|
130
|
+
`homePath: "/home"` (the empty Chat): change only that value. When the file
|
|
131
|
+
is missing (a slug equal to the template name, or a workspace app), create
|
|
132
|
+
it:
|
|
133
|
+
|
|
134
|
+
```ts
|
|
135
|
+
import { defineAppConfig } from "@agent-native/core/server";
|
|
136
|
+
export default defineAppConfig({ app: { homePath: "/<route>" } });
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Then check that `/` lands on the route, and restart the dev server if it
|
|
140
|
+
does not. Other edit points in the chat scaffold: a route file under
|
|
141
|
+
`app/routes/`, a `<Link>` inside the `<nav>` of
|
|
142
|
+
`app/components/layout/Sidebar.tsx` before `<ChatThreadsSection />`, and the
|
|
143
|
+
route and selected ids in `app/hooks/use-navigation-state.ts`. Leave
|
|
144
|
+
`home.tsx`, `chat.$threadId.tsx`, `Layout.tsx`, and `root.tsx` as they are.
|
|
145
|
+
|
|
146
|
+
- Teach the in-app agent the new app. Rewrite the purpose line of `AGENTS.md`
|
|
147
|
+
and add one short section (routes, invariants, the action table with
|
|
148
|
+
unpadded cells, the new navigation fields, the sample-data rule), keeping
|
|
149
|
+
the file under about 5,500 characters (compact prompts cut it at 6,000). Put
|
|
150
|
+
the primary actions in `INITIAL_TOOL_NAMES` and a domain-specific system
|
|
151
|
+
prompt in `server/plugins/agent-chat.ts`, and the display name in
|
|
152
|
+
`rawAppTitle` in `app/lib/app-config.ts` (and `app.name` in the branding
|
|
153
|
+
plugin when it exists).
|
|
154
|
+
- The header title is the page's only title: no in-page H1, eyebrow, or
|
|
155
|
+
subtitle, and no heading row under the header that names the view again
|
|
156
|
+
("Findings" under "Audit workbench"). Put the view switcher or object name
|
|
157
|
+
in the header with `useSetPageTitle(node)` and the primary verb with
|
|
158
|
+
`useSetHeaderActions(node)`, both from `@agent-native/toolkit/app-shell`.
|
|
159
|
+
The title node must shrink: text in `<span className="min-w-0 truncate">`
|
|
160
|
+
with the full value in `title`. Header actions never shrink, so at 390px keep
|
|
161
|
+
one labelled button and turn the rest into icon buttons with `aria-label`,
|
|
162
|
+
or one overflow menu.
|
|
163
|
+
- Panes fill the viewport: the page root is `flex h-full min-h-0`, and each pane
|
|
164
|
+
scrolls itself. No `max-w-3xl mx-auto` page column; the A7 reading column is
|
|
165
|
+
the one exception.
|
|
166
|
+
- The nav rail takes 276px and the open agent sidebar 380px, so at 1440 the
|
|
167
|
+
domain surface is about 780px (1164px with the agent closed). Design
|
|
168
|
+
two-pane layouts for that width (a 280-320px list beside a detail of about
|
|
169
|
+
460px), collapse rails into popovers first, and reflow with container
|
|
170
|
+
queries (`@container`, `@3xl:`). Review the sidebar-open click shot too.
|
|
171
|
+
- Import controls from `@/components/ui/*`. When one is missing, add a one-line
|
|
172
|
+
re-export like the scaffold's `button.tsx`:
|
|
173
|
+
`export * from "@agent-native/toolkit/ui/<name>";`. The toolkit ships tabs,
|
|
174
|
+
badge, table, select, dialog, sheet, popover, slider, switch, toggle-group,
|
|
175
|
+
scroll-area, resizable, skeleton, empty, avatar, progress, checkbox,
|
|
176
|
+
separator, kbd, textarea, alert-dialog, and chart. Use
|
|
177
|
+
`pnpm dlx shadcn@latest add <name>` only for a component the toolkit lacks.
|
|
178
|
+
- Editable grids use `DataGrid` from `@agent-native/toolkit/data-grid`. Charts
|
|
179
|
+
use `ChartContainer` and `ChartTooltip` from `@/components/ui/chart` (a
|
|
180
|
+
re-export of the toolkit's) over `recharts`, added at the toolkit's own
|
|
181
|
+
range so one copy is installed:
|
|
182
|
+
`pnpm add recharts@"$(node -p "require('./node_modules/@agent-native/toolkit/package.json').dependencies.recharts")"`.
|
|
183
|
+
Icons come from `@tabler/icons-react`, one stroke weight.
|
|
184
|
+
- Long text (plans, briefs, notes, agent output) renders as formatted content:
|
|
185
|
+
fixed sections as structure, free text through `InlineMarkdown` (with
|
|
186
|
+
`renderLists`) from `@agent-native/toolkit/app/review`. Never raw `#` or
|
|
187
|
+
`**`, and never markdown in a monospace block.
|
|
188
|
+
- Confirm destructive actions with `AlertDialog`, never browser dialogs.
|
|
189
|
+
|
|
190
|
+
## 6. Sample data
|
|
191
|
+
|
|
192
|
+
- Derive it from the source's examples: the same fields, ranges, and edge
|
|
193
|
+
cases. Write synthetic lookalikes by default. Reuse the worked example's own
|
|
194
|
+
names and values only when the user supplied them for this app (a workbook,
|
|
195
|
+
a fixture) or the source marks them as fictional, and label them sample or
|
|
196
|
+
snapshot. Never include anything marked internal or confidential, and never
|
|
197
|
+
a real person's contact detail.
|
|
198
|
+
- Enough varied records to fill the archetype (a dozen or more by default),
|
|
199
|
+
with the edge cases the source mentions (overdue, conflict, blocked, missing
|
|
200
|
+
value). Numbers come from the same functions the UI uses, so totals agree
|
|
201
|
+
across views.
|
|
202
|
+
- Make it look real. Store dates as offsets from the seed moment ("2 days
|
|
203
|
+
ago", "Wed 14:00 this week") so the first viewport reads as now. Names are
|
|
204
|
+
unique; amounts are not all round; titles vary in length, with one over 60
|
|
205
|
+
characters and one 9-digit amount; optional fields are sometimes blank; each
|
|
206
|
+
status the UI shows has at least two records. Avoid Acme, John Doe, Foo, and
|
|
207
|
+
Test 1. A board lane holds 3-6 cards; merge or collapse a thinner one.
|
|
208
|
+
- Hazards stay visible: missing renders as missing, not 0; partial renders as
|
|
209
|
+
partial; untrusted text renders as text and never enters a prompt as an
|
|
210
|
+
instruction.
|
|
211
|
+
- Insert it with an idempotent action (for example `seed-sample-data`) that the
|
|
212
|
+
client calls once per user; never at module load, in a migration, or at
|
|
213
|
+
server start. Mark rows as sample. One "Sample data" menu entry clears them,
|
|
214
|
+
and the choice is remembered. No badge on every row.
|
|
215
|
+
- Media goes in `public/` or file storage, never SQL. A spreadsheet's sample is
|
|
216
|
+
the workbook's own bounded values, labelled as a snapshot.
|
|
217
|
+
|
|
218
|
+
## 7. Agent moments the user can watch
|
|
219
|
+
|
|
220
|
+
A control named in the source's verbs (Draft, Check, Pressure-test, Regenerate)
|
|
221
|
+
does four things:
|
|
222
|
+
|
|
223
|
+
1. At the click, the object enters a working state in local state, in the slot
|
|
224
|
+
where the result will land (the `working` shimmer, "Drafting", Cancel).
|
|
225
|
+
Then persist the status through an action so a reload and the agent see
|
|
226
|
+
it: `idle`, `agent_working`, `needs_review`, `accepted`, `failed`. Failed
|
|
227
|
+
never looks like idle.
|
|
228
|
+
2. It calls `sendToAgentChat` as SKILL.md step 4 describes, with the object id
|
|
229
|
+
and a bounded summary; `chatTarget: "local"` keeps the run in this app's
|
|
230
|
+
own agent when the app is embedded in another frame.
|
|
231
|
+
3. The agent writes the result through an action into the rows the UI renders;
|
|
232
|
+
the chat run refreshes action queries, so the object updates in place.
|
|
233
|
+
4. The result shows attribution and Accept, Edit, Retry.
|
|
234
|
+
|
|
235
|
+
An object never stays busy without a run behind it:
|
|
236
|
+
|
|
237
|
+
- Read `useAgentEngineConfigured()` from
|
|
238
|
+
`@agent-native/core/client/use-agent-engine-configured`. When `missing` is
|
|
239
|
+
true (no AI provider), the click still opens the sidebar on the shared
|
|
240
|
+
setup card, and the object shows "Connect AI to draft" instead of a working
|
|
241
|
+
state.
|
|
242
|
+
- If `isGenerating` from `useSendToAgentChat()` in
|
|
243
|
+
`@agent-native/toolkit/app/chat` has not turned true within about 8 seconds
|
|
244
|
+
of the click, or turns false without a result, set `failed` with "No agent
|
|
245
|
+
run finished" and Retry.
|
|
246
|
+
- The read action computes status: an `agent_working` row older than 10
|
|
247
|
+
minutes reads as `failed`.
|
|
248
|
+
|
|
249
|
+
Put the verb on the object (row, card, block, cell, section) and at most one
|
|
250
|
+
bulk verb in the header. Never a lone ghost "Ask agent" beside a primary
|
|
251
|
+
button, and never a control labelled as AI that changes nothing on the page.
|
|
252
|
+
|
|
253
|
+
Agent-authored content carries one mark everywhere: a 6px `--primary` dot,
|
|
254
|
+
"Agent, 4s" in `text-muted-foreground`, and a `bg-accent` tint on the block
|
|
255
|
+
until the user accepts or edits it.
|
|
256
|
+
|
|
257
|
+
## 8. Craft floor
|
|
258
|
+
|
|
259
|
+
- Contrast: text 4.5:1, large text and chart marks 3:1. Status is a dot plus a
|
|
260
|
+
label, never color alone.
|
|
261
|
+
- Color: one accent family for action, selection, and state; tinted neutrals.
|
|
262
|
+
Status and chart colors come from tokens (`text-ok`, `bg-bad/10`,
|
|
263
|
+
`stroke-chart-1`), never a Tailwind palette shade (red-100, gray-500), a
|
|
264
|
+
white or black utility, or hex in a route or component: those stay light in
|
|
265
|
+
dark mode.
|
|
266
|
+
- Type: one workhorse sans, tabular numbers for data, balanced headings, prose
|
|
267
|
+
at 65-75ch, sentence case.
|
|
268
|
+
- Surfaces: shadows over borders on cards and panels; concentric radii (outer
|
|
269
|
+
radius = inner radius + padding); a 1px low-opacity outline on images. Group
|
|
270
|
+
by proximity before boxing: tight groups, generous separation, more space
|
|
271
|
+
above a heading than below. A card gets a title or a description, never
|
|
272
|
+
both.
|
|
273
|
+
- Interaction: a 40px hit area on desktop and 44px on touch (a dense direction
|
|
274
|
+
may draw a 28-32px control and extend its hit area with a pseudo-element),
|
|
275
|
+
press scale 0.96, visible focus rings, and hover, disabled, loading, and
|
|
276
|
+
error states. Inputs are 16px on mobile; iOS zooms below that.
|
|
277
|
+
- Motion: 150-250 ms on named properties with `ease-out-strong`, never
|
|
278
|
+
`transition-all`; motion shows state change only; no load choreography;
|
|
279
|
+
honor `prefers-reduced-motion`.
|
|
280
|
+
- Overflow: check the long title and the 9-digit amount at 390px and with the
|
|
281
|
+
sidebar open. Truncate with the full value reachable (`min-w-0 truncate`
|
|
282
|
+
plus `title`, or a line clamp). A table with more than three columns becomes
|
|
283
|
+
a row list at 390px (name, primary value, one secondary line) or pins its
|
|
284
|
+
first column with a visible edge fade; a cut-off header is a fail.
|
|
285
|
+
- Charts: an explicit height on the container (`h-64` or an aspect class); a
|
|
286
|
+
chart in a flex pane without one renders at 0px. One hero series in
|
|
287
|
+
`--chart-1`, comparison series muted or `--chart-2` to `--chart-4`, direct
|
|
288
|
+
end labels instead of a legend, a dotted 1px `--border` grid with no
|
|
289
|
+
vertical lines, no axis lines, compact ticks with units ($1.2m, 38%),
|
|
290
|
+
tabular figures, a zero baseline for bars, gaps drawn as gaps, the
|
|
291
|
+
actual-to-projected boundary marked, and the one thing worth noticing
|
|
292
|
+
annotated. No dual axes, 3D, or a pie with more than three slices. If a
|
|
293
|
+
`dataviz` skill is installed, read it first.
|
|
294
|
+
- States: every collection has four, drawn in its own layout. Loading is a
|
|
295
|
+
layout-shaped `Skeleton`. Empty (sample data cleared, or a filter with no
|
|
296
|
+
hits) uses `Empty` from `@/components/ui/empty`: one sentence naming the next
|
|
297
|
+
verb, and that verb as a button. Error is inline in the pane that failed:
|
|
298
|
+
the reason, Retry, and the last good data left visible. Partial is a
|
|
299
|
+
labelled row above the data, never a silently short list. A toast alone is
|
|
300
|
+
not an error state. Writes are optimistic with rollback; a spinner only for
|
|
301
|
+
a short mutation.
|
|
302
|
+
|
|
303
|
+
## 9. Anti-patterns
|
|
304
|
+
|
|
305
|
+
- A stepper, numbered tabs, "Step N of M", or a wizard as the shell.
|
|
306
|
+
- A centered narrow column; a textarea or form as the home of a source that is
|
|
307
|
+
not form- or input-shaped (A11, A12).
|
|
308
|
+
- An eyebrow over a large H1 and a subtitle; the nav title repeated in the
|
|
309
|
+
page; a heading under the header title; section headings that restate the
|
|
310
|
+
object.
|
|
311
|
+
- Cards in cards; equal-weight card grids as page structure.
|
|
312
|
+
- A stat strip over data already visible; a row of big-number tiles (the
|
|
313
|
+
hero-metric template). One hero number inside a chart header is fine.
|
|
314
|
+
- An empty first viewport while sample data is on; an empty state with no next
|
|
315
|
+
verb; lorem, "Item 1", uniform fake rows.
|
|
316
|
+
- Unchanged scaffold tokens; one accent on everything; status-chip soup.
|
|
317
|
+
- Paragraphs over objects: helper text, explanatory footers; raw markdown.
|
|
318
|
+
- Default chart styling; SVG strokes that vanish in dark mode.
|
|
319
|
+
- Palette classes or hex for status, surface, or text; a colored side-border
|
|
320
|
+
stripe wider than 1px on a card, row, or alert; an emoji or unicode glyph
|
|
321
|
+
standing in for an icon.
|
|
322
|
+
- `transition: all`, entrance animation on every load, hover-only actions.
|
|
323
|
+
- Sparkle, wand, magic, or robot icons; a second freeform prompt box.
|