Prototype

A coding run that builds a web-application reads references/implementing.md. The rest of this file is how the design agent writes a prototype.

A prototype is the reviewable picture of a web-application before it is built: its screens, navigation, roles, flows and display states, filled with mock data, running in a sandbox inside the review page. It is the web application's artifact in the design. The design flow writes it after the data model and the roles, and before the API contracts, which then serve its screens. The business reviewer uses it and comments on it, and the build makes what it shows.

The screens are a React module written against a fixed kit of components (@wso2/prototype-kit). You compose screens from the kit; you do not build components, style anything, or reach outside the frame.

Inputs

Read these before writing anything:

• specs/design/design.cell: every component … web-application line is one prototype to write. No web-application means there is nothing to do: say so and stop. When the turn names components, write only those.
• specs/design/domain-model.md: the records. Each entity that a screen shows or changes is a collection in the mock data, and its fields are the entity's attributes (see Mock data).
• specs/design/security.json: the roles. When the file exists, each prototype role's id is a role's name from it, copied verbatim (same case, same spelling), and its name is a short human label for that role. Include exactly the roles that use this application. Each role's description says what the role does and what it never sees: show each role only the screens, controls and records that its description allows. Without the file, take the roles from the PRD's actors and give them short kebab-case ids.
• The web application's design.json: stories lists the stories it serves.
• The requirements of those stories: each feature's file, specs/requirements/features/F<n>-<slug>.md, with its stories (F<n>.<m>) and its Decisions, the *assumed* lines included; product-wide.md for the items that apply to it; and prd.md's Actors, for the people your records are about. Every story the application serves gets at least one screen. Set a story aside only when the product gives it no view (sign-in through the platform's SSO, a machine-facing endpoint), and name it in your closing.
• A sketch or mockup the user attached: the layout brief. Refine it; do not reinvent it. Where it and the stories disagree, the stories' scope wins and the sketch's layout intent survives inside it.
• specs/design/components/<component>/prototype.json and prototype.tsx if they already exist: you are revising them, not starting over (see Stable ids).

Output

Two files per web-application, in specs/design/components/<component>/, where <component> is the web-application's name in the cell:

1. prototype.json, the manifest: the roles, display states, screens and flows the reviewer picks from. Write it first.
2. prototype.tsx, the screens: one React component per manifest screen, exported with defineApp. It is checked against the manifest already written.

Write a new file with ONE addFile of the whole file. Revise an existing one with editFile edits: the file is already in front of you, and an edit costs what it changes. Never write a partial file to finish later.

Each write of prototype.tsx is type-checked alone. A change to a record type and its uses (a field that you add, rename or remove) cannot go in as one edit per line: the first edit leaves the other uses wrong, and the check refuses it (TYPE_ERROR, one finding for each wrong line). Write such a change, or any other change to many lines, in one write: removeFile, then ONE addFile of the whole corrected file, with each id as it was.

This step writes only these two files. A screen can need a record, a field or a role that the data model or security.json does not have. Then change that file first (it comes earlier in the design), and write the screen after it. Do not change a requirement here: the design's gap check writes the requirements.

Every write is checked as it lands: the manifest's shape and references, the source's static rules, then a render of every screen for every role that reaches it in every display state. A refusal lists every finding with its code and where (a JSON path in the manifest, a line in the source, or the screen, role and state that failed to draw). Fix all of them and retry once. The codes are listed at the end of The kit.

The manifest

Plain JSON, schema version 3. Every object is closed: a key not shown here is refused.

{
  "schemaVersion": 3,
  "name": "Expense approvals",
  "entryScreen": "screen.queue",
  "roles": [{ "id": "Approver", "name": "Approver" }],
  "states": [
    { "id": "state.default", "name": "Default" },
    { "id": "state.empty", "name": "Nothing to show" },
    { "id": "state.validation-error", "name": "Validation errors" },
    { "id": "state.failed", "name": "Expense feed failed" }
  ],
  "screens": [
    { "id": "screen.queue", "name": "Approval queue", "roleIds": ["Approver"] },
    { "id": "screen.detail", "name": "Expense detail", "roleIds": ["Approver"] },
    { "id": "screen.account", "name": "Account", "roleIds": ["Approver"] },
    { "id": "screen.signed-out", "name": "Signed out", "roleIds": ["Approver"] }
  ],
  "flows": [
    { "id": "flow.approve", "name": "Approve an expense", "roleId": "Approver",
      "screenIds": ["screen.queue", "screen.detail"] }
  ]
}

• roles, states and screens have at least one entry; their ids and the flows' ids share one namespace and are unique together. entryScreen is the screen the prototype opens on. name is the application's name.
• A screen's roleIds are the roles that reach it. A flow is one role's walk through screens that role reaches, in order, for one story. Give each story that has a view a flow, named for what the actor does ("Submit a claim").
• The app shell's screens, an account screen and a signed-out screen, go to every role: every user has them.
• A settings screen exists only for the settings that the requirements name (a notification choice, a default that a user picks). It goes to the roles that set them, and it holds those settings and nothing else. When the requirements name no setting, write no settings screen. Never invent a preference (a digest email, a Slack alert, a compact view) to fill one.
• states always starts with a default state (state.default); add one per presentation a reviewer must see:
  • state.empty wherever a list can be empty.
  • Wherever the product can refuse or fail what a screen does, the states that the refusal or the failure produces. A form that a requirement limits (a required receipt, a cap) shows its validation errors in state.validation-error: its Fields' error and a ValidationSummary. A screen whose data or action can fail (an outside service it needs, a save) gets state.failed: an error Alert saying what failed and what the user can do. A step that can be slow (an outside service, a long-running job) gets state.delayed: an info or warning Alert saying the result is on its way. A prototype with only default and empty states hides the presentations a reviewer most needs to judge.

The screens

import { useState, type ReactNode } from "react";
import {
  Alert, AppShell, Button, Detail, Dialog, EmptyState, Field, Form, Heading, Screen, Section, Stat,
  StatGroup, Table, defineApp, useCollection, useDisplayState, useNav, useParams,
} from "@wso2/prototype-kit";

interface Expense { id: string; employee: string; amount: string; status: string }

const expenses: Expense[] = [
  { id: "1042", employee: "Maya Fernando", amount: "$148.20", status: "Awaiting approval" },
  { id: "1039", employee: "Ravi Perera", amount: "$62.00", status: "Awaiting approval" },
  { id: "1031", employee: "Ana Silva", amount: "$310.00", status: "Approved" },
];

const user = { name: "Ravi Perera", email: "ravi@acme.example" };

function Shell({ children }: { children: ReactNode }) {
  return (
    <AppShell
      id="shell"
      user={user}
      nav={[{ id: "nav.queue", label: "Approval queue", to: "screen.queue" }]}
      account="screen.account"
      signOut="screen.signed-out"
    >
      {children}
    </AppShell>
  );
}

function Queue() {
  const state = useDisplayState();
  const all = useCollection<Expense>("expenses");
  const waiting = state === "state.empty" ? [] : all.items.filter((e) => e.status === "Awaiting approval");
  const approved = all.items.filter((e) => e.status === "Approved").length;
  return (
    <Shell>
      <Heading id="heading.queue" text="Approval queue" />
      {state === "state.failed" && (
        <Alert id="alert.feed-failed" tone="error" title="Expense feed unavailable" text="Amounts may be stale. Refresh in a few minutes." />
      )}
      <StatGroup>
        <Stat id="stat.waiting" label="Awaiting you" value={String(waiting.length)} hint="claims to decide" icon="Inbox" tone="warning" />
        <Stat id="stat.approved" label="Approved" value={String(approved)} hint="this month" icon="CircleCheck" tone="success" />
      </StatGroup>
      <Section id="section.expenses" title="Expenses" count={waiting.length} subtitle="Oldest first. Open a claim to reject it with a reason.">
        <Table
          id="table.expenses"
          columns={["Employee", { label: "Amount", kind: "number" }, { label: "Status", kind: "status" }]}
          rows={waiting.map((e) => ({
            id: `expense.${e.id}`,
            cells: [e.employee, e.amount],
            status: { text: e.status, tone: "warning" },
            to: "screen.detail",
            params: { expense: e.id },
            actions: [{ id: `expense.${e.id}.approve`, label: "Approve", onPress: () => all.update(e.id, { status: "Approved" }) }],
          }))}
          empty={<EmptyState id="empty.queue" title="Nothing to approve" text="New claims appear here." />}
        />
      </Section>
    </Shell>
  );
}

function ExpenseDetail() {
  const { expense: id } = useParams();
  const state = useDisplayState();
  const navigate = useNav();
  const all = useCollection<Expense>("expenses");
  const [rejecting, setRejecting] = useState(false);
  const expense = (id ? all.get(id) : undefined) ?? all.items[0]!;
  const decide = (status: string) => {
    all.update(expense.id, { status });
    navigate.go("screen.queue");
  };
  return (
    <Shell>
      <Heading id="heading.detail" text={`Expense ${expense.id}`} />
      <Detail
        id="detail.expense"
        fields={[
          { label: "Employee", value: expense.employee },
          { label: "Amount", value: expense.amount },
        ]}
      />
      <Button id="btn.approve" label="Approve" emphasis="primary" onPress={() => decide("Approved")} />
      <Button id="btn.reject" label="Reject" emphasis="danger" onPress={() => setRejecting(true)} />
      <Dialog id="dialog.reject" title={`Reject expense ${expense.id}`} open={rejecting} onClose={() => setRejecting(false)}>
        <Form
          id="form.reject"
          onSubmit={() => decide("Rejected")}
          actions={<Button id="btn.reject.confirm" label="Reject" emphasis="danger" submit />}
        >
          <Field
            id="field.reason"
            label="Reason"
            type="textarea"
            required
            error={state === "state.validation-error" ? "Give the employee a reason" : undefined}
          />
        </Form>
      </Dialog>
    </Shell>
  );
}

function Account() {
  return (
    <Shell>
      <Heading id="heading.account" text="Account" />
      <Detail id="detail.account" fields={[{ label: "Name", value: user.name }, { label: "Email", value: user.email }]} />
    </Shell>
  );
}

function SignedOut() {
  return (
    <Screen>
      <Heading id="heading.signed-out" text="You are signed out" />
      <Button id="btn.sign-in" label="Sign in" emphasis="primary" to="screen.queue" />
    </Screen>
  );
}

export default defineApp({
  screens: {
    "screen.queue": Queue,
    "screen.detail": ExpenseDetail,
    "screen.account": Account,
    "screen.signed-out": SignedOut,
  },
  data: { expenses },
});

• One component per manifest screen, keyed by the screen's id in defineApp({ screens }): exactly the manifest's screens, no more, no less.
• Every screen sits in the app shell. Write one <AppShell> in a small local component (Shell above) and make it every screen's root: it draws the product's header, the signed-in user and the user menu (Account, Settings, Sign out) and the side navigation. Its account and signOut are screens you write: an account screen with the user's details, and a signed-out screen. Only that signed-out screen, outside the product, has a bare <Screen> as its root, with a way to sign back in. Give settings only when the prototype has a settings screen (see the manifest rules): without it, the user menu has no Settings entry. The shell's menu adds the application's own user-menu entries (a profile, billing) before Sign out. A reviewer points at an entry by opening the menu in Preview, then switching to Annotate.
• One shell serves every role. A navigation entry is drawn only for the roles that reach its screen. Give user the person each role signs in as (pick by useRole() when roles differ); the header shows the viewing role's name beside them.
• Read the review through the hooks. useDisplayState() is the display state the reviewer chose and useRole() the role they view as: branch on them to show an error, an empty list, a role's own controls. Show a control only to the roles that reach where it leads: a to a role cannot follow is refused.
• Navigate with to on a Button, Link, table row, row action or breadcrumb (with params the target reads through useParams()); useNav().go(...) inside an onPress for a navigation that follows an action. Every screen must also draw without params (the reviewer can open any screen from the pickers), so fall back to the first record.
• Overlays are the screen's own state: const [open, setOpen] = useState(false) and <Dialog open={open} onClose={() => setOpen(false)}>. Tabs and Steppers keep their own position, or take active and onChange when a button moves them (a wizard's Next).
• Forms submit through the kit. A <Form onSubmit> with a <Button submit> validates its Fields (required, pattern) and then calls onSubmit with their values keyed by name (default: the Field's id). A Field with no value holds what is typed into it; give it defaultValue to start filled.
• The mock data is defineApp({ data }). An array of records that each have a string id is a collection: read it with useCollection(name) and change it with create, update and remove, so the next screen shows the result. Anything else is a single value for useValue(key). The change lives in memory until the reviewer presses Reset data; nothing is sent anywhere.

What a prototype may not use is refused as it lands: imports other than react and @wso2/prototype-kit; raw HTML elements (<div>, <table>, <img>, …), because every element is a kit component; the page, storage, network and code-generation APIs (window, document, fetch, eval, …); and anything nondeterministic (Math.random(), Date.now(), new Date() with no argument; use useToday() for today's date). Styles do not exist: the theme draws every component, and a component takes no className or style.

What the reviewer sees

The review renderer draws only what the screen component renders: kit components, inside the chrome its <AppShell> draws (the header with the product's name and the signed-in user, the user menu with Account, Settings when the shell names a settings screen, and Sign out, the side navigation). A bare <Screen> is drawn with no chrome at all.

Nothing else is drawn automatically: no notification bell, search, theme toggle, help menu or footer, whatever the built application's shell will carry. If a reviewer asks for such chrome, model it in the kit: a navigation entry, or a Button or Link in the screen's content (a Heading's actions for the top right) whose to is the screen it leads to or whose onPress opens a Drawer (a notification list) or a Dialog (a confirmation). Only if what they ask for is outside the kit, say so in your reply and name the limitation. Never tell a reviewer the platform draws something the screen does not render.

The Oxygen look

The reviewer sees the prototype in the Oxygen theme, the look of WSO2 products, so a prototype should read as an Oxygen screen. The host applies the theme: the source never imports one, never styles anything, and never names Oxygen. Your part is composing screens the way an Oxygen application composes them:

• Page anatomy. A screen is the <AppShell> holding a <Heading> (the page title, with page-wide action Buttons in actions), then the content in the order a user works through it: headline numbers as one <StatGroup> of <Stat>s, then a <Section> per part of the page (a list, a form, a record), with <Filters> and the <Table> inside it, and <Detail>, <Form> and <Timeline> for a single record. A sub-page opens with <Breadcrumbs> back to its list.
• Stats in a group. Put a screen's <Stat>s in one <StatGroup>, never a <Stack direction="row"> or <Grid>: the group gives them one width. Give each a hint that gives the number its scale ("of 20 left this year", "claims to decide") and an icon from the kit's list that names what it counts; tone colours the icon when the number needs attention.
• Sections own their actions. A <Section> titles a part of the page, with count for the records it lists and subtitle for one line on what it holds. An action that adds to or acts on that part sits in the Section's actions (New request above the requests), not under the table and not in the page Heading.
• One primary action per screen. emphasis="primary" marks the screen's main action and nothing else; destructive actions are "danger".
• Status is a chip, not prose. A record's status is the table's status column ({ label: "Status", kind: "status" } in columns, and each row's status: { text, tone }) or a <Badge>: success, warning, error, info, default. Put the column where it reads best; the row's cells fill the other columns in order. Callouts are <Alert>s with a tone.
• Row actions are buttons, not cells. What a user does to one record without opening it (Cancel, Approve) is the row's actions, each with an id built from the row's (`${rowId}.cancel`), a label, and to or onPress like a Button (emphasis: "danger" for a destructive one). They draw in a trailing column (behind one menu past two) and pressing one never presses the row, so the row can still open the record. Never write an action's label into a cell. Figures are { label, kind: "number" } columns.
• Navigation is the shell's side rail, one entry per top-level screen. Account and Settings live in the user menu, not the rail.
• Records, not cards. Show a list of records as a <Table> whose rows open the record; use <Split> for a record next to its activity.
• Forms are short and labelled. One <Form> per task, a <Field> per input with a plain label, required where the API requires it, errors in the Field's error and a <ValidationSummary> for the whole form.

When the organization names a design system, its skill is loaded beside this one and is the full account of how an enterprise screen is composed (a listing page's header, filters and table, a form's layout and actions). Read it for the arrangement and build each screen that way from the kit; with none loaded, use the rules above. Its setup, packages and code are the build's concern, not this flow's: the kit's components are the only vocabulary here.

The kit

Nothing else exists: no markup, styles, scripts, charts, file upload or custom component. Express a screen in these components or leave the part out.

<!-- kit:start -->

A prototype is prototype.json (the manifest) and prototype.tsx, which imports only react and @wso2/prototype-kit. Every component with an id is an element a reviewer can point at: give each a stable id, unique on its screen.

Module

defineApp(definition: PrototypeAppDefinition): PrototypeApp

Declare the prototype: export default defineApp({ screens, data }).

PrototypeAppDefinition

• screens: Record<string, ComponentType> — One component per manifest screen, keyed by the screen's id.
• data?: Record<string, unknown> — The mock data the screens share, as JSON literals. An array of records that each have a string id is a collection (useCollection(name)); anything else is a single value (useValue(key)). Changes live until Reset data (or a reload without --persist).

View hooks

useNav(): KitNav

KitNav

• screen: string — The screen shown.
• go: (screenId: string, params?: Record<string, string>) => void — Go to a screen, optionally with params the target reads with useParams.

useParams(): Readonly<Record<string, string>>

The params the navigation to this screen carried. Empty when the reviewer opened the screen from the preview's pickers, so every screen must render without them (fall back to the first record).

useRole(): string

The id of the role the reviewer is viewing as.

useDisplayState(): string

The id of the display state the reviewer chose (e.g. empty, loading, error).

Data hooks

useCollection<T extends { id: string; }>(name: string): Collection<T>

The collection name from defineApp({ data }): an array of records that each have a string id.

Collection

A collection of mock records, and the ways to change it for every screen.

• items: readonly T[] — The records, in insertion order.
• get: (id: string) => T | undefined
• create: (record: Omit<T, "id">) => string — Adds a record and returns its new id, ${name}-${n} with n past the highest number in use.
• update: (id: string, patch: Partial<Omit<T, "id">>) => void
• remove: (id: string) => void

useValue<T>(key: string): [T, (next: T | ((previous: T) => T)) => void]

The single value key from defineApp({ data }), and a setter shared by every screen.

useToday(): string

Today's date, fixed (PROTOTYPE_TODAY): a prototype never reads the clock.

PROTOTYPE_TODAY = "2026-01-15"

The fixed date every prototype treats as today (ISO YYYY-MM-DD).

Layout

<AppShell>

The root of a screen inside the product's chrome: header, user menu and side navigation. Use <Screen> for a screen outside it (signed out).

• id: string — The shell's id; its user menu's elements are <id>.user, <id>.account, <id>.settings (with settings) and <id>.sign-out.
• product?: string — The product's name in the header; prototype.json's name by default.
• user: AppShellUser — The signed-in user the header shows.
• nav: NavigationItem[] — The side navigation's entries.
• account: string — The screen the user menu's Account entry opens.
• settings?: string — The screen the user menu's Settings entry opens. Leave it out when the application has nothing to set: the menu then has no Settings entry.
• signOut: string — The screen Sign out leads to: a signed-out screen, drawn on a bare <Screen>.
• menu?: NavigationItem[] — More user-menu entries (a profile, billing), drawn after Account (and Settings) and before Sign out.
• children?: ReactNode — The screen's content.

AppShellUser

• name: string
• email?: string — Shown under the name in the user menu.
• role?: string — The role beside the name; the viewing role's name in prototype.json by default, so a role switch shows in the header.

<Screen>

The root of a screen outside the app shell (signed out, a landing page): its content, and navigation if any.

• nav?: ReactNode — Navigation for an app drawn without <AppShell>: one <Navigation>, usually shared by every screen.
• children?: ReactNode

<Section>

A titled part of a screen — a table, a form, a group of stats — with the actions that belong to it.

• id: string
• title: string
• subtitle?: string — One line under the title: what the section holds or why.
• count?: number — How many records the section lists, shown beside the title.
• actions?: ReactNode — The section's own Buttons ("New request" above the requests it adds to).
• children?: ReactNode

<Stack>

Children in a column (default) or a wrapping row.

• direction?: "row" | "column"
• children?: ReactNode

<Grid>

Children in 1–6 equal columns.

• columns: number — 1–6 equal columns (one column on a narrow window).
• children?: ReactNode

<Split>

Two panes side by side (stacked on a narrow window).

• left: ReactNode
• right: ReactNode
• ratio?: number — The left pane's share of 12 columns (default 6).

<Detail>

A read-only record: label/value pairs.

• id: string
• title?: string
• fields: DetailField[]

DetailField

• label: string
• value: string

Navigation

<Navigation>

Navigation for an app drawn on <Screen nav> (<AppShell nav> draws its own). Its items are what a reviewer points at.

• id: string
• layout: "side" | "top"
• items: NavigationItem[]

NavigationItem

• id: string
• label: string
• to: string — The screen the entry opens; it shows as active there.

<Breadcrumbs>

A trail back to where the reviewer came from.

• id: string
• items: BreadcrumbItem[] — The trail, root first.

BreadcrumbItem

• id: string
• label: string
• to?: string — Where the crumb leads; the last crumb is the current page and takes none.
• params?: Record<string, string>

<Tabs>

Tabbed panels. Each tab header is an element a reviewer can point at (its id); the Tabs itself is layout.

• id: string
• tabs: Panel[]
• active?: string — The open tab, when the screen controls it; the first tab otherwise.
• onChange?: ((tabId: string) => void)

<Stepper>

A multi-step wizard. Each step header is an element a reviewer can point at (its id).

• id: string
• steps: Panel[]
• active?: string — The current step, when the screen controls it (a Next button); the first step otherwise.
• onChange?: ((stepId: string) => void)

Panel

• id: string
• label: string
• content: ReactNode

Content

<Heading>

A page or section title, with the actions beside it.

• id: string
• text: string
• level?: "page" | "section" — page (default) for a screen's title; section titles a part of it. Prefer <Section> for a part with its own actions or records.
• actions?: ReactNode — Buttons and Links beside the heading.

<Text>

A paragraph of body text.

• id: string
• text: string
• tone?: "primary" | "secondary" — secondary (default) for body copy, primary for emphasis.

<Badge>

A status chip.

• id: string
• label: string
• tone?: Tone

<Stat>

A headline number with its label. Put a screen's stats side by side in a <StatGroup>.

• id: string
• label: string
• value: string
• hint?: string — A short line under the value that gives it scale or context: "of 20 days", "3 due this week".
• icon?: StatIcon — An icon beside the label.
• tone?: Tone — Colours the icon (default is the theme's primary).

StatIcon = "Activity" | "Bell" | "Briefcase" | "Bug" | "Building2" | "Calendar" | "CalendarCheck" | "CalendarClock" | "CalendarDays" | "ChartColumn" | "CircleCheck" | "CircleX" | "ClipboardList" | "Clock" | "Cloud" | "Cpu" | "CreditCard" | "Database" | "DollarSign" | "FileText" | "Gauge" | "Globe" | "HeartPulse" | "Hourglass" | "Inbox" | "Layers" | "ListChecks" | "Lock" | "Mail" | "MessageSquare" | "Package" | "Plane" | "Receipt" | "Rocket" | "Server" | "Shield" | "ShoppingCart" | "Star" | "Tag" | "Ticket" | "Timer" | "TrendingDown" | "TrendingUp" | "TriangleAlert" | "Truck" | "User" | "UserCheck" | "Users" | "Wallet" | "Zap"

The icons a <Stat> may show, named as in WSO2's Oxygen icon set (Lucide's names). A theme draws each or none; an unknown name fails the check.

<StatGroup>

A row of <Stat>s at equal widths, wrapping on a narrow window.

• children?: ReactNode — The <Stat>s, in reading order.

<Alert>

A callout: info, success, warning or error.

• id: string
• tone: Tone
• title?: string
• text: string

<EmptyState>

What a list shows when there is nothing in it.

• id: string
• title: string
• text: string
• actions?: ReactNode — The Buttons that start something.

<Button>

A button. Give it to to navigate, onPress to do anything else, submit to submit its form.

• id: string
• label: string
• emphasis?: "primary" | "danger" — primary for the screen's main action, danger for a destructive one; outlined otherwise.
• disabled?: boolean
• submit?: boolean — Submits the enclosing <Form> (which validates its fields, then calls its onSubmit).
• to?: string — Navigate to this screen when pressed. Prefer it to onPress for plain navigation: the checks verify it.
• params?: Record<string, string> — The params to carries, read on the target with useParams.
• onPress?: (() => void) — Run when pressed: change mock data, open a dialog, navigate conditionally.

<Link>

An inline link; presses like a Button.

• id: string
• label: string
• to?: string — Navigate to this screen when pressed. Prefer it to onPress for plain navigation: the checks verify it.
• params?: Record<string, string> — The params to carries, read on the target with useParams.
• onPress?: (() => void) — Run when pressed: change mock data, open a dialog, navigate conditionally.

Tone = "default" | "info" | "success" | "warning" | "error"

Pressable

• to?: string — Navigate to this screen when pressed. Prefer it to onPress for plain navigation: the checks verify it.
• params?: Record<string, string> — The params to carries, read on the target with useParams.
• onPress?: (() => void) — Run when pressed: change mock data, open a dialog, navigate conditionally.

Forms

<Form>

A form card: its Fields, then its action Buttons. Validates on submit.

• id: string
• title?: string
• children?: ReactNode — Its Fields.
• actions?: ReactNode — Its Buttons, under the fields; a <Button submit> submits.
• onSubmit?: ((values: Record<string, string>) => void) — Called with every field's value, keyed by name, when a submit passes validation.

<Field>

One input. It holds what is typed into it; inside a Form, the Form validates and submits it.

• id: string
• label: string
• name?: string — The key of its value in the enclosing Form's onSubmit values (default: its id).
• type?: FieldType
• value?: string — Controls the field: it shows this; with onChange it is editable, without it read-only.
• defaultValue?: string — The starting value of a field that holds its own (no value). A switch is on or off.
• options?: string[] — A select's choices.
• error?: string — A problem to show regardless of validation (e.g. in a validation-error display state).
• required?: boolean
• pattern?: string — A regular expression the whole value must match when it is not empty.
• patternMessage?: string — What a value that does not match pattern shows.
• placeholder?: string
• onChange?: ((value: string) => void)

FieldType = "number" | "text" | "select" | "date" | "textarea" | "switch"

<Filters>

A filter bar above a list.

• id: string
• children?: ReactNode — Its Fields, laid out compactly in a row.

<ValidationSummary>

The problems a failed submit shows, for a display state that shows them without a submit.

• id: string
• issues: string[]

Data

<Table>

A table of records.

• id: string
• title?: string
• columns: (string | TableColumn)[]
• rows: TableRow[]
• onRowPress?: ((rowId: string) => void) — Run when a row is pressed, with its id; a row with neither this nor to is only highlighted.
• empty?: ReactNode — What an empty table shows instead (an <EmptyState>).

TableColumn

• label: string
• kind?: "number" | "text" | "status" — text (default); number aligns figures to the right; status shows each row's status as a badge (one per table). A plain string is a text column.

TableRow

• id: string — The row's element id: unique on the screen (prefix it with the table's).
• cells: string[] — One per text or number column, in column order; the status column takes status.
• status?: TableStatus — The badge in the table's status column.
• actions?: TableAction[] — What can be done to this record, drawn as buttons in a trailing column; pressing one does not press the row.
• tone?: Tone — Colours the last cell as a status, in a table without a status column. Prefer status.
• to?: string — Open this screen when the row is pressed.
• params?: Record<string, string>

TableStatus

• text: string
• tone: Tone

TableAction

• id: string — The action's element id: unique on the screen (prefix it with the row's).
• label: string
• emphasis?: "danger" — danger for a destructive action.
• to?: string — Navigate to this screen when pressed. Prefer it to onPress for plain navigation: the checks verify it.
• params?: Record<string, string> — The params to carries, read on the target with useParams.
• onPress?: (() => void) — Run when pressed: change mock data, open a dialog, navigate conditionally.

<Timeline>

An activity history.

• id: string
• title?: string
• entries: TimelineEntry[] — Newest first.

TimelineEntry

• when: string
• who: string
• text: string

Overlays

<Dialog>

A modal.

• id: string
• title: string
• open: boolean
• onClose: () => void
• children?: ReactNode
• actions?: ReactNode — Its Buttons, at the bottom.

<Drawer>

A side panel.

• id: string
• title: string
• open: boolean
• onClose: () => void
• children?: ReactNode

Finding codes

prototype check --json prints { ok, findings: [{ code, file, location, message }] } and exits 1 when there are findings.

Code	Meaning
MISSING_FILE	prototype.json or prototype.tsx is not in the folder.
SCHEMA_VIOLATION	prototype.json is not JSON, or does not have the manifest's shape.
UNSUPPORTED_VERSION	prototype.json's schemaVersion is not 3.
DUPLICATE_ID	A role, state, screen or flow id repeats another; the four share one namespace.
UNKNOWN_REFERENCE	A manifest reference names nothing, or a flow step its role cannot reach.
SYNTAX_ERROR	prototype.tsx does not parse.
FORBIDDEN_IMPORT	An import other than react and @wso2/prototype-kit, a dynamic import(), or require.
FORBIDDEN_API	A browser, network, storage, code-generation or nondeterministic API.
FORBIDDEN_ELEMENT	A raw HTML element; screens are drawn with kit components only.
SOURCE_TOO_LARGE	prototype.tsx is over the size cap.
NO_APP	prototype.tsx does not export default defineApp({ screens, data }).
SCREEN_MISMATCH	defineApp's screens are not exactly the manifest's screens.
UNKNOWN_NAV_TARGET	A to or go() names a screen that does not exist, or one the viewing role cannot reach.
TYPE_ERROR	prototype.tsx does not type-check: it reads a property, prop or name its types do not have, or passes a value of the wrong type.
RENDER_FAILED	The module, or a screen for some role and display state, throws or runs too long.
DUPLICATE_ELEMENT_ID	Two elements on one screen share an id.

<!-- kit:end -->

Mock data

Records are part of the source and never generated at render time, so write them out in full:

• Shaped by the data model. Each collection in defineApp({ data }) is an entity of domain-model.md, and each record has that entity's attributes. Columns, detail fields and form fields are those attributes, in words a user reads (submittedAt becomes "Submitted"). A value has the type the model gives it: an enum value is one of its values, an amount reads as an amount. A relation shows as the related record's name, not its id. Type the records after the entity (interface Expense { … }).
• Realistic. Plausible names, amounts, dates and statuses for the domain; never foo, test, Lorem ipsum or Item 1.
• Deterministic. The same design gives the same records: fixed values, no randomness, no "today" other than useToday(). A row's id is derived from the record (expense.1042).
• Enough rows to read as real (three to six), and a state in which a list is empty when the story has one.

Stable ids

Manifest ids and element ids (the id of every kit component) are identities, labels are not: a reviewer's annotations point at element ids, and shared links name screens, flows and states, so:

• Name them <kind>.<slug> from what the thing is (screen.queue, btn.approve, field.amount), except role ids, which are security.json's names. An element id is unique on its screen; a row's id is prefixed with its table's kind (expense.1042).
• Revising an existing prototype keeps every key and id whose thing still exists. Rename labels freely; change an id only when its thing is removed or genuinely becomes something else.
• Regenerating a prototype that has review comments (/prototype on a reviewed design) is a revision like any other: edits, ids kept. Leave specs/design/review.json as it is. Its comments stay open for Address comments, and the file's Checked mark clears by itself when the prototype changes.

Closing

When a prototype passes its checks, report it in one chat line: its screen count and flow count, then each story you set aside and anything from the design you could not show, with the reason.