Fable UI: A Registry of Product Interfaces an AI Agent Can Actually Use

Fable UI is not trying to make another component library.

That would be the wrong problem.

React already has component libraries. shadcn/ui already proved the copy-and-own model. The Vercel AI SDK already gives developers tool calling and streaming primitives.

The gap Fable UI cares about is more specific:

How does an AI agent use product UI without being allowed to invent the product?

That is the line.

Most AI product integrations stop at chat. The model streams text. Sometimes it calls tools. The answer appears as prose, markdown, or a custom component someone wired by hand.

That works until the user asks for product work:

• a KPI
• a chart
• records
• filters
• a form
• a confirmation
• suggested next actions
• row detail
• a resource-backed browser

At that point, a chat answer starts acting like a weak substitute for an interface.

Fable UI is the attempt to make the missing layer installable.

What Fable UI Is

Fable UI is a copy-and-own registry of AI-intent-aware product experiences.

Each registry item can include:

• React UI source.
• A Zod schema for the tool payload.
• A Vercel AI SDK tool definition.
• A renderer contract for tool parts.
• A model-facing manifest.
• Examples and docs.
• Eval prompts where routing behavior needs proof.
• Optional integration glue.

The current launch direction is Next.js-first, TypeScript-first, shadcn-first, Vercel AI SDK-first, and provider-agnostic through the AI SDK.

The install model matters.

Fable UI does not hide the interface contract behind a black-box service. It installs source into the host app. Developers can inspect the component, edit the schema, tune the manifest, wire it into their AI route, and keep the UI inside their design system.

That is important because AI interface code is not just visual code. It shapes model behavior.

What Fable UI Is Not

The boundary is part of the product.

Fable UI is not:

• a full agent runtime
• a chat framework
• a database permission layer
• a replacement for your backend
• a prompt-to-code app generator
• a black-box UI SaaS
• a generic component library with AI branding

The model can request a trusted UI surface. It does not get to decide authorization, query private databases directly, invent backend operations, or execute arbitrary writes.

The host app owns:

• authentication
• authorization
• tenant scope
• data access
• business logic
• server-side validation
• side effects
• persistence

Fable UI lives between the model and the product surface.

It makes the interface selectable. It does not make the model authoritative.

The Core Architecture

The architecture is deliberately boring in the places that matter:

User prompt
model chooses tool
typed schema validates payload
tool part streams or returns
Fable renderer maps tool to component
installed React UI renders
host app handles data and actions

A Fable tool definition connects the AI SDK tool to the component renderer.

For example, the show_chart definition shape looks like this:

export const showChart = defineFableComponent({
  name: "show_chart",
  schema: showChartInputSchema,
  tool: showChartTool,
  renderer: {
    Component: Charts,
    loadingProps: { title: "Charts", data: [], isLoading: true },
    emptyProps: { title: "Charts", data: [] },
    errorProps: (description: string) => ({
      title: "Charts unavailable",
      data: [],
      error: { title: "Charts unavailable", description },
    }),
    toProps: (data) => ({ ...data }),
  },
})

That definition contains both the runtime tool and the UI renderer contract.

The AI route should pass only the tool object:

const tools = {
  show_chart: showChart.tool,
}

The client renderer receives tool parts and uses the full Fable definition map:

<FableToolPart part={part} registry={registry} />

This separation keeps the route light and keeps rendering logic in the UI layer.

The renderer validates part.output ?? part.input against the schema before converting it to component props. Invalid payloads render component error states. Unknown tools render fallback UI.

That is one of the small details that makes the architecture trustworthy.

The Manifest Is the Missing Primitive

The manifest is where Fable UI becomes more than "components plus schemas."

A tool description has to be short. It travels directly with the AI SDK tool and has to fit inside model context without becoming a manual.

The manifest can be more explicit.

It defines:

• intent
• use-when rules
• do-not-use-when rules
• neighboring tools
• prefer-instead guidance
• payload expectations
• trigger prompts
• anti-trigger prompts
• eval prompts
• safety notes

This is not just developer documentation. It is model-selection infrastructure.

The model does not only need to know that MetricCard exists. It needs to know that MetricCard should not steal prompts asking for records. It needs to know that DataBrowser should not become a confirmation flow. It needs to know that Charts should show static display-ready data, not fetch private analytics by itself.

Bad manifests create bad product behavior.

The UI can be beautiful and still wrong if the model selects it at the wrong moment.

That is why manifest quality is central to Fable UI.

The First Surfaces

The first surfaces are not random cards. They map to common conversational product moments.

MetricCard: Direct Numeric Answer

MetricCard renders one primary metric with a label, value, optional trend, and context.

The tool is show_metric.

Use it for one total, count, amount, percentage, balance, SLA value, or KPI.

Do not use it for lists, browsing, forms, confirmations, destructive actions, or long prose.

The surface is intentionally small because a metric should not pretend to be a table.

Charts: Visual Comparison and Trend

Charts renders static chart payloads as line, bar, or pie charts.

The tool is show_chart.

Use it when display-ready data is clearer as a trend, comparison, or part-to-whole view.

It should not fetch URLs, query databases, run SQL, or decide whether private data can be shown. The host app fetches, authorizes, validates, and passes safe rows into the chart payload.

DataBrowser: Record Exploration

DataBrowser is the strongest product proof because records expose the weakness of chat.

Markdown tables are fine for a tiny snapshot. They are bad for actual exploration.

Fable splits this into two tools:

• show_table for small static snapshots.
• show_data_browser for browsing, search, filters, sorting, pagination, row detail, and row actions.

show_table is appropriate when rows are already available and the answer is bounded.

show_data_browser is appropriate when the user needs to inspect a resource or explore a larger row set.

For real backend data, the model should pass a resourceId from the safe resource manifest. The host app resolves that id through a registered resource and driver.

The model should not see raw SQL, Firestore paths, REST endpoints, secrets, headers, or authorization logic.

ConfirmationCard: Human-in-the-Loop Gate

ConfirmationCard asks for explicit approval before a host-owned side effect.

The tool is request_confirmation.

Use it before writes, deletes, sends, refunds, charges, status changes, or destructive operations.

But confirmation is not authorization. The backend still decides whether the user can perform the action.

The UI captures intent. The server enforces reality.

FormCard: Structured Input Collection

FormCard collects a small number of typed fields during a conversation.

The tool is collect_input.

Use it when the task needs missing structured values: text, number, select, date, textarea, or toggle.

Do not use it as a full workflow engine. Keep v1 forms short. The host app validates submitted values before any side effect.

SuggestedActions: Workflow Continuation

SuggestedActions renders safe follow-up prompts.

The tool is show_next_actions.

Clicking an action sends the action prompt as the next normal user message. It does not call host APIs directly, perform writes, or bypass the chat flow.

That makes it useful for continuing work without turning a suggestion button into hidden automation.

DataBrowser as the Proof

DataBrowser is where the thesis becomes concrete.

If a user asks for "the last 10 orders," a metric card is wrong. A paragraph is weak. A markdown table is only barely acceptable.

The user likely needs to inspect rows, search, filter, sort, paginate, and open row detail.

That is product UI.

Fable UI's resource model keeps the boundary clear:

• The model gets labels, visible columns, allowed filters, sort options, row action descriptions, and usage guidance.
• The model does not get source configuration.
• The host app owns fetching, authentication, authorization, validation, tenancy, and action execution.

The registry stores drivers and resources. A DataBrowser with resourceId: "orders" asks the registry for that resource. The registry resolves the driver, passes context, fetches rows, and returns safe data to render.

This lets an assistant choose "orders" without knowing how orders are stored.

That is the correct shape.

The model should know what product surface to ask for. It should not know the private plumbing.

Architecture Decisions

The project has a few decisions that keep it from becoming too broad too early.

Use shadcn registry before a custom CLI. The copy-and-own model already matches the adoption goal.

Use AI SDK UI over an RSC-first path for the initial production-facing direction. Tool registration, streaming, and client rendering are familiar and portable.

Stay provider-agnostic through the Vercel AI SDK. The quickstart supports provider configuration through environment variables instead of binding Fable to one model vendor.

Keep protocol interoperability as future work. AG-UI, A2UI, and MCP Apps are useful layers, but Fable UI should first prove the registry item and manifest contract.

Keep data access app-owned. Optional REST and Firebase drivers exist for DataBrowser resources, but the model still receives only safe manifests. The host app remains the permission boundary.

Require mockable flows. AI UI needs demos and tests that do not depend on a live model behaving perfectly every time.

Testing the Contract

Fable UI needs several kinds of tests.

The normal ones:

• schema tests
• component tests
• renderer tests
• loading, empty, error, and disabled states
• invalid payload behavior
• install and dry-run validation

And the AI-specific ones:

• positive routing prompts
• anti-trigger prompts
• conflict prompts
• manifest parsing
• tool-selection evals

This is where the registry can prove quality.

A normal component registry can test whether a component renders.

An AI-intent-aware registry also has to test whether the model selects the right component.

That is a different bar.

Why Copy-and-Own Matters

Copy-and-own is not only a distribution preference. It is a trust model.

Fable UI files affect product behavior:

• schemas define payload boundaries
• tool descriptions guide model calls
• manifests shape selection
• renderers decide failure behavior
• components define user interaction

Teams should be able to inspect and change those files.

They should be able to tune manifests for their domain, remove surfaces they do not trust, adjust UI states to match their design system, and keep sensitive data boundaries visible.

The installed result should feel like part of the host app, not an embedded black box.

Current Status

The current MDX docs describe Fable UI as a public shadcn registry with a quickstart, core renderer, AI SDK integration docs, manifests, DataBrowser resources, optional REST and Firebase drivers, and component docs for:

• MetricCard
• SuggestedActions
• ConfirmationCard
• FormCard
• DataBrowser and ShowTable
• Charts

Some overview pages still contain older wording that says only MetricCard is current. Before publishing this as a final status claim, the implementation state should be checked against the live repository.

The safe way to describe the project today is:

Fable UI's documented direction has moved from one proof surface toward a fuller registry of trusted AI-selectable product surfaces. The core product line remains the same: installed UI, typed tools, manifests, safe rendering, and host-owned authority.

Closing

The interesting part of Fable UI is not that AI can show a card.

The interesting part is that the card comes with a contract.

The component knows its schema. The tool knows its payload. The manifest knows its boundary. The renderer knows how to fail safely. The host app knows it still owns data, auth, validation, and side effects.

That is what makes an interface usable by an AI agent without giving the agent the keys to the product.

Fable UI is trying to make AI product interfaces feel less like chatbots and more like trusted workflows.

Not because the model becomes unlimited.

Because the product becomes explicit about what the model is allowed to choose.