M The Microapp Handbook Part II · Chapter 8 of 13

Part II · Chapter 8 of 13

Tool UX

The widget conventions that turn brand and engine into one product. Inputs, outputs, errors, mode-switching, and the shared primitives Bob inherits.

10 min read

Colophon defines the colors and the type. Built for Agents defines the API surface. This chapter is the missing layer — the widget conventions that turn brand and engine into one product. Two tools side-by-side should feel like the same product, not two tools we both happen to host.

Why this chapter exists: in the May overnight builds, ten parallel Bob agents shipped ten tools — and each Bob made local UX choices. Five different mode-switch patterns, four different Copy-button styles, three different error treatments. The brand-palette test caught color violations; nothing catches UX-shape violations. This chapter is what catches them. Bob reads it. Reviewers cite it. Drift lands here as a fix, not a debate.

How to use this chapter. When you ship a tool, the widget must follow every rule below — not "interpret in the spirit of," but the literal rule. If a rule is wrong for a specific tool, the path is: open a PR that changes this chapter, then ship the divergence. The chapter is the constitution, not a suggestion.

1. The shape of a widget

Every Microapp widget follows the same vertical flow. Don't invent a new layout per tool.

  1. Input section — the fields the user fills. One column on mobile; up to two columns on desktop only when the fields are clearly paired (e.g. width + height).
  2. Primary action — one button, or auto-compute on input change (preferred for fast operations). Never both.
  3. Output section — the answer. The main result is visually dominant; secondary stats sit underneath.
  4. Secondary actions — Copy, Reset, Clear, Download. Below the output, smaller weight than the primary action.
  5. Context — formula line, worked example, FAQ. After the output, optional, never above it.

Tier 1 vs Tier 2 — when to pick which

Tier 1 is an engine config rendered by <ToolEngine> (see Tool Engines). Tier 2 is a custom React widget at src/components/tools/<Name>.tsx. The split decides itself:

Single formula, fixed input set, no mode-switching
→
Tier 1 (engine config)
Mode picker reshapes inputs (tabs, jurisdiction, multi-shape)
→
Tier 2 (custom widget)
Interaction is the product (counters, drag-crop, paint)
→
Tier 2 (custom widget)
localStorage persistence required
→
Tier 2 (custom widget)
Output is a download/file (PDF, image, document)
→
Tier 2 (custom widget)

Default to Tier 1 when the math is one line. Going Tier 2 means inheriting all the conventions in the rest of this chapter — the engine config gets them for free via <ToolEngine>.

2. Inputs

  1. Every input has a real <label htmlFor>. Never a styled <div> pretending to be a label. Screen readers need the association; Ben's a11y audit blocks PRs that skip it.
  2. Mobile tap targets ≥44pt. That's min-height: 2.75rem at the default 16px root. Inputs, buttons, chips — anything tappable.
  3. Numeric inputs use type="number" with inputMode="decimal" when fractions are expected. Mobile numeric keyboards depend on it.
  4. Pre-fill an example when the input shape is non-obvious. Median calculator lands with 3 sample numbers so the textarea isn't a blank wall. Word counter lands empty (the input shape is self-evident). Picking right is judgment; the test is "does an unfamiliar user know what to type?"
  5. Units are dropdowns, never modes. "Convert pixels at DPI 96" is one input shape with a unit picker; "DC vs AC three-phase" is a mode change because the inputs are different. Use the mode-switching rules below for the latter.

3. Mode switching — one pattern, not five

Five tools shipped in one week with five different ways to switch modes. That stops here.

≤3 modes, same inputs (formula varies, fields don't)
→
SegmentedControl
≥3 modes, different inputs per mode
→
ModeTabs (top tabs)
Mode state must survive reload or be shareable as a URL
→
ModeTabs with hashRoute
Single binary choice (e.g. "uppercase output: on/off")
→
Toggle
Banned for mode-switching: dropdowns, gear-icon menus, separate pages, accordion sections. A dropdown is a unit picker. A gear icon is for settings (sound on/off, theme). Modes are a primary interaction — they need to be visible on first render.

4. Outputs

Numeric precision — one rule

  1. Default: 4 significant figures. Not 6, not 8, not "as many as JavaScript gives us." Four is enough precision for engineering, finance, and stats homework; more is just visual noise.
  2. Money: 2 decimal places. Always. $1,234.56, never $1234.5601. Use fmtCurrency(n) from the shared util.
  3. Percentages: 2 decimals or 4 sig figs, whichever is fewer. 16.67%, not 16.66666...%.
  4. Per-tool overrides need justification. If your spec calls for 6 decimals on something, write the reason in the spec. Kai locks it; Ben checks it.

Layout

  1. The main result is the largest text in the widget. Bigger than the H1, bigger than the inputs. The user came for this number — show it.
  2. Secondary stats sit under the main result in a label-value table or grid. Same row → same precision and same unit.
  3. The formula line is optional — include it when the result invites "wait, how did you get that?". Set it small and monospace, under the result. Educational tools (chemistry, stats) should include it; one-shot converters (hex-to-decimal) shouldn't.
  4. Loss/edge states surface honestly. If profit is negative, show -$10.00 in coral — don't hide it. If divide-by-zero, show — — never NaN, never Infinity.

Copy buttons

Every result that someone might copy into another tool needs a Copy button. Standardized.

  1. Position: directly to the right of the result, vertically centered. Not at the top of the widget. Not in a kebab menu.
  2. Label: just "Copy" — short. No icon-only buttons (accessibility); icon-plus-label is fine.
  3. Feedback: sonner toast. Use the toast.success("Copied") from sonner — already a dep. No alerts, no inline "Copied!" text-swap (it shifts layout).
  4. Multiple results = multiple Copy buttons. One per result. Don't make the user click "Copy" and then choose which thing.

5. Errors and empty states

  1. Voice: AmEx, never airline. §6 voice rule 10 again. "That's frustrating. Try this." Not "Error: invalid input." Not "Please be advised that..."
  2. Visual: <ToolError> primitive. Coral background, role="alert", optional icon. Never a generic browser alert. Never a thrown exception bubbling up.
  3. Position: under the input that caused it (when scoped to one field) or in the output area (when the whole calculation can't run). Never at the top of the widget — that's where the title is, not where errors live.
  4. Empty states get a sentence, not silence. "Paste some numbers above — comma, space, or newline separated — to see the median." Tells the user what shape of input you want.

6. Action buttons

  1. Primary = one button per widget, green (--color-brand-green). The main action: "Calculate", "Generate", "Convert", "Compress". Never multiple primaries — if the widget has two primary actions, it's two widgets.
  2. Secondary = cream/border for "Reset", "Clear", "Use example", "Add row". Visual weight is lower than primary.
  3. Destructive = coral with a modal. "Reset to zero", "Clear history". Long-press is banned — it's invisible to first-timers and not keyboard-equivalent. A modal with explicit confirm + cancel is the only acceptable pattern.
  4. Position: under the input section, right-aligned on desktop, full-width on mobile. Don't put the primary action above the inputs (the visual flow is input-then-act, not act-then-input).

7. Persistence

Some tools are their persistence — a tally counter loses its point if reload zeros it. Others are one-shot — a percentage calculator doesn't need to remember last week's input. The default is no persistence; persistence is opt-in.

  1. Persist when the tool is stateful by nature — counters, preference toggles, multi-row editors where the rows themselves are the work. Don't persist for one-shot calculators.
  2. Use localStorage, never IndexedDB or cookies. Keep it cheap, keep it readable, keep it client-only.
  3. Pattern: hydration guard + ref + useEffect. Don't read localStorage during render — Astro SSR will mismatch. See ClickerCounter.tsx for the reference implementation.
  4. localStorage disabled = service-voice notice. Some browsers (private mode, certain device managers) block it. "Your browser isn't saving the count. It'll reset when you close the tab." Let the tool keep working in-memory.

8. The 30-second test

From the Simplicity Pledge: a first-time visitor must be able to use the tool in under 30 seconds, with zero documentation. That rule has UX consequences worth spelling out:

  1. No onboarding modals. If the widget needs to teach the user how to use it, the input is wrong. Redesign the input.
  2. No "Get started" buttons. The page IS the tool. The user gets started by typing.
  3. No tutorials, walkthroughs, or coachmarks. If you reach for these, your widget needs simplifying — not annotation.
  4. No welcome screens, splash screens, or interstitials. The result is the welcome.
  5. No "Sign in to continue" before the first calculation. Members get clean pages; non-members get ads. Both get the result. Covenant Item 02.

The test for whether you've passed: open the tool in a fresh incognito tab, set a 30-second timer, see if you can get an answer. If yes, ship. If no, simplify.

9. The shared primitives

Bob imports these by name. New tools use them. Existing tools get retrofitted when touched. This is the bridge from the constitution to the implementation.

<ToolError>
Coral alert with role="alert". Renders only when message is non-empty. Use for input validation errors and divide-by-zero states. import { ToolError } from "@/components/ui/ToolError"
<CopyButton>
Button labeled "Copy" with sonner toast feedback. Takes a value prop (string) and an optional label for screen readers. Standardized everywhere a result can be copied. import { CopyButton } from "@/components/ui/CopyButton"
<ModeTabs>
Top tabs for mode-switching when modes reshape inputs. Optional hashRoute persists state in the URL. Use for ≥3 modes; for ≤3 same-input modes, use <SegmentedControl> instead. import { ModeTabs } from "@/components/ui/ModeTabs"
<SegmentedControl>
Pill-style segmented selector for ≤3 options that share an input shape. Smaller visual weight than tabs. import { SegmentedControl } from "@/components/ui/SegmentedControl"
<ResultCard>
Boxed output container with optional label, primary value, and footer (formula line, secondary stats). The dominant visual block of the widget. import { ResultCard } from "@/components/ui/ResultCard"
<NumberOutput>
Precision-aware number display. Takes value, format ("sigfig" | "money" | "percent" | "integer"), and optional unit. Handles the precision rules in §4 so every Bob doesn't reinvent them. import { NumberOutput } from "@/components/ui/NumberOutput"
<PrimaryButton>
The green main action. One per widget. Full-width on mobile, right-aligned on desktop. import { PrimaryButton } from "@/components/ui/Button"
<SecondaryButton>
Cream/border secondary action. "Reset", "Clear", "Use example", "Add row". import { SecondaryButton } from "@/components/ui/Button"
<DestructiveButton> + <ConfirmModal>
Coral button for irreversible actions. Wired to a confirmation modal — never long-press, never bare-click. Modal copy comes from the tool's spec. import { DestructiveButton, ConfirmModal } from "@/components/ui/Button"
Adding a new primitive. If you're about to invent a widget pattern that doesn't fit any of these, the path is: (1) open a PR adding the primitive to src/components/ui/ with a documented signature, (2) add it to this chapter, (3) only then use it in your tool. The chapter is the contract.

10. Drift — what currently violates this chapter

Honest section. The conventions above were written after ten tools had already shipped, each with its own UX. The drift is documented here so this chapter doesn't read as aspirational. Each row is queued for retrofit; the order is opportunistic (when we touch the widget for another reason, we update it).

Tool What drifts Fix on next touch
ClickerCounter Gear-icon settings drawer; mode-switch via gear (not tabs) Move sound toggle to a labeled <Toggle>; multi-counter switch via <ModeTabs>
OvertimeCalculator Jurisdiction picker is a dropdown (should be <ModeTabs> — input shape changes) Swap dropdown for tabs; "Federal" / "California" become top-level mode labels
WattsToAmps Segmented mode is fine; PF chip styling is bespoke Move PF chips to a shared <ChipGroup> primitive once we extract one
InvisibleText Copy button is full-width hero (not the §4 standard placement) Move Copy button to right-of-result; the hero "Copy cursed text" pattern was inherited from a single agent's choice
MedianCalculator "Copy summary" with sonner toast is correct; secondary stats use ad-hoc number formatting Route stats through <NumberOutput format="sigfig">
ImageCropper Inline errorMsg state; doesn't use <ToolError> Swap to the primitive once extracted
Tier 1 engine tools (40+) Render via <ToolEngine>; that component pre-dates this chapter Update ToolEngine internals to use the same primitives — that one change retrofits all 40 in one PR

When this table gets to zero rows, the site is consistent. Until then, the chapter is the goal and the table is the gap.

For Bob and Ben

Bob: read this chapter before generating any widget. The checklist.md in your skill folder links here as required reading. Import primitives by name; don't reinvent.

Ben: add a "Tool UX check" pass to your audit. For each violation, cite the section number ("§3 mode-switching", "§4 numeric precision"). Block the merge until the violation is either fixed or this chapter is updated to permit it.