Principles

One Zod schema is the single source of truth. It validates on the server, validates on the client, infers TypeScript types, and drives rendering. There are no separate action definitions, surface configurations, or render instructions.

The AI doesn't need to know about React. It doesn't need to know about components. It returns data that matches a schema — the same schema it already uses as its tool's outputSchema. The rendering is the framework's job, not the model's job.

// Server: define tool output shape
const getMetrics = tool({
  outputSchema: KpiCardSchema,
  execute: async () => ({
    id: "revenue",
    label: "Revenue",
    value: 142580,
    confidence: 0.92,
  }),
})

// Client: render it
<KpiCard part={part} />

Components handle their entire lifecycle from a single prop. Loading? Skeleton with shimmer. Streaming? Progressive render. Success? Animated entrance. Parse error? Helpful inline error with field-level suggestions. The developer never writes conditional rendering for tool states.

// Handles loading, streaming, error, AND success
<KpiCard part={part} />

// Not this:
if (part.state === "loading") return <Skeleton />
if (part.state === "error") return <Error msg={part.error} />
const data = validate(part.output)
if (!data) return <ParseError />
return <KpiCard data={data} />

Common affordances are built in, not opt-in. A DataTable sorts columns, formats currencies, and shows row counts by default. A KpiCard animates numbers and shows confidence badges by default. You don't configure these — you disable them if you don't want them.

Every schema supports two fields that don't exist in traditional UI libraries: confidence (0–1) and source (provenance). These are first-class because AI outputs are probabilistic — users deserve to know how certain the data is and where it came from.

These fields are optional in every schema. If the AI doesn't provide them, the component renders cleanly without them. But when they're present, the user sees exactly how much to trust the output. No other library does this.

When a component asks the user to decide (approve, select, confirm), the interactive controls must transform into a permanent record after the decision. This is the receipt pattern. It prevents stale buttons in chat history, saves vertical space, and gives the AI a clear signal of what was chosen.

const [receipt, setReceipt] = useState<TawReceipt>()

<OptionList
  part={part}
  onAction={(actionId, payload) => {
    // payload.receipt is ready to use
    setReceipt(payload.receipt)
  }}
  receipt={receipt}
/>

// Before decision: full interactive list
// After decision: compact "✓ Rolling Deploy" receipt

Receipt labels use past tense: Approved, Selected, Confirmed, Skipped. The action description stays imperative. Pattern: [Past-tense verb] [What was acted on]

Every component, every option, every row has a stable id. These must be backend identifiers (database IDs, slugs, URLs) — never array indexes or random UUIDs generated at render time.

Addressability is what makes the AI useful after the first response. When the user says " tell me more about the Acme Corp row", the AI can reference row.name === "Acme Corp" because the data has stable keys. When the user picks an option, the receipt contains selectedIds: ["rolling"] — not selectedIndex: 0.

AI interfaces have a different constraint set than traditional product UIs. They live inside a conversation flow. They appear at unpredictable moments. They must communicate their purpose immediately — without navigation, tabs, or a learning curve. taw-ui components are designed to satisfy these constraints first, not as an afterthought.

Chat is often where AI interfaces live today — but the principles here apply anywhere AI returns structured output: sidebars, command palettes, embedded panels, async notifications. The rules stay the same: single-column, immediately scannable, actionable with one interaction.

No input fields. The chat composer is the input. The only interactive elements are selection (pick from options the AI provides) and confirmation (approve/reject what the AI proposes). Limit visible choices to 5–7. If the AI needs to show more, it should say so — not render a paginated table.

When the AI returns data that doesn't match the schema, the component must never render null, crash, or show a blank space. It renders a helpful inline error that shows exactly which fields failed validation and suggests corrections.

Parse errors show the expected type, the received value, and a" Did you mean? " suggestion when possible. This is critical for development — the AI model iterates faster when it can see what went wrong. And in production, a visible error is always better than a silent one.