Guide

Quick Start

One command. Your code. Full ownership.

taw-ui uses the shadcn registry. One command copies a component into your project — including its schema, types, and shared utilities. No npm dependency. No runtime. Just your code. Let's add a component and render your first AI-native interface.

Install

terminal

npx shadcn@latest add "https://taw-ui.com/r/kpi-card.json"

This copies kpi-card.tsx, its schema, and shared utilities into @/components/taw/. Everything lives in your project — edit layout, styles, behavior, anything. No external dependency to manage or version.

Define your tool

server.ts — define tool

import { KpiCardSchema } from "@/components/taw/kpi-card"

const getMetrics = tool({
  description: "Get business metrics",
  parameters: z.object({ metric: z.string() }),
  outputSchema: KpiCardSchema,
  execute: async ({ metric }) => ({
    id: metric,
    stats: [{
      key: "users",
      label: "Active Users",
      value: 8421,
      format: { kind: "number", compact: true },
      diff: { value: 4.2 },
    }],
    source: { label: "Analytics API", freshness: "just now" },
  }),
})

The outputSchema does double duty: it tells the LLM what shape to return, and it's the same schema your component validates against at render time. One schema. Both sides. No synchronization required.

Render

chat.tsx — render component

import { KpiCard } from "@/components/taw/kpi-card"

<KpiCard part={part} />

Active Users

0+4.2%

Analytics API· just now

What you just gained

That one line does a lot:

✓Loading state — while the tool is running, KpiCard shows a shimmer skeleton automatically. No if (loading) needed.

✓Streaming — as partial data arrives, the component renders progressively. Skeletons fill in as fields resolve.

✓Animated entrance — numbers count up with spring physics when the result lands. Motion that feels earned, not decorative.

✓Schema validation — if the AI returns the wrong shape, you get a helpful inline error with field-level details and "Did you mean?" suggestions. Never a blank space, never a silent failure.

✓Source provenance — the source field renders as a subtle footer automatically. Users know where the data came from.

✓Full ownership — the component lives in your project. Open @/components/taw/kpi-card.tsx and change anything. Everything lives in your project. Update the schema, the component, or both — it's all yours.

Where to go next

ConceptsThe mental model: lifecycle, confidence, receipt pattern, and more

PrinciplesThe design thinking behind taw-ui — how we believe AI interfaces should be built

KpiCardThe component you just added — full props, schema, and examples

DataTableSortable tables with 9 column types — currency, percent, delta, badges

OptionListInteractive choices with the receipt pattern — see decisions in action

InsightCardStructured AI analysis with sentiment-coded recommendations

AlertCardSeverity-based proactive alerts with inline metrics

LinkCardRich link previews with OG metadata and favicon