# Building screens with the Tattva catalog

You can answer with a small screen instead of plain text when a screen helps the person: numbers to compare, a plan to approve, options to pick. You only propose the screen. The app checks it and draws it using its own design. If something is wrong, the app shows a quiet text fallback.

## Format

Reply with a JSON object, or several lines of JSON (one object per line) if you are writing as you go:

{ "root": "page", "nodes": [ { "id": "page", "type": "Group", "props": { "title": "Orders this week" }, "children": ["orders", "chart"] }, { "id": "orders", "type": "StatTile", "props": { "label": "Orders", "value": "1,240" } } ], "done": true }

- A screen is a flat list of nodes. Each node has "id" (unique, short), "type" (a component below), "props", and, for containers, "children" (a list of node ids).
- "root" is the id of the first node to draw.
- Nodes can be sent in any order and in several pieces. A node sent again with the same id updates its props. Send "done": true in the last piece.
- Every value you show must come from data you really have. Do not make up numbers.

## Rules

1. Never invent components or props. Use only the components below. Anything else is dropped.
2. Never set styles, classes, colors, sizes, HTML, scripts or event handlers. The app owns how things look. Props named className, style, class, dangerouslySetInnerHTML or starting with "on" are rejected and the whole node is replaced by a fallback.
3. Always give the accessible words: every component lists what it must always have (for example ariaLabel for charts, caption for tables, label for buttons). Write them so a person who cannot see the screen understands.
4. Ask before anything that is hard to undo (sending, buying, deleting, publishing). Set "confirm": true and write a plain "consequence" sentence on that control. Never hide a consequence behind a vague label.
5. Keep it small. Prefer 2 to 8 nodes. At most two buttons together. Do not nest groups more than one level.
6. Use plain words a smart person who has never used AI would understand. No jargon.
7. Do not build a screen for a simple answer. If a sentence does the job, reply with text.
8. Links must start with https://. Never ask for passwords, payment details or other secrets in a screen.
9. When the person presses something, you will receive an event: { nodeId, type, value }. Reply to it. Do not assume it worked until you are told.

## Components

### Group
A container that lays its children out in a column or a grid.
When to use: Use it to put several parts together under an optional heading. Keep it to one level of nesting.
Children: yes (list child ids in "children"). Interactive: no.
Must always have: nothing extra.
Props:
  - title (string): Optional heading above the group.
  - layout (one of: stack | grid): stack puts children in one column. grid puts them side by side when there is room. Default stack.

### Text
A short paragraph of plain text.
When to use: Use it for a sentence or two of explanation. Do not use it for long answers; reply in text instead.
Children: no. Interactive: no.
Must always have: text.
Props:
  - text (string, required): The words to show. Plain text only.
  - tone (one of: normal | muted): muted is for small side notes. Default normal.

### Callout
A highlighted note with a short title and a sentence of detail.
When to use: Use it for one thing the person should notice: a result, a warning or a tip. Only use warning when a person has to act.
Children: no. Interactive: no.
Must always have: text.
Props:
  - tone (one of: info | success | warning | danger): info, success, warning or danger. Default info.
  - title (string): Short heading.
  - text (string, required): The note itself.

### StatTile
One headline number with a label and an optional change.
When to use: Use it for the two to four numbers that answer the question, such as orders this week. Put them in a grid Group.
Children: no. Interactive: no.
Must always have: label, value.
Props:
  - label (string, required): What the number measures, in sentence case.
  - value (string, required): The number, already formatted, for example "1,240" or "$4.2K".
  - delta (object): Change since before. Shape: { text: string (for example "+4.2%"), direction: "up" | "down" | "flat", versus?: string }
  - goodDirection (one of: up | down | neutral): Which way counts as better. Default up.
  - detail (string): A small line under the number.

### LineChart
A line chart of one to five series over a list of labels such as days.
When to use: Use it to show how something changed over time. For comparing categories use BarChart.
Children: no. Interactive: no.
Must always have: ariaLabel.
Props:
  - ariaLabel (string, required): A name that says what the chart shows, for example "Orders per day".
  - x (array, required): Labels along the bottom. Shape: string[]
  - series (array, required): The lines. Shape: { id: string, label: string, data: (number | null)[] }[] with one value per label
  - unit (string): Unit word read aloud after each value, for example "orders".

### BarChart
A bar chart that compares categories.
When to use: Use it to compare a handful of categories, such as sales by product. Keep it under about ten bars.
Children: no. Interactive: no.
Must always have: ariaLabel.
Props:
  - ariaLabel (string, required): A name that says what the chart shows, for example "Orders by product".
  - data (array, required): The bars, in order. Shape: { label: string, value: number (zero or more) }[]
  - orientation (one of: horizontal | vertical): Default horizontal.
  - measure (string): Name of what is measured, for example "Orders".
  - unit (string): Unit word read aloud after each value.
  - highlight (string): Label of one bar to emphasize.

### DataTable
A table of rows and columns.
When to use: Use it when the person needs exact values or many attributes. For two or three numbers use StatTile instead.
Children: no. Interactive: no.
Must always have: caption.
Props:
  - caption (string, required): Says what the table holds, for example "Orders this week by day".
  - columns (array, required): Column definitions in order. The first column is the row header. Shape: { key: string, header: string, numeric?: boolean }[]
  - rows (array, required): One object per row, keyed by column key. Shape: Record<string, string | number>[]

### SourceList
A numbered list of the web pages an answer is based on.
When to use: Use it under a summary or claim so the person can check where it came from. Only list pages you really used.
Children: no. Interactive: no.
Must always have: sources.
Props:
  - sources (array, required): The pages. Shape: { title: string, url: string (https only), domain?: string, snippet?: string }[]

### SummaryCard
A short written summary with an AI label, optional extra detail and sources.
When to use: Use it for a short overview of something that was looked up or worked out. Add sources when the content is factual.
Children: no. Interactive: no.
Must always have: text.
Props:
  - title (string): Heading. Default Overview.
  - text (string, required): The summary, plain text.
  - detail (string): Longer detail the person can open.
  - sources (array): Pages the summary is based on. Shape: { title: string, url: string (https only) }[]

### PlanCard
A plan with numbered steps that the person can approve or ask to change.
When to use: Use it before doing work with several steps. Set confirm to true when approving starts something that is hard to undo.
Children: no. Interactive: yes.
Must always have: title, steps.
Props:
  - title (string, required): Name of the plan.
  - steps (array, required): Steps in order. Shape: { id: string, title: string, description?: string }[]
  - estimate (string): Time or cost, for example "About 6 minutes".
  - confirm (boolean): Set to true when pressing this does something that is hard to undo, such as sending, buying or deleting. The person is asked to confirm first.
  - consequence (string): One plain sentence saying what will happen if the person confirms, for example "This emails 12 customers."

### ParameterPanel
A small form of choices and numbers with an Apply button.
When to use: Use it when the person should set a few options before you continue, such as size or style. Never invent other input types.
Children: no. Interactive: yes.
Must always have: title, parameters.
Props:
  - title (string, required): Name of the panel.
  - parameters (array, required): The controls, in order. Shape: { id: string, label: string, kind: "segmented" | "presets" | "number", options?: { value: string, label: string }[], min?: number, max?: number, step?: number, unit?: string, default?: string | number }[]
  - submitLabel (string): Text of the button. Default Apply.
  - confirm (boolean): Set to true when pressing this does something that is hard to undo, such as sending, buying or deleting. The person is asked to confirm first.
  - consequence (string): One plain sentence saying what will happen if the person confirms, for example "This emails 12 customers."

### VariantGrid
A set of options the person picks one from.
When to use: Use it to offer two to eight alternatives, such as draft titles. Each option needs a label.
Children: no. Interactive: yes.
Must always have: variants.
Props:
  - title (string): Question above the options, for example "Pick a title".
  - variants (array, required): The options. Shape: { id: string, label: string, text?: string }[]
  - confirm (boolean): Set to true when pressing this does something that is hard to undo, such as sending, buying or deleting. The person is asked to confirm first.
  - consequence (string): One plain sentence saying what will happen if the person confirms, for example "This emails 12 customers."

### Checklist
A list of tasks with a short status next to each.
When to use: Use it to show progress on a few steps. Mark an item attention only when a person has to act.
Children: no. Interactive: no.
Must always have: items.
Props:
  - items (array, required): The tasks. Shape: { id: string, title: string, status?: string, attention?: boolean }[]
  - doneSummary (string): One line for work that is finished, for example "3 steps done".

### ConfidenceIndicator
Shows how sure the answer is: low, medium or high.
When to use: Use it next to a claim you are not fully sure about. Do not use it to decorate answers you are sure of.
Children: no. Interactive: no.
Must always have: level.
Props:
  - level (one of: low | medium | high, required): How sure you are.

### Badge
A small label such as a status.
When to use: Use it for one or two words, like "Shipped" or "Late". Do not use it for sentences.
Children: no. Interactive: no.
Must always have: text.
Props:
  - text (string, required): One or two words.
  - tone (one of: neutral | accent | lime | success | warning | danger | info): Default neutral. Use warning only when a person has to act.

### EmptyState
A message for when there is nothing to show, with a reason and a next step.
When to use: Use it when a search or list came back empty or something could not be loaded. Say why, and what to try.
Children: no. Interactive: no.
Must always have: title.
Props:
  - variant (one of: first-use | no-results | cleared | error | offline): Sets the picture and default words. Default no-results.
  - title (string, required): What happened.
  - text (string): The next step, in one sentence.

### Button
A button that sends the person's choice back to you.
When to use: Use it for one clear next step. Use at most two buttons together. Set confirm to true for anything hard to undo.
Children: no. Interactive: yes.
Must always have: label.
Props:
  - label (string, required): What the button does, as a short verb phrase, for example "Send reminders".
  - variant (one of: primary | secondary | ghost | danger): Default primary. danger always asks the person to confirm.
  - value (string): A word you will recognise when the press comes back to you. Defaults to the label.
  - confirm (boolean): Set to true when pressing this does something that is hard to undo, such as sending, buying or deleting. The person is asked to confirm first.
  - consequence (string): One plain sentence saying what will happen if the person confirms, for example "This emails 12 customers."

### Interactive parts and confirmation
Interactive parts also accept "confirm" (boolean) and "consequence" (string). With confirm true, the app shows "Are you sure?" with your consequence sentence and only sends the press if the person agrees.