{ "note": "Tattva components, generated from the documentation registry at build time. Import every component from the package index, never from deep paths.", "version": 1, "site": "https://lkb00.github.io/tattva/", "count": 228, "components": [ { "id": "button", "name": "Button", "level": "atom", "since": "0.5", "aka": [ "btn", "call to action", "cta" ], "category": "controls", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "loading", "note": "Pass busy: a spinner takes the place of the label at the same width, presses are ignored, aria-busy is set and busyLabel (default \"Working\") is read. It keeps focus and stays in the Tab order.", "source": "documented" }, { "name": "disabled", "note": "Pass the native disabled attribute; it looks dimmed, ignores clicks and is skipped by keyboard.", "source": "documented" }, { "name": "hover", "note": "The background shifts to a darker or tinted shade when the pointer is over it.", "source": "documented" }, { "name": "focus", "note": "A visible focus ring appears when you reach it with the keyboard.", "source": "documented" }, { "name": "pressed", "note": "While held down it sinks to --press-scale in --dur-instant and comes back in --dur-fast when let go. Off under reduced motion.", "source": "documented" } ], "summary": "A rounded button with a text label. It comes in five styles and three sizes, and can hold an icon.", "description": "Button is how people take an action. Its style shows how important the action is. Primary is dark and bold. Lime is a bright highlight for the one most positive action. Secondary has an outline. Ghost has no border. Danger is for actions that delete things. It sinks a little when pressed. Set busy while work runs after a press, and a spinner takes the place of the label. It never sends a form unless you ask it to.", "purpose": "The main way to take an action. Its style shows how much the action matters, so one strong button can lead a screen while quieter ones sit beside it.", "useFor": [ "An action with a short verb label, like Send, Save or Regenerate.", "The one main action on a screen: use the primary or lime style.", "A second, quieter action next to the main one: use secondary or ghost.", "Deleting something, or anything that cannot be undone: use danger." ], "notFor": [ { "text": "An action shown by an icon alone", "use": "icon-button" }, { "text": "A setting that turns on or off right away", "use": "switch" }, { "text": "Picking one option from a small set", "use": "segmented-control" } ], "whenToUse": [ "Use one primary button per screen, for the action you most want people to take.", "Use lime for one positive highlight, with dark text. Lime is only ever a background.", "Use secondary for the second action beside a primary one. Use ghost for quiet toolbar actions.", "Start labels with a verb that says what happens, like \"Regenerate\" or \"Delete chat\".", "Use busy, not disabled, while a press is being handled, so focus stays on the button." ], "avoid": [ "Do not use the danger style unless something is deleted or cannot be undone.", "Do not put two primary buttons side by side.", "Do not make a button amber. Amber is only for when a person has to act.", "Do not use an icon alone in a Button. For icon-only buttons, use IconButton with a label." ], "accessibility": [ "It is a real button, so the Tab key reaches it and Enter and Space press it.", "A clear outline shows when someone tabs to it.", "A disabled button looks faded, cannot be pressed and is skipped by the Tab key.", "While busy it sets aria-busy, keeps focus and stays in the Tab order, and screen readers hear busyLabel after the label, which stays in the page but cannot be seen. Presses do nothing until busy is off.", "On press it sinks to --press-scale in --dur-instant and comes back in --dur-fast. IconButton has the same press.", "The press is off, and color changes are instant, for people who turn off motion in their system settings." ], "accessibilityYouDo": [ "Write a label that says what happens, such as \"Delete chat\", not \"OK\".", "Set type to \"submit\" when the button should send a form. It does not by default.", "If you put only an icon inside, add a name for screen readers, or use IconButton instead.", "While busy, set busyLabel to what is happening, such as \"Saving\". Turn busy off when the work ends, and show the result or the error on the page." ], "onPhone": [ "On a touch screen every button keeps the size it is drawn at and has an invisible tap area at least 44px tall and wide, so sm and md stay small but are easy to tap.", "The label never wraps, so a long label can run past a narrow container. Keep labels short or shorten them on a phone.", "Hover colours do nothing on a phone, so the pressed state is the only feedback: the button sinks a little under the finger and comes back when it lifts." ], "importPath": "import { Button } from \"./index\"", "sourcePath": "src/atoms/Button.tsx", "props": [ { "name": "variant", "type": "\"primary\" | \"lime\" | \"secondary\" | \"ghost\" | \"danger\"", "required": false, "default": "\"primary\"", "description": "Visual weight of the button. Exported as ButtonVariant." }, { "name": "size", "type": "\"sm\" | \"md\" | \"lg\"", "required": false, "default": "\"md\"", "description": "Height and padding: 32px, 36px or 44px. Exported as ButtonSize." }, { "name": "leading", "type": "ReactNode", "required": false, "default": null, "description": "Content rendered before the label, usually an icon." }, { "name": "trailing", "type": "ReactNode", "required": false, "default": null, "description": "Content rendered after the label." }, { "name": "busy", "type": "boolean", "required": false, "default": "false", "description": "Work is running after a press. The label gives way to a spinner without changing the width, presses are ignored, and the button keeps focus and stays in the Tab order. Sets aria-busy." }, { "name": "busyLabel", "type": "string", "required": false, "default": "\"Working\"", "description": "Read by screen readers while busy, for example \"Saving\"." }, { "name": "type", "type": "\"button\" | \"submit\" | \"reset\"", "required": false, "default": "\"button\"", "description": "Native button type. Set to \"submit\" explicitly inside forms." }, { "name": "ref", "type": "Ref", "required": false, "default": null, "description": "The button element, for moving focus to it, for example onto the safe choice of a confirmation." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Merged after the variant and size classes, so it can override them." }, { "name": "children", "type": "ReactNode", "required": false, "default": null, "description": "The label." }, { "name": "...rest", "type": "ButtonHTMLAttributes", "required": false, "default": null, "description": "Passed to the underlying \n \n \n \n \n" }, { "title": "Sizes", "description": "Small, medium and large. Medium is the default.", "code": "
\n \n \n \n
" }, { "title": "With icons", "description": "An icon can sit before or after the label.", "code": "
\n \n \n \n
" }, { "title": "Busy while saving", "description": "Press it and it shows a spinner for a moment. The button keeps its width, ignores more presses and keeps focus, so nothing jumps and a second press does not save twice.", "code": "function Example() {\n const [busy, setBusy] = useState(false);\n const save = () => {\n setBusy(true);\n window.setTimeout(() => setBusy(false), 1500);\n };\n return ;\n}" }, { "title": "Disabled", "description": "A disabled button looks faded and cannot be pressed.", "code": "
\n \n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-button/", "markdownUrl": "https://lkb00.github.io/tattva/docs/button.md" }, { "id": "icon-button", "name": "IconButton", "level": "atom", "since": "0.5", "aka": [ "icon only button", "action icon" ], "category": "controls", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "selected", "note": "Set with the active prop.", "source": "prop" } ], "summary": "A round button that shows only an icon. It always has a name, and it can show an on or off state.", "description": "IconButton is for actions shown by a small picture alone, like copy, regenerate, send and stop. It must have a label. The label is read by screen readers and shown as a tooltip on hover. Set active to make it an on-or-off button with a soft highlight.", "purpose": "A small round button for actions people know by their icon, such as copy, send or stop. There are no words on it, so it always takes a name that screen readers read and a mouse shows as a tooltip.", "useFor": [ "Toolbar actions under a reply, like copy and regenerate.", "The send and stop buttons in a message box.", "An on-or-off action, like marking a reply as good: set active." ], "notFor": [ { "text": "An action whose icon people may not recognise", "use": "button" }, { "text": "A setting that stays on until someone turns it off", "use": "switch" } ], "whenToUse": [ "Always give it a label that names the action, like \"Copy\" or \"Stop generating\".", "Use lime for the send button and primary for stop.", "Use active for real on-or-off buttons, and keep the label the same when the state changes.", "Use a slightly smaller icon in the small size." ], "avoid": [ "Do not use IconButton when the icon is unclear. Use a Button with text.", "Do not use active to mark the page someone is on.", "Do not put text inside. The button is a fixed square.", "Do not make it amber. Amber is only for when a person has to act." ], "accessibility": [ "Screen readers read the label as the button's name.", "The same label shows as a tooltip when a mouse hovers over it.", "When active is set, screen readers say whether it is pressed.", "It is a real button, so the Tab key reaches it, Enter and Space press it, and a clear outline shows on focus.", "A disabled button cannot be pressed. The lime send button stays visible but faded." ], "accessibilityYouDo": [ "Give it a label that names the action, such as \"Stop generating\".", "Keep the label the same when active changes. Screen readers already say whether it is pressed.", "Leave active out for plain actions, so screen readers do not treat them as on-or-off buttons." ], "onPhone": [ "On a touch screen the button keeps its size and has a tap area at least 44px tall and wide, even at size sm.", "The name only shows as a hover tooltip, which a phone never shows, so the icon must be clear without it.", "Leave room between neighbouring icon buttons. Each tap area is 44px wide, so buttons packed close together share the space between them." ], "importPath": "import { IconButton } from \"./index\"", "sourcePath": "src/atoms/Button.tsx", "props": [ { "name": "label", "type": "string", "required": true, "default": null, "description": "Accessible name. Applied as aria-label and as the title tooltip." }, { "name": "variant", "type": "\"ghost\" | \"secondary\" | \"primary\" | \"lime\"", "required": false, "default": "\"ghost\"", "description": "Visual style. There is no danger variant." }, { "name": "size", "type": "\"sm\" | \"md\"", "required": false, "default": "\"md\"", "description": "Square size, 28px (sm) or 36px (md)." }, { "name": "active", "type": "boolean", "required": false, "default": null, "description": "Sets aria-pressed and applies the soft accent background. Leave undefined for a plain action button." }, { "name": "type", "type": "\"button\" | \"submit\" | \"reset\"", "required": false, "default": "\"button\"", "description": "Native button type." }, { "name": "ref", "type": "Ref", "required": false, "default": null, "description": "The button element, for moving focus to it." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Merged last, so it can override the defaults." }, { "name": "children", "type": "ReactNode", "required": false, "default": null, "description": "The icon, typically an icon from lib/icons at 14 to 16px." }, { "name": "...rest", "type": "ButtonHTMLAttributes", "required": false, "default": null, "description": "Passed to the underlying " } ], "pageUrl": "https://lkb00.github.io/tattva/component-spinner/", "markdownUrl": "https://lkb00.github.io/tattva/docs/spinner.md" }, { "id": "skeleton", "name": "Skeleton", "level": "atom", "since": "0.5", "aka": [ "placeholder", "shimmer", "loading placeholder", "ghost element" ], "category": "states", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [], "summary": "A shimmering gray block that holds the place of content while it loads.", "description": "Skeleton is a gray block with a soft moving shine. It has no size of its own, so you set its width and height. Use several to sketch the shape of what is about to appear.", "purpose": "A gray block with a soft moving shine that holds the space of content still loading. Several together sketch the shape of what is coming, so the page does not jump when it arrives.", "useFor": [ "Lines of text that are loading: vary the widths.", "A list row with a picture and text, before the data arrives.", "Cards or images whose size you already know." ], "notFor": [ { "text": "A short wait inside a button", "use": "spinner" }, { "text": "The wait before the assistant replies", "use": "typing-indicator" }, { "text": "A load that failed", "use": "error-state" } ], "whenToUse": [ "Match the size and position of the real content, so the page does not jump.", "Vary line lengths so it looks like real text.", "Use a round block for pictures of people and gently rounded blocks for text and images.", "Replace the whole group with real content at once.", "Set a width and height on each block. Without them it has no size and shows nothing." ], "avoid": [ "Do not leave blocks on screen after something fails. Show an error message instead.", "Do not use it inside a button. Use Spinner.", "Do not put text inside a Skeleton. Screen readers cannot see it.", "Do not use a Skeleton and a Spinner for the same area." ], "accessibility": [ "Screen readers skip it.", "The shine stops for people who turn off motion in their system settings.", "It cannot be pressed, and the Tab key skips it." ], "accessibilityYouDo": [ "Tell screen readers the area is loading, for example with a hidden status message. The blocks themselves are skipped." ], "onPhone": [ "Skeleton has no size of its own. It fills the width and height you give it, so use classes that fit a narrow screen.", "The shimmer runs on a phone unless the person has asked for less motion." ], "importPath": "import { Skeleton } from \"./index\"", "sourcePath": "src/atoms/Skeleton.tsx", "props": [ { "name": "className", "type": "string", "required": false, "default": null, "description": "Sets the size and any radius override. Without a height and width the block collapses to zero." }, { "name": "...rest", "type": "HTMLAttributes", "required": false, "default": null, "description": "Passed to the
." } ], "variantsHint": {}, "tokens": [ "--surface-sunken", "--border", "--animate-shimmer" ], "related": [ "spinner", "shimmer-text", "typing-indicator" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Text lines", "description": "Make the lines different lengths so it looks like a paragraph.", "code": "
\n \n \n \n
" }, { "title": "Message row", "description": "A round block for a picture, with two lines of text beside it.", "code": "
\n \n
\n \n \n
\n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-skeleton/", "markdownUrl": "https://lkb00.github.io/tattva/docs/skeleton.md" }, { "id": "switch", "name": "Switch", "level": "atom", "since": "0.5", "aka": [ "toggle", "toggle switch", "on off" ], "category": "forms", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "selected", "note": "Set with the checked prop.", "source": "prop" }, { "name": "disabled", "note": "Set with the disabled prop.", "source": "prop" } ], "summary": "An on-off switch with a name for screen readers. It can be disabled and can carry a hidden explanation.", "description": "Switch turns a setting on or off right away, like turning web search on. Your code keeps track of whether it is on. When on, the track is dark. When off, it is gray. The knob slides across. The area you can press is larger than it looks, so it is easy to hit.", "purpose": "Turns one setting on or off the moment it is pressed, with no save step. The knob position and the track color both show the state, so color is not the only clue.", "useFor": [ "A setting that applies right away, like web search or memory.", "A row in a settings list, with the setting's name beside it.", "A setting that is locked: disable it and give the reason." ], "notFor": [ { "text": "An action, like sending or deleting", "use": "button" }, { "text": "A choice between more than two options", "use": "segmented-control" }, { "text": "An icon action that shows a pressed state", "use": "icon-button" } ], "whenToUse": [ "Use it for settings that apply right away, with no save step.", "Show a visible label next to it and give the switch the same name.", "Name the setting, not the action. Write \"Web search\", not \"Turn on web search\".", "Keep the on-or-off value in your own code and pass it back as checked." ], "avoid": [ "Do not use a Switch for a choice that needs a confirm step. Use a checkbox or a form.", "Do not use it for an action. Use a Button.", "Do not make the on state amber. The track is dark when on.", "Do not disable a switch without saying why. Give the reason in the explanation or nearby text.", "Do not rely on the hidden explanation for visible help text. Only screen readers hear it, so show any help text yourself." ], "accessibility": [ "Screen readers call it a switch and say whether it is on or off.", "It is a real button, so the Tab key reaches it and Enter and Space flip it.", "The description is read after the name and state.", "The pressable area is bigger than the track, and bigger still on touch screens.", "A disabled switch is skipped by the Tab key, and screen readers call it unavailable." ], "accessibilityYouDo": [ "Give it a label that names the setting, such as \"Web search\". A visible label beside it does not name it.", "When it is disabled, say why in description and in visible text nearby." ], "onPhone": [ "On a touch screen the switch gets a hit area of at least 44px by 44px, while the track stays 20px tall.", "With a visible label, tapping the label also toggles the switch.", "Put the switch and its label on one row with room to spare, so two switches never sit closer than 44px." ], "importPath": "import { Switch } from \"./index\"", "sourcePath": "src/atoms/Switch.tsx", "props": [ { "name": "checked", "type": "boolean", "required": true, "default": null, "description": "Current state. The component is fully controlled." }, { "name": "onChange", "type": "(v: boolean) => void", "required": true, "default": null, "description": "Called with the opposite of checked when the switch is activated." }, { "name": "label", "type": "string", "required": true, "default": null, "description": "Accessible name, applied as aria-label. When children are given, the children are the name instead and label is not used." }, { "name": "children", "type": "ReactNode", "required": false, "default": null, "description": "Visible label beside the switch. Pressing it flips the switch, and it becomes the accessible name." }, { "name": "labelPosition", "type": "\"start\" | \"end\"", "required": false, "default": "\"end\"", "description": "Which side of the switch the children sit on. Only matters when children are given." }, { "name": "disabled", "type": "boolean", "required": false, "default": null, "description": "Dims the switch, removes it from the tab order and blocks onChange." }, { "name": "description", "type": "string", "required": false, "default": null, "description": "Extra context announced after the name. Rendered as screen reader text and linked with aria-describedby." }, { "name": "id", "type": "string", "required": false, "default": null, "description": "Id on the button, for a visible label that uses htmlFor." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Classes for the button. The hit area is the button, so margins and alignment apply to it." } ], "variantsHint": { "labelPosition": [ "start", "end" ] }, "tokens": [ "--accent", "--border-strong", "--dur-fast", "--focus-ring" ], "related": [ "icon-button", "button" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Controlled switch", "description": "Your code keeps the on-or-off value and updates it when the switch is pressed.", "code": "function Example() {\n const [on, setOn] = useState(true);\n return ;\n}" }, { "title": "In a settings row", "description": "The switch has no words of its own. Put a visible label beside it and give it the same name.", "code": "function Example() {\n const [search, setSearch] = useState(true);\n const [memory, setMemory] = useState(false);\n return (\n
\n
\n Web search\n \n
\n
\n Memory\n \n
\n
\n );\n}" }, { "title": "Disabled with a description", "description": "A disabled switch looks faded and cannot be changed. The explanation is read out after the name, so say why the setting is unavailable.", "code": "
\n \n {}} label=\"Memory\"\n disabled description=\"Turned off by your workspace admin.\" />\n
" }, { "title": "With a visible label", "description": "Pass the words as children. They sit beside the switch, pressing them flips it, and a screen reader uses them as the name.", "code": "function Example() {\n const [on, setOn] = useState(true);\n return Web search;\n}" } ], "pageUrl": "https://lkb00.github.io/tattva/component-switch/", "markdownUrl": "https://lkb00.github.io/tattva/docs/switch.md" }, { "id": "section-label", "name": "SectionLabel", "level": "atom", "since": "0.5", "aka": [ "overline", "eyebrow", "subheader", "list subheader", "group label" ], "category": "controls", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [], "summary": "A tiny capital-letter label that names a group in a list, with room for a small action.", "description": "SectionLabel is a small label in capital letters. It names a group of items. Make it a heading if it should show up in the page outline. At the end of the row you can add a count or a short link. It carries no content of its own.", "purpose": "A tiny capital-letter label that names a group of items, such as Today or Pinned. It stays quiet so the items stand out, and it has room at the end for a count or one small action.", "useFor": [ "Grouping chats by date in a side list.", "Naming a section in a tray or a settings panel.", "A group name with a count or a Clear button at the end." ], "notFor": [ { "text": "A page or card title" }, { "text": "A status on a single item", "use": "badge" } ], "whenToUse": [ "Use short words like \"Pinned\" or \"Last 7 days\". It shows in capitals by itself, so write it normally.", "Put it right above the group it names.", "Use the end of the row for one small control or a count.", "Make it a heading only when it is a real section title." ], "avoid": [ "Do not use it as a page or card title. Use the large headings.", "Do not type labels in capitals. The style does it.", "Do not put long sentences in it.", "Do not put several actions at the end of the row." ], "accessibility": [ "It is plain text by default, so it does not add a heading to the page outline.", "Screen readers read the text as you typed it. The capitals are only a style." ], "accessibilityYouDo": [ "Set as to a heading level when the label should appear in the page outline, and pick the level that fits.", "Give whatever you put in action its own name, such as a button label." ], "onPhone": [ "The label and the action sit on one row. The label can wrap if the action takes the space.", "The label text is 12px on touch screens.", "If the action is a button, it keeps its size on a touch screen and has a 44px tap area, so the row does not get taller. A small link needs the tap class to get the same tap area." ], "importPath": "import { SectionLabel } from \"./index\"", "sourcePath": "src/atoms/SectionLabel.tsx", "props": [ { "name": "children", "type": "ReactNode", "required": true, "default": null, "description": "The label text." }, { "name": "action", "type": "ReactNode", "required": false, "default": null, "description": "Content aligned to the end of the row, wrapped in a muted text-small leading-4 span." }, { "name": "as", "type": "\"p\" | \"h2\" | \"h3\" | \"h4\"", "required": false, "default": "\"p\"", "description": "Element to render. A label is plain text by default. Use a heading level only when it belongs in the page outline." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Merged onto the outer flex row." } ], "variantsHint": { "as": [ "p", "h2", "h3", "h4" ] }, "tokens": [ "--fg-muted" ], "related": [ "badge", "ai-disclosure" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Label only", "description": "A plain group name above a list.", "code": "
\n Today\n
" }, { "title": "With an action", "description": "Add a button or link at the end of the row.", "code": "
\n Clear}>Recent chats\n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-section-label/", "markdownUrl": "https://lkb00.github.io/tattva/docs/section-label.md" }, { "id": "attention-dot", "name": "AttentionDot", "level": "atom", "since": "0.5", "aka": [ "notification dot", "badge dot", "unread indicator", "indicator" ], "category": "controls", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [], "summary": "A small amber dot that means a person has to do something.", "description": "AttentionDot is a tiny amber circle. It is the only sign that something needs a person. Examples are a request for approval, a step that failed and needs a decision, or a reply that blocks progress. Always put it next to words that say what is needed. Amber is never for decoration or general warnings.", "purpose": "A tiny amber dot that means a person has to do something before work can go on. Amber is kept for this alone, so the dot always stands out.", "useFor": [ "A request waiting for approval.", "A chat or task in a list that is blocked on the person.", "A failed step that needs a decision." ], "notFor": [ { "text": "General warnings, or problems the system will fix by itself", "use": "callout" }, { "text": "A full list of everything waiting on the person", "use": "approval-inbox" } ], "whenToUse": [ "Use it only when a person must act before work can go on.", "Put it next to words that say what is needed.", "Use a specific label like \"Approval needed\" when the default is too vague.", "Remove it as soon as the person has acted." ], "avoid": [ "Do not use it for problems the system can fix on its own, or for general warnings.", "Do not use it alone. It must come with words.", "Do not change its color or add another amber element beside it.", "Do not use it as a decorative bullet." ], "accessibility": [ "Screen readers read it as an image named \"Needs attention\", or your label.", "It does not move, so motion settings do not affect it.", "It cannot be pressed, and the Tab key skips it." ], "accessibilityYouDo": [ "Put words next to it that say what is needed.", "Give it a specific label, such as \"Approval needed\", when the default \"Needs attention\" is too vague.", "Remove it as soon as the person has acted." ], "onPhone": [ "The dot is a fixed 6px circle and is not tappable, on a phone or anywhere else.", "Place it on or next to a control that has the 44px target, and do not rely on the dot alone to be seen at arm's length." ], "importPath": "import { AttentionDot } from \"./index\"", "sourcePath": "src/atoms/AttentionDot.tsx", "props": [ { "name": "label", "type": "string", "required": false, "default": "\"Needs attention\"", "description": "Accessible name for the dot, applied as aria-label." } ], "variantsHint": {}, "tokens": [ "--attention" ], "related": [ "badge", "ai-badge" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Beside text", "description": "The dot comes with a line saying what the person has to do.", "code": "
\n \n The assistant wants to run a command on your computer\n
" }, { "title": "In a list row", "description": "A chat in a list that is waiting on you. The dot is the marker. The words say why.", "code": "
\n Quarterly report\n \n \n Needs your input\n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-attention-dot/", "markdownUrl": "https://lkb00.github.io/tattva/docs/attention-dot.md" }, { "id": "typing-indicator", "name": "TypingIndicator", "level": "atom", "since": "0.5", "aka": [ "typing dots", "is typing", "loading dots" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [], "summary": "Three pulsing dots that show the assistant is getting ready to reply.", "description": "TypingIndicator is three small dots that pulse one after another. Show it where the reply will appear, from the moment someone sends a message until the first words show up. Then replace it with the reply. Screen readers announce its label.", "purpose": "Three pulsing dots in the spot where the reply will appear. They fill the gap between sending a message and the first words, so people know the assistant heard them.", "useFor": [ "The moment after a message is sent, until the first words arrive.", "Beside the assistant's avatar, where the reply will start." ], "notFor": [ { "text": "A step you can name, like searching the web", "use": "shimmer-text" }, { "text": "Loading that is not the assistant replying", "use": "spinner" }, { "text": "A reply that has started to appear", "use": "message" } ], "whenToUse": [ "Show it only until the first words appear.", "Put it in the same spot where the reply will appear.", "Change the label when the assistant is doing something specific.", "Use ShimmerText beside it when you can name the step, like a search." ], "avoid": [ "Do not keep it on screen once the reply starts appearing.", "Do not use it for loading that is not the assistant. Use Spinner or Skeleton.", "Do not show several in the same conversation.", "Do not make the dots lime or amber." ], "accessibility": [ "It is marked as a status and named by its label, \"Assistant is thinking\" by default.", "The dots have no text, so screen readers get only the label.", "The dots stop pulsing for people who turn off motion in their system settings." ], "accessibilityYouDo": [ "Change the label when the assistant is doing something specific." ], "onPhone": [ "TypingIndicator is three small dots and looks the same on a phone.", "It is not tappable. Put it in the message list where the next reply will start, so it does not push content when the reply arrives." ], "importPath": "import { TypingIndicator } from \"./index\"", "sourcePath": "src/atoms/TypingIndicator.tsx", "props": [ { "name": "label", "type": "string", "required": false, "default": "\"Assistant is thinking\"", "description": "Accessible name announced for the status." } ], "variantsHint": {}, "tokens": [ "--fg-subtle", "--animate-pulse-dot" ], "related": [ "shimmer-text", "spinner", "skeleton" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Default", "description": "The default label is \"Assistant is thinking\".", "code": "" }, { "title": "Where the reply will appear", "description": "Placed at the start of the coming reply, under the person's message, so nothing jumps when text arrives.", "code": "
\n Can you check my order?\n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-typing-indicator/", "markdownUrl": "https://lkb00.github.io/tattva/docs/typing-indicator.md" }, { "id": "shimmer-text", "name": "ShimmerText", "level": "atom", "since": "0.5", "aka": [ "shimmer", "loading text", "status text" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [], "summary": "Status text with a moving shine, for steps like \"Searching the web…\".", "description": "ShimmerText is a line of text with a shine that sweeps across it. Use it to show what the assistant is doing right now. When the step ends, replace it with the result.", "purpose": "One line of status text with a shine sweeping across it. The shine says the work is still going; the words say what the assistant is doing.", "useFor": [ "A step in progress, like \"Searching the web…\".", "Next to a small spinner when a step takes a while.", "A status line that you replace with the result when the step ends." ], "notFor": [ { "text": "The wait before you know what the assistant is doing", "use": "typing-indicator" }, { "text": "A list of the steps the assistant has taken", "use": "step-timeline" }, { "text": "Body text or headings" } ], "whenToUse": [ "Write a short phrase that names the step, like \"Reading 4 files…\".", "Replace it with the finished text when the step is done.", "Show one step at a time.", "Keep it short enough for one line." ], "avoid": [ "Do not use it for body text or headings.", "Do not leave it moving after the work has stopped.", "Only plain text works inside it, not other elements.", "Do not change its text color. The shine needs the default." ], "accessibility": [ "It is real text, so screen readers read it and people can select it.", "The shine stops for people who turn off motion in their system settings." ], "accessibilityYouDo": [ "Put it in an area that announces changes if people must hear each step. It does not announce itself.", "Never put the only copy of something important here. Part of the text is light and hard to read." ], "onPhone": [ "ShimmerText is inline text at 14px and wraps with the text around it on a narrow screen.", "The shimmer runs on a phone. It is a status line, so keep it short." ], "importPath": "import { ShimmerText } from \"./index\"", "sourcePath": "src/atoms/ShimmerText.tsx", "props": [ { "name": "children", "type": "string", "required": true, "default": null, "description": "The status text. Only strings are accepted." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Merged last. Use it to change size or spacing." } ], "variantsHint": {}, "tokens": [ "--fg-subtle", "--fg", "--animate-shimmer" ], "related": [ "typing-indicator", "spinner", "skeleton" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Status step", "description": "One line saying what the assistant is doing.", "code": "Searching the web…" }, { "title": "With a spinner", "description": "Add a small Spinner when the step takes a while.", "code": "
\n \n Reading 4 files…\n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-shimmer-text/", "markdownUrl": "https://lkb00.github.io/tattva/docs/shimmer-text.md" }, { "id": "hero-heading", "name": "HeroHeading", "level": "atom", "since": "0.5", "aka": [ "hero", "headline", "welcome heading" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "typing", "note": "Pass type (on by default) to reveal the text one character at a time; it shows in full at once when the user prefers reduced motion.", "source": "documented" } ], "summary": "A big centered headline that types itself out once, then stays still.", "description": "HeroHeading is the big greeting on an empty chat. It types out one letter at a time. If you turn typing off, or the person has turned off motion, the full text shows at once.", "purpose": "The big greeting on an empty chat. It types itself out once and then stays still, so the empty screen feels alive without moving forever.", "useFor": [ "The opening line of an empty chat.", "A greeting on a start page: turn typing off if people see it on every visit." ], "notFor": [ { "text": "Naming a group of items in a list", "use": "section-label" }, { "text": "Titles inside cards or sections" } ], "whenToUse": [ "Use it once per screen, as the opening line of an empty chat.", "Keep it to one short sentence so it fits on two lines on a phone.", "Turn typing off when it would replay on every visit.", "Speak to the person in a single sentence." ], "avoid": [ "Do not use it for section titles or inside cards.", "Do not change the text quickly. Each change types out again.", "Do not add another moving element next to it.", "Do not make screen readers announce it again. They already get the full sentence." ], "accessibility": [ "Screen readers hear the whole sentence at once, not each letter as it types.", "People who turn off motion see the full text right away.", "It is a second-level heading." ], "accessibilityYouDo": [ "Check that a second-level heading fits your page outline. It is always one." ], "onPhone": [ "The heading is centred and balanced, and it is smaller below the sm breakpoint so it wraps on a phone.", "Text is typed in letter by letter, and only the typed part is drawn, so on a narrow screen the heading grows taller line by line as it types. Reserve space for it if the content below should not move.", "Under reduced motion it shows all at once." ], "importPath": "import { HeroHeading } from \"./index\"", "sourcePath": "src/atoms/HeroHeading.tsx", "props": [ { "name": "text", "type": "string", "required": true, "default": null, "description": "The headline. Changing it restarts the typing animation." }, { "name": "type", "type": "boolean", "required": false, "default": "true", "description": "When false, the whole text renders at once with no animation." } ], "variantsHint": {}, "tokens": [ "--fg", "--font-serif" ], "related": [ "section-label", "ai-disclosure" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Typed", "description": "The default. The text types out when the page opens and whenever the text changes.", "code": "" }, { "title": "Static", "description": "Turn typing off to show the full text at once, for example on a page people visit often.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-hero-heading/", "markdownUrl": "https://lkb00.github.io/tattva/docs/hero-heading.md" }, { "id": "citation-marker", "name": "CitationMarker", "level": "atom", "since": "0.5", "aka": [ "inline citation", "footnote", "reference marker", "citation" ], "category": "trust", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "hover", "note": "The number fills with the accent colour when the pointer is over it.", "source": "documented" }, { "name": "focus", "note": "A visible focus ring appears when you reach the link with the keyboard.", "source": "documented" } ], "summary": "A small numbered link that points to a source, placed after a claim in a reply.", "description": "CitationMarker is a small numbered tag raised slightly like a footnote. It links to the source you give it, or to a matching spot on the same page. Hovering highlights it. Place it right after the claim it supports.", "purpose": "A small raised number after a claim that links to its source, like a footnote. It keeps the sentence readable while letting people check where a fact came from.", "useFor": [ "After a claim in a reply that comes from a source.", "Linking to a matching entry in a source list on the same page." ], "notFor": [ { "text": "Showing a source's details when people point at it", "use": "citation-hover-card" }, { "text": "The full list of sources under a reply", "use": "source-list" }, { "text": "A label that stands outside a sentence", "use": "badge" } ], "whenToUse": [ "Number markers in the order the sources first appear.", "Give each a title, so the tooltip and screen readers say what the source is.", "Give each marker a real link, or give your source list matching anchors.", "Place the marker right after the claim." ], "avoid": [ "Do not use it for footnotes that are not links.", "Do not reuse a number for different sources in one message.", "Do not use it outside a sentence. Use Badge for a standalone label.", "Do not rely on hover to show the source. People on touch screens never see it." ], "accessibility": [ "It is a real link, so the Tab key reaches it and Enter follows it.", "Screen readers hear \"Source 1\" followed by the title.", "The title also shows as a tooltip when a mouse hovers over it.", "A clear outline shows when someone tabs to it." ], "accessibilityYouDo": [ "Give each marker a title, so screen readers hear what the source is, not only its number.", "Leave some space around markers in dense text. They are small to tap." ], "onPhone": [ "The marker is only 16px tall, but on touch screens it gets an invisible tap area about 8px larger on each side.", "Its number is 12px on touch screens.", "The tooltip with the source title needs a hover, so a phone only sees the number. Show the source name in the list below the text." ], "importPath": "import { CitationMarker } from \"./index\"", "sourcePath": "src/atoms/CitationMarker.tsx", "props": [ { "name": "n", "type": "number", "required": true, "default": null, "description": "The number shown in the chip and used in the default anchor and label." }, { "name": "href", "type": "string", "required": false, "default": "`#source-${n}`", "description": "Link target. Defaults to an in-page anchor named for the number." }, { "name": "title", "type": "string", "required": false, "default": null, "description": "Source title. Shown as the native tooltip and appended to the accessible name." } ], "variantsHint": {}, "tokens": [ "--accent-soft", "--accent-fg", "--accent", "--on-accent" ], "related": [ "badge", "ai-badge" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "In a sentence", "description": "Markers sit right after the text they support.", "code": "

\n Revenue grew 12% year on year, driven\n by subscriptions.\n

" }, { "title": "Default target", "description": "With no link given, it jumps to the matching source on the same page.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-citation-marker/", "markdownUrl": "https://lkb00.github.io/tattva/docs/citation-marker.md" }, { "id": "ai-badge", "name": "AIBadge", "level": "atom", "since": "0.5", "aka": [ "ai tag", "ai chip" ], "category": "trust", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "solid", "note": "Pass solid for a filled lime badge instead of the soft one.", "source": "documented" } ], "summary": "A lime-tinted badge with a sparkle that marks content made by AI.", "description": "AIBadge is a Badge with a sparkle and a short label. Use it on generated images, summaries and drafts, so people can tell AI work from human work. It says \"AI-generated\" by default. You can change the words.", "purpose": "A badge with a sparkle that marks one piece of content as made by AI. It sits on the item itself, so people can tell AI work from human work at a glance.", "useFor": [ "A generated image, summary or draft.", "A card whose text the assistant wrote.", "Content on a photo or a busy background: turn on solid." ], "notFor": [ { "text": "A note about the whole conversation", "use": "ai-disclosure" }, { "text": "AI content that needs an explanation, or an undo after editing", "use": "ai-label" }, { "text": "Content a person wrote" } ], "whenToUse": [ "Put it on anything the AI wrote or made, like summaries or images.", "Keep the label to two words or fewer.", "Place it close to the content it describes, like a corner of a card.", "Use the same words for the same kind of content everywhere." ], "avoid": [ "Do not use it on content a person wrote.", "Do not use it as a general highlight. The sparkle means AI.", "Do not swap it for a plain Badge in the accent color.", "Do not use it in place of AIDisclosure when the whole conversation needs a caution." ], "accessibility": [ "Screen readers read the label as part of the text around it.", "Screen readers skip the sparkle.", "It cannot be pressed, and the Tab key skips it." ], "accessibilityYouDo": [ "Use a label that says what the content is, such as \"AI summary\".", "Turn on solid on images or busy backgrounds, so the text stays readable." ], "onPhone": [ "AIBadge is not tappable and does not change on a phone.", "Its text is 12px on touch screens.", "Set solid when the badge sits on an image, as on any screen size." ], "importPath": "import { AIBadge } from \"./index\"", "sourcePath": "src/atoms/AIBadge.tsx", "props": [ { "name": "label", "type": "string", "required": false, "default": "\"AI-generated\"", "description": "Text shown next to the sparkle." }, { "name": "solid", "type": "boolean", "required": false, "default": "false", "description": "Use the opaque lime badge. Set it when the badge sits on an image or another busy background so the text keeps its contrast." } ], "variantsHint": {}, "tokens": [ "--lime", "--fg" ], "related": [ "badge", "ai-disclosure", "avatar" ], "composedOf": [ "badge" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Default", "description": "The standard label for content made by AI.", "code": "" }, { "title": "Custom label", "description": "Change the words to describe the kind of content.", "code": "
\n \n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-ai-badge/", "markdownUrl": "https://lkb00.github.io/tattva/docs/ai-badge.md" }, { "id": "ai-disclosure", "name": "AIDisclosure", "level": "atom", "since": "0.5", "aka": [ "ai notice", "ai disclaimer", "transparency notice" ], "category": "trust", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [], "summary": "A small centered note reminding people to check the assistant's answers.", "description": "AIDisclosure is one line of small, light text. It sits below the message box or the conversation. It says \"AI can make mistakes. Check important information.\" You can replace the words. It has no icon or border.", "purpose": "One small, quiet line that reminds people the assistant can be wrong. It sits once under the message box, so it is always there without competing with the conversation.", "useFor": [ "Under the message box in a chat.", "At the end of a generated answer or report.", "A caution for a sensitive topic, such as medication: change the words." ], "notFor": [ { "text": "Marking one item as made by AI", "use": "ai-badge" }, { "text": "A warning the person must read or act on", "use": "callout" }, { "text": "Legal terms people must agree to" } ], "whenToUse": [ "Show it once, under the message box or at the end of the conversation.", "Keep custom text to one short sentence.", "State plainly what the person should check.", "Keep it light so it stays quiet." ], "avoid": [ "Do not repeat it under every message. Use AIBadge to mark single items.", "Do not make it an amber warning. Amber is only for when a person has to act.", "Do not use it for legal terms that need a link or a click to agree.", "Do not write long paragraphs. It is small and centered." ], "accessibility": [ "Screen readers read it as a normal paragraph, in page order.", "It is not announced when its words change." ], "accessibilityYouDo": [ "Keep critical instructions out of it. It is the lightest text in the system and easy to miss.", "If you add a link, give it words that say where it goes." ], "onPhone": [ "The line is centred 12px text that wraps on a narrow screen.", "It is not tappable. Keep it visible near the input, not behind a tap." ], "importPath": "import { AIDisclosure } from \"./index\"", "sourcePath": "src/atoms/AIDisclosure.tsx", "props": [ { "name": "children", "type": "ReactNode", "required": false, "default": null, "description": "Replaces the default message when provided." } ], "variantsHint": {}, "tokens": [ "--fg-subtle" ], "related": [ "ai-badge", "section-label" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Default", "description": "The built-in message.", "code": "" }, { "title": "Custom message", "description": "Change the words for a specific part of your product.", "code": "Answers about medication are not medical advice." } ], "pageUrl": "https://lkb00.github.io/tattva/component-ai-disclosure/", "markdownUrl": "https://lkb00.github.io/tattva/docs/ai-disclosure.md" }, { "id": "avatar-stack", "name": "AvatarStack", "level": "molecule", "since": "0.5", "aka": [ "avatar group", "facepile", "avatar list" ], "category": "controls", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "overflow", "note": "When total is larger than the people shown (or max cuts the list), a plus disc and a count appear.", "source": "documented" }, { "name": "compact", "note": "Pass compact to shorten large counts, for example 1.2K.", "source": "documented" } ], "summary": "A few overlapping avatars, a plus, then how many more people there are.", "description": "AvatarStack shows that people are here or took part, without listing everyone. It draws the first few avatars, a plus, then the number of others. Use it for viewers of a page, people in a shared chat, or who voted. The picture is decoration; screen readers hear one sentence with the names and the count.", "purpose": "Shows that people are here or took part, without listing them all. The avatars overlap to stay small, and the number says how many more there are.", "useFor": [ "Who is viewing a page or document right now.", "Who is in a shared chat.", "Who voted, reacted or took part in something." ], "notFor": [ { "text": "A single person", "use": "avatar" }, { "text": "A full list of names that people need to read or pick from" } ], "whenToUse": [ "Use real counts only. If you cannot count it, do not show it.", "Put the people the viewer knows first.", "Name what is counted with label, for example \"voted\" or \"viewing now\".", "Keep it to three faces. More faces add noise, not trust." ], "avoid": [ "Do not invent or round up numbers to look popular.", "Do not make the stack the only way to see who is there. Link to the full list when people need it.", "Do not use it for one person. Use Avatar.", "Do not colour the plus or the number. Lime belongs to the assistant." ], "accessibility": [ "Screen readers hear one sentence with the names and the count, for example \"Lokesh, Mira, Asha and 1,245 others\". The drawn avatars and number are skipped.", "The assistant is read as \"Assistant\" in that sentence.", "The number uses equal-width digits, so it does not jump when it changes.", "A ring in the page color separates overlapping avatars in light and dark mode." ], "accessibilityYouDo": [ "Wrap it in a link or button if it should open the full list. On its own it cannot be pressed.", "Set total to everyone counted, so the sentence screen readers hear gives the right number.", "Pick a label that reads well after the number, such as \"viewers\" or \"others\"." ], "onPhone": [ "Stays inline and keeps its size, so it fits beside a title or in a row on a narrow screen.", "It is not a tap target. A button around it gets a 44px tap area on touch screens, but a link around it needs the tap class or its own padding.", "Names and the count are read from a hidden sentence, so nothing depends on hover." ], "importPath": "import { AvatarStack } from \"./index\"", "sourcePath": "src/molecules/AvatarStack.tsx", "props": [ { "name": "people", "type": "{ name: string; kind?: \"user\" | \"ai\" }[]", "required": true, "default": null, "description": "People to show, most relevant first. Only the first max are drawn." }, { "name": "total", "type": "number", "required": false, "default": "people.length", "description": "Everyone counted, including the ones drawn. The number shown is the rest." }, { "name": "max", "type": "number", "required": false, "default": "3", "description": "How many avatars to draw before the plus." }, { "name": "label", "type": "string", "required": false, "default": "\"others\"", "description": "Word after the number, for example \"voted\" or \"viewing\"." }, { "name": "size", "type": "\"sm\" | \"md\"", "required": false, "default": "\"md\"", "description": "24px or 32px avatars." }, { "name": "compact", "type": "boolean", "required": false, "default": "false", "description": "Show 1.2k instead of 1,248." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Merged after the base classes." } ], "variantsHint": { "size": [ "sm", "md" ] }, "tokens": [ "--bg", "--border", "--surface", "--fg", "--fg-muted" ], "related": [ "avatar", "badge" ], "composedOf": [ "avatar" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Three people and the rest", "description": "The default: three avatars, a plus, and how many others.", "code": "" }, { "title": "Short numbers and a custom word", "description": "Use compact for big counts, and name what is being counted.", "code": "" }, { "title": "With the assistant, small", "description": "In a shared chat the assistant can be one of the faces. Small fits beside a title or in a list row.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-avatar-stack/", "markdownUrl": "https://lkb00.github.io/tattva/docs/avatar-stack.md" }, { "id": "callout", "name": "Callout", "level": "molecule", "since": "0.5", "aka": [ "alert", "banner", "notice", "inline message", "admonition", "message bar" ], "category": "states", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "danger", "note": "Set tone to danger to announce it as an alert; the other tones announce it as a status.", "source": "documented" } ], "summary": "A message box inside the page, with a color for its mood, an optional title and an optional button.", "description": "Callout is the base for every notice shown inside the page. It is a soft rounded box with an icon, an optional title, some text and an optional button. It has four moods: info, success, warning and danger. ErrorState, RefusalNotice and RateLimitNotice are built on it, so try those first if one fits.", "purpose": "A notice that sits inside the page instead of popping up over it. The soft color sets the mood, while the icon and the words carry the meaning.", "useFor": [ "A note about the page or the app, such as a saved draft or an unstable connection.", "A warning someone should read before going on.", "A short message with one button that fixes or follows up on it." ], "notFor": [ { "text": "A failure the person can try again", "use": "error-state" }, { "text": "A request the assistant will not do", "use": "refusal-notice" }, { "text": "A usage limit with a reset time", "use": "rate-limit-notice" } ], "whenToUse": [ "Give every callout a title or a clear first sentence, so color is not the only clue.", "Add one button for the next step the reader can take, like Retry or Upgrade.", "Use danger only for things that failed. Use info for limits and neutral notes.", "Keep the text to one or two sentences." ], "avoid": [ "Do not stack several callouts. Combine them or show the most important one.", "Do not use warning as decoration. It is amber, which tells people to take a look.", "Do not put long forms or lists inside. Link to a fuller page instead.", "Do not use neutral or accent colors. Only the four moods work here." ], "accessibility": [ "When it appears, screen readers announce danger right away and the other moods politely.", "The icon is hidden from screen readers.", "Info and success show a circle icon, warning and danger a triangle, so color is never the only clue." ], "accessibilityYouDo": [ "Write a title or text that says what happened, because the icon is not read out.", "Name the button for what it does, such as \"Retry upload\".", "Use the danger mood only for problems that need attention now, because screen readers interrupt for it." ], "onPhone": [ "Fills the width of its container, and the message wraps beside the icon.", "On a phone the action drops to its own line under the message, so the message keeps its full width.", "The action button keeps its size and has a 44px tap area on touch screens." ], "importPath": "import { Callout } from \"./index\"", "sourcePath": "src/molecules/Callout.tsx", "props": [ { "name": "tone", "type": "\"info\" | \"success\" | \"warning\" | \"danger\"", "required": false, "default": "\"info\"", "description": "Colour family of the surface and text. Info and success use the info icon, warning and danger use the alert icon." }, { "name": "title", "type": "string", "required": false, "default": null, "description": "Short bold heading above the body." }, { "name": "children", "type": "ReactNode", "required": false, "default": null, "description": "Body content. Rendered at 90% opacity under the title." }, { "name": "action", "type": "ReactNode", "required": false, "default": null, "description": "Trailing slot, usually a small Button." } ], "variantsHint": { "tone": [ "info", "success", "warning", "danger" ] }, "tokens": [ "--info-soft", "--info-fg", "--success-soft", "--success-fg", "--warning-soft", "--warning-fg", "--danger-soft", "--danger-fg", "--radius-card" ], "related": [ "error-state", "refusal-notice", "rate-limit-notice" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Informational", "description": "The default mood. Use it for neutral notes that ask nothing of the reader.", "code": "Your changes are saved and will sync when you are back online." }, { "title": "All tones", "description": "Success, warning and danger look alike apart from color. Screen readers announce danger more urgently.", "code": "
\n The file is ready to download.\n Uploads over 20 MB may take a minute.\n The connection dropped before the file finished.\n
" }, { "title": "With an action", "description": "Add a button at the end of the box.", "code": "Retry}>\n Responses may be delayed.\n" } ], "pageUrl": "https://lkb00.github.io/tattva/component-callout/", "markdownUrl": "https://lkb00.github.io/tattva/docs/callout.md" }, { "id": "collapsible", "name": "Collapsible", "level": "molecule", "since": "0.5", "aka": [ "disclosure", "expander", "details", "show more", "expand collapse" ], "category": "controls", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "open or closed", "note": "Set with the defaultOpen prop.", "source": "prop" }, { "name": "opening", "note": "The content grows open and fades in over --dur-base on --ease-arrive. It is clipped only while the height moves. Instant under reduced motion.", "source": "documented" }, { "name": "closing", "note": "The content shrinks and fades in --dur-fast, then is hidden from everyone with the hidden attribute. Instant under reduced motion.", "source": "documented" } ], "summary": "A heading with an arrow that shows or hides extra content when pressed.", "description": "Collapsible is a full-width heading with an arrow. Pressing it opens a hidden section, which grows open and closes a little faster. It starts closed unless you say otherwise. ThinkingBlock and ToolCallCard are built on it. Use it for extra detail most people do not need at first.", "purpose": "Hides detail that most people do not need at first behind a heading they can press. The arrow turns to show whether it is open.", "useFor": [ "Advanced options under a simpler form.", "Long detail, such as logs or notes, that would crowd the page.", "Your own expandable section when ThinkingBlock or ToolCallCard do not fit." ], "notFor": [ { "text": "The assistant's reasoning", "use": "thinking-block" }, { "text": "One step the assistant took, with its status", "use": "tool-call-card" }, { "text": "Content that most people need to read" } ], "whenToUse": [ "Make the heading say what is inside, like Sources or Full output.", "Use it to tuck away extra detail that would make the page long.", "Add space inside the hidden section yourself." ], "avoid": [ "Do not hide anything a person must act on.", "Do not put buttons inside the heading. The whole heading is one button.", "Do not stack many of them when tabs or a table would be clearer." ], "accessibility": [ "The heading is a real button. Screen readers say whether the section is open or closed.", "Enter and Space open and close it, and the keyboard stays on the heading.", "When closed, the hidden section is hidden from everyone, so screen readers and the Tab key skip it.", "The arrow is hidden from screen readers.", "The content grows open in --dur-base and closes in --dur-fast, on --ease-arrive. It is clipped only while the height moves, so focus rings inside are not cut off once it is open.", "When people turn off motion in their system settings, it opens and closes at once." ], "accessibilityYouDo": [ "Write heading words that make sense alone, because the arrow is not read out.", "Do not put another button or link inside the heading: the heading is already a button." ], "onPhone": [ "The whole header row is the button, so the tap target is the full width. On touch screens its tap area is at least 44px tall.", "It opens by tap and has no hover state, so it works the same on a phone.", "The content grows open in place and pushes the page down, with no scrolling area of its own." ], "importPath": "import { Collapsible } from \"./index\"", "sourcePath": "src/molecules/Collapsible.tsx", "props": [ { "name": "header", "type": "ReactNode", "required": true, "default": null, "description": "Content of the toggle button, shown next to the chevron." }, { "name": "children", "type": "ReactNode", "required": true, "default": null, "description": "Panel content. Stays mounted and is hidden with the hidden attribute once it has finished closing." }, { "name": "defaultOpen", "type": "boolean", "required": false, "default": "false", "description": "Initial open state when the part keeps its own state." }, { "name": "open", "type": "boolean", "required": false, "default": null, "description": "Controls whether it is open. Use with onOpenChange; without it the part keeps its own state." }, { "name": "onOpenChange", "type": "(open: boolean) => void", "required": false, "default": null, "description": "Called with the new value when the header is pressed." }, { "name": "headingLevel", "type": "2 | 3 | 4 | 5 | 6", "required": false, "default": null, "description": "Wraps the header button in a heading of this level, so screen reader users can jump between sections." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Class applied to the outer wrapper." } ], "variantsHint": { "headingLevel": [ 2, 3, 4, 5, 6 ] }, "tokens": [ "--fg-subtle", "--dur-fast", "--dur-base", "--ease-arrive" ], "related": [ "thinking-block", "tool-call-card" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Closed by default", "description": "The heading can hold more than words, like a count or a badge.", "code": "Advanced options}>\n

These settings apply to new chats only.

\n" }, { "title": "Open by default", "description": "Start it open when the content is the main reason people came.", "code": "Details}>\n

Created on 4 March by the workspace owner.

\n" } ], "pageUrl": "https://lkb00.github.io/tattva/component-collapsible/", "markdownUrl": "https://lkb00.github.io/tattva/docs/collapsible.md" }, { "id": "tray-row", "name": "TrayRow", "level": "molecule", "since": "0.5", "aka": [ "list item", "sidebar item", "nav item" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "hover", "note": "The row gets a soft background and shows its trailing text, such as Open.", "source": "documented" }, { "name": "focus", "note": "A visible focus ring appears and the trailing text shows when you reach the row with the keyboard.", "source": "documented" }, { "name": "attention", "note": "Pass attention to swap the icon for a small attention dot.", "source": "documented" }, { "name": "truncated", "note": "On wider screens a long detail is cut off with an ellipsis.", "source": "documented" } ], "summary": "A compact list row with an icon, a title, a detail line and a hint that shows on hover.", "description": "TrayRow is one pressable row for tight lists, like a task tray or recent items. Place it inside a list. When attention is on, the icon becomes an amber dot and the detail text gets darker. That marks the row that needs a person.", "purpose": "A compact row that can be pressed, for tight lists. The amber dot is the one mark that says this row is waiting on a person.", "useFor": [ "Items in a task tray or a list of recent things.", "A row that opens something when pressed.", "Showing which item is waiting on the person: turn on attention." ], "notFor": [ { "text": "A to-do item that shows status and is not pressed", "use": "checklist-row" }, { "text": "A tag that shows what the chat is about", "use": "context-chip" } ], "whenToUse": [ "Put rows inside a list.", "Mark only rows that truly wait on a person.", "Write a detail that says the status or the next step.", "Keep titles short so the detail has room." ], "avoid": [ "Do not mark most rows. The amber dot loses meaning when it is common.", "Do not hide essential actions in the hint. It only shows on hover or keyboard focus.", "Do not use it outside a list." ], "accessibility": [ "The row is a real button. The Tab key reaches it, and Enter or Space presses it.", "The amber dot is read as \"Needs attention\".", "The hint at the end shows on hover and on keyboard focus, and always shows on touch screens.", "On touch screens the row keeps its size and has a tap area at least 44px tall." ], "accessibilityYouDo": [ "Put rows inside a list (ul or ol). Each row is already a list item.", "Give the list a name for screen readers if the page has more than one.", "When attention is on, say why in the detail text." ], "onPhone": [ "Under 640px wide the row has rounded corners, the title sits above the detail, and the detail wraps instead of being cut off.", "From 640px wide the title and detail share one line and the detail is truncated.", "Rows keep their size and have a tap area at least 44px tall on touch screens, and the trailing text is always visible there instead of only on hover." ], "importPath": "import { TrayRow } from \"./index\"", "sourcePath": "src/molecules/TrayRow.tsx", "props": [ { "name": "title", "type": "string", "required": true, "default": null, "description": "Primary label, medium weight." }, { "name": "detail", "type": "string", "required": false, "default": null, "description": "Secondary text that truncates when space runs out." }, { "name": "attention", "type": "boolean", "required": false, "default": null, "description": "Shows the amber dot instead of the icon and sets the detail text to the foreground colour." }, { "name": "icon", "type": "ReactNode", "required": false, "default": null, "description": "Leading icon. Ignored when attention is true." }, { "name": "trailing", "type": "ReactNode", "required": false, "default": null, "description": "Small text or node at the right edge. Hidden until the row is hovered or focused." }, { "name": "onClick", "type": "() => void", "required": false, "default": null, "description": "Click handler for the row button." } ], "variantsHint": {}, "tokens": [ "--surface-hover", "--fg", "--fg-subtle", "--attention", "--radius-control", "--radius-card" ], "related": [ "checklist-row", "context-chip" ], "composedOf": [ "attention-dot" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Plain rows", "description": "Icons are optional. The hint at the end shows on hover or when the row is reached by keyboard.", "code": "
    \n } title=\"Meeting notes\" detail=\"Edited today\" trailing=\"Open\" />\n } title=\"Roadmap draft\" detail=\"Edited yesterday\" trailing=\"Open\" />\n
" }, { "title": "Needs attention", "description": "Mark the row where a person has to decide something. The detail should say what.", "code": "
    \n \n } title=\"Invoice batch\" detail=\"Sent\" />\n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-tray-row/", "markdownUrl": "https://lkb00.github.io/tattva/docs/tray-row.md" }, { "id": "context-chip", "name": "ContextChip", "level": "molecule", "since": "0.5", "aka": [ "context pill", "context chip", "mention chip", "attached context" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "hover", "note": "When onClick is set, the pill gets a soft background under the pointer.", "source": "documented" }, { "name": "focus", "note": "When onClick or onClear is set, those buttons show a focus ring on keyboard focus.", "source": "documented" }, { "name": "clearable", "note": "Pass onClear to add a small clear button inside a shared rounded background.", "source": "documented" } ], "summary": "A small tag near the message box that shows what the chat is about.", "description": "ContextChip shows what a chat is about. It can be a button that opens a list of choices. It can be a label with a remove button. Or it can be a plain label.", "purpose": "Shows what the chat is about, right beside the message box. It can open choices, be removed, or simply sit there as a label.", "useFor": [ "Showing the project, file or folder the chat is limited to.", "Letting a person change that scope: give it onClick to open choices.", "Letting a person drop the scope: give it onClear." ], "notFor": [ { "text": "Ready-made questions to send", "use": "suggestion-chips" }, { "text": "A file attached to one message", "use": "attachment-chip" }, { "text": "A status or category label", "use": "badge" } ], "whenToUse": [ "Make it pressable when the topic can be changed. Add a remove button when it can be removed.", "Keep labels to a few words, like a file name.", "Put tags in one row near the message box." ], "avoid": [ "Do not make a tag both pressable and removable unless both make sense.", "Do not use it for tags or filters in a table. It is only for the message box.", "Do not use very long file names. Shorten them first." ], "accessibility": [ "With onClick it is a real button. Without it, it is plain text and the Tab key skips it.", "The remove button is a real button named \"Clear context\".", "The arrow and the remove cross are hidden from screen readers. The label is read.", "After the tag is cleared, keyboard focus moves to what is left of the pill, else the next control, else the message box. Pass focusAfterClear to choose another place." ], "accessibilityYouDo": [ "When the pill opens choices, move focus into them, because the choices are yours.", "When there is more than one removable tag, give each a clearLabel that says what it clears, such as \"Clear project Atlas\".", "Pass an icon that is hidden from screen readers, so only the label is read." ], "onPhone": [ "On touch screens the pill stays 28px tall. Its clear button, and the pill itself when it is a button, keep their size and have a 44px tap area.", "It has no hover-only parts: the picker opens on tap and the clear button is always shown.", "The label has no truncation, so keep it short for a narrow screen." ], "importPath": "import { ContextChip } from \"./index\"", "sourcePath": "src/molecules/ContextChip.tsx", "props": [ { "name": "children", "type": "ReactNode", "required": true, "default": null, "description": "Label text." }, { "name": "icon", "type": "ReactNode", "required": false, "default": null, "description": "Leading icon in the subtle foreground colour." }, { "name": "onClick", "type": "() => void", "required": false, "default": null, "description": "Turns the pill into a button and adds a chevron. Use it to open a picker." }, { "name": "onClear", "type": "() => void", "required": false, "default": null, "description": "Adds a clear button after the pill. The pill itself then has no border." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the pill body." } ], "variantsHint": {}, "tokens": [ "--border", "--surface", "--surface-hover", "--fg", "--fg-subtle", "--radius-control" ], "related": [ "suggestion-chips", "tray-row" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Picker and removable", "description": "The first tag opens a list of choices. The second is something attached that the person can remove.", "code": "
\n } onClick={() => {}}>All sources\n } onClear={() => {}}>Q3 planning.pdf\n
" }, { "title": "Static label", "description": "With neither, it is a plain label.", "code": "}>2 files attached" } ], "pageUrl": "https://lkb00.github.io/tattva/component-context-chip/", "markdownUrl": "https://lkb00.github.io/tattva/docs/context-chip.md" }, { "id": "suggestion-chips", "name": "SuggestionChips", "level": "molecule", "since": "0.5", "aka": [ "suggestions", "suggested prompts", "quick replies", "prompt starters", "chips" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "hover", "note": "A chip gets a stronger border and a soft background under the pointer.", "source": "documented" }, { "name": "focus", "note": "A visible focus ring appears on a chip when you reach it with the keyboard.", "source": "documented" }, { "name": "empty", "note": "Pass an empty suggestions array and no chips are shown.", "source": "documented" } ], "summary": "A row of ready-made questions a person can pick.", "description": "SuggestionChips shows a few ready-made questions as small buttons. When a person picks one, your app gets the exact words and decides whether to fill the message box or send it. Use it on an empty chat and after a reply to make the next step easy.", "purpose": "Gives a person a ready-made next step instead of a blank box. Each suggestion is a short button holding the exact words.", "useFor": [ "An empty chat, to show what the assistant can do.", "After a reply, to offer likely follow-up questions." ], "notFor": [ { "text": "A whole first screen with starting ideas and what the assistant can do", "use": "starter-gallery" }, { "text": "Showing what the chat is about", "use": "context-chip" }, { "text": "Picking one setting from a few options", "use": "segmented-control" } ], "whenToUse": [ "Offer three to five suggestions, worded the way the person would say them.", "Make each one a complete request that makes sense on its own.", "Change them as the conversation moves on." ], "avoid": [ "Do not show suggestions while a reply is still appearing. They compete with it.", "Do not repeat the same suggestion twice.", "Do not use long sentences. A paragraph inside a small button is hard to read." ], "accessibility": [ "The list is named \"Suggested prompts\", and screen readers hear how many suggestions there are.", "Each suggestion is a real button that reads its own words.", "The Tab key reaches each suggestion, and Enter or Space picks it." ], "accessibilityYouDo": [ "Move the keyboard to the message box, or wherever fits, after a pick.", "Give every suggestion different words. They are told apart only by their words." ], "onPhone": [ "Chips wrap onto new rows instead of scrolling sideways.", "Each chip keeps its size and has a 44px tap area on touch screens.", "A tap calls onPick, and no part of it needs hover." ], "importPath": "import { SuggestionChips } from \"./index\"", "sourcePath": "src/molecules/SuggestionChips.tsx", "props": [ { "name": "suggestions", "type": "string[]", "required": true, "default": null, "description": "Prompt texts to show. Each string is also used as its key, so keep them unique." }, { "name": "onPick", "type": "(s: string) => void", "required": true, "default": null, "description": "Called with the chosen suggestion." } ], "variantsHint": {}, "tokens": [ "--border", "--border-strong", "--surface", "--surface-sunken", "--fg-muted", "--fg", "--radius-control" ], "related": [ "context-chip" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Pick a prompt", "description": "It does not remember the choice. Here the demo keeps it.", "code": "const [picked, setPicked] = useState(null);\n\n" } ], "pageUrl": "https://lkb00.github.io/tattva/component-suggestion-chips/", "markdownUrl": "https://lkb00.github.io/tattva/docs/suggestion-chips.md" }, { "id": "message-actions", "name": "MessageActions", "level": "molecule", "since": "0.5", "aka": [ "message toolbar", "copy retry", "response actions", "actions" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "copied", "note": "After a successful copy the icon becomes a check and the label reads Copied for about 1.5 seconds.", "source": "documented" }, { "name": "hover", "note": "Each icon button gets a soft background under the pointer.", "source": "documented" }, { "name": "focus", "note": "Each icon button shows a focus ring on keyboard focus.", "source": "documented" } ], "summary": "Copy and retry buttons that sit under an assistant reply.", "description": "MessageActions is a small row of icon buttons under a reply. Copy saves the text so it can be pasted. It shows a check and \"Copied\" for a moment. The Regenerate button only appears if you turn it on. It is made for the bottom of a Message.", "purpose": "Small icon buttons under a reply for what people do after reading it: copy it, or ask for a new one. Icons keep the row quiet so it does not compete with the answer.", "useFor": [ "Under every finished assistant reply.", "Offering a fresh answer: pass onRegenerate to show the second button." ], "notFor": [ { "text": "Rating whether a reply was good", "use": "feedback-bar" }, { "text": "Copying a piece of code inside a reply", "use": "code-block" }, { "text": "Moving between versions of a reply", "use": "version-pager" } ], "whenToUse": [ "Put it at the bottom of an assistant Message once the reply is finished.", "Give it the plain text of the answer.", "Add Regenerate only when a new try is possible." ], "avoid": [ "Do not show it on a person's messages or while the reply is still appearing.", "Do not add more than a few actions. Put extras in a menu.", "Do not assume copying always works. If the browser blocks it, nothing is shown." ], "accessibility": [ "Both buttons have names that screen readers read: \"Copy response\" and \"Regenerate response\".", "After copying, a check shows and the name changes to \"Copied\" for a moment.", "Both buttons work with the keyboard, and their names also show as a tooltip on hover.", "The icons are hidden from screen readers." ], "accessibilityYouDo": [ "Add your own announcement if people must know the copy worked. Screen readers may not read the name change.", "Tell people when copying fails. The button stays silent when the clipboard is blocked." ], "onPhone": [ "The copy and regenerate buttons stay 28px square on touch screens and have a 44px tap area.", "The buttons have a title for hover, which a phone does not show, so the label is read by screen readers only.", "Copy needs clipboard access from the browser. If it is blocked, nothing happens and no error is shown." ], "importPath": "import { MessageActions } from \"./index\"", "sourcePath": "src/molecules/MessageActions.tsx", "props": [ { "name": "text", "type": "string", "required": true, "default": null, "description": "Plain text written to the clipboard when Copy is pressed." }, { "name": "onRegenerate", "type": "() => void", "required": false, "default": null, "description": "When set, adds a Regenerate response button." } ], "variantsHint": {}, "tokens": [ "--fg-subtle", "--surface-hover", "--dur-fast" ], "related": [ "feedback-bar", "message" ], "composedOf": [ "icon-button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Copy only", "description": "Without the retry option, only Copy shows.", "code": "" }, { "title": "Copy and regenerate", "description": "", "code": " {}} />" } ], "pageUrl": "https://lkb00.github.io/tattva/component-message-actions/", "markdownUrl": "https://lkb00.github.io/tattva/docs/message-actions.md" }, { "id": "code-block", "name": "CodeBlock", "level": "molecule", "since": "0.5", "aka": [ "code snippet", "syntax highlighter", "pre", "code viewer" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "copied", "note": "After a successful copy the Copy button shows a check and the word Copied for about 1.5 seconds.", "source": "documented" }, { "name": "focus", "note": "The Copy button and the scrollable code area each show a focus ring on keyboard focus.", "source": "documented" }, { "name": "scrolling", "note": "A line wider than the block scrolls sideways instead of wrapping.", "source": "documented" } ], "summary": "A dark box for code, with the language name and a Copy button.", "description": "CodeBlock shows code exactly as written. A bar on top holds the language name and a Copy button. The button briefly says Copied. Long lines scroll sideways instead of wrapping. It does not color the code.", "purpose": "Shows code exactly as written, on a dark panel so it stands apart from the words around it. Long lines scroll sideways instead of wrapping, so nothing is broken up.", "useFor": [ "Code, commands or settings inside a reply.", "Any text that people must copy exactly." ], "notFor": [ { "text": "A short name or value inside a sentence" }, { "text": "Changes between two versions of a file", "use": "diff-view" }, { "text": "Formatted text with headings and lists", "use": "markdown" } ], "whenToUse": [ "Set the language so people know what they are copying.", "Use it for multi-line code and commands in replies.", "Remove blank lines at the end of the code." ], "avoid": [ "Do not use it for a single word in a sentence. Use inline code styling.", "Do not expect long lines to wrap. They scroll sideways.", "Do not paste in secrets like passwords. Anything shown can be copied." ], "accessibility": [ "The box is a figure, and the bar with the language name is its caption.", "Copy is a real button with visible words. Screen readers politely hear \"Copied\" when it works.", "The Tab key can reach the code area, so keyboard users can scroll long lines with the arrow keys.", "The icons are hidden from screen readers." ], "accessibilityYouDo": [ "Explain what the code does in the words around it. The language name alone is not enough.", "Tell people when copying fails. The button stays silent when the clipboard is blocked." ], "onPhone": [ "Long lines scroll sideways inside the block and do not wrap, so the page itself does not scroll sideways.", "The Copy button keeps its size and has a 44px tap area on touch screens, so the header row does not get taller.", "If the browser blocks clipboard access, Copy does nothing and shows no error." ], "importPath": "import { CodeBlock } from \"./index\"", "sourcePath": "src/molecules/CodeBlock.tsx", "props": [ { "name": "code", "type": "string", "required": true, "default": null, "description": "Source text shown in the block and copied to the clipboard." }, { "name": "language", "type": "string", "required": false, "default": "\"text\"", "description": "Label shown in the caption. It does not trigger highlighting." } ], "variantsHint": {}, "tokens": [ "--code-bg", "--code-fg", "--code-muted", "--border", "--radius-card" ], "related": [ "message", "tool-call-card" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "With a language", "description": "The language is only a name shown on top.", "code": "" }, { "title": "Default label", "description": "With no language, the name reads text.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-code-block/", "markdownUrl": "https://lkb00.github.io/tattva/docs/code-block.md" }, { "id": "message", "name": "Message", "level": "molecule", "since": "0.5", "aka": [ "chat bubble", "chat message", "response", "turn" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "streaming", "note": "Set with the streaming prop.", "source": "prop" } ], "summary": "One turn in a conversation: a bubble for the person, open text across the full width for the assistant.", "description": "Message shows one turn. A person's messages sit on the right in a soft bubble. The assistant's messages are open text across the full width, with no mark beside them, so long answers are easy to read and short ones do not leave a column of marks down the thread. Screen readers hear \"Assistant\" before each reply. Set mark to top to show a small AI mark and the name above a reply. While a reply is still appearing, a blinking cursor shows and screen readers stay quiet. When it finishes, they hear one short \"Response complete\" note. The bottom area holds actions, feedback or sources.", "purpose": "One turn in a chat. The person's words sit in a bubble on the right; the assistant's reply is open text across the full width, so long answers and code have room.", "useFor": [ "Each turn of a conversation, from the person or the assistant.", "A reply that is still being written: turn on streaming.", "A finished reply with actions, feedback or sources underneath." ], "notFor": [ { "text": "A whole conversation that should be read out as it grows", "use": "message-list" }, { "text": "Notes from the app itself, such as limits or errors", "use": "callout" }, { "text": "A refusal or a safety stop", "use": "refusal-notice" } ], "whenToUse": [ "Keep the assistant's text out of a bubble so long text and code have room.", "Put actions and feedback at the bottom, and only after the reply ends.", "Wrap the messages in an area that announces new replies if your app should read them out.", "Show the AI mark once, on the first reply, or not at all. The thread already says who is speaking." ], "avoid": [ "Do not put the assistant's text in a bubble. The layout needs it open.", "Do not put a mark beside every reply. It pushes the text in and fills the thread with repeated marks.", "Do not add a bottom area to a person's message. It is ignored.", "Remember to mark the reply as finished, or the blinking cursor stays." ], "accessibility": [ "Screen readers stay quiet while words arrive, then say \"Response complete\" once.", "The blinking cursor is hidden from screen readers.", "Screen readers hear the name (\"Assistant\" by default) before every reply, whether or not the mark shows.", "The rise-in motion stops when people turn off motion in their system settings." ], "accessibilityYouDo": [ "Set streaming to false when the reply ends. Until then the cursor keeps blinking and nothing is announced.", "Put conversations in MessageList, so screen readers hear new replies as they arrive.", "Give images and charts inside a reply their own text alternatives.", "When more than one assistant or agent speaks, give each its name and set mark to top, so people can see who said what." ], "onPhone": [ "The user bubble is at most 80% of the width, and the assistant text takes the full width.", "The assistant text can shrink to the width of the screen and wraps. Wide children such as tables or code must scroll inside themselves." ], "importPath": "import { Message } from \"./index\"", "sourcePath": "src/molecules/Message.tsx", "props": [ { "name": "variant", "type": "\"bubble\" | \"plain\"", "required": false, "default": "\"bubble\"", "description": "How the person's own turn looks. bubble is a right-aligned bubble. plain is left-aligned serif text with no box, like a line in a letter. It only changes user messages." }, { "name": "mark", "type": "\"none\" | \"top\"", "required": false, "default": "\"none\"", "description": "Assistant only. none shows no mark: the reply uses the full width. top shows a small AI mark and the name above the reply. Use it once per thread, or on every reply when more than one assistant speaks." }, { "name": "name", "type": "string", "required": false, "default": "\"Assistant\"", "description": "Assistant only. Shown with the mark, and read by screen readers before every reply." }, { "name": "showAvatar", "type": "boolean", "required": false, "default": null, "description": "Deprecated: use mark. true shows the mark above the reply." }, { "name": "role", "type": "\"user\" | \"assistant\"", "required": true, "default": null, "description": "Chooses the layout. User renders a bubble, assistant renders open text across the full width." }, { "name": "streaming", "type": "boolean", "required": false, "default": null, "description": "Assistant only. Shows a blinking caret, sets aria-busy and sets aria-live=\"off\" on the text while tokens arrive." }, { "name": "completeLabel", "type": "string", "required": false, "default": "\"Response complete\"", "description": "Assistant only. Announced once through a polite status region when streaming changes from true to false." }, { "name": "children", "type": "ReactNode", "required": true, "default": null, "description": "Message content." }, { "name": "footer", "type": "ReactNode", "required": false, "default": null, "description": "Assistant only. Slot under the content for MessageActions, FeedbackBar or sources." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the outer wrapper." } ], "variantsHint": { "variant": [ "bubble", "plain" ], "mark": [ "none", "top" ], "role": [ "user", "assistant" ] }, "tokens": [ "--surface-sunken", "--fg", "--fg-muted", "--lime", "--on-lime", "--radius-card" ], "related": [ "message-actions", "feedback-bar", "thinking-block" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "User and assistant", "description": "The person's bubble never fills the whole width. The assistant has no bubble.", "code": "
\n Can you summarize the meeting?\n \n

The team agreed to ship on Friday and review the open risks on Wednesday.

\n \n
" }, { "title": "Streaming", "description": "While words are still appearing, a blinking cursor shows and screen readers do not read each new word.", "code": "\n

Looking at the notes now, the main decision was

\n" }, { "title": "With a footer", "description": "Add actions and feedback at the bottom once the reply is finished.", "code": "\n {}} />\n \n
\n }\n>\n

The team agreed to ship on Friday.

\n" }, { "title": "Plain turns, with the mark once", "description": "The person's turns are serif text with no bubble. The first reply shows the AI mark and name above it; the rest need no mark, because the thread already says who is speaking.", "code": "
\n My refund from Flipkart is stuck.\n I read your message and found the order.\n Yes, that one.\n Is the amount ₹3,499?\n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-message/", "markdownUrl": "https://lkb00.github.io/tattva/docs/message.md" }, { "id": "thinking-block", "name": "ThinkingBlock", "level": "molecule", "since": "0.5", "aka": [ "reasoning", "chain of thought", "thoughts", "thinking", "reasoning trace" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "selected", "note": "Set with the active prop.", "source": "prop" } ], "summary": "A closed note of the assistant's thinking. It shimmers while it works and shows how long it took when done.", "description": "ThinkingBlock starts closed. While the assistant is working, it says Thinking with a shimmer. After that it says how many seconds it thought. Opening it shows the thinking in light text with a line on the left.", "purpose": "Keeps the assistant's reasoning out of the way but within reach. It starts closed, shimmers while the assistant works, then says how long it took.", "useFor": [ "Reasoning the assistant shows before its answer.", "Letting people check how an answer was reached, if they want to." ], "notFor": [ { "text": "One step the assistant took, such as a search", "use": "tool-call-card" }, { "text": "The answer itself", "use": "message" }, { "text": "A simple waiting signal with nothing to open", "use": "typing-indicator" } ], "whenToUse": [ "Show it above the answer, so the answer stays the main thing.", "Switch to the finished look with the real time taken.", "Keep it closed so people choose to see the detail.", "Pass seconds once thinking ends. Without it, the heading says 0s." ], "avoid": [ "Do not open it by default. It has no setting for that.", "Do not present the thinking as a checked source.", "Do not show a made-up time. Leave the block out instead." ], "accessibility": [ "The heading is a real button. Screen readers say whether it is open or closed.", "\"Thinking…\" and the time it took are real text that screen readers read. The shimmer is only a visual effect.", "The shimmer stops when people turn off motion in their system settings.", "When closed, the reasoning is skipped by screen readers." ], "accessibilityYouDo": [ "Announce when thinking ends if screen reader users need to know. The part does not." ], "onPhone": [ "The header is a full-width button with a tap area at least 44px tall on touch screens.", "The opened text sits behind a left rule and wraps to the screen width.", "It is closed by default, so it takes one line on a phone until someone taps it." ], "importPath": "import { ThinkingBlock } from \"./index\"", "sourcePath": "src/molecules/ThinkingBlock.tsx", "props": [ { "name": "active", "type": "boolean", "required": false, "default": null, "description": "When true the header shimmers and reads Thinking." }, { "name": "seconds", "type": "number", "required": false, "default": null, "description": "Elapsed seconds shown when not active. Falls back to 0." }, { "name": "children", "type": "ReactNode", "required": true, "default": null, "description": "Reasoning text shown when expanded." } ], "variantsHint": {}, "tokens": [ "--fg-subtle", "--fg-muted", "--border" ], "related": [ "tool-call-card", "collapsible", "message" ], "composedOf": [ "collapsible", "shimmer-text" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Active", "description": "Use while the assistant is still thinking.", "code": "Comparing the two schedules against the team calendar." }, { "title": "Finished", "description": "When done, give the time taken. It shows 0 seconds if you leave it out.", "code": "Comparing the two schedules against the team calendar." } ], "pageUrl": "https://lkb00.github.io/tattva/component-thinking-block/", "markdownUrl": "https://lkb00.github.io/tattva/docs/thinking-block.md" }, { "id": "tool-call-card", "name": "ToolCallCard", "level": "molecule", "since": "0.5", "aka": [ "tool call", "tool use", "function call", "tool" ], "category": "agents", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "status", "note": "Set with the status prop.", "source": "prop" } ], "summary": "A card that shows one step the assistant took, with its status, how long it took, and what went in and out.", "description": "ToolCallCard shows one step the assistant took. The top line gives the step name, a short summary, how long it took and a status tag. Opening it shows what was sent and what came back. The icon is a tool while waiting, a spinner while running, a check when done and an alert if it failed. A failure also tints the border.", "purpose": "Makes one step the assistant took visible and easy to check. The top line says what it is and how it went; what went in and came out stays folded until someone wants it.", "useFor": [ "A search, file read or other action the assistant ran.", "A step that failed, with what was sent and what came back.", "A step that is still running." ], "notFor": [ { "text": "The assistant's reasoning", "use": "thinking-block" }, { "text": "A list of many steps in a task", "use": "step-timeline" }, { "text": "An action that needs the person's approval first", "use": "approval-prompt" } ], "whenToUse": [ "Write a summary anyone would understand.", "Update the same card as the step moves from waiting to running to done.", "Show the time taken once the step finishes.", "When a step fails, show what went wrong." ], "avoid": [ "Do not put secrets or personal data in what was sent. It shows as plain text.", "Do not use it to ask for approval. It reports. It does not ask.", "Do not leave a failed step without a note on what to do next." ], "accessibility": [ "The top line is a real button. Screen readers say whether it is open or closed.", "Status is written as a word (Queued, Running, Done or Failed), not shown by icon and color alone.", "While running, the spinner is read as \"Loading\". The other icons are hidden from screen readers.", "The Tab key can reach the input box, so long lines can be scrolled with the keyboard." ], "accessibilityYouDo": [ "Announce status changes yourself if they matter, for example from an area that screen readers watch for updates.", "Write the summary in plain words, such as Searching \"q3 revenue\", so the step makes sense without opening it." ], "onPhone": [ "The name and the summary are each cut to one line with an ellipsis, and the full text is not shown anywhere else on the card.", "The input and output blocks both scroll sideways, and long unbroken strings in the output wrap.", "The whole header is one tap target that opens the details, with a tap area at least 44px tall on touch screens." ], "importPath": "import { ToolCallCard } from \"./index\"", "sourcePath": "src/molecules/ToolCallCard.tsx", "props": [ { "name": "name", "type": "string", "required": true, "default": null, "description": "Tool identifier, shown in a monospace face." }, { "name": "status", "type": "\"pending\" | \"running\" | \"success\" | \"error\"", "required": true, "default": null, "description": "Drives the icon, the badge label (Queued, Running, Done, Failed) and the badge tone." }, { "name": "summary", "type": "string", "required": false, "default": null, "description": "One-line human description of what the tool is doing." }, { "name": "input", "type": "unknown", "required": false, "default": null, "description": "Any value. Shown as indented JSON in the expanded panel when it is not undefined." }, { "name": "output", "type": "ReactNode", "required": false, "default": null, "description": "Result shown in the expanded panel when it is not null or undefined." }, { "name": "durationMs", "type": "number", "required": false, "default": null, "description": "Elapsed time in milliseconds, shown in seconds with one decimal. Hidden while running." } ], "variantsHint": { "status": [ "pending", "running", "success", "error" ] }, "tokens": [ "--surface", "--border", "--danger", "--success", "--surface-sunken", "--fg-muted", "--fg-subtle", "--radius-card" ], "related": [ "thinking-block", "collapsible", "code-block" ], "composedOf": [ "collapsible", "badge", "spinner" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Pending and running", "description": "A waiting step says Queued. A running step shows a spinner and no time yet.", "code": "
\n \n \n
" }, { "title": "Success with details", "description": "Open the card to see what was sent and what came back.", "code": "" }, { "title": "Error", "description": "The red tag, alert icon and tinted border make a failed step easy to spot.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-tool-call-card/", "markdownUrl": "https://lkb00.github.io/tattva/docs/tool-call-card.md" }, { "id": "checklist-row", "name": "ChecklistRow", "level": "molecule", "since": "0.5", "aka": [ "task row", "todo item" ], "category": "agents", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "attention", "note": "Set attention on the item to show a dot beside the status and use the stronger text colour.", "source": "documented" } ], "summary": "A list row with a title, an optional tag and a status on the right. An amber dot marks items that need a person.", "description": "ChecklistRow shows one item from a to-do list. The title and an optional tag sit on the left. The status sits on the right in light text. If the item needs a person, the status is darker and has an amber dot. A thin line separates rows.", "purpose": "One item in a to-do list, with its status at the end of the row. Only items that need a person get the amber dot and darker status, so they stand out.", "useFor": [ "Steps in a task that the assistant or a team is working through.", "A list where a few items wait on the person and most do not." ], "notFor": [ { "text": "A row that opens something when pressed", "use": "tray-row" }, { "text": "A whole list with finished work folded away", "use": "checklist" }, { "text": "A step the assistant is running right now", "use": "tool-call-card" } ], "whenToUse": [ "Put rows inside a list.", "Use the amber dot only when a person has to act, and say what in the status.", "Use the tag for a small label, like a type or priority." ], "avoid": [ "Do not use the amber dot for progress or priority. It means a person must act.", "Do not combine a long title with a tag. The title gets cut short.", "Do not expect it to be pressable. It has no checkbox." ], "accessibility": [ "Each row is a list item, so inside a list screen readers hear how many items there are.", "The amber dot is read as \"Needs attention\".", "Status is written in words, not shown by color alone." ], "accessibilityYouDo": [ "Put rows in a list (ul or ol) and give the list a name for screen readers.", "Give every item its own id.", "When attention is on, say why in the status.", "Give anything pressable that you put in the title or tag its own name." ], "onPhone": [ "The row fills the width. The title takes the space left by the status on the right.", "It is not tappable. If a row should open something, wrap it in a button of your own, which gets a 44px tap area, or a link with the tap class.", "Rows have 12px of padding above and below, and no minimum height." ], "importPath": "import { ChecklistRow } from \"./index\"", "sourcePath": "src/molecules/ChecklistRow.tsx", "props": [ { "name": "item", "type": "ChecklistItem", "required": true, "default": null, "description": "Object with id (string, required), title (ReactNode, required), badge (ReactNode), status (string) and attention (boolean)." } ], "variantsHint": {}, "tokens": [ "--border", "--fg", "--fg-subtle", "--attention" ], "related": [ "tray-row" ], "composedOf": [ "attention-dot" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Mixed statuses", "description": "Only the row that needs a person gets the dot. The others stay quiet.", "code": "
    \n \n \n Draft, status: \"In progress\" }} />\n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-checklist-row/", "markdownUrl": "https://lkb00.github.io/tattva/docs/checklist-row.md" }, { "id": "confidence-indicator", "name": "ConfidenceIndicator", "level": "molecule", "since": "0.5", "aka": [ "confidence score", "certainty", "uncertainty indicator" ], "category": "trust", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "low", "note": "Set level to low for one bar, a warning badge and a verify-before-relying note.", "source": "documented" }, { "name": "medium", "note": "Set level to medium for two bars and a neutral badge.", "source": "documented" }, { "name": "high", "note": "Set level to high for three bars and a success badge.", "source": "documented" } ], "summary": "Three bars and a label that show how sure the assistant is about an answer.", "description": "ConfidenceIndicator pairs three small bars with a label: Low, Medium or High confidence. It never relies on color alone. More bars fill as confidence rises, and screen readers get a sentence that explains the level. High is green and medium is gray. Low is amber, because a person should double-check the answer. Use it beside replies that are not always reliable.", "purpose": "Tells people how far to trust an answer. Bars, a word and a sentence all say the same thing, so nobody needs to see color to read it.", "useFor": [ "Beside a reply or fact that is not always reliable.", "Next to an extracted value that a person may need to check." ], "notFor": [ { "text": "The model's own rating of itself, or any number you have not measured (see the Trust and safety guide)" }, { "text": "How much of something is used", "use": "meter" }, { "text": "Saying that content was made by AI", "use": "ai-label" } ], "whenToUse": [ "Show it near the answer it describes, like at the bottom of a message.", "Base the level on something real: how well the sources support the answer, how much of the question was covered, or a success rate you measured on real cases. Write down what each level means for your product.", "When confidence is low, suggest a next step, like checking sources.", "Leave it out when you have no real signal. No label is better than one that guesses." ], "avoid": [ "Do not drive it from the model's own rating of itself (\"I am 90% sure\"). Models are often sure and wrong.", "Do not show a percentage you have not measured; a number looks more exact than it is.", "Do not put it on every answer as decoration.", "Do not drop the words to save space. They are the main clue.", "Do not add levels beyond low, medium and high." ], "accessibility": [ "The bars are hidden from screen readers. They read the label, such as \"High confidence\".", "A hidden sentence explains the level, such as \"Low confidence. Verify before relying on this.\" Setting showText to false removes it.", "The same sentence shows as a tooltip on hover.", "The bars' grow-in motion stops when people turn off motion in their system settings." ], "accessibilityYouDo": [ "Keep showText on unless the same explanation is already written nearby.", "Place it right next to the answer it rates, so it is clear what it refers to." ], "onPhone": [ "It stays on one line: bars, then the badge.", "The longer sentence, such as \"Verify before relying on this\", is only a hover tooltip and a screen reader line, so on a phone the bars and the badge word carry the meaning.", "The badge text is at least 12px on touch screens." ], "importPath": "import { ConfidenceIndicator } from \"./index\"", "sourcePath": "src/molecules/ConfidenceIndicator.tsx", "props": [ { "name": "level", "type": "\"low\" | \"medium\" | \"high\"", "required": true, "default": null, "description": "Confidence level. Controls the bars, the badge tone and the label." }, { "name": "showText", "type": "boolean", "required": false, "default": "true", "description": "Includes a visually hidden sentence that explains the level, for example Low confidence. Verify before relying on this." } ], "variantsHint": { "level": [ "low", "medium", "high" ] }, "tokens": [ "--attention", "--attention-soft", "--attention-fg", "--success", "--success-soft", "--fg-subtle", "--border-strong" ], "related": [ "callout" ], "composedOf": [ "badge" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "All levels", "description": "Low fills one bar, medium two and high three.", "code": "
\n \n \n \n
" }, { "title": "Without the hidden explanation", "description": "Turn off the hidden explanation for screen readers. The tooltip still shows on hover.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-confidence-indicator/", "markdownUrl": "https://lkb00.github.io/tattva/docs/confidence-indicator.md" }, { "id": "feedback-bar", "name": "FeedbackBar", "level": "molecule", "since": "0.5", "aka": [ "thumbs up down", "rating", "feedback", "like dislike" ], "category": "trust", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "reason picker", "note": "After a thumbs down, a row of reasons and a Skip button appears below the icons.", "source": "documented" }, { "name": "submitted", "note": "After a rating is sent a thank-you message appears and further clicks are ignored until resetKey changes.", "source": "documented" }, { "name": "focus", "note": "The thumb buttons and reason buttons show a focus ring on keyboard focus.", "source": "documented" } ], "summary": "Thumbs up and down buttons, with a short list of reasons after a thumbs down.", "description": "FeedbackBar asks how a reply was. A thumbs up is sent right away. A thumbs down shows a row of reasons and a Skip button. Picking a reason sends it with the rating. Skip sends just the rating. After that, the chosen thumb stays pressed and a thank-you appears beside it. Change resetKey when a new message arrives to start over.", "purpose": "A quick way to say whether a reply helped. A thumbs down asks why with one tap, and Skip keeps the reason optional.", "useFor": [ "Under a finished assistant reply.", "Collecting a reason when a reply was wrong, unhelpful or unsafe." ], "notFor": [ { "text": "Copying or retrying a reply", "use": "message-actions" }, { "text": "A detailed written report or survey" } ], "whenToUse": [ "Show it after a reply is finished, next to the message actions.", "Keep the thank-you short and plain.", "Save the answer in onSubmit. The part only hands it to you.", "Change resetKey when a new message arrives, so the bar starts fresh." ], "avoid": [ "Do not force a reason. Keep Skip so people can send just the rating.", "Do not reuse one bar for several messages without a resetKey. It will not clear itself.", "Do not use it for general surveys. It rates one reply." ], "accessibility": [ "The thumbs are named \"Good response\" and \"Bad response\", and screen readers say which one is pressed.", "After a rating is sent, the chosen thumb stays pressed and pressing either does nothing.", "The reasons form a group named \"What went wrong?\". Each reason and Skip is a real button the keyboard can reach.", "The thank-you line is announced politely when it appears." ], "accessibilityYouDo": [ "Keep it directly under the reply it rates. Every bar uses the same button names, so position tells screen reader users which reply they are rating." ], "onPhone": [ "The thumb buttons stay 28px square on touch screens and have a 44px tap area.", "After a thumbs down the reasons wrap onto new rows. Each keeps its size and has a 44px tap area on touch screens.", "Nothing needs hover, and the thank-you line is shown beside the thumbs." ], "importPath": "import { FeedbackBar } from \"./index\"", "sourcePath": "src/molecules/FeedbackBar.tsx", "props": [ { "name": "onSubmit", "type": "(rating: \"up\" | \"down\", reason?: string) => void", "required": true, "default": null, "description": "Called once per message. Thumbs up sends only the rating. A reason button sends rating down and the reason text. Skip sends rating down with no reason." }, { "name": "resetKey", "type": "unknown", "required": false, "default": null, "description": "Any value, such as the message id. When it changes, the bar clears its rating and returns to the thumbs. It does not reset on first render." } ], "variantsHint": {}, "tokens": [ "--fg-muted", "--accent-soft", "--accent-fg", "--border" ], "related": [ "message-actions", "message" ], "composedOf": [ "button", "icon-button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Interactive", "description": "Try thumbs down to see the reasons. The line below shows what was sent.", "code": " console.log(rating, reason)} />" }, { "title": "Reset for a new message", "description": "Send feedback, then choose Next message. The bar starts fresh for each new message.", "code": " send(message.id, rating, reason)} />" } ], "pageUrl": "https://lkb00.github.io/tattva/component-feedback-bar/", "markdownUrl": "https://lkb00.github.io/tattva/docs/feedback-bar.md" }, { "id": "source-card", "name": "SourceCard", "level": "molecule", "since": "0.5", "aka": [ "source", "reference card", "link card", "citation card" ], "category": "trust", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "hover", "note": "The card gets a stronger border and a soft background under the pointer.", "source": "documented" }, { "name": "focus", "note": "A visible focus ring appears when you reach the card link with the keyboard.", "source": "documented" }, { "name": "truncated", "note": "A long title is cut to one line and a long snippet to two lines.", "source": "documented" } ], "summary": "A numbered link card for one source.", "description": "SourceCard is a link in a box. It has a numbered lime-tinted marker, a title, the website name and an optional short excerpt. The matching CitationMarker jumps to it. It opens in a new tab. Put several in a numbered list.", "purpose": "One numbered source that an answer drew on. The number matches the citation in the text, so people can check where a claim came from.", "useFor": [ "The list of sources under a reply.", "A place for citation markers in the text to jump to." ], "notFor": [ { "text": "The marker inside the sentence itself", "use": "citation-marker" }, { "text": "A whole set of sources laid out in columns", "use": "source-list" } ], "whenToUse": [ "Put cards in a numbered list so they match the small numbers in the text.", "Keep numbers steady and matching the CitationMarkers.", "Add an excerpt when the title alone is unclear." ], "avoid": [ "Do not use lime for text. Here it only fills the small number circle.", "Do not leave the website blank. It tells people where the link goes.", "Do not use it outside a list." ], "accessibility": [ "The whole card is one link. Screen readers read the number, title, website and excerpt in order.", "Long titles and excerpts are cut short on screen, but screen readers still read all of it.", "Each card carries an anchor for its number, so citation markers can jump to it.", "The rise-in motion stops when people turn off motion in their system settings." ], "accessibilityYouDo": [ "Put cards in a numbered list (ol), so screen readers hear the count.", "Say in the nearby text that sources open in a new tab.", "Give every source its own number, matching its citation marker." ], "onPhone": [ "The whole card is one link that opens in a new tab, so the tap target is the full card.", "The title is cut to one line and the snippet to two lines, so every card stays short.", "Render it inside a list that sets the columns. The card itself fills the width it is given." ], "importPath": "import { SourceCard } from \"./index\"", "sourcePath": "src/molecules/SourceCard.tsx", "props": [ { "name": "source", "type": "Source", "required": true, "default": null, "description": "Object with id (number), title (string), url (string), domain (string) and snippet (string, optional). The id forms the li anchor source-{id}." } ], "variantsHint": {}, "tokens": [ "--lime", "--border", "--border-strong", "--surface", "--surface-sunken", "--fg-subtle", "--radius-card" ], "related": [ "message", "confidence-indicator" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Source list", "description": "The numbers match the small numbers in the text.", "code": "
    \n \n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-source-card/", "markdownUrl": "https://lkb00.github.io/tattva/docs/source-card.md" }, { "id": "error-state", "name": "ErrorState", "level": "molecule", "since": "0.5", "aka": [ "error page", "error message", "failure state", "retry" ], "category": "states", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "retry", "note": "Pass onRetry to show a Try again button next to the message.", "source": "documented" } ], "summary": "A red message for a problem that can be fixed, with an optional Try again button.", "description": "ErrorState is a red Callout titled \"Something went wrong\". You give it a message. You can also add a Try again button. Use it when something failed and trying again is safe.", "purpose": "Says that something failed, that it can be fixed, and offers to try again. It is a red Callout with that wording ready to use.", "useFor": [ "A request that failed and is safe to try again.", "A part of the page that could not load." ], "notFor": [ { "text": "A request the assistant will not do", "use": "refusal-notice" }, { "text": "A usage limit", "use": "rate-limit-notice" }, { "text": "A whole empty area with a drawing", "use": "empty-state" } ], "whenToUse": [ "Say what happened in plain words, and whether the person's work was kept.", "Add Try again only when it can work.", "Use a specific title when you know the cause." ], "avoid": [ "Do not use it for refusals or usage limits. Use RefusalNotice or RateLimitNotice.", "Do not show error codes or technical details as the message.", "Do not blame the person. Describe what went wrong on our side." ], "accessibility": [ "Screen readers announce it right away when it appears.", "Try again is a real button with visible words.", "An alert icon and the words come with the red, so color is not the only clue." ], "accessibilityYouDo": [ "Write a message that says what failed and whether the person's work is safe.", "Move the keyboard to a sensible spot after a retry works or fails again." ], "onPhone": [ "The message wraps, and on a phone the Try again button drops under it so the text keeps its full width.", "Try again keeps its size and has a 44px tap area on touch screens.", "It fills the width of its container." ], "importPath": "import { ErrorState } from \"./index\"", "sourcePath": "src/molecules/ErrorState.tsx", "props": [ { "name": "title", "type": "string", "required": false, "default": "\"Something went wrong\"", "description": "Heading of the callout." }, { "name": "message", "type": "ReactNode", "required": true, "default": null, "description": "What happened, and whether the person's work is safe." }, { "name": "onRetry", "type": "() => void", "required": false, "default": null, "description": "Adds a Try again button when provided." } ], "variantsHint": {}, "tokens": [ "--danger-soft", "--danger-fg" ], "related": [ "callout", "refusal-notice", "rate-limit-notice" ], "composedOf": [ "callout", "button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "With retry", "description": "Say whether the person's work is safe and offer a next step.", "code": " {}} />" }, { "title": "Custom title, no retry", "description": "Leave out Try again when trying again will not help.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-error-state/", "markdownUrl": "https://lkb00.github.io/tattva/docs/error-state.md" }, { "id": "refusal-notice", "name": "RefusalNotice", "level": "molecule", "since": "0.5", "aka": [ "refusal", "declined request", "content policy message" ], "category": "trust", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "alternative", "note": "Pass alternative to add a second line suggesting what to do instead.", "source": "documented" } ], "summary": "A calm notice for a request the assistant will not do, with an optional alternative.", "description": "RefusalNotice is a Callout titled \"I can't help with that.\" It explains why and can offer something else instead. A refusal is not an error, so it is not red or amber.", "purpose": "Explains calmly that the assistant will not do something. It uses the info color, not red or amber, because a refusal is not an error.", "useFor": [ "A request the assistant declines, with the reason.", "Offering an allowed alternative next to the refusal." ], "notFor": [ { "text": "Something that broke and can be tried again", "use": "error-state" }, { "text": "A usage limit", "use": "rate-limit-notice" } ], "whenToUse": [ "Say calmly, in one sentence, what you can't do.", "Offer something else whenever you can.", "Keep the calm tone. The colors are chosen on purpose." ], "avoid": [ "Do not use red or amber. A refusal is not a failure.", "Do not lecture or repeat the request back at length.", "Do not use it when something broke. Use ErrorState." ], "accessibility": [ "Screen readers announce it politely when it appears.", "The title \"I can't help with that\" is written in words. The icon is hidden from screen readers." ], "accessibilityYouDo": [ "Write a reason that names the boundary, because the title is always the same.", "Give any link or button in the alternative a clear name." ], "onPhone": [ "The reason and the alternative wrap to the screen width.", "It fills the width of its container.", "It has no buttons of its own. If you pass an alternative with a link, give the link the tap class so it has a 44px tap area." ], "importPath": "import { RefusalNotice } from \"./index\"", "sourcePath": "src/molecules/RefusalNotice.tsx", "props": [ { "name": "reason", "type": "string", "required": true, "default": null, "description": "Short explanation of the boundary." }, { "name": "alternative", "type": "ReactNode", "required": false, "default": null, "description": "Optional paragraph offering what can be done instead." } ], "variantsHint": {}, "tokens": [ "--info-soft", "--info-fg" ], "related": [ "error-state", "rate-limit-notice", "callout" ], "composedOf": [ "callout" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Reason and alternative", "description": "Offer something useful the assistant can do instead.", "code": "" }, { "title": "Reason only", "description": "", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-refusal-notice/", "markdownUrl": "https://lkb00.github.io/tattva/docs/refusal-notice.md" }, { "id": "rate-limit-notice", "name": "RateLimitNotice", "level": "molecule", "since": "0.5", "aka": [ "quota exceeded", "usage limit", "too many requests", "throttling message" ], "category": "states", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "upgrade", "note": "Pass onUpgrade to show an Upgrade button next to the message.", "source": "documented" } ], "summary": "An amber message that says when a usage limit resets, with an optional Upgrade button.", "description": "RateLimitNotice is a warning Callout titled \"You've reached the usage limit.\" The text says when the limit resets, like \"Limits reset in 2 hours.\" You can add an Upgrade button. The wording is fixed, so give it a short time like 2 hours.", "purpose": "Tells people they reached a usage limit and when it resets. Amber marks that they must wait or act before going on.", "useFor": [ "A person has used up their messages or credits for now.", "Offering a way to upgrade: pass onUpgrade." ], "notFor": [ { "text": "How much has been used before the limit is reached", "use": "usage-meter" }, { "text": "A failure that can be tried again right away", "use": "error-state" } ], "whenToUse": [ "Give the real time until the limit resets.", "Offer Upgrade only if it applies to the person's plan.", "Place it where the blocked action would have been.", "Disable the blocked action, or explain it next to the action, so people do not run into the limit again." ], "avoid": [ "Do not show it before the limit is reached. Use a quieter hint.", "Do not use a full date. Give a short time.", "Do not use it when the service is down. Use ErrorState." ], "accessibility": [ "Screen readers announce it politely when it appears.", "Upgrade is a real button with visible words.", "The icon is hidden from screen readers. The title and the reset time carry the meaning." ], "accessibilityYouDo": [ "Pass a short time, such as \"2 hours\", because it is read inside \"Limits reset in …\"." ], "onPhone": [ "The message wraps, and on a phone the Upgrade button drops under it so the text keeps its full width.", "Upgrade keeps its size and has a 44px tap area on touch screens.", "It fills the width of its container." ], "importPath": "import { RateLimitNotice } from \"./index\"", "sourcePath": "src/molecules/RateLimitNotice.tsx", "props": [ { "name": "resetsIn", "type": "string", "required": true, "default": null, "description": "Human duration inserted into the sentence Limits reset in {resetsIn}." }, { "name": "onUpgrade", "type": "() => void", "required": false, "default": null, "description": "Adds an Upgrade button when provided." } ], "variantsHint": {}, "tokens": [ "--warning-soft", "--warning-fg" ], "related": [ "error-state", "refusal-notice", "callout" ], "composedOf": [ "callout", "button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "With upgrade", "description": "The Upgrade button is a small primary button.", "code": " {}} />" }, { "title": "Wait only", "description": "", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-rate-limit-notice/", "markdownUrl": "https://lkb00.github.io/tattva/docs/rate-limit-notice.md" }, { "id": "variant-tile", "name": "VariantTile", "level": "molecule", "since": "0.5", "aka": [ "variation", "option tile", "image tile" ], "category": "creating", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "selected", "note": "Set with the selected prop.", "source": "prop" } ], "summary": "A square tile for one AI-made option that a person can pick.", "description": "VariantTile shows one of several AI-made options as a square you can pick. Put tiles in a VariantGrid so the arrow keys move between them. An AI badge always sits at the top left. The chosen tile gets a thick dark border and a check mark at the bottom right, so color is not the only clue.", "purpose": "One AI-made option shown as a square, so options can be compared side by side. The chosen one gets a check mark and a dark border, not only a color change.", "useFor": [ "Picking one of several generated images, layouts or drafts.", "Inside VariantGrid, which adds arrow key movement between tiles." ], "notFor": [ { "text": "A whole set of options to choose from", "use": "variant-grid" }, { "text": "Picking several images at once", "use": "media-grid" }, { "text": "A few text options with no picture", "use": "segmented-control" } ], "whenToUse": [ "Use VariantGrid, or wrap tiles in a group that screen readers know is a set of choices, with a name.", "Give each option a clear name, like Option B, sand block.", "Let the content fill the whole square, like a cropped image." ], "avoid": [ "Do not allow picking more than one. Only one tile can be chosen.", "Do not remove the AI badge from AI-made content.", "Do not use it for navigation. It is for choosing between AI-made options." ], "accessibility": [ "Each tile is a button that screen readers treat as a choice. They read its label and whether it is selected.", "A chosen tile shows a check mark and a thicker border, not just color.", "The rise-in motion stops when people turn off motion in their system settings." ], "accessibilityYouDo": [ "Use VariantGrid, or build the group yourself: set tabIndex to -1 on tiles that are not chosen and move between tiles with the arrow keys.", "Give each tile a label that says how it differs, such as \"Option A, warm gradient\".", "Say that the option is AI-made in the label or the nearby text if that matters. The label replaces the tile's content, so the badge is not read out." ], "onPhone": [ "Each tile is a square that fills the width its grid gives it, and has a tap area of at least 44px on touch screens.", "Selection is a tap, and the check mark shows without hover.", "Choose the number of columns in the grid, since the tile size comes from it." ], "importPath": "import { VariantTile } from \"./index\"", "sourcePath": "src/molecules/VariantTile.tsx", "props": [ { "name": "variant", "type": "Variant", "required": true, "default": null, "description": "Object with id (string), node (ReactNode shown inside the tile) and label (string used as the accessible name)." }, { "name": "selected", "type": "boolean", "required": true, "default": null, "description": "Whether this tile is the chosen option." }, { "name": "onSelect", "type": "(id: string) => void", "required": true, "default": null, "description": "Called with variant.id when the tile is pressed." }, { "name": "tabIndex", "type": "number", "required": false, "default": null, "description": "Set to -1 on tiles that are not the tab stop of a roving group. VariantGrid does this for you. Leave it unset for a standalone tile, which then stays a tab stop." } ], "variantsHint": {}, "tokens": [ "--fg", "--bg", "--border", "--border-strong", "--shadow-md", "--radius-card" ], "related": [ "variant-grid", "source-card" ], "composedOf": [ "ai-badge" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Choose one", "description": "Here the demo keeps track of the choice. Without VariantGrid, arrow keys do not move between tiles, so the Tab key stops on each one.", "code": "const [selected, setSelected] = useState(\"a\");\n\n
\n {variants.map((v) => (\n \n ))}\n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-variant-tile/", "markdownUrl": "https://lkb00.github.io/tattva/docs/variant-tile.md" }, { "id": "tray", "name": "Tray", "level": "organism", "since": "0.5", "aka": [ "sidebar list", "navigation list", "panel list" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [], "summary": "A soft panel with a short list of things to look at, and an optional message box under it.", "description": "Tray shows a few rows under a small heading. Use it on a landing view to show what needs a person. A message box can sit at the bottom, lined up with the list. Keep the list short. It does not scroll.", "purpose": "A soft panel that gathers the few things a person should look at now. The message box can sit underneath, so the list and the input share one edge.", "useFor": [ "A short list of tasks that need a person, on a landing screen.", "A few suggested starting points with a message box under them.", "A small group of open items that all fit without scrolling." ], "notFor": [ { "text": "A long list that has to scroll" }, { "text": "Past chats in the side panel", "use": "conversation-list" }, { "text": "Progress of a running task, with finished work folded away", "use": "checklist" } ], "whenToUse": [ "Keep the list to a few rows so it can be read at a glance.", "Put the message box in the footer so it lines up with the list.", "Mark a row as needing attention only when a person has to act.", "Give the panel a heading so screen readers can name it." ], "avoid": [ "Do not use it for long lists. Use a full list page instead.", "Do not add a border or a second panel inside it.", "Only put list rows inside it. Other content will not display correctly.", "Do not mark every row. When everything is amber, nothing stands out." ], "accessibility": [ "With a label, screen readers can find the panel by that name.", "Rows sit in a real list, so screen readers say how many items there are.", "The label is plain text, so it does not add a level to the page outline." ], "accessibilityYouDo": [ "Give it a label unless a nearby heading already names the list.", "Put only list rows, such as TrayRow, inside it.", "Give each row that needs a person a detail that says what is needed, not just the amber dot." ], "onPhone": [ "Fills the width of its container, and the rows inside it keep their size and have a tap area at least 44px tall on a touch screen.", "Each row stacks its title above its detail on a phone, and the detail wraps instead of being cut off.", "A row's trailing text, which shows only on hover on a desktop, is always visible on a touch screen." ], "importPath": "import { Tray } from \"./index\"", "sourcePath": "src/organisms/Tray.tsx", "props": [ { "name": "label", "type": "string", "required": false, "default": null, "description": "Small uppercase heading rendered with SectionLabel. Also becomes the aria-label of the section." }, { "name": "action", "type": "ReactNode", "required": false, "default": null, "description": "Right-aligned text beside the label, such as a count or a link. Only rendered when label is set." }, { "name": "children", "type": "ReactNode", "required": true, "default": null, "description": "The rows. Rendered inside a ul, so pass li elements such as TrayRow." }, { "name": "footer", "type": "ReactNode", "required": false, "default": null, "description": "Rendered below the list, inside the sand surface. Intended for a Composer." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes merged onto the section, for width or spacing." } ], "variantsHint": {}, "tokens": [ "--surface-sunken (bg-sunken)", "--shadow-sm", "--fg-muted", "--attention (via TrayRow)", "--radius-card" ], "related": [ "composer", "checklist", "conversation-list" ], "composedOf": [ "section-label" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Rows that need attention", "description": "A row marked as needing attention gets an amber dot. Use it only when a person has to act.", "code": "
\n \n \n \n } title=\"Launch plan\" detail=\"On track\" trailing=\"Open →\" />\n \n
" }, { "title": "With a message box underneath", "description": "The message box sits inside the panel, lined up with the list.", "code": "
\n {}}\n tools={} onClick={() => {}}>All projects}\n />\n }\n >\n \n \n
" }, { "title": "Without a heading", "description": "Leave the heading out for a plain list. Screen readers then get no name for it, so only do this when a nearby heading explains the list.", "code": "
\n \n } title=\"Find missing documents\" />\n } title=\"Reconcile invoices\" />\n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-tray/", "markdownUrl": "https://lkb00.github.io/tattva/docs/tray.md" }, { "id": "message-list", "name": "MessageList", "level": "organism", "since": "0.5", "aka": [ "thread", "chat thread", "conversation", "message thread" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [], "summary": "A column that holds a conversation and reads out new messages.", "description": "MessageList holds the messages of one conversation in a centered column with even spacing. Screen readers read out each new message as it arrives. A reply that is still being written stays quiet until it is done, then says so once.", "purpose": "The column that holds one conversation. It reads new turns out to screen readers as they are added, so people who cannot see the screen can follow along.", "useFor": [ "The messages of one conversation, in order.", "A thread where replies arrive while the person waits.", "A page with more than one conversation, each with its own name." ], "notFor": [ { "text": "A single turn on its own", "use": "message" }, { "text": "The box where people type", "use": "composer" }, { "text": "A list of past chats", "use": "conversation-list" } ], "whenToUse": [ "Put each message directly inside it so each new one is read out.", "Mark the reply as still being written while its words arrive.", "Give each conversation its own name when a page shows more than one.", "Place it inside ThreadTemplate, which already sets a good reading width." ], "avoid": [ "Do not put the message box inside it. Everything added there is read out.", "Do not rebuild the list for every new word. Update the last message instead.", "Do not add other read-out areas inside it." ], "accessibility": [ "Screen readers hear each new message as it is added, without being cut off.", "Changes to messages already on screen are not read out again.", "It is named \"Conversation\" for screen readers unless you give it another name.", "It has no keyboard controls of its own." ], "accessibilityYouDo": [ "Put each Message directly inside it, so each new one is read out.", "Set streaming on the reply that is still being written, and turn it off when it ends.", "Give each list its own label when a page shows more than one conversation.", "Keep the message box and other read-out areas outside it." ], "onPhone": [ "Fills the width of its container up to 768px, so on a phone it is the full width with a 24px gap between messages.", "It does not scroll or pin itself. Your scrolling parent must handle the on-screen keyboard and the bottom safe area." ], "importPath": "import { MessageList } from \"./index\"", "sourcePath": "src/organisms/MessageList.tsx", "props": [ { "name": "children", "type": "ReactNode", "required": true, "default": null, "description": "The messages, in order. Usually Message components." }, { "name": "label", "type": "string", "required": false, "default": "\"Conversation\"", "description": "Accessible name of the log region. Change it when more than one thread is on screen." } ], "variantsHint": {}, "tokens": [ "max-w-3xl reading width", "gap-6 spacing" ], "related": [ "composer", "markdown", "source-list" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "A short conversation", "description": "Your messages and the assistant's replies stack in one column.", "code": "\n Summarise the meeting notes.\n The team agreed to ship on Friday and review metrics next week.\n" }, { "title": "A reply that is still being written", "description": "Give the conversation a name for screen readers. A reply that is still being written shows a blinking cursor.", "code": "\n What drove growth?\n Revenue grew mostly because of enterprise renewals\n" } ], "pageUrl": "https://lkb00.github.io/tattva/component-message-list/", "markdownUrl": "https://lkb00.github.io/tattva/docs/message-list.md" }, { "id": "composer", "name": "Composer", "level": "organism", "since": "0.5", "aka": [ "chat input", "prompt input", "message input", "chat box", "prompt box" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "streaming", "note": "Set with the generating prop.", "source": "prop" }, { "name": "disabled", "note": "Set with the disabled prop.", "source": "prop" } ], "summary": "The box where people type a message, with attach, tools and send or stop.", "description": "Composer is where people type to the assistant. Enter sends. Shift and Enter start a new line. It never sends while someone is still choosing a character with an input method. While the assistant is replying, Send turns into Stop. The box grows as you type, then scrolls. Show the attach button only if your app can take files.", "purpose": "The one place people type to the assistant. Send turns into Stop while a reply is being written, so the main button always does what matters right now.", "useFor": [ "The message box at the bottom of a conversation.", "A message box inside a Tray on a landing screen.", "A chat where people may need to stop a long reply." ], "notFor": [ { "text": "Describing something to make, such as an image, where Enter should add a line", "use": "prompt-box" }, { "text": "A short one-line search or filter field" } ], "whenToUse": [ "Keep one Composer at the bottom of the conversation, as wide as the messages.", "Always let people stop a reply while it is being written.", "Put choices such as project or model beside Send.", "Set the limit to the real one so the counter is honest.", "Pass onAttach only when your app can really take files. The button appears whenever it is set.", "Pass onStop whenever you set generating, so Stop really stops the reply." ], "avoid": [ "Do not show the attach button if your app cannot take files. A button that does nothing is confusing.", "Do not show more than one Composer in the same conversation.", "Do not add a second send button. Enter and the green button already cover it.", "Do not use the green Send button for anything else. Green marks the one main send action." ], "accessibility": [ "The text box is named \"Message\" for screen readers.", "Enter sends and Shift and Enter add a new line. Enter never sends while someone is still choosing a character with an input method.", "The buttons are named \"Attach file\", \"Send message\" and \"Stop generating\".", "Send stays off until there is text to send.", "Near the limit a character count appears, and screen readers hear it politely." ], "accessibilityYouDo": [ "Show the sent message or an error after onSend, so people know what happened.", "Give anything you put in tools its own name for screen readers." ], "onPhone": [ "The text box is 16px on a touch screen so the page does not zoom on focus, and it grows up to 200px tall as the person types.", "The attach, tools and send controls wrap onto their own line when they do not fit. Each has a 44px tap area on a touch screen.", "The phone keyboard is asked to show a send key. Enter sends and Shift+Enter adds a new line, which is hard to reach on a phone, so people cannot easily write a second line.", "It does no keyboard or safe-area handling of its own, so keep it above the on-screen keyboard and the bottom safe area yourself." ], "importPath": "import { Composer } from \"./index\"", "sourcePath": "src/organisms/Composer.tsx", "props": [ { "name": "placeholders", "type": "string[]", "required": false, "default": null, "description": "Example messages that take turns as the placeholder while the box is empty, so a blank field shows what kind of thing to type. With reduced motion the first one stays still. Overrides placeholder." }, { "name": "placeholderInterval", "type": "number", "required": false, "default": "4000", "description": "Milliseconds each example stays." }, { "name": "onSend", "type": "(text: string) => void", "required": true, "default": null, "description": "Called with the trimmed text on Enter or Send. The field is cleared afterwards." }, { "name": "generating", "type": "boolean", "required": false, "default": null, "description": "When true the send button becomes Stop, and submitting is blocked." }, { "name": "onStop", "type": "() => void", "required": false, "default": null, "description": "Called when Stop is pressed while generating." }, { "name": "placeholder", "type": "string", "required": false, "default": "\"Message the assistant…\"", "description": "Placeholder text of the textarea." }, { "name": "maxLength", "type": "number", "required": false, "default": "4000", "description": "Hard limit on the textarea. A counter appears once the text passes 90% of it." }, { "name": "onAttach", "type": "() => void", "required": false, "default": null, "description": "Called when Attach file is pressed. The attach button renders only when this is provided." }, { "name": "tools", "type": "ReactNode", "required": false, "default": null, "description": "Extra controls rendered between the attach button, when present, and the send button." }, { "name": "disabled", "type": "boolean", "required": false, "default": null, "description": "Disables the textarea and Send and dims the whole composer." } ], "variantsHint": {}, "tokens": [ "--border-strong", "--surface", "--shadow-sm / --shadow-md", "--fg-subtle", "--warning-fg (counter)", "--lime (Send)", "--radius-field" ], "related": [ "prompt-box", "tray", "message-list" ], "composedOf": [ "icon-button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Default", "description": "Send stays off until something is typed. Try Enter, then Shift and Enter.", "code": "
\n console.log(text)} />\n
" }, { "title": "With an attach button", "description": "The Attach file button shows only when files are allowed. Press it to see what happens.", "code": "
\n openFilePicker()} onSend={(text) => console.log(text)} />\n
" }, { "title": "While a reply is being written", "description": "The green Send button turns into Stop. Enter does nothing until the reply is done.", "code": "
\n {}} onSend={() => {}} />\n
" }, { "title": "With a choice beside Send", "description": "Add choices such as a project picker. They sit to the left of Send.", "code": "
\n {}}\n tools={} onClick={() => {}}>All projects}\n />\n
" }, { "title": "Near the character limit", "description": "The limit here is 40 characters. Type more than 36 to see the counter.", "code": "
\n {}} />\n
" }, { "title": "Rotating examples", "description": "An empty box shows one example at a time instead of a row of example chips. With reduced motion, the first example stays.", "code": " console.log(text)}\n placeholders={[\n \"My order was cancelled but no refund came\",\n \"UPI payment failed and the money is gone\",\n \"The flight was cancelled and I want my money back\",\n ]}\n/>" } ], "pageUrl": "https://lkb00.github.io/tattva/component-composer/", "markdownUrl": "https://lkb00.github.io/tattva/docs/composer.md" }, { "id": "conversation-list", "name": "ConversationList", "level": "organism", "since": "0.5", "aka": [ "chat history", "conversation history", "threads list", "sidebar history" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "current", "note": "The item whose id matches activeId gets a highlighted background and aria-current set to page.", "source": "documented" }, { "name": "hover", "note": "An item gets a soft background under the pointer.", "source": "documented" }, { "name": "focus", "note": "A visible focus ring appears on an item or the New chat button on keyboard focus.", "source": "documented" }, { "name": "empty", "note": "With no items, only the New chat button is shown.", "source": "documented" }, { "name": "row menu", "note": "With onRename or onDelete, each row gets a More menu (drawn on the page, so a scrolling side bar cannot clip it).", "source": "documented" }, { "name": "confirming delete", "note": "Choosing Delete swaps the row for \"Delete this chat?\" with Keep it and Delete side by side; focus lands on Keep it and Escape cancels.", "source": "documented" } ], "summary": "Past chats grouped by day, with a New chat button, for the side bar.", "description": "ConversationList shows a New chat button and the titles of past chats under small group names. Groups appear in the order they are given. Chats with no group go under Recent. The open chat is highlighted. Your app keeps track of which chat is open.", "purpose": "The history of past chats for the side panel. A New chat button sits on top, so starting fresh is always one press away.", "useFor": [ "Past chats in the AppShell side panel, grouped by day.", "Switching between chats, with the open one highlighted.", "Starting a new chat from the side panel." ], "notFor": [ { "text": "The main site menu or links to other parts of the app" }, { "text": "The messages inside one chat", "use": "message-list" } ], "whenToUse": [ "Use groups such as Today and Yesterday, newest first.", "Keep titles short. Long ones wrap onto a second line and make the list harder to scan.", "Place it in the side bar of AppShell, which sets the width.", "Keep the highlight matching the chat that is open." ], "avoid": [ "Do not use it as the main site menu. It lists chats only.", "Do not expect it to sort. It keeps the order you give it.", "Do not add extra actions inside a row. Each row is one button." ], "accessibility": [ "It is a navigation area named \"Conversations\".", "Each chat is a real button, so Tab, Enter and Space work.", "The open chat is marked as current for screen readers and gets a background, so color is not the only clue.", "Each group of chats is its own list, so screen readers say how many chats it holds." ], "accessibilityYouDo": [ "Keep activeId in step with the chat that is open, so the right one is announced as current.", "Write titles that tell chats apart. The title is all a screen reader hears for each row.", "Use one per page. Its navigation name, \"Conversations\", is fixed." ], "onPhone": [ "Each row title is a full-width button with a tap area at least 44px tall on a touch screen, and long titles wrap instead of being cut off.", "The row menu button grows from 32px to 44px on a touch screen, and the menu opens as a bottom sheet.", "Delete asks in place with Keep and Delete side by side, each with a 44px tap area." ], "importPath": "import { ConversationList } from \"./index\"", "sourcePath": "src/organisms/ConversationList.tsx", "props": [ { "name": "items", "type": "ConversationItem[]", "required": true, "default": null, "description": "Conversations to show. ConversationItem is { id: string; title: string; group?: string }." }, { "name": "activeId", "type": "string", "required": false, "default": null, "description": "Id of the open conversation. It receives aria-current and the active style." }, { "name": "onSelect", "type": "(id: string) => void", "required": true, "default": null, "description": "Called with the id when an item is clicked." }, { "name": "onNew", "type": "() => void", "required": true, "default": null, "description": "Called when New chat is pressed." }, { "name": "onRename", "type": "(id: string) => void", "required": false, "default": null, "description": "When given, each row gets a More menu with Rename. Your code asks for the new name." }, { "name": "onDelete", "type": "(id: string) => void", "required": false, "default": null, "description": "When given, each row gets Delete in its More menu. Pressing it asks once, in place, with Keep it as easy to press as Delete and focus on Keep it. Called only after the person confirms." }, { "name": "labels", "type": "{ delete?: string; keep?: string; confirm?: (title: string) => string }", "required": false, "default": null, "description": "The words of the in-place confirmation." } ], "variantsHint": {}, "tokens": [ "--surface-hover (bg-hover)", "--fg-muted", "--fg-subtle", "--radius-control", "--radius-card" ], "related": [ "tray", "app-shell" ], "composedOf": [ "button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Grouped history", "description": "Each chat has a group name. Groups show in the order they first appear.", "code": "const [active, setActive] = useState(\"2\");\n\n
\n {}}\n items={[\n { id: \"1\", title: \"Q3 revenue analysis\", group: \"Today\" },\n { id: \"2\", title: \"Onboarding email draft\", group: \"Today\" },\n { id: \"3\", title: \"SQL help\", group: \"Yesterday\" },\n { id: \"4\", title: \"Meeting notes summary\", group: \"Yesterday\" },\n ]}\n />\n
" }, { "title": "Chats with no groups", "description": "Chats with no group all go under Recent.", "code": "const [active, setActive] = useState(\"a\");\n\n
\n {}}\n items={[\n { id: \"a\", title: \"Trip planning\" },\n { id: \"b\", title: \"Contract summary\" },\n ]}\n />\n
" }, { "title": "Rename and delete from a row menu", "description": "Each row gets a More menu. Delete asks once, right in the row, and Keep it is as easy to press as Delete. The menu is drawn on the page itself, so a scrolling side bar cannot cut it off.", "code": " askForName(id)}\n onDelete={(id) => remove(id)}\n/>" } ], "pageUrl": "https://lkb00.github.io/tattva/component-conversation-list/", "markdownUrl": "https://lkb00.github.io/tattva/docs/conversation-list.md" }, { "id": "markdown", "name": "Markdown", "level": "organism", "since": "0.5", "aka": [ "rich text", "markdown renderer", "formatted text" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "unclosed code fence", "note": "A code fence with no closing line still renders as a code block, so partly streamed text does not break.", "source": "documented" }, { "name": "unsafe link", "note": "A link whose address is not http, https or mailto is shown as plain text instead of a link.", "source": "documented" }, { "name": "wide table", "note": "A table wider than the column scrolls sideways and can be focused with the keyboard.", "source": "documented" } ], "summary": "Turns the assistant's formatted text into headings, lists, links and tables, even while it is still being written.", "description": "Markdown shows formatted text safely. It handles headings, bold, italic, links, lists, quotes, tables, dividers and code. Lists can go three levels deep. A code block that is not finished yet still shows as code while the reply is being written. Markers like [1] become small source numbers. Only web and email links work.", "purpose": "Turns the assistant's formatted text into real headings, lists, tables and code. It builds the page safely and copes with text that stops halfway, so it can show a reply while it is still arriving.", "useFor": [ "The body of an assistant reply.", "A reply that is still being written: pass all the text so far each time.", "A draft document shown inside a CanvasPanel." ], "notFor": [ { "text": "A code sample on its own, outside a reply", "use": "code-block" }, { "text": "Text that people need to edit" } ], "whenToUse": [ "Put it in a container that sets text size and spacing.", "While the reply is being written, give it all the text so far each time.", "Show a SourceList under the reply so the [1] markers point somewhere.", "Use it for assistant replies, where the content is not known ahead of time." ], "avoid": [ "Do not expect images, web code, checkbox lists or lists deeper than three levels. Deeper items stay at level three.", "Do not add web code to the text. It is shown as plain text.", "Do not use it to edit documents. It only displays text.", "Do not rely on it for the page's heading structure. Its headings sit below the page title." ], "accessibility": [ "Headings are marked as headings, one level below the page title.", "Lists are real lists, so screen readers say how many items there are and how deep they go.", "Table columns have headers, and a wide table can be reached with Tab and scrolled sideways.", "Source markers like [1] are links that screen readers hear as \"Source 1\".", "Only web and email links become links, and they open in a new tab. The text cannot add scripts to the page." ], "accessibilityYouDo": [ "Put it inside a Message with streaming on while the reply arrives, so screen readers are not interrupted by every word.", "Show a SourceList on the same page, so source markers lead somewhere.", "Ask for link text that makes sense on its own, not \"click here\"." ], "onPhone": [ "Tables and code blocks scroll sideways inside their own box, so a wide one never pushes the page wider.", "Source markers like [1] get a larger invisible tap area on a touch screen.", "Paragraphs wrap long unbroken words and addresses, so they do not push the page wider." ], "importPath": "import { Markdown } from \"./index\"", "sourcePath": "src/organisms/Markdown.tsx", "props": [ { "name": "children", "type": "string", "required": true, "default": null, "description": "The Markdown source. Partial text is fine. Re-render with the growing string while streaming." } ], "variantsHint": {}, "tokens": [ "--surface-sunken (code, table head)", "--border (tables, rules)", "--accent-fg (links)", "--accent-soft-border (blockquote)", "--fg-muted", "--code-bg (via CodeBlock)", "--radius-card" ], "related": [ "source-list", "message-list" ], "composedOf": [ "citation-marker", "code-block" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "A rich reply", "description": "Shows a heading, bold and italic text, a link, a source number, a table, a quote, a list, a divider and code.", "code": "const RICH = `## Quarterly summary\n\nRevenue grew **12%** …`;\n\n
\n {RICH}\n
" }, { "title": "Nested lists", "description": "Indent each level. Numbered and bulleted lists can mix. Three levels is the most.", "code": "const NESTED = `Plan for the release:\n\n1. Prepare the build\n - Update the changelog\n - Bump versions\n 1. Core package\n 2. Docs site\n2. Ship it\n - Tag the commit\n- Notify the team`;\n\n
\n {NESTED}\n
" }, { "title": "Code that is still being written", "description": "The end of the code has not arrived yet. It still shows as code, not as stray symbols.", "code": "const STREAMING = \"Here is a small helper:\\n\\n```ts\\nexport function clamp(...) {\\n return Math.min(...);\";\n\n
\n {STREAMING}\n
" }, { "title": "A risky link becomes plain text", "description": "Links that could run code are not clickable. Only their words stay.", "code": "
\n {\"Open [the safe page](https://example.com) or [this one](javascript:alert(1)).\"}\n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-markdown/", "markdownUrl": "https://lkb00.github.io/tattva/docs/markdown.md" }, { "id": "step-timeline", "name": "StepTimeline", "level": "organism", "since": "0.5", "aka": [ "stepper", "steps", "progress steps", "activity timeline", "wizard steps" ], "category": "agents", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "done", "note": "A step with state done shows a green check and a green connector line.", "source": "documented" }, { "name": "active", "note": "A step with state active shows a spinner and is marked as the current step.", "source": "documented" }, { "name": "todo", "note": "A step with state todo shows its number and dimmed title.", "source": "documented" }, { "name": "failed", "note": "A step with state failed shows a red cross.", "source": "documented" } ], "summary": "A list of steps in a task, showing which are done, in progress, waiting or failed.", "description": "StepTimeline shows the stages of a task in order, joined by a thin line. Done steps get a green check. The current step shows a spinner. Failed steps show a cross. Waiting steps show their number. Use it when order matters and people want to know where things stand.", "purpose": "Shows the stages of a task in order, so people see at a glance what is done, what is happening now and what failed.", "useFor": [ "A task whose steps must happen in order.", "Showing where a running workflow stands.", "Showing which step failed, with later steps still waiting." ], "notFor": [ { "text": "Open items with no set order", "use": "checklist" }, { "text": "Events with dates, such as a history of changes", "use": "timeline" }, { "text": "The details of one tool the assistant used", "use": "tool-call-card" } ], "whenToUse": [ "Mark only one step as in progress at a time.", "Use the detail line to say who or what is being waited on.", "Keep titles short, starting with an action word.", "Say why a step failed in its detail line, so people do not have to look elsewhere." ], "avoid": [ "Do not use it for to-dos with no order. Use Checklist.", "Do not use it for dozens of steps. It cannot fold or scroll.", "Do not use amber here. Amber is for rows that need a person, in Checklist and ApprovalPrompt." ], "accessibility": [ "It is a numbered list named \"Task progress\".", "The step in progress is marked as the current step for screen readers.", "Each step has hidden text with its state (done, active, todo or failed), so meaning does not rest on color or icon.", "The spinner on the current step is read as \"Loading\"." ], "accessibilityYouDo": [ "Mark only one step as active at a time.", "Put the reason for a failure in the step's detail. The hidden text only says \"failed\".", "Tell people when a step finishes or fails, for example with a short status message. The list does not announce changes." ], "onPhone": [ "Steps stack in one column, and titles and details wrap inside the space beside the marker.", "Nothing in it is tappable, so there are no touch targets to size. Detail text is 12px." ], "importPath": "import { StepTimeline } from \"./index\"", "sourcePath": "src/organisms/StepTimeline.tsx", "props": [ { "name": "steps", "type": "Step[]", "required": true, "default": null, "description": "Ordered steps. Step is { id: string; title: string; detail?: string; state: \"done\" | \"active\" | \"todo\" | \"failed\" }." } ], "variantsHint": {}, "tokens": [ "--success", "--danger", "--accent", "--border / --border-strong", "--fg-muted / --fg-subtle" ], "related": [ "checklist", "approval-prompt" ], "composedOf": [ "spinner" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "In progress", "description": "One step done, one in progress, one waiting.", "code": "" }, { "title": "A failed step", "description": "A failed step gets a red cross and says what went wrong. Later steps keep waiting.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-step-timeline/", "markdownUrl": "https://lkb00.github.io/tattva/docs/step-timeline.md" }, { "id": "approval-prompt", "name": "ApprovalPrompt", "level": "organism", "since": "0.5", "aka": [ "confirmation", "approve deny", "human in the loop", "confirm action" ], "category": "agents", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "low risk", "note": "Set risk to low for a quiet border and an optional Always allow button when onAlways is passed.", "source": "documented" }, { "name": "medium or high risk", "note": "Set risk to medium or high for a warning-tinted box and a coloured risk badge.", "source": "documented" }, { "name": "focus", "note": "The Approve, Deny and Always allow buttons show a focus ring on keyboard focus.", "source": "documented" } ], "summary": "A pause that asks a person before the assistant does something important.", "description": "ApprovalPrompt stops the assistant before an action and says exactly what will happen. It shows a risk label, the details, and equal Approve and Deny buttons. Low risk looks neutral. Medium and high risk use amber, because a person has to decide. High risk gets a red label. Always allow shows only for low risk. Use it before anything that sends, deletes, spends or shares.", "purpose": "Stops the assistant before an action that matters and says exactly what will happen. Approve and Deny sit side by side, so saying no is as easy as saying yes.", "useFor": [ "Before the assistant sends, deletes, spends or shares something.", "An action that cannot be undone: set risk to high.", "A read-only action people may want to allow every time: set risk to low and pass onAlways." ], "notFor": [ { "text": "Harmless actions that change nothing" }, { "text": "Choosing how much the assistant may do on its own", "use": "permission-mode-switcher" }, { "text": "A question the assistant needs answered before it can go on", "use": "agent-question-card" } ], "whenToUse": [ "Name the real person, file or amount, so no one has to guess.", "Make Deny as easy to find as Approve.", "Set the risk by what the action does: can it be undone, and who does it reach.", "Offer Always allow only for low-risk actions that just look." ], "avoid": [ "Do not ask about harmless actions. Too many questions teach people to click through.", "Do not use vague words like This action may have effects.", "Do not pre-select Approve for high-risk actions.", "Do not expect Always allow on medium or high risk. It never shows." ], "accessibility": [ "Screen readers announce it as an alert dialog named \"Approval needed\" followed by the action.", "The risk level is written in words, such as \"high risk\", so color is not the only clue.", "Approve, Deny and Always allow are real buttons that work with Tab, Enter and Space.", "Always allow never shows for medium or high risk, even if you pass onAlways." ], "accessibilityYouDo": [ "Move focus to the prompt when it appears, for example to Deny, or show it where the person is already working. It does not move focus by itself.", "Tell people the result of their choice, for example with a short status message.", "Write the detail with the real names, files and amounts." ], "onPhone": [ "The action, risk badge and details fill the width, and the Approve and Deny buttons wrap onto a second line if they do not fit.", "Every button has a 44px tap area on a touch screen, and Deny is the same size as Approve.", "It sits in the page and does not open as a sheet, so place it where the person will see it without scrolling." ], "importPath": "import { ApprovalPrompt } from \"./index\"", "sourcePath": "src/organisms/ApprovalPrompt.tsx", "props": [ { "name": "action", "type": "string", "required": true, "default": null, "description": "Short title of what the agent wants to do. Also used in the dialog's accessible name." }, { "name": "detail", "type": "ReactNode", "required": true, "default": null, "description": "Exactly what will happen, in plain language with real values, not placeholders." }, { "name": "risk", "type": "\"low\" | \"medium\" | \"high\"", "required": false, "default": "\"medium\"", "description": "Low uses the neutral sunken surface and a neutral badge. Medium uses the attention surface and a warning badge. High uses the attention surface and a danger badge. The level is always written in the badge text. Also decides whether Always allow can show." }, { "name": "onApprove", "type": "() => void", "required": true, "default": null, "description": "Called when Approve is pressed." }, { "name": "onDeny", "type": "() => void", "required": true, "default": null, "description": "Called when Deny is pressed." }, { "name": "onAlways", "type": "() => void", "required": false, "default": null, "description": "Adds an Always allow ghost button. Rendered only when risk is low." } ], "variantsHint": { "risk": [ "low", "medium", "high" ] }, "tokens": [ "--warning / --warning-soft / --warning-fg (medium and high surface)", "--surface-sunken (low surface)", "--danger-soft / --danger-fg (high risk badge)", "--fg-muted", "--radius-card" ], "related": [ "checklist", "step-timeline" ], "composedOf": [ "badge", "button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "High risk", "description": "An action that cannot be undone, in amber with a red label. There is no Always allow.", "code": "This permanently removes 14 projects from the workspace Acme Studio. It cannot be undone.}\n onApprove={() => {}}\n onDeny={() => {}}\n/>" }, { "title": "Medium risk (the default)", "description": "An action others will see, in amber. Medium is used when no level is given.", "code": "An email from team@example.com will be sent now.}\n onApprove={() => {}}\n onDeny={() => {}}\n/>" }, { "title": "Low risk with Always allow", "description": "An action that only looks, in a neutral color. It can offer Always allow so people are not asked again. Click a button to see the choice.", "code": "The assistant will list file names in /reports/2026. Nothing is changed.}\n onApprove={() => {}}\n onDeny={() => {}}\n onAlways={() => {}}\n/>" } ], "pageUrl": "https://lkb00.github.io/tattva/component-approval-prompt/", "markdownUrl": "https://lkb00.github.io/tattva/docs/approval-prompt.md" }, { "id": "checklist", "name": "Checklist", "level": "organism", "since": "0.5", "aka": [ "todo list", "task list", "plan steps" ], "category": "agents", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "done summary", "note": "Pass doneSummary to add a final row with a check and the summary text.", "source": "documented" }, { "name": "empty", "note": "With no items and no doneSummary, only the top border is drawn.", "source": "documented" } ], "summary": "A list of what is still open, with finished work folded into one line.", "description": "Checklist shows open items as rows, each with an optional tag and status. Rows that need a person get an amber dot. Finished work is folded into one summary line so the list stays short. Use it for a task in progress, such as people who still owe a document.", "purpose": "Shows what is still open in a running task and folds finished work into one line, so the list stays short and the open items stand out.", "useFor": [ "People or items that still owe something, such as missing documents.", "A task in progress where only a few items need a person.", "Open work with a one-line summary of what is already done." ], "notFor": [ { "text": "Steps that must happen in a set order", "use": "step-timeline" }, { "text": "A short list of things to open from a landing screen", "use": "tray" } ], "whenToUse": [ "List open items first and fold finished ones into the summary line.", "Mark a row only when a person has to act.", "Write status as a short fact with a time, such as No reply in 5 days.", "Use the tag for a category, not for status." ], "avoid": [ "Do not list every finished item. The summary line is there to avoid that.", "Do not use amber for items that are only late or still being handled by the assistant.", "Do not use it for steps that must happen in order. Use StepTimeline." ], "accessibility": [ "It is a real list, so screen readers say how many items there are.", "The amber dot is read as \"Needs attention\", next to the status words.", "The check mark in the summary line is hidden from screen readers. The words carry the meaning." ], "accessibilityYouDo": [ "Write a status that says what is needed, such as \"No reply in 5 days\".", "Put a real button or link in the title if a row should open something. Rows do nothing on their own.", "Mark a row as needing attention only when a person has to act." ], "onPhone": [ "Each row runs the full width, with the title on the left and the status on the right.", "The rows are not tappable, so there are no touch targets to size. Status text is 12px." ], "importPath": "import { Checklist } from \"./index\"", "sourcePath": "src/organisms/Checklist.tsx", "props": [ { "name": "items", "type": "ChecklistItem[]", "required": true, "default": null, "description": "Open items. ChecklistItem is { id: string; title: ReactNode; badge?: ReactNode; status?: string; attention?: boolean }." }, { "name": "doneSummary", "type": "string", "required": false, "default": null, "description": "One line summarising completed work. Shown as a final row with a check mark." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes merged onto the list." } ], "variantsHint": {}, "tokens": [ "--border (top and row rules)", "--border-strong (summary check)", "--attention (dot)", "--fg-muted / --fg-subtle" ], "related": [ "step-timeline", "approval-prompt", "tray" ], "composedOf": [ "checklist-row", "attention-dot" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Open items with a summary", "description": "The first row needs a person, so it has an amber dot. Finished work is one line at the end.", "code": "Dana Whitfield, badge: Form A, status: \"No reply in 5 days, due in 2\", attention: true },\n { id: \"2\", title: Owen Park, badge: Form A, status: \"Reminder sent yesterday\" },\n ]}\n/>" }, { "title": "Nothing needs a person", "description": "When nothing needs a person, no amber appears.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-checklist/", "markdownUrl": "https://lkb00.github.io/tattva/docs/checklist.md" }, { "id": "source-list", "name": "SourceList", "level": "organism", "since": "0.5", "aka": [ "sources", "references", "bibliography", "citations list" ], "category": "trust", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [], "summary": "The numbered sources behind an answer, shown in two columns.", "description": "SourceList shows a Sources heading and one card per source. Each card is a link that opens in a new tab. The numbers match the [1] markers in the reply. Place it under a reply that backs up its claims.", "purpose": "Shows where an answer came from: it lists the sources behind a reply as numbered cards, so people can check a claim. The numbers match the [1] markers in the text.", "useFor": [ "Under a finished reply that cites its sources.", "Research answers where people may want to read the original.", "Next to Markdown, whose [1] markers jump to the matching card." ], "notFor": [ { "text": "One source shown when someone hovers a marker", "use": "citation-hover-card" }, { "text": "A single source on its own", "use": "source-card" } ], "whenToUse": [ "Use numbers that match the [n] markers in the reply.", "Use real page titles and websites so people can judge a source at a glance.", "Add a short quote when it shows why the source backs up the claim.", "Show it only after the reply is finished, so nothing jumps while people read." ], "avoid": [ "Do not show a source the reply never mentions.", "Do not reuse numbers across replies on one page. Links would point to the wrong source.", "Do not use links you have not checked. Cards open whatever link you give them." ], "accessibility": [ "It is an area named \"Sources\" that holds a numbered list.", "Each card is one link, read as its number, title, website and quote.", "Each card can be jumped to from a matching [1] marker in the reply." ], "accessibilityYouDo": [ "Use ids that match the [n] markers in the reply, and keep them unique on the page.", "Say that links open in a new tab if that matters to your users. Screen readers are not told." ], "onPhone": [ "Sources show in one column on a phone and in two columns from 600px wide.", "Each source is a link that opens in a new tab, and its title is cut to one line and its snippet to two.", "A source card is taller than 44px, so the whole card is an easy tap target." ], "importPath": "import { SourceList } from \"./index\"", "sourcePath": "src/organisms/SourceList.tsx", "props": [ { "name": "sources", "type": "Source[]", "required": true, "default": null, "description": "Sources to list. Source is { id: number; title: string; url: string; domain: string; snippet?: string }." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes merged onto the section." } ], "variantsHint": {}, "tokens": [ "--surface", "--border / --border-strong", "--surface-sunken (hover)", "--lime (number badge fill)", "--fg-muted / --fg-subtle" ], "related": [ "markdown", "message-list" ], "composedOf": [ "source-card" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Three sources", "description": "The short quote is optional. Cards sit in two columns on wider screens.", "code": "
\n \n
" }, { "title": "Beside the reply it supports", "description": "The [1] and [2] in the text point to the first and second source below.", "code": "
\n {\"Revenue grew 12% quarter over quarter.[1] Churn held steady.[2]\"}\n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-source-list/", "markdownUrl": "https://lkb00.github.io/tattva/docs/source-list.md" }, { "id": "prompt-box", "name": "PromptBox", "level": "organism", "since": "0.5", "aka": [ "prompt input", "generation prompt", "prompt field" ], "category": "creating", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "loading", "note": "Set with the busy prop.", "source": "prop" } ], "summary": "A box for describing what you want made, with a Generate button and optional examples.", "description": "PromptBox is for tools that make things, such as images. It has a three-line text box, a character count and a green Generate button. While it works, the button is off and shows Generating. Example ideas appear as small buttons that fill the box when clicked. Use it when the result is a set of new things, not a chat reply.", "purpose": "A roomy box for describing something to make, such as an image or a draft. Enter adds a line instead of sending, because these descriptions are often long and reworked before each run.", "useFor": [ "The input of a tool that makes images, designs or drafts.", "Offering a few example ideas that fill the box in one click.", "A Generate step that takes a while: set busy so it cannot be pressed twice." ], "notFor": [ { "text": "Chatting back and forth with the assistant", "use": "composer" }, { "text": "Fine settings such as size, style or seed", "use": "parameter-panel" } ], "whenToUse": [ "Use it when each submit makes something new.", "Offer two or three examples so new people see what to write.", "Keep it in the working state the whole time, so people cannot submit twice.", "Pair it with VariantGrid and CanvasPanel in a SplitCanvasTemplate.", "Set busy back to false when the run ends, or Generate stays off." ], "avoid": [ "Do not use it for chat. Use Composer, which has Enter and Stop.", "Do not show a PromptBox and a Composer on the same screen.", "Do not use long sentences as examples. They do not fit in small buttons." ], "accessibility": [ "It is a real form, and the text box is named \"Prompt\" for screen readers.", "Generate is a real button. It stays off while the box is empty or busy.", "While busy, the button text changes to \"Generating…\" and its spinner is read as \"Loading\".", "Example ideas are real buttons, so they work from the keyboard.", "Screen readers hear when generating starts and when it ends." ], "accessibilityYouDo": [ "Set doneMessage to say where the results are, such as \"Done. 4 images below.\"" ], "onPhone": [ "The text box is 16px on a touch screen so the page does not zoom on focus. It stays three rows tall and does not grow.", "Enter adds a new line, so people send with the Generate button, which has a 44px tap area on a touch screen.", "The example chips wrap onto more lines. Each keeps its size and has a 44px tap area on a touch screen." ], "importPath": "import { PromptBox } from \"./index\"", "sourcePath": "src/organisms/PromptBox.tsx", "props": [ { "name": "onGenerate", "type": "(prompt: string) => void", "required": true, "default": null, "description": "Called with the trimmed prompt on submit. Not called when empty or busy." }, { "name": "busy", "type": "boolean", "required": false, "default": null, "description": "Disables Generate and swaps its label and icon for a spinner with Generating…" }, { "name": "placeholder", "type": "string", "required": false, "default": "\"Describe what you want to create…\"", "description": "Placeholder text for the textarea." }, { "name": "examples", "type": "string[]", "required": false, "default": "[]", "description": "Prompts offered as Try pills. Clicking one replaces the textarea content." } ], "variantsHint": {}, "tokens": [ "--border-strong", "--surface", "--shadow-sm", "--lime (Generate)", "--fg-subtle", "--surface-hover", "--radius-control", "--radius-field" ], "related": [ "composer", "variant-grid", "canvas-panel" ], "composedOf": [ "button", "spinner" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "With example ideas", "description": "Click an example to fill the box, then Generate. The demo shows Generating for 1.5 seconds.", "code": "const [busy, setBusy] = useState(false);\n\n
\n { setBusy(true); setTimeout(() => setBusy(false), 1500); }}\n />\n
" }, { "title": "While it works", "description": "The button is off, so a second request cannot start. The text can still be edited.", "code": "
\n {}} />\n
" }, { "title": "Custom placeholder", "description": "Change the hint text to match what is being made.", "code": "
\n {}} />\n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-prompt-box/", "markdownUrl": "https://lkb00.github.io/tattva/docs/prompt-box.md" }, { "id": "variant-grid", "name": "VariantGrid", "level": "organism", "since": "0.5", "aka": [ "variations grid", "results grid", "image grid" ], "category": "creating", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "selected", "note": "The tile whose id matches selectedId is checked and is the one tab stop.", "source": "documented" }, { "name": "loading", "note": "Pass loadingCount to append that many shimmering placeholder tiles.", "source": "documented" }, { "name": "keyboard", "note": "Arrow keys, Home and End move focus between tiles and select the one reached.", "source": "documented" }, { "name": "empty", "note": "With no variants, only loading placeholders (if any) are drawn.", "source": "documented" } ], "summary": "A set of made options where you pick one, with empty slots held for ones still coming.", "description": "VariantGrid shows options as square tiles, two across or four on wider screens. You can pick exactly one, and the pick shows a check mark as well as a border. Tab goes to the picked tile and arrow keys move and pick. Loading slots keep the layout from jumping while more options arrive.", "purpose": "Shows options the assistant made as square tiles and lets people pick one. Empty slots hold space for options still on the way, so tiles do not jump around.", "useFor": [ "Picking one of several generated images or designs.", "A round of options that arrive one by one: set loadingCount.", "Comparing options side by side before opening one in a canvas." ], "notFor": [ { "text": "Picking several options at once" }, { "text": "Media that people look at but do not choose between", "use": "media-grid" }, { "text": "Buttons to vary, upscale or remix one option", "use": "variation-actions" } ], "whenToUse": [ "Give each option its own name.", "Hold space for options that are still arriving.", "Make the content fill the square tile.", "Mark made images with the AI label. VariantTile adds it for you.", "Update selectedId in onSelect, since arrow keys pick as they move." ], "avoid": [ "Do not use it to pick several. It allows one choice.", "Do not put buttons inside a tile. The whole tile is the button.", "Do not rely on border color alone to show the pick. The check mark covers it." ], "accessibility": [ "It is a group of choices named \"Generated variants\". Each tile has its own name, and screen readers say which one is picked.", "Only one tile is a Tab stop. Arrow keys move and pick, wrapping at the ends, and Home and End jump to the first and last.", "The pick shows a check mark and a thicker border, not color alone.", "Loading slots are hidden from screen readers.", "Screen readers hear when options start generating and when new ones arrive, such as \"4 options ready\"." ], "accessibilityYouDo": [ "Give each variant a label that tells it apart, not just a letter.", "Set label, loadingMessage and readyMessage when you translate." ], "onPhone": [ "Tiles show in two columns on a phone and in four columns from 600px wide, and each tile stays square.", "Tiles are tapped to select, and the selected tile shows a check mark, so selection does not depend on hover.", "Loading slots are the same square size, so the grid does not jump when the options arrive." ], "importPath": "import { VariantGrid } from \"./index\"", "sourcePath": "src/organisms/VariantGrid.tsx", "props": [ { "name": "variants", "type": "Variant[]", "required": true, "default": null, "description": "Options to show. Variant is { id: string; node: ReactNode; label: string }. The node fills a square tile." }, { "name": "selectedId", "type": "string", "required": false, "default": null, "description": "Id of the chosen variant. Leave undefined for no selection." }, { "name": "onSelect", "type": "(id: string) => void", "required": true, "default": null, "description": "Called with the id when a tile is clicked." }, { "name": "loadingCount", "type": "number", "required": false, "default": "0", "description": "Number of skeleton squares appended after the variants." } ], "variantsHint": {}, "tokens": [ "--fg (selected border)", "--border / --border-strong", "--shadow-md", "--surface-sunken (skeleton)", "rounded-2xl tiles" ], "related": [ "prompt-box", "canvas-panel" ], "composedOf": [ "variant-tile", "skeleton" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Four options, one picked", "description": "Each option has a name for screen readers. Tab to the picked tile, then use the arrow keys, Home and End.", "code": "const [sel, setSel] = useState(\"a\");\n\n },\n { id: \"b\", label: \"Variant B\", node:
},\n { id: \"c\", label: \"Variant C\", node:
},\n { id: \"d\", label: \"Variant D\", node:
},\n ]}\n/>" }, { "title": "More options on the way", "description": "Two options are ready and two slots are held, so the grid keeps its size.", "code": " {}}\n loadingCount={2}\n variants={[\n { id: \"a\", label: \"Variant A\", node:
},\n { id: \"b\", label: \"Variant B\", node:
},\n ]}\n/>" }, { "title": "Nothing picked yet", "description": "Leave the pick empty until the person chooses.", "code": " {}}\n variants={[\n { id: \"a\", label: \"Variant A\", node:
},\n { id: \"b\", label: \"Variant B\", node:
},\n ]}\n/>" } ], "pageUrl": "https://lkb00.github.io/tattva/component-variant-grid/", "markdownUrl": "https://lkb00.github.io/tattva/docs/variant-grid.md" }, { "id": "canvas-panel", "name": "CanvasPanel", "level": "organism", "since": "0.5", "aka": [ "canvas", "artboard", "workspace" ], "category": "creating", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "first or last version", "note": "The previous arrow is disabled on version 1 and the next arrow on the last version.", "source": "documented" }, { "name": "single version", "note": "When versions is 1 or version is not set, the version switcher is hidden.", "source": "documented" } ], "summary": "A side panel for a document, code or design that stays after the chat message.", "description": "CanvasPanel is a titled panel that scrolls. It holds a document, code or a design. Its top bar shows the title and, if there is more than one version, Previous and Next buttons with a v of n label. It can also show Regenerate, Close and your own buttons. Use it beside the conversation in SplitCanvasTemplate.", "purpose": "A side panel for work that lasts longer than one message, such as a document, code or a design. It keeps versions, so people can go back while the chat moves on.", "useFor": [ "A draft document or code that the assistant keeps editing.", "Moving between versions of the same piece of work.", "The right side of SplitCanvasTemplate." ], "notFor": [ { "text": "A reply that only matters in the conversation", "use": "message" }, { "text": "A code snippet inside a reply", "use": "code-block" } ], "whenToUse": [ "Give the panel a height. It fills it and scrolls its own content.", "Use it for content that stays after the message that made it.", "Start version numbers at 1, and update the content when the version changes.", "Mark made content with an AI label in your own buttons area." ], "avoid": [ "Do not use it for one-off messages. Replies belong in the conversation.", "Do not put the main controls for making things inside it. They belong in the main column.", "Do not give a version count above 1 without saying which version is shown, or the buttons stay hidden." ], "accessibility": [ "It is an area named by its title, and the title is also a heading.", "The version buttons sit in a group named \"Version history\", are named \"Previous version\" and \"Next version\", and turn off at the ends.", "Regenerate and Close are icon buttons named \"Regenerate\" and \"Close panel\".", "When the version changes, screen readers hear it, such as \"Version 2 of 3\".", "The content area can be reached with Tab and scrolled with the arrow keys.", "After Close, keyboard focus returns to what had focus when the panel opened, such as the button that opened it. Pass focusAfterClose to choose another place." ], "accessibilityYouDo": [ "Give any buttons you pass in actions their own names." ], "onPhone": [ "It is a side panel with no phone layout of its own, so on a phone you must give it the full screen or a sheet yourself.", "It fills the height of its parent and scrolls its content inside, so the parent needs a set height.", "The title is cut to one line and the version, regenerate and close controls wrap below it. Each control has a 44px tap area on a touch screen." ], "importPath": "import { CanvasPanel } from \"./index\"", "sourcePath": "src/organisms/CanvasPanel.tsx", "props": [ { "name": "title", "type": "string", "required": true, "default": null, "description": "Artifact name. Shown truncated in the header and used as the panel's aria-label." }, { "name": "version", "type": "number", "required": false, "default": null, "description": "Current version, 1-based. Needed for the version switcher to appear." }, { "name": "versions", "type": "number", "required": false, "default": "1", "description": "Total number of versions. The switcher shows only when this is greater than 1." }, { "name": "onVersionChange", "type": "(v: number) => void", "required": false, "default": null, "description": "Called with the new version number from the previous and next buttons." }, { "name": "onClose", "type": "() => void", "required": false, "default": null, "description": "Shows a Close panel icon button when provided." }, { "name": "onRegenerate", "type": "() => void", "required": false, "default": null, "description": "Shows a Regenerate icon button when provided." }, { "name": "children", "type": "ReactNode", "required": true, "default": null, "description": "The artifact. Rendered in a scrolling body with 16px padding." }, { "name": "actions", "type": "ReactNode", "required": false, "default": null, "description": "Extra header controls, such as an AI badge or an Export button." } ], "variantsHint": {}, "tokens": [ "--surface", "--border (line)", "--shadow-md", "--fg-muted", "--radius-card" ], "related": [ "prompt-box", "variant-grid", "split-canvas-template" ], "composedOf": [ "button", "icon-button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Versioned document", "description": "With more than one version, Previous and Next appear and turn off at the ends.", "code": "const [v, setV] = useState(2);\n\n
\n {}} onClose={() => {}}>\n

Draft text for version {v}.

\n \n
" }, { "title": "Title only", "description": "With no versions, Regenerate or Close, the top bar shows only the title.", "code": "
\n \n

Static content.

\n \n
" }, { "title": "Your own buttons", "description": "Your buttons sit after Regenerate and before Close.", "code": "
\n Export}>\n

Panel body.

\n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-canvas-panel/", "markdownUrl": "https://lkb00.github.io/tattva/docs/canvas-panel.md" }, { "id": "app-shell", "name": "AppShell", "level": "template", "since": "0.5", "aka": [ "layout", "app layout", "sidebar layout", "scaffold", "frame" ], "category": "screens", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "narrow screen", "note": "Below the medium breakpoint the sidebar rail is hidden and only the main area shows.", "source": "documented" } ], "summary": "The outer frame of a screen: a narrow side panel and one main area.", "description": "AppShell is the frame around every screen. It puts an optional side panel on the left and one main area on the right, and fills the height it is given. On small screens a Menu button opens the side panel in a sheet, so it stays reachable. Keep navigation in the side panel so the main area stays free for the work.", "purpose": "The frame around every screen: a narrow side panel for navigation and one main area for the work. The side panel stays narrow so it never competes with the main area.", "useFor": [ "The outer frame of any app screen.", "A screen with past chats or navigation in a side panel.", "A full-width screen with no side panel: leave rail out." ], "notFor": [ { "text": "Splitting the main area into chat and work side by side", "use": "split-canvas-template" }, { "text": "Spacing content inside a section", "use": "stack" } ], "whenToUse": [ "Put navigation and the user card in the side panel so the main area stays calm.", "Give the frame a space with a set height.", "Put a template (HomeTemplate, ThreadTemplate) inside it.", "Check how it looks without the side panel, since it is hidden on small screens." ], "avoid": [ "Do not put important actions only in the side panel. It is hidden on narrow screens.", "Do not add a third column. Use SplitCanvasTemplate inside the main area instead.", "Do not put an AppShell inside another AppShell." ], "accessibility": [ "The side panel is an area named \"Sidebar\" and the main area is the page's main area, so screen reader users can jump between them.", "On small screens the side panel is hidden from sight and from screen readers.", "Inside a docs preview the two areas become plain boxes, so the host page keeps one main area." ], "accessibilityYouDo": [ "Give people another way to reach navigation on small screens, since the side panel is hidden there.", "Use one AppShell per page. Do not put one inside another.", "Put a template such as ThreadTemplate inside it, which adds the page's top heading." ], "onPhone": [ "Below the md breakpoint the sidebar moves into a side sheet that opens from a Menu button above the main area. Use menuLabel to rename that button.", "The main area takes the full width and can shrink without overflowing.", "The shell is as tall as its parent, so give the parent a height; use the dynamic viewport height so phone browser bars are counted." ], "importPath": "import { AppShell } from \"./index\"", "sourcePath": "src/templates/AppShell.tsx", "props": [ { "name": "rail", "type": "ReactNode", "required": false, "default": null, "description": "Left sidebar content such as a conversation list and user card. Rendered in an aside with 272px width from md up. Below md it opens from a Menu button in a left side sheet." }, { "name": "menuLabel", "type": "string", "required": false, "default": "Menu", "description": "Name of the button that opens the rail on a phone." }, { "name": "children", "type": "ReactNode", "required": true, "default": null, "description": "The main column. Rendered inside main as a flex column, so children can use flex-1 and min-h-0." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Merged onto the root. Use it to fix a height such as h-160 for previews. By default the shell fills its container." } ], "variantsHint": {}, "tokens": [ "--bg", "--fg", "w-68 rail width" ], "related": [ "home-template", "thread-template", "split-canvas-template" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Side panel and main area", "description": "The frame fills the space around it, so give that space a height. Make the window narrow and the side panel disappears.", "code": "
\n {}} onNew={() => {}} />}>\n
Main content goes here.
\n \n
" }, { "title": "Without a side panel", "description": "With no side panel, the main area takes the full width. The studio page uses this form.", "code": "
\n \n
Full-width main column.
\n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-app-shell/", "markdownUrl": "https://lkb00.github.io/tattva/docs/app-shell.md" }, { "id": "home-template", "name": "HomeTemplate", "level": "template", "since": "0.5", "aka": [ "home page layout", "landing layout" ], "category": "screens", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [], "summary": "The first screen of a new conversation: one greeting and one tray, centered.", "description": "HomeTemplate centers a heading, one block of content and an optional note in a narrow column. Use it for a new conversation, where nothing should compete with the greeting. The content block answers the headline, usually a Tray with a Composer at the bottom.", "purpose": "The screen before a conversation starts. One greeting and one block of content sit in a narrow centered column, so nothing competes with getting started.", "useFor": [ "A new chat, before the first message.", "A landing screen whose greeting is answered by a Tray with a message box.", "Showing the AI notice right under the starting point." ], "notFor": [ { "text": "A conversation that has already started", "use": "thread-template" }, { "text": "A screen with several sections or dashboards" } ], "whenToUse": [ "Use it only for a new conversation, before the first message.", "Keep one heading and one block of content.", "Put the Composer inside the Tray so they share one width.", "Place it inside AppShell, which gives it the height to center in." ], "avoid": [ "Do not add more sections below the tray. Anything extra competes with the greeting.", "Do not use it once a conversation has started. Switch to ThreadTemplate.", "Do not make it wider. The narrow column keeps lines easy to read." ], "accessibility": [ "The title bar holds the page's top heading, \"New chat\" unless you change it.", "The content scrolls when it is taller than the screen.", "Reading order matches what people see: title, greeting, content, note." ], "accessibilityYouDo": [ "Use HeroHeading for the greeting, so screen readers can find it as a heading.", "Set header to name the screen if \"New chat\" is not right.", "Decide which control gets focus first, usually the message box." ], "onPhone": [ "The content sits at the top on a phone and is centred vertically from the md breakpoint up.", "Side padding is 1rem and the content column is capped at 48rem, so it fills the screen on a phone.", "The area scrolls on its own when the content is taller than the screen." ], "importPath": "import { HomeTemplate } from \"./index\"", "sourcePath": "src/templates/HomeTemplate.tsx", "props": [ { "name": "heading", "type": "ReactNode", "required": true, "default": null, "description": "The greeting. Use HeroHeading." }, { "name": "children", "type": "ReactNode", "required": true, "default": null, "description": "The block that answers the headline, usually a Tray with its Composer as footer." }, { "name": "footnote", "type": "ReactNode", "required": false, "default": null, "description": "A quiet line under the content, for example AIDisclosure." } ], "variantsHint": {}, "tokens": [ "max-w-read", "space-y-8", "px-4 py-10" ], "related": [ "app-shell", "thread-template", "tray" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Greeting, tray and AI notice", "description": "A greeting, a tray with one row and a message box, and the AI notice below.", "code": "
\n \n } footnote={}>\n {}} />}>\n \n \n \n \n
" }, { "title": "Empty placeholders", "description": "The same layout with plain placeholders, showing what goes where.", "code": "
\n \n Heading slot} footnote={

Footnote slot

}>\n
Children slot
\n \n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-home-template/", "markdownUrl": "https://lkb00.github.io/tattva/docs/home-template.md" }, { "id": "thread-template", "name": "ThreadTemplate", "level": "template", "since": "0.5", "aka": [ "chat layout", "chat page layout" ], "category": "screens", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [], "summary": "A conversation that scrolls, with the message box fixed at the bottom.", "description": "ThreadTemplate has an optional title row, a scrolling conversation and a message box that stays at the bottom. The conversation and message box share one width, so text and input line up. It needs a parent that stacks things top to bottom, such as the main area of AppShell.", "purpose": "A conversation that scrolls, with the message box fixed at the bottom. Both share one width, so the text people read and the box they type in line up.", "useFor": [ "Any chat once the first message is sent.", "A running workflow shown as a conversation, with checklists and approval requests.", "A screen with a title bar and controls such as Share." ], "notFor": [ { "text": "A new chat before the first message", "use": "home-template" }, { "text": "Work that should stay in view beside the chat", "use": "split-canvas-template" } ], "whenToUse": [ "Place it directly inside AppShell so it fills the main area.", "Wrap messages in MessageList so screen readers announce new ones.", "Use it for workflows too. It can hold a checklist, steps and approval requests.", "Use the note for the AI notice so it stays close to the input." ], "avoid": [ "Do not put it in a space with no set height. The conversation cannot scroll and the message box will not stay at the bottom.", "Do not put the message box inside the conversation. It would scroll away.", "Do not give the conversation a different width. The shared width keeps text and input lined up." ], "accessibility": [ "The title bar holds the page's top heading.", "The message box sits outside the scrolling area, so it never scrolls away.", "Reading order goes title, conversation, message box, note." ], "accessibilityYouDo": [ "Wrap messages in MessageList, so screen readers hear new ones. The template announces nothing.", "Pass a header. Without one, the page's top heading is empty.", "Place it inside AppShell, which supplies the main area." ], "onPhone": [ "Side padding is 1rem on a phone and 1.5rem from the sm breakpoint, and the column is capped at 48rem.", "The messages scroll in their own area while the composer stays at the bottom.", "The composer area adds the bottom safe area to its padding, so it clears the home bar on a phone." ], "importPath": "import { ThreadTemplate } from \"./index\"", "sourcePath": "src/templates/ThreadTemplate.tsx", "props": [ { "name": "header", "type": "ReactNode", "required": false, "default": null, "description": "Optional title row above the thread. Rendered in a 56px header element." }, { "name": "children", "type": "ReactNode", "required": true, "default": null, "description": "The conversation or workflow body. Scrolls inside a max-w-3xl column." }, { "name": "composer", "type": "ReactNode", "required": true, "default": null, "description": "The input, pinned to the bottom in the same column width as the body." }, { "name": "footnote", "type": "ReactNode", "required": false, "default": null, "description": "Rendered under the composer, for example AIDisclosure." } ], "variantsHint": {}, "tokens": [ "max-w-3xl", "--fg-muted (header)", "px-4 sm:px-6 gutters" ], "related": [ "app-shell", "home-template", "split-canvas-template", "message-list", "composer" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "A conversation with a message box", "description": "The title sits above the conversation. Messages scroll while the message box stays put.", "code": "
\n \n {}} />} footnote={}>\n \n Draft a welcome email for new customers.\n Here is a short draft you can adapt.\n \n \n \n
" }, { "title": "Empty placeholders", "description": "With no title, the content starts at the top. Anything can fill the conversation, not only messages.", "code": "
\n \n Composer slot
}>\n
Thread body
\n \n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-thread-template/", "markdownUrl": "https://lkb00.github.io/tattva/docs/thread-template.md" }, { "id": "split-canvas-template", "name": "SplitCanvasTemplate", "level": "template", "since": "0.5", "aka": [ "split layout", "canvas layout", "two pane layout" ], "category": "screens", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [], "summary": "Chat or controls on the left, and the thing you are making on the right.", "description": "SplitCanvasTemplate splits the main area into two columns: a left side for chat or controls and a right side for the work. On smaller screens they stack, with the work below. The left side scrolls on its own. Use it when the result should stay in view while the person keeps working.", "purpose": "Splits the main area in two: chat or controls on the left, the thing being made on the right. The work stays in view while the person keeps changing it.", "useFor": [ "Editing a document or code with the assistant beside it.", "A studio with the prompt and options on the left and the chosen draft on the right.", "Any screen where the result must stay visible while people work." ], "notFor": [ { "text": "A plain chat with no lasting result", "use": "thread-template" }, { "text": "A new chat before the first message", "use": "home-template" } ], "whenToUse": [ "Put a CanvasPanel on the right so it fills the height.", "Use it when the result should stay in view while the person makes changes.", "Keep the controls for making things on the left.", "Check the stacked layout on small screens, where the canvas comes after the left side." ], "avoid": [ "Do not use it for plain chat. ThreadTemplate is the right frame.", "Do not put lasting content on the left and short-lived content on the canvas. The canvas is for the thing being made.", "Do not set fixed heights on the sides. The template handles overflow itself." ], "accessibility": [ "The two sides are named areas, \"Conversation\" and \"Canvas\" by default.", "The left side comes first in reading order, which matches the stacked layout on small screens.", "The title bar holds the page's top heading." ], "accessibilityYouDo": [ "Rename the sides with primaryLabel and canvasLabel when they hold something other than a chat and a canvas.", "Pass a header. Without one, the page's top heading is empty.", "Tell people when the canvas changes because of something they did on the left. The template does not." ], "onPhone": [ "Below the lg breakpoint the conversation and the canvas stack in one column, conversation first, and the page scrolls as one.", "The stacked canvas is at least 22.5rem tall; from lg up the two sit side by side and scroll separately.", "Side padding is 1rem on a phone and 1.5rem from sm." ], "importPath": "import { SplitCanvasTemplate } from \"./index\"", "sourcePath": "src/templates/SplitCanvasTemplate.tsx", "props": [ { "name": "primary", "type": "ReactNode", "required": true, "default": null, "description": "Left column: the conversation or controls. Wrapped in a section named by primaryLabel (default Conversation) that scrolls and spaces its children by 24px." }, { "name": "canvas", "type": "ReactNode", "required": true, "default": null, "description": "Right column: the artifact that outlives a single message, usually CanvasPanel. Wrapped in a section named by canvasLabel (default Canvas). Stacks under primary on narrow screens." }, { "name": "primaryLabel", "type": "string", "required": false, "default": "\"Conversation\"", "description": "Accessible name for the left region. Change it when the column holds controls rather than a chat." }, { "name": "canvasLabel", "type": "string", "required": false, "default": "\"Canvas\"", "description": "Accessible name for the right region." } ], "variantsHint": {}, "tokens": [ "gap-4 / p-4", "grid-cols 5fr / 6fr at lg", "min-h-90 canvas on small screens" ], "related": [ "app-shell", "thread-template", "canvas-panel" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "A prompt and a canvas", "description": "A document on the right. On a narrow screen the two sides stack.", "code": "
\n \n {}} />}\n canvas={\n \n {\"# Launch announcement\\n\\nA calmer way to build with AI.\"}\n \n }\n />\n \n
" }, { "title": "Empty placeholders", "description": "Each side has a name for screen readers. The defaults are Conversation on the left and Canvas on the right, and both can be renamed.", "code": "
\n \n Primary slot
}\n canvas={
Canvas slot
}\n />\n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-split-canvas-template/", "markdownUrl": "https://lkb00.github.io/tattva/docs/split-canvas-template.md" }, { "id": "home-page", "name": "HomePage", "level": "page", "since": "0.5", "aka": [ "landing page", "start page" ], "category": "screens", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [], "summary": "The first screen: a headline backed up by the list of tasks right below it.", "description": "HomePage is what a person sees before any conversation starts. The headline says how many tasks need them, and the tray below lists those tasks with amber dots. The message box sits in the same tray, with a small tag that shows what the assistant can see. Nothing else is on screen.", "purpose": "A worked example of the first screen. The headline says how many tasks need the person, and the tray right below lists them, so the claim and the proof sit together.", "useFor": [ "A starting point to copy for your own landing screen.", "Seeing how AppShell, HomeTemplate, Tray and Composer fit together.", "Checking where attention dots and the AI notice go." ], "notFor": [ { "text": "Dropping into a product as it is, since it holds sample data" }, { "text": "A landing screen built with your own content", "use": "home-template" } ], "whenToUse": [ "Copy it as a starting point and replace the sample rows with real tasks.", "Keep the headline true to the tray. The count in the heading should match the rows below.", "Use amber only for rows that need a person.", "Keep the message box at the bottom of the tray." ], "avoid": [ "Do not add navigation cards or promo blocks around the tray.", "Do not list tasks that need nothing from the person under \"Needs you\".", "Do not drop the page into your app as it is. It contains sample data." ], "accessibility": [ "Screen readers find a side panel named \"Sidebar\" and one main area.", "The headline types itself out once, shows whole when people turn off motion in their system settings, and screen readers always get the full text.", "Rows that need a person show an amber dot, read as \"Needs attention\", beside written detail.", "Rows are buttons. In the message box, Enter sends and Shift and Enter add a new line." ], "accessibilityYouDo": [ "Give each real task a detail that says what is needed, not just the amber dot.", "Give people a way to reach the side panel on small screens." ], "onPhone": [ "The sidebar opens from a Menu button in a side sheet on a phone.", "The greeting, the task list and the composer stack in one column.", "The page is 45rem tall at most and never taller than the phone screen height." ], "importPath": "import { HomePage } from \"./index\"", "sourcePath": "src/pages/HomePage.tsx", "props": [ { "name": "(none)", "type": "-", "required": false, "default": null, "description": "This page takes no props. It is a reference composition with sample content, meant to be copied and adapted." } ], "variantsHint": {}, "tokens": [ "--bg", "--surface-sunken (tray)", "--attention (dots)", "--lime (send)" ], "related": [ "thread-page", "workflow-page", "studio-page" ], "composedOf": [ "app-shell", "home-template", "hero-heading", "ai-disclosure", "tray-row", "context-chip", "tray", "composer" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Full page", "description": "The whole screen at a fixed height. The headline types itself out once.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-home-page/", "markdownUrl": "https://lkb00.github.io/tattva/docs/home-page.md" }, { "id": "thread-page", "name": "ThreadPage", "level": "page", "since": "0.5", "aka": [ "chat page", "conversation page" ], "category": "screens", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "streaming", "note": "Sending a message streams the reply, shows Stop on the composer and holds back sources and feedback until it finishes.", "source": "documented" } ], "summary": "A full answer with the assistant's thinking, the steps it took, sources and feedback.", "description": "ThreadPage shows one full reply from the assistant. The reply appears as it is written, after a thinking section and a card showing the step it took. It ends with how sure the assistant is, its sources, message actions and a feedback bar. Those only appear once the reply is finished, so the page does not jump while people read. Suggestion chips offer follow-ups, and the send button becomes Stop while the reply is being written.", "purpose": "A worked example of one full answer: thinking, a step the assistant took, the reply as it is written, then sources and feedback. The extras wait until the reply ends, so the page does not jump.", "useFor": [ "A starting point for a research or question-and-answer screen.", "Seeing the order of thinking, steps, answer, sources and feedback.", "Seeing how Stop, streaming text and follow-up suggestions work together." ], "notFor": [ { "text": "A long task with approvals and steps", "use": "workflow-page" }, { "text": "A tool that makes images or drafts", "use": "studio-page" } ], "whenToUse": [ "Copy the order: thinking, steps taken, answer, then how sure it is, sources and actions.", "Show the extras only when the reply is finished.", "Put source numbers in the reply so they link to the source cards.", "Show follow-up suggestions after the last reply, and hide them while a reply is being written." ], "avoid": [ "Do not show feedback or actions while the reply is still being written.", "Do not put the message box inside the scrolling conversation. ThreadTemplate keeps it at the bottom.", "Do not use the sample reply in your real product. Swap in your own." ], "accessibility": [ "New messages are read out politely. The reply being written is marked busy, then says \"Response complete\" once.", "The blinking cursor is hidden from screen readers.", "Before words arrive, the typing indicator is read as \"Assistant is thinking\".", "Sources are a numbered list of links, and the [1] markers in the reply link to them.", "Stop replaces Send while the reply is written, and works from the keyboard." ], "accessibilityYouDo": [ "Keep streaming on the reply in step with your real stream, and turn it off when it ends." ], "onPhone": [ "The sidebar opens from a Menu button in a side sheet on a phone, and the page shows the conversation.", "Messages, sources and the composer fit one column, and the composer stays at the bottom while the messages scroll.", "The page is 45rem tall at most and never taller than the phone screen height. The composer area clears the bottom safe area." ], "importPath": "import { ThreadPage } from \"./index\"", "sourcePath": "src/pages/ThreadPage.tsx", "props": [ { "name": "(none)", "type": "-", "required": false, "default": null, "description": "This page takes no props. It is a reference composition with sample content, meant to be copied and adapted." } ], "variantsHint": {}, "tokens": [ "--surface-sunken (user bubble)", "--lime", "--success (confidence)", "--border" ], "related": [ "home-page", "workflow-page", "studio-page" ], "composedOf": [ "app-shell", "thread-template", "ai-disclosure", "typing-indicator", "message", "message-actions", "thinking-block", "tool-call-card", "feedback-bar", "confidence-indicator", "suggestion-chips", "composer", "markdown", "message-list", "source-list" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Full page", "description": "The reply is written when the page loads. Press Stop to interrupt it, or send a message to start another.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-thread-page/", "markdownUrl": "https://lkb00.github.io/tattva/docs/thread-page.md" }, { "id": "workflow-page", "name": "WorkflowPage", "level": "page", "since": "0.5", "aka": [ "agent page", "workflow" ], "category": "screens", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "decided", "note": "After Approve or Deny is chosen, a line below the prompt states the decision.", "source": "documented" } ], "summary": "A task in progress, shown as a conversation: heading, checklist, approval request and steps.", "description": "WorkflowPage shows a long task as a conversation. A heading and a status line open the page. A checklist shows who still owes a reply, with finished work folded into one line. An approval request holds the next action until a person says yes. A step list shows where the task is overall. The message box stays at the bottom, so a person can still ask a question while the task waits.", "purpose": "A worked example of a long task shown as a conversation. Open items, the decision that needs a person and overall progress stack in one column, and the message box stays for questions.", "useFor": [ "A starting point for tasks that wait on people, such as chasing documents.", "Seeing how Checklist, ApprovalPrompt and StepTimeline fit in a thread.", "Showing how to confirm a decision with a short message." ], "notFor": [ { "text": "A plain question and answer", "use": "thread-page" }, { "text": "One list of everything waiting for the person across tasks", "use": "approval-inbox" } ], "whenToUse": [ "Use the conversation layout so follow-up questions stay possible.", "Put the request that needs a person where it is easy to spot, between the checklist and the step list.", "Say what will be sent, to whom and when in the approval request.", "Confirm the outcome of a decision with a message, as the page does.", "Keep the status line under the heading in step with the checklist." ], "avoid": [ "Do not mark work in progress as needing attention. Amber means a person has to act.", "Do not list finished items one by one. Fold them into one summary line.", "Do not ask for approval without a Deny option." ], "accessibility": [ "The approval request is announced as an alert dialog named after its action.", "After a choice, a status message says \"Decision: Approved\" or \"Decision: Denied\", and screen readers hear it.", "Rows that need attention show a dot, read as \"Needs attention\", with written status.", "The step list tells screen readers which step is current and the state of each step." ], "accessibilityYouDo": [ "Move focus to the approval request if it appears after the page has loaded. The page does not do this.", "Tell people when a step changes state. The step list does not announce it." ], "onPhone": [ "The sidebar opens from a Menu button in a side sheet on a phone, and the page shows the workflow in one column.", "The approval buttons keep their size and have a 44px tap area on touch screens. The checklist rows are not tappable.", "The page is 45rem tall at most and never taller than the phone screen height. The composer area clears the bottom safe area." ], "importPath": "import { WorkflowPage } from \"./index\"", "sourcePath": "src/pages/WorkflowPage.tsx", "props": [ { "name": "(none)", "type": "-", "required": false, "default": null, "description": "This page takes no props. It is a reference composition with sample content, meant to be copied and adapted." } ], "variantsHint": {}, "tokens": [ "--attention / --warning-soft", "--success (steps)", "--border (checklist rules)", "font-serif heading" ], "related": [ "home-page", "thread-page", "studio-page" ], "composedOf": [ "app-shell", "thread-template", "ai-disclosure", "badge", "context-chip", "checklist", "approval-prompt", "step-timeline", "composer" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Full page", "description": "Approve or deny the reminder to see the decision message appear under the request.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-workflow-page/", "markdownUrl": "https://lkb00.github.io/tattva/docs/workflow-page.md" }, { "id": "studio-page", "name": "StudioPage", "level": "page", "since": "0.5", "aka": [ "studio", "creative workspace" ], "category": "screens", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "generating", "note": "Pressing Generate shows two options plus two shimmering placeholder tiles for about two seconds.", "source": "documented" } ], "summary": "A creative studio: write a prompt and see options on the left, the one you pick on the right.", "description": "StudioPage is for tools that make something, not just reply in chat. The left side has a prompt box and a grid of options. Placeholder tiles keep the grid steady while options load. The right side shows the chosen draft, with its version history. Only a narrow icon rail sits at the edge, so the two columns get almost the full width.", "purpose": "A worked example of a tool that makes things. The prompt and options sit on the left and the chosen draft with its versions on the right, so people compare and refine without losing their place.", "useFor": [ "A starting point for an image, design or writing studio.", "Seeing how PromptBox, VariantGrid and CanvasPanel fit in a SplitCanvasTemplate.", "Seeing loading slots and a version switcher work together." ], "notFor": [ { "text": "A plain question and answer", "use": "thread-page" }, { "text": "A long task with approvals", "use": "workflow-page" } ], "whenToUse": [ "Use it when people refine something and compare options.", "Reserve placeholder tiles so the grid keeps its layout while options load.", "Keep the draft on the canvas, where it stays visible while the prompt changes.", "Label AI-made content with the AI badge." ], "avoid": [ "Do not use it for plain questions and answers. Use the thread page.", "Do not hide version history. People expect to go back after making new options.", "Do not show more than a few options per round. The grid is made for four." ], "accessibility": [ "The two sides are named \"Make options\" and \"Draft\" for screen readers.", "The options are a group of choices with one Tab stop. Arrow keys move and pick, and the picked one shows a check mark.", "While busy, the Generate button reads \"Generating…\".", "The version buttons are named \"Previous version\" and \"Next version\", and the draft also says which version is shown in text.", "On narrow screens the two sides stack, with the draft after the options." ], "accessibilityYouDo": [ "Announce when new options are ready. The grid and the prompt box do not.", "Give each option a label that describes it, not just a letter.", "Announce version changes if people need to hear them." ], "onPhone": [ "The sidebar opens from a Menu button in a side sheet on a phone, and below the lg breakpoint the options and the draft stack in one column that scrolls as one.", "The draft panel is at least 22.5rem tall when stacked, so the user scrolls down past the options to reach it.", "The page is 45rem tall at most and never taller than the phone screen height." ], "importPath": "import { StudioPage } from \"./index\"", "sourcePath": "src/pages/StudioPage.tsx", "props": [ { "name": "(none)", "type": "-", "required": false, "default": null, "description": "This page takes no props. It is a reference composition with sample content, meant to be copied and adapted." } ], "variantsHint": {}, "tokens": [ "--surface", "--border", "--lime (Generate)", "--shadow-md (canvas)" ], "related": [ "home-page", "thread-page", "workflow-page" ], "composedOf": [ "app-shell", "split-canvas-template", "prompt-box", "variant-grid", "canvas-panel", "markdown", "ai-badge" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Full page", "description": "Click Generate to see the busy state and placeholder tiles, then switch versions at the top of the canvas.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-studio-page/", "markdownUrl": "https://lkb00.github.io/tattva/docs/studio-page.md" }, { "id": "model-picker", "name": "ModelPicker", "level": "molecule", "since": "0.5", "aka": [ "model selector", "model switcher", "model dropdown" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "open", "note": "Pressing the trigger opens a panel of model options; choosing one closes it.", "source": "documented" }, { "name": "option disabled", "note": "Set disabled on a model, or list its id in limit.limitedIds, to dim it and make it unselectable.", "source": "documented" }, { "name": "limit notice", "note": "Pass limit to show a note at the top of the panel saying why some models are unavailable and which one is used instead.", "source": "documented" }, { "name": "routed", "note": "When the chosen model has auto set and routedId is passed, the trigger shows via the routed model and the panel says who answered.", "source": "documented" }, { "name": "keyboard", "note": "Arrow keys, Home and End move between enabled models and select the one reached.", "source": "documented" }, { "name": "focus", "note": "The trigger and the model options show a focus ring on keyboard focus.", "source": "documented" } ], "summary": "A small button that opens a list for choosing how the assistant answers, with optional thinking time and limit messages.", "description": "ModelPicker shows the current choice on a small button. Opening it lists the options, each with a name, a one-line description and an optional tag. An optional switch below sets how long the assistant thinks. When Auto is picked, the button can show which option actually answered. When a limit is reached, those options are turned off, a line explains why and names the one used instead.", "purpose": "A compact button that opens a short list of ways the assistant can answer, each with a one-line description. It stays honest about what happened: it names the option that answered when Auto chose, and says why an option is off when a limit is reached.", "useFor": [ "Letting people choose between a few answer modes, such as Fast and Thinking.", "Showing which option actually answered when Auto is picked.", "Explaining that a limit was reached and naming the option used instead.", "Setting how long the assistant thinks, with the optional switch." ], "notFor": [ { "text": "Turning tools such as web search on or off", "use": "tool-menu" }, { "text": "Two or three choices that should always be visible", "use": "segmented-control" }, { "text": "A usage limit that needs its own message", "use": "rate-limit-notice" } ], "whenToUse": [ "Write a description that says when to choose each option.", "Whenever Auto is picked, show which option answered.", "Name the replacement when a limit is reached.", "Keep option names short enough to fit the button." ], "avoid": [ "Do not hide an option behind Auto with no way to pick it directly.", "Do not remove turned-off options. Show them with the reason.", "Do not use it for settings that are not a single choice. Use Switch or checkboxes." ], "accessibility": [ "The options are a group of single choices named by the label, and screen readers hear which one is picked.", "Arrow keys move and pick, Home and End jump to the ends, and options that are off are skipped. Tab stops on one option only.", "The button says the label before the current choice and tells screen readers whether the list is open. On open, the cursor goes to the picked option, and Escape closes the list and returns to the button.", "Options that are off stay visible, with the reason written above the list.", "The list opens on the other side if it would run off the screen, and stays inside the screen edges." ], "accessibilityYouDo": [ "Write a label that names what is being chosen, such as Model or Mode. Screen readers use it for the button and the list.", "When a limit is reached, write the reason in plain words and say when it resets, if you know." ], "onPhone": [ "The trigger keeps its 32px height and has a 44px tap area on touch screens. It shortens a long model name with an ellipsis.", "On a phone the panel opens as a bottom sheet with a backdrop. On wider screens it is an anchored popover 20rem wide, never wider than the screen minus 2rem.", "Each model row and the thinking time options have a 44px tap area on touch screens." ], "importPath": "import { ModelPicker } from \"./index\"", "sourcePath": "src/molecules/ModelPicker.tsx", "props": [ { "name": "models", "type": "ModelOption[]", "required": true, "default": null, "description": "Options with id, name, optional description, badge, auto and disabled." }, { "name": "value", "type": "string", "required": false, "default": null, "description": "Selected id. Omit for uncontrolled use." }, { "name": "defaultValue", "type": "string", "required": false, "default": null, "description": "Initial id when uncontrolled. Defaults to the first model." }, { "name": "onChange", "type": "(id: string) => void", "required": false, "default": null, "description": "Called when an enabled option is chosen." }, { "name": "label", "type": "string", "required": false, "default": "\"Model\"", "description": "Accessible name for the trigger, the panel and the radio group." }, { "name": "routedId", "type": "string", "required": false, "default": null, "description": "Id of the model that answered. Shown only while the selected option has auto set." }, { "name": "routedText", "type": "(modelName: string) => string", "required": false, "default": "Answered by {name}", "description": "Builds the line that names the answering model." }, { "name": "effortOptions", "type": "SegmentOption[]", "required": false, "default": null, "description": "Choices for the thinking time control. Omit to hide it." }, { "name": "effortValue", "type": "string", "required": false, "default": null, "description": "Selected effort. Omit for uncontrolled use." }, { "name": "defaultEffort", "type": "string", "required": false, "default": null, "description": "Initial effort when uncontrolled. Defaults to the first option." }, { "name": "onEffortChange", "type": "(value: string) => void", "required": false, "default": null, "description": "Called when the effort changes." }, { "name": "effortLabel", "type": "string", "required": false, "default": "\"Thinking time\"", "description": "Visible label and group name for the effort control." }, { "name": "limit", "type": "ModelLimit", "required": false, "default": null, "description": "Puts the picker in the limit-reached state: reason, limitedIds and fallbackId." }, { "name": "fallbackText", "type": "(modelName: string) => string", "required": false, "default": "Continuing on {name}.", "description": "Builds the line that names the fallback model." }, { "name": "align", "type": "\"start\" | \"end\"", "required": false, "default": "\"start\"", "description": "Horizontal alignment of the panel." }, { "name": "side", "type": "\"bottom\" | \"top\"", "required": false, "default": "\"bottom\"", "description": "Side of the trigger the panel opens on." }, { "name": "triggerExtra", "type": "ReactNode", "required": false, "default": null, "description": "Content placed after the model name on the chip." } ], "variantsHint": { "align": [ "start", "end" ], "side": [ "bottom", "top" ] }, "tokens": [ "--surface", "--surface-sunken", "--surface-raised", "--border", "--fg-muted", "--shadow-lg", "--radius-control" ], "related": [ "segmented-control", "popover", "rate-limit-notice" ], "composedOf": [ "popover", "segmented-control", "badge" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Modes with thinking time", "description": "An Auto option, two fixed options and a Standard or Extended switch.", "code": "" }, { "title": "Auto picks for you", "description": "Auto is picked and Thinking answered. The button says so and the list repeats it.", "code": "" }, { "title": "Usage limit reached", "description": "Thinking is turned off, the reason is shown and the replacement is named. Fast can still be picked.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-model-picker/", "markdownUrl": "https://lkb00.github.io/tattva/docs/model-picker.md" }, { "id": "tool-chip", "name": "ToolChip", "level": "molecule", "since": "0.5", "aka": [ "tool toggle", "enabled tool" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "removable", "note": "Pass onRemove to show a small remove button on the right.", "source": "documented" }, { "name": "hover", "note": "The remove button gets a soft background under the pointer.", "source": "documented" }, { "name": "focus", "note": "The remove button shows a focus ring on keyboard focus.", "source": "documented" }, { "name": "truncated", "note": "A long label is cut off with an ellipsis.", "source": "documented" } ], "summary": "A small tag in the message box showing a tool that is on, with a Remove button.", "description": "ToolChip shows one tool that is turned on, such as Web search. It has an optional icon, the tool name and a Remove button. The button is named Remove plus the tool name, so a row of tags is clear to a screen reader. Leave out the remove option for a tool that is locked on.", "purpose": "Shows one tool that is switched on, such as Web search, right by the message box. People can see what the assistant will use and remove it in one step.", "useFor": [ "Each tool that is turned on for the next message.", "A tool that is locked on, shown without a Remove button." ], "notFor": [ { "text": "Files or images attached to a message", "use": "attachment-chip" }, { "text": "Choosing which tools to turn on", "use": "tool-menu" }, { "text": "Showing what the chat is about", "use": "context-chip" } ], "whenToUse": [ "Show a tag for every tool that is on, next to the text box.", "Use the same icon as the tool has in ToolMenu.", "Keep labels to one or two words." ], "avoid": [ "Do not use it for attached files. Use AttachmentChip.", "Do not show a tag for a tool that is off.", "Do not take away the button unless there is another way to turn the tool off." ], "accessibility": [ "The Remove button is a real button named after the tool, such as \"Remove Web search\".", "The icon is hidden from screen readers. The tool name carries the meaning.", "A clear outline shows when the Remove button has keyboard focus.", "After Remove, keyboard focus moves to the next tag, else the previous one, else the message box, so it never falls to the top of the page. Pass focusAfterRemove to choose another place." ], "accessibilityYouDo": [ "Set removeLabel when you translate, so the button name matches the language of the page." ], "onPhone": [ "The chip is at least 32px tall and shortens a long label with an ellipsis, so it never grows wider than its container.", "On touch screens the remove button keeps its size and has a 44px tap area, so the chip stays the same size." ], "importPath": "import { ToolChip } from \"./index\"", "sourcePath": "src/molecules/ToolChip.tsx", "props": [ { "name": "label", "type": "string", "required": true, "default": null, "description": "Tool name. Also used in the remove button name." }, { "name": "icon", "type": "ReactNode", "required": false, "default": null, "description": "Leading icon. Decorative." }, { "name": "onRemove", "type": "() => void", "required": false, "default": null, "description": "Shows the remove button and handles its press." }, { "name": "removeLabel", "type": "string", "required": false, "default": "Remove {label}", "description": "Overrides the remove button name." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the chip." } ], "variantsHint": {}, "tokens": [ "--surface-sunken", "--border", "--fg", "--fg-muted", "--surface-hover", "--radius-control" ], "related": [ "tool-menu", "context-chip", "attachment-chip" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Tags you can remove", "description": "Pressing Remove takes the tag away.", "code": "const [tools, setTools] = useState([\"Web search\", \"Deep research\"]);\n\n
\n {tools.map((t) => (\n }\n onRemove={() => setTools((l) => l.filter((x) => x !== t))} />\n ))}\n {tools.length === 0 && No tools on.}\n
" }, { "title": "A tag that stays", "description": "With no remove option there is no button. Use it when the tool is locked on.", "code": "} />" } ], "pageUrl": "https://lkb00.github.io/tattva/component-tool-chip/", "markdownUrl": "https://lkb00.github.io/tattva/docs/tool-chip.md" }, { "id": "tool-menu", "name": "ToolMenu", "level": "organism", "since": "0.5", "aka": [ "tools menu", "plugins menu", "tool picker" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "open", "note": "Pressing the plus button opens a menu with Attach, Tools and Connectors groups.", "source": "documented" }, { "name": "item disabled", "note": "Set disabled on an item to dim it and stop clicks.", "source": "documented" }, { "name": "tool on", "note": "A tool with checked true shows a check mark and stays in the menu when pressed.", "source": "documented" }, { "name": "connector status", "note": "Set status on a connector to show short text such as Connected on its right.", "source": "documented" }, { "name": "empty group", "note": "A group with no items is left out of the menu.", "source": "documented" } ], "summary": "The plus menu by the message box, with ways to attach things, tools you can switch on, and connected apps.", "description": "ToolMenu is a plus button that opens a menu with three sections. Attach and Connectors items do something and close the menu. Tools have a check mark and stay open when toggled, so several can be on. The cursor moves to the first item when it opens, and arrow keys, Home and End move between items. Tab closes the menu. If the menu would run off the screen, it opens on the other side.", "purpose": "The plus button by the message box that gathers everything you can add to a message: files, tools and connected apps. Tools keep the menu open when switched, so several can be turned on in one go.", "useFor": [ "Attaching a file or a photo to a message.", "Turning tools such as web search or deep research on and off.", "Picking a connected app as a source." ], "notFor": [ { "text": "Choosing how the assistant answers", "use": "model-picker" }, { "text": "Settings that belong on a settings page" }, { "text": "Moving around the site" } ], "whenToUse": [ "Keep the menu open when a tool is toggled so several can be switched on.", "Use short status words for connected apps, such as Connected.", "Show every tool that is on as a ToolChip by the message box, so people can see and remove it without opening the menu." ], "avoid": [ "Do not put settings that belong in a settings page into the menu.", "Do not use it as a site menu.", "Do not leave out the check mark. A tool without one looks like a button that does something." ], "accessibility": [ "It is a real menu. Tool rows are check items that tell screen readers whether they are on.", "On open, the cursor moves to the first available item. Arrow keys wrap around, Home and End jump, and items that are off are skipped.", "Escape closes the menu and returns to the plus button. Tab closes it and moves on through the page.", "Each section is a group named by its heading, and the heading is not read twice.", "The plus button is named by the label, and the menu opens on the other side if it would run off the screen." ], "accessibilityYouDo": [ "Pass checked for every tool from your own state, because screen readers read it out." ], "onPhone": [ "On a phone the menu opens as a bottom sheet, because it is a menu; the sheet scrolls if the list is long.", "Every row is at least 44px tall on touch screens.", "Labels and descriptions are cut off with an ellipsis, so keep them short.", "Choosing an attach or connector row closes the sheet, while turning a tool on or off keeps it open." ], "importPath": "import { ToolMenu } from \"./index\"", "sourcePath": "src/organisms/ToolMenu.tsx", "props": [ { "name": "attach", "type": "ToolMenuAction[]", "required": false, "default": "[]", "description": "Attach items with id, label, icon, description and disabled." }, { "name": "tools", "type": "ToolMenuTool[]", "required": false, "default": "[]", "description": "Tool items. Each has a checked boolean owned by the parent." }, { "name": "connectors", "type": "ToolMenuConnector[]", "required": false, "default": "[]", "description": "Connector items with an optional status text." }, { "name": "onAttach", "type": "(id: string) => void", "required": false, "default": null, "description": "Called when an attach item is chosen." }, { "name": "onToggle", "type": "(id: string, checked: boolean) => void", "required": false, "default": null, "description": "Called with the new checked value when a tool is chosen." }, { "name": "onConnector", "type": "(id: string) => void", "required": false, "default": null, "description": "Called when a connector item is chosen." }, { "name": "labels", "type": "{ attach?: string; tools?: string; connectors?: string }", "required": false, "default": "Attach, Tools, Connectors", "description": "Section headings." }, { "name": "label", "type": "string", "required": false, "default": "\"Add to message\"", "description": "Name of the trigger button and the menu." }, { "name": "align", "type": "\"start\" | \"end\"", "required": false, "default": "\"start\"", "description": "Horizontal alignment of the panel." }, { "name": "side", "type": "\"bottom\" | \"top\"", "required": false, "default": "\"top\"", "description": "Side of the button the panel opens on. Top suits a composer at the bottom of the page." } ], "variantsHint": { "align": [ "start", "end" ], "side": [ "bottom", "top" ] }, "tokens": [ "--surface-raised", "--border", "--surface-hover", "--fg-muted", "--shadow-lg" ], "related": [ "tool-chip", "popover", "composer" ], "composedOf": [ "popover", "button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Menu with tags", "description": "Switching a tool on or off updates its check and adds or removes its tag next to the button.", "code": " }, { id: \"image\", label: \"Add a photo\", icon: }]}\n tools={tools.map((t) => ({ ...t, checked: !!on[t.id] }))}\n connectors={[{ id: \"drive\", label: \"Google Drive\", status: \"Connected\" }]}\n onToggle={(id, checked) => setOn((s) => ({ ...s, [id]: checked }))}\n/>" }, { "title": "Tools only", "description": "Sections with nothing in them are left out.", "code": ", checked: true }]} />" } ], "pageUrl": "https://lkb00.github.io/tattva/component-tool-menu/", "markdownUrl": "https://lkb00.github.io/tattva/docs/tool-menu.md" }, { "id": "attachment-chip", "name": "AttachmentChip", "level": "molecule", "since": "0.5", "aka": [ "attachment", "file chip", "uploaded file" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "status", "note": "Set with the status prop.", "source": "prop" } ], "summary": "A tag for an attached file or image, with name, size, upload progress, an error with Retry, and Remove.", "description": "AttachmentChip shows one attached file by the message box. It has a thumbnail or icon, the file name and size. While uploading it shows a progress bar and a percentage. If the upload fails, it shows the problem in red with a Retry button. Remove is always there and is named after the file.", "purpose": "Shows one file attached to a message, with its upload state. Progress, failure and the way out are all visible, so people know whether the file will be sent.", "useFor": [ "A file or image attached in the message box.", "An upload in progress, with a bar and a percentage.", "An upload that failed, with the reason and a Retry button." ], "notFor": [ { "text": "A tool that is switched on", "use": "tool-chip" }, { "text": "Showing what the chat is about", "use": "context-chip" } ], "whenToUse": [ "Say what went wrong and what the person can do.", "Keep Remove available while uploading so a person can cancel.", "Use a real thumbnail for images when you have one." ], "avoid": [ "Do not use amber for a failed upload. Use red with a Retry button.", "Do not show progress without a visible percentage.", "Do not use it for tools. Use ToolChip." ], "accessibility": [ "While uploading, the bar is a meter named \"Uploading\" plus the file name, and screen readers read the percentage.", "The percentage and the error are written in words, so color is not the only clue.", "Retry and Remove are buttons named after the file, such as \"Remove q3-planning.pdf\".", "The default file and image icons are hidden from screen readers.", "When an upload finishes or fails, screen readers hear it: the file name and \"uploaded\", or the file name and the error. Nothing is read when the chip first appears.", "After Remove, keyboard focus moves to the next attachment, else the previous one, else the message box. Pass focusAfterRemove to choose another place." ], "accessibilityYouDo": [ "Keep any thumbnail you pass decorative, with an empty text alternative, because the file name is already shown.", "Set readyMessage and errorMessage when you translate." ], "onPhone": [ "The chip is 16rem wide but shrinks to fit a narrower container.", "A long file name is cut off with an ellipsis, and the full name is only in a title tip that does not show on touch, so show the full name elsewhere if it matters.", "The Retry and remove buttons keep their size and have a 44px tap area on touch screens." ], "importPath": "import { AttachmentChip } from \"./index\"", "sourcePath": "src/molecules/AttachmentChip.tsx", "props": [ { "name": "name", "type": "string", "required": true, "default": null, "description": "File name. Truncated with the full name in the title." }, { "name": "size", "type": "string", "required": false, "default": null, "description": "Display size such as 2.4 MB." }, { "name": "kind", "type": "\"file\" | \"image\"", "required": false, "default": "\"file\"", "description": "Chooses the default icon." }, { "name": "thumbnail", "type": "ReactNode", "required": false, "default": null, "description": "Replaces the default icon." }, { "name": "status", "type": "\"ready\" | \"uploading\" | \"error\"", "required": false, "default": "\"ready\"", "description": "Which state to show." }, { "name": "progress", "type": "number", "required": false, "default": "0", "description": "Upload progress from 0 to 100." }, { "name": "errorMessage", "type": "string", "required": false, "default": "\"Upload failed\"", "description": "Text shown in the error state." }, { "name": "onRetry", "type": "() => void", "required": false, "default": null, "description": "Shows Retry in the error state." }, { "name": "onRemove", "type": "() => void", "required": false, "default": null, "description": "Shows the remove button." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the chip." } ], "variantsHint": { "kind": [ "file", "image" ], "status": [ "ready", "uploading", "error" ] }, "tokens": [ "--surface", "--surface-sunken", "--border", "--danger", "--danger-fg", "--fg-muted", "--radius-card" ], "related": [ "tool-chip", "meter", "composer" ], "composedOf": [ "meter", "button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Ready, uploading and failed", "description": "All three states together. Retry on the failed one makes it ready.", "code": " {}} />\n {}} />\n" }, { "title": "Your own thumbnail", "description": "Use any picture, such as a preview of the image.", "code": "} />" } ], "pageUrl": "https://lkb00.github.io/tattva/component-attachment-chip/", "markdownUrl": "https://lkb00.github.io/tattva/docs/attachment-chip.md" }, { "id": "voice-panel", "name": "VoicePanel", "level": "organism", "since": "0.5", "aka": [ "voice mode", "voice chat", "call screen", "voice session" ], "category": "voice", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "status", "note": "Set with the state prop.", "source": "prop" } ], "summary": "A voice conversation (VoiceSession) on the shared AI disc, with every mic, turn and connection state in words, captions, and separate Mute, Hold and End.", "description": "VoicePanel, also exported as VoiceSession, runs a spoken conversation with the assistant. It is built on AIPresence, so voice uses the same AI disc as the rest of the product. It has fifteen states, from connecting, listening and speaking to on hold, muted, mic blocked, reconnecting and ended, and each one is written in words. Mute, Hold and End are separate controls, with End set apart in a danger outline. Push-to-talk turns the main control into Hold to talk, with slide off to cancel. Mic blocked and no mic are amber, because the person must act. Every older VoicePanel prop still works.", "purpose": "Shows a live voice conversation so that nothing depends on hearing the audio or seeing the animation: the state is in words, the mic state is always visible, and captions carry what was said.", "useFor": [ "A spoken conversation with the assistant, hands-free or push-to-talk.", "A support call where the assistant checks something and says so while it works.", "Telling people the mic is blocked, the call is on hold, or the connection is coming back.", "A voice session that may share the camera or the screen." ], "notFor": [ { "text": "Typing a message", "use": "composer" }, { "text": "Showing the assistant is getting ready to reply in text", "use": "typing-indicator" }, { "text": "Reviewing a finished call as an operator", "use": "call-record" } ], "whenToUse": [ "Keep captions on by default, and keep the transcript after the call.", "Say what the assistant is doing when it works, such as Checking your order, and show it on screen too.", "Keep Mute, Hold and End as three different things.", "Use the footer to say why it is reconnecting and what people can do." ], "avoid": [ "Do not rely on the disc alone to show the state, and do not give it a face.", "Do not fill silence with fake breaths or filler words. Say One moment, checking.", "Do not use amber for Live or Reconnecting. Amber is only for mic blocked or no mic.", "Do not make End a primary button next to Mute, and do not remove Mute or End to save space." ], "accessibility": [ "There is one polite status region (the disc's). It announces each state change once, never caption words.", "The disc is hidden from screen readers. The words and the captions carry the information.", "Simple captions are a role=\"log\" that can be reached by keyboard and scrolled. It does not read new captions out.", "Mute, Camera, Share screen and Hold to talk report whether they are on with aria-pressed, and their names stay the same.", "Keys work while focus is inside the panel and never while typing in a field: Space held to talk, M to mute, Esc to interrupt. End has no key.", "The person's own mic level is three neutral bars, never lime. Lime is the AI disc only.", "When people turn off motion in their system settings, the disc is drawn still for each state and the state text stays." ], "accessibilityYouDo": [ "Keep the captions filled from your speech service, so people who cannot hear can still follow.", "Pass muted, and the camera and screen state, from your own state, so each button reports whether it is on.", "Stop the microphone and the call in onEnd. Stop the assistant's audio within a moment in onInterrupt.", "In micBlocked and noMic, give onTypeInstead a real text route. Every voice flow needs one.", "Never restart the camera or screen sharing yourself after a lock. Wait for the person to press Turn camera on.", "When a screen reader is running, offer push-to-talk so the assistant does not hear the reader." ], "onPhone": [ "The panel fills the width up to 32rem and its padding shrinks a step below 640px. Place it in a full-height Sheet for the phone layout.", "The main control is 56px tall. Every other button has a 44px tap area on touch screens.", "End sits on the far right, away from Mute, in a danger outline, so it is not pressed by mistake.", "Camera and Share screen show only their icons below 640px; their names stay for screen readers.", "The disc shrinks from large to medium once captions appear, so captions get the middle of the screen.", "Hold to talk ignores scrolling and the long-press menu, and sliding a finger off it cancels.", "Key hints hide on touch screens." ], "importPath": "import { VoicePanel } from \"./index\"", "sourcePath": "src/organisms/VoicePanel.tsx", "props": [ { "name": "state", "type": "\"connecting\" | \"ready\" | \"listening\" | \"userSpeaking\" | \"thinking\" | \"working\" | \"speaking\" | \"interrupted\" | \"muted\" | \"held\" | \"reconnecting\" | \"micBlocked\" | \"noMic\" | \"ended\" | \"error\"", "required": true, "default": null, "description": "Current state. Drives the disc, the words and which controls show." }, { "name": "stateLabels", "type": "Partial>", "required": false, "default": null, "description": "Overrides the visible text for any state." }, { "name": "inputMode", "type": "\"handsFree\" | \"pushToTalk\"", "required": false, "default": "\"handsFree\"", "description": "Push-to-talk turns the main control into Hold to talk." }, { "name": "onInputModeChange", "type": "(mode: \"handsFree\" | \"pushToTalk\") => void", "required": false, "default": null, "description": "Shows a Hands-free / Push to talk switch when given." }, { "name": "onTalkStart", "type": "() => void", "required": false, "default": null, "description": "Push-to-talk: the person started holding." }, { "name": "onTalkEnd", "type": "(cancelled: boolean) => void", "required": false, "default": null, "description": "Push-to-talk: the person let go. cancelled is true when they slid off first." }, { "name": "captions", "type": "VoiceCaption[] | ReactNode", "required": false, "default": "[]", "description": "Simple captions (id, speaker, text), or your own node such as LiveCaptions." }, { "name": "speakerLabels", "type": "{ you: string; assistant: string }", "required": false, "default": "You, Assistant", "description": "Names shown before each simple caption." }, { "name": "emptyCaptions", "type": "string", "required": false, "default": null, "description": "Text shown when there are no captions." }, { "name": "muted", "type": "boolean", "required": false, "default": null, "description": "Pressed state of Mute. Defaults to true when state is muted." }, { "name": "onMutedChange", "type": "(muted: boolean) => void", "required": false, "default": null, "description": "Called by Mute and by the M key." }, { "name": "onHold", "type": "() => void", "required": false, "default": null, "description": "Shows Hold. Nothing is heard or said until Resume." }, { "name": "onResume", "type": "() => void", "required": false, "default": null, "description": "Called by Resume in the held state." }, { "name": "onEnd", "type": "() => void", "required": false, "default": null, "description": "Called by End. End has no key." }, { "name": "onInterrupt", "type": "() => void", "required": false, "default": null, "description": "Shows Interrupt while speaking, and makes Esc stop the assistant." }, { "name": "inputLevel", "type": "number", "required": false, "default": null, "description": "Mic level 0 to 1. Moves the disc while listening and fills the neutral level bars on Mute." }, { "name": "outputLevel", "type": "number", "required": false, "default": null, "description": "Assistant level 0 to 1. Moves the disc while speaking. Ignored under reduced motion." }, { "name": "workingLabel", "type": "string", "required": false, "default": null, "description": "Text for the working state, such as Checking your calendar." }, { "name": "onMicRetry", "type": "() => void", "required": false, "default": null, "description": "Allow microphone (blocked) or Check again (no mic)." }, { "name": "onTypeInstead", "type": "() => void", "required": false, "default": null, "description": "Type instead, in the blocked and no mic states." }, { "name": "media", "type": "{ camera?: \"on\" | \"off\" | \"stoppedBySystem\"; screen?: \"on\" | \"off\" | \"stoppedBySystem\" }", "required": false, "default": null, "description": "Camera and screen state. stoppedBySystem shows a notice with a button to turn it on again." }, { "name": "cameraOn", "type": "boolean", "required": false, "default": null, "description": "Pressed state of Camera, when you do not pass media." }, { "name": "onCameraChange", "type": "(on: boolean) => void", "required": false, "default": null, "description": "Shows the Camera toggle when provided." }, { "name": "screenSharing", "type": "boolean", "required": false, "default": null, "description": "Pressed state of Share screen, when you do not pass media." }, { "name": "onScreenChange", "type": "(on: boolean) => void", "required": false, "default": null, "description": "Shows the Share screen toggle when provided. onScreenShareChange is the older name." }, { "name": "elapsed", "type": "string", "required": false, "default": null, "description": "Time since the start, such as 02:14. Shown, never announced." }, { "name": "usage", "type": "ReactNode", "required": false, "default": null, "description": "Minutes or credits used, such as a compact UsageMeter." }, { "name": "disclosure", "type": "ReactNode", "required": false, "default": null, "description": "Who is talking and whether it is recorded." }, { "name": "footer", "type": "ReactNode", "required": false, "default": null, "description": "Content under the state, such as a connection hint." }, { "name": "showKeyHints", "type": "boolean", "required": false, "default": "true", "description": "Shows Esc, M and Space hints on screens with a fine pointer." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the panel." } ], "variantsHint": { "state": [ "connecting", "ready", "listening", "userSpeaking", "thinking", "working", "speaking", "interrupted", "muted", "held", "reconnecting", "micBlocked", "noMic", "ended", "error" ], "inputMode": [ "handsFree", "pushToTalk" ] }, "tokens": [ "--lime", "--surface", "--surface-sunken", "--border", "--border-strong", "--warning-soft", "--warning-fg", "--danger", "--danger-fg", "--danger-soft", "--radius-card", "--dur-fast", "--dur-base", "--dur-slow" ], "related": [ "ai-presence", "composer", "typing-indicator", "message-queue", "call-record" ], "composedOf": [ "ai-presence", "button", "kbd", "segmented-control" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Every state", "description": "Pick a state, or use the buttons: Mute, Hold then Resume, Interrupt while speaking (or Esc), and End. Keys work while focus is inside the panel.", "code": " setState(\"held\")}\n onResume={() => setState(\"listening\")}\n onInterrupt={() => setState(\"interrupted\")}\n onEnd={() => setState(\"ended\")}\n onMicRetry={askForMic}\n onTypeInstead={openChat}\n cameraOn={camera}\n onCameraChange={setCamera}\n workingLabel=\"Checking your order\"\n inputLevel={micLevel}\n outputLevel={voiceLevel}\n elapsed=\"02:14\"\n disclosure={Shop assistant · AI · Recorded}\n captions={captions}\n/>" }, { "title": "Push to talk", "description": "Hold the button, or hold Space, while you talk. Slide off the button before letting go to cancel. Switch to Hands-free to listen all the time.", "code": " setState(\"userSpeaking\")}\n onTalkEnd={(cancelled) => cancelled ? setState(\"ready\") : send()}\n muted={muted}\n onMutedChange={setMuted}\n onEnd={end}\n captions={[]}\n/>" }, { "title": "Mic blocked, on hold, camera stopped", "description": "Mic blocked is amber with Allow microphone and Type instead, because the person must act. On hold dims the disc. The camera notice is calm and waits for a press.", "code": "\n" }, { "title": "Older VoicePanel props", "description": "Code written for the first VoicePanel keeps working: state, captions, muted, onMutedChange and onEnd.", "code": " {}}\n captions={[\n { id: \"1\", speaker: \"you\", text: \"What should I pack for two days in Lisbon?\" },\n { id: \"2\", speaker: \"assistant\", text: \"Pack layers and comfortable shoes. The hills are steep.\" },\n ]}\n/>" } ], "pageUrl": "https://lkb00.github.io/tattva/component-voice-panel/", "markdownUrl": "https://lkb00.github.io/tattva/docs/voice-panel.md" }, { "id": "message-queue", "name": "MessageQueue", "level": "organism", "since": "0.5", "aka": [ "queued messages", "pending messages" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "empty", "note": "With no items, the list is replaced by the emptyText message.", "source": "documented" }, { "name": "first or last", "note": "The move up button is disabled on the first message and move down on the last.", "source": "documented" }, { "name": "shortcut hint", "note": "Pass sendNowShortcut to show a key hint on the first message's Send now button.", "source": "documented" }, { "name": "focus", "note": "Every button in a row shows a focus ring on keyboard focus.", "source": "documented" } ], "summary": "Messages sent while the assistant is busy, with Send now, reorder and delete.", "description": "MessageQueue lists messages a person sent while the assistant was busy. Each one has a dashed outline and muted text until it runs. A header explains the difference between waiting in line and steering, and you can change that text. Each message has Send now, move up, move down and delete. Your app keeps the order. An empty message shows when the list is empty.", "purpose": "Holds messages a person sent while the assistant was still busy. They look pending, with a dashed outline and muted text, so nobody mistakes them for messages already sent.", "useFor": [ "Messages typed while the assistant is working on an earlier one.", "Letting people send a waiting message now, move it, or delete it before it runs." ], "notFor": [ { "text": "Messages that have been sent", "use": "message-list" }, { "text": "The steps the assistant plans to take", "use": "plan-card" } ], "whenToUse": [ "Show it only while the assistant is working or when messages are waiting.", "Change the header text to match how your product handles waiting and steering.", "Reorder items in your own state when onMove is called. The list does not reorder itself.", "Show the shortcut on Send now only if that shortcut really works in your product." ], "avoid": [ "Do not show waiting messages in the chat as if they were sent.", "Do not expect it to reorder itself. Your app keeps the order.", "Do not hide Delete. People should be able to remove a message before it runs." ], "accessibility": [ "It is a named section, and the waiting messages are a numbered list.", "Every icon button is named with the message's place, such as \"Move message 2 up\". Send now is named with the message text.", "Move up is turned off on the first message, and move down on the last.", "After a move, screen readers hear the new place, such as \"Message moved to position 1 of 3\".", "Waiting messages differ by a dashed outline and muted text, as well as the header and count." ], "accessibilityYouDo": [], "onPhone": [ "Each queued message shows its text on a line that gets cut off, and the buttons wrap below it when the row is too narrow.", "Send now and the move and delete buttons keep their size and have a 44px tap area on touch screens.", "Messages are reordered with the up and down buttons; there is no drag." ], "importPath": "import { MessageQueue } from \"./index\"", "sourcePath": "src/organisms/MessageQueue.tsx", "props": [ { "name": "items", "type": "QueuedMessage[]", "required": true, "default": null, "description": "Queued messages in send order, each with id and text." }, { "name": "onSendNow", "type": "(id: string) => void", "required": false, "default": null, "description": "Called when Send now is pressed on an item." }, { "name": "onMove", "type": "(id: string, direction: \"up\" | \"down\") => void", "required": false, "default": null, "description": "Called to move an item one place. The parent reorders items." }, { "name": "onDelete", "type": "(id: string) => void", "required": false, "default": null, "description": "Called when delete is pressed." }, { "name": "title", "type": "string", "required": false, "default": "\"Queued\"", "description": "Heading and region name." }, { "name": "description", "type": "ReactNode", "required": false, "default": null, "description": "Header copy explaining queue and steering. Has a default sentence that you can replace." }, { "name": "emptyText", "type": "string", "required": false, "default": null, "description": "Text shown when items is empty." }, { "name": "sendNowShortcut", "type": "string", "required": false, "default": null, "description": "Shortcut hint shown on the first item's Send now. Omit to hide." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the region." } ], "variantsHint": {}, "tokens": [ "--surface", "--surface-sunken", "--border", "--border-strong", "--fg-muted", "--fg-subtle", "--radius-card" ], "related": [ "composer", "voice-panel", "kbd" ], "composedOf": [ "button", "badge", "kbd" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "A line you can reorder", "description": "Move, send and delete change the list. Send now removes the message as if it had started.", "code": " setItems((l) => l.filter((m) => m.id !== id))}\n onMove={move}\n onDelete={(id) => setItems((l) => l.filter((m) => m.id !== id))}\n/>" }, { "title": "Nothing waiting", "description": "With no messages, a short note shows instead.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-message-queue/", "markdownUrl": "https://lkb00.github.io/tattva/docs/message-queue.md" }, { "id": "version-pager", "name": "VersionPager", "level": "molecule", "since": "0.5", "aka": [ "branch picker", "response versions", "regenerate pager", "pagination" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "selected", "note": "Set with the current prop.", "source": "prop" } ], "summary": "Previous and next buttons with a count like 1/3, for the versions of one message.", "description": "VersionPager steps through the versions made when a message is edited or written again. Buttons turn off at either end. Screen readers hear the new position. It can show an Edited label and a button to branch off. It starts on the latest version.", "purpose": "Steps through the versions of one message, made by editing it or asking again. The count is small so the message itself stays the focus.", "useFor": [ "A message that was edited, so the earlier wording is still there to look at.", "A reply that was written again, so people can compare the attempts.", "Starting a new chat from one version, with the branch button." ], "notFor": [ { "text": "Going back to an earlier point in a long piece of work", "use": "checkpoint-list" }, { "text": "Switching between an AI suggestion and the person's own edit", "use": "revert-toggle" }, { "text": "A list of saved versions of a document or design", "use": "version-history" } ], "whenToUse": [ "Keep the pager next to the message it belongs to.", "Change the message text with the version so the count and text match.", "Offer a branch button only if your product can start a separate chat." ], "avoid": [ "Do not use it for unrelated messages. It is for versions of one message.", "Do not hide the count. The position is the point of the control.", "Do not move the cursor when the version changes. People should be able to keep clicking." ], "accessibility": [ "Previous and next are named buttons that turn off at the first and last version.", "After each step, screen readers hear the new position, such as \"Version 2 of 3\".", "The visible count is hidden from screen readers so it is not read twice.", "The whole control is a group named \"Message versions\"." ], "accessibilityYouDo": [ "Change the message text when the version changes, so what people hear matches the count.", "Place the pager right after the message it belongs to, so screen reader users know which message it changes." ], "onPhone": [ "The pager wraps onto a second line if the edited label and branch button do not fit.", "The previous and next buttons keep their size and have a 44px tap area on a touch screen.", "Tapping steps one version at a time; there is no swipe, so keep the pager next to the message it changes." ], "importPath": "import { VersionPager } from \"./index\"", "sourcePath": "src/molecules/VersionPager.tsx", "props": [ { "name": "total", "type": "number", "required": true, "default": null, "description": "Number of sibling versions." }, { "name": "current", "type": "number", "required": false, "default": null, "description": "Controlled current version, 1-based." }, { "name": "defaultCurrent", "type": "number", "required": false, "default": "total", "description": "Starting version in uncontrolled mode." }, { "name": "onChange", "type": "(version: number) => void", "required": false, "default": null, "description": "Called with the new 1-based version." }, { "name": "edited", "type": "boolean", "required": false, "default": null, "description": "Shows the edited label." }, { "name": "editedLabel", "type": "string", "required": false, "default": "\"Edited\"", "description": "Text of the edited label." }, { "name": "branchAction", "type": "ReactNode", "required": false, "default": null, "description": "Slot for an action such as Branch from here." }, { "name": "announce", "type": "(current: number, total: number) => string", "required": false, "default": "Version N of M", "description": "Builds the polite announcement." }, { "name": "label", "type": "string", "required": false, "default": "\"Message versions\"", "description": "Accessible name for the group." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the wrapper." } ], "variantsHint": {}, "tokens": [ "--fg-muted", "--surface-sunken", "--border", "--radius-control" ], "related": [ "message-actions", "feedback-bar", "checkpoint-list" ], "composedOf": [ "icon-button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Default", "description": "Starts on the latest version.", "code": "" }, { "title": "Edited, with a branch button", "description": "Use it when your product can start a new chat from this version.", "code": "Branch from here} />" } ], "pageUrl": "https://lkb00.github.io/tattva/component-version-pager/", "markdownUrl": "https://lkb00.github.io/tattva/docs/version-pager.md" }, { "id": "memory-notice", "name": "MemoryNotice", "level": "molecule", "since": "0.5", "aka": [ "memory updated", "saved to memory" ], "category": "trust", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "actions", "note": "Pass onManage or onUndo to show Manage and Undo buttons under the text.", "source": "documented" }, { "name": "dismissible", "note": "Pass onDismiss to show a close button on the right.", "source": "documented" } ], "summary": "A short notice that says what was saved to memory, with Manage, Undo and close.", "description": "MemoryNotice appears when something is saved and says exactly what. Manage opens the memory list and Undo removes the item. Each button shows only if you provide what it does. It looks neutral because nothing needs fixing.", "purpose": "Says exactly what was just saved to memory, at the moment it is saved, so people can check it and take it back. It looks neutral because nothing has gone wrong.", "useFor": [ "Right after the assistant saves something about the person.", "Giving a quick way to undo a save or open the full memory list.", "Confirming a save to one project's memory, with your own title." ], "notFor": [ { "text": "Seeing or editing everything that is remembered", "use": "memory-list" }, { "text": "Telling people that a chat is not being saved", "use": "private-chat-banner" }, { "text": "A warning or error the person must fix", "use": "callout" } ], "whenToUse": [ "Show it right when something is saved, and quote what was saved.", "Make Undo actually remove the item.", "Send Manage to the full memory list." ], "avoid": [ "Do not say only \"Memory updated\". Name what changed.", "Do not use amber. Saving is not something the person must fix.", "Do not keep it on screen after the person closes it." ], "accessibility": [ "It is a polite status message, so screen readers can read it without cutting in.", "The close button has only an icon, so it carries the name \"Dismiss memory notice\".", "Manage, Undo and close are real buttons that work with the keyboard.", "The icon is hidden from screen readers." ], "accessibilityYouDo": [ "Write the saved text in the person's own terms, so it makes sense when heard on its own.", "Move focus to a sensible place after Undo or close removes the notice." ], "onPhone": [ "The notice fills the width, and the text wraps beside the icon.", "Manage and Undo sit under the text and wrap if they do not fit. Each has a 44px tap area on a touch screen.", "The dismiss button stays at the right edge, keeps its size and has a 44px tap area." ], "importPath": "import { MemoryNotice } from \"./index\"", "sourcePath": "src/molecules/MemoryNotice.tsx", "props": [ { "name": "title", "type": "string", "required": false, "default": "\"Memory updated\"", "description": "Heading." }, { "name": "saved", "type": "ReactNode", "required": true, "default": null, "description": "What was saved, in the person's terms." }, { "name": "onManage", "type": "() => void", "required": false, "default": null, "description": "Opens the memory manager. The button is hidden when omitted." }, { "name": "onUndo", "type": "() => void", "required": false, "default": null, "description": "Removes the saved item. The button is hidden when omitted." }, { "name": "onDismiss", "type": "() => void", "required": false, "default": null, "description": "Dismisses the notice. The close button is hidden when omitted." }, { "name": "manageLabel", "type": "string", "required": false, "default": "\"Manage\"", "description": "Label of the manage button." }, { "name": "undoLabel", "type": "string", "required": false, "default": "\"Undo\"", "description": "Label of the undo button." }, { "name": "dismissLabel", "type": "string", "required": false, "default": "\"Dismiss memory notice\"", "description": "Accessible name of the close button." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the wrapper." } ], "variantsHint": {}, "tokens": [ "--surface-sunken", "--border", "--fg-muted", "--radius-card" ], "related": [ "memory-list", "private-chat-banner", "callout" ], "composedOf": [ "button", "icon-button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "With actions", "description": "Undo and close both hide the notice here.", "code": " {}} onUndo={() => setShown(false)} onDismiss={() => setShown(false)} />" }, { "title": "Information only", "description": "With no buttons, the notice only says what was saved.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-memory-notice/", "markdownUrl": "https://lkb00.github.io/tattva/docs/memory-notice.md" }, { "id": "memory-list", "name": "MemoryList", "level": "organism", "since": "0.5", "aka": [ "memories", "saved memories", "memory settings" ], "category": "trust", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "paused", "note": "Turn on the Pause memory switch (or pass paused) to stop saving new memories while keeping existing ones.", "source": "documented" }, { "name": "past chats off", "note": "Turn off the Search past chats switch (or pass searchChats false) to stop replies drawing on earlier conversations.", "source": "documented" }, { "name": "editing", "note": "Pressing the edit button turns that entry into a text box with Save and Cancel; Save is disabled when the text is empty.", "source": "documented" }, { "name": "empty", "note": "With no entries, a dashed box shows emptyState or a default message.", "source": "documented" } ], "summary": "A list of what the assistant remembers. Each item can be edited or deleted. Two switches sit on top.", "description": "MemoryList shows a Pause memory switch and a Search past chats switch above one row for each remembered topic. Each row says where it applies and has Edit and Delete. Your app keeps the data. The empty message can be replaced.", "purpose": "The place where people see, fix and remove what the assistant remembers. The two switches sit on top because they change how memory works for everything below them.", "useFor": [ "A memory page in settings.", "Letting people pause memory, or stop replies drawing on past chats.", "Showing where each memory applies, such as all chats or one project." ], "notFor": [ { "text": "Telling people that one thing was just saved", "use": "memory-notice" }, { "text": "A chat that saves nothing at all", "use": "private-chat-banner" } ], "whenToUse": [ "Show where each memory applies.", "Explain what pausing does to memories already saved.", "Add an undo or a confirm step for delete. The list calls onDelete as soon as the button is pressed." ], "avoid": [ "Do not hide entries behind a search. Show them as a list people can scan.", "Do not rename the switches without saying what they control.", "Do not store anything here. Your app keeps the data." ], "accessibility": [ "Both switches have names and are read as on or off.", "Edit and delete buttons name the memory they act on, such as \"Edit memory: Work\".", "The edit box has a visible label and gets focus when it opens.", "Save is turned off while the edit box is empty.", "After Save or Cancel, keyboard focus returns to that memory's Edit button. After a delete it moves to the next memory (or the previous one, or the empty message), and screen readers hear \"Memory deleted.\"" ], "accessibilityYouDo": [ "Give each memory a topic. Without one, the edit and delete buttons repeat the whole memory text in their names.", "Set deletedMessage when you translate." ], "onPhone": [ "The two switches at the top have a 44px tap area, and their descriptions wrap beside them.", "Each row keeps its edit and delete buttons at the right, each with a 44px tap area on a touch screen, and the memory text wraps in the space left.", "Editing opens a text box that takes focus at once, so the on-screen keyboard appears; the text is 16px so the page does not zoom." ], "importPath": "import { MemoryList } from \"./index\"", "sourcePath": "src/organisms/MemoryList.tsx", "props": [ { "name": "entries", "type": "MemoryEntry[]", "required": true, "default": null, "description": "Items with id, optional topic, text and scope." }, { "name": "onEdit", "type": "(id: string, text: string) => void", "required": false, "default": null, "description": "Called when an edit is saved." }, { "name": "onDelete", "type": "(id: string) => void", "required": false, "default": null, "description": "Called when delete is chosen." }, { "name": "paused", "type": "boolean", "required": false, "default": null, "description": "Controlled state of Pause memory." }, { "name": "defaultPaused", "type": "boolean", "required": false, "default": "false", "description": "Starting state when uncontrolled." }, { "name": "onPausedChange", "type": "(paused: boolean) => void", "required": false, "default": null, "description": "Called when the pause switch changes." }, { "name": "searchChats", "type": "boolean", "required": false, "default": null, "description": "Controlled state of Search past chats." }, { "name": "defaultSearchChats", "type": "boolean", "required": false, "default": "true", "description": "Starting state when uncontrolled." }, { "name": "onSearchChatsChange", "type": "(on: boolean) => void", "required": false, "default": null, "description": "Called when the search switch changes." }, { "name": "emptyState", "type": "ReactNode", "required": false, "default": null, "description": "Replaces the empty message." }, { "name": "pauseLabel", "type": "string", "required": false, "default": "\"Pause memory\"", "description": "Label of the pause switch." }, { "name": "pauseDescription", "type": "string", "required": false, "default": null, "description": "Helper text under the pause label." }, { "name": "searchLabel", "type": "string", "required": false, "default": "\"Search past chats\"", "description": "Label of the search switch." }, { "name": "searchDescription", "type": "string", "required": false, "default": null, "description": "Helper text under the search label." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the wrapper." } ], "variantsHint": {}, "tokens": [ "--surface", "--border", "--border-strong", "--fg-muted", "--radius-field", "--radius-card" ], "related": [ "memory-notice", "private-chat-banner" ], "composedOf": [ "badge", "button", "icon-button", "switch" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Editable list", "description": "Edits and deletes work in this demo.", "code": " setItems(items.map((m) => (m.id === id ? { ...m, text } : m)))}\n onDelete={(id) => setItems(items.filter((m) => m.id !== id))}\n/>" }, { "title": "Nothing remembered", "description": "Change the message shown when the list is empty.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-memory-list/", "markdownUrl": "https://lkb00.github.io/tattva/docs/memory-list.md" }, { "id": "private-chat-banner", "name": "PrivateChatBanner", "level": "molecule", "since": "0.5", "aka": [ "incognito", "temporary chat", "private mode" ], "category": "trust", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "compact", "note": "Set variant to compact for a small pill instead of the full banner.", "source": "documented" }, { "name": "exit", "note": "Pass onExit to show an Exit button (a close icon in the compact form).", "source": "documented" } ], "summary": "A notice that stays visible during a private chat, says how long a copy is kept, and has Exit.", "description": "PrivateChatBanner tells people the chat is private for as long as it lasts. The full version says how long a copy is kept and has an Exit button. The small version is a pill for the top bar. Both look neutral. You write the wording, so it states your real time.", "purpose": "Keeps it clear, for the whole chat, that this chat is private and how long a copy is kept. It looks neutral because a private chat is a choice, not a problem.", "useFor": [ "The top of a private or temporary chat, for as long as it lasts.", "A small pill in the top bar when space is tight.", "Stating your product's real retention time in your own words." ], "notFor": [ { "text": "Confirming that something was saved to memory", "use": "memory-notice" }, { "text": "A warning the person must act on", "use": "callout" } ], "whenToUse": [ "Keep it visible for the whole private chat.", "Use the small pill when space is tight.", "Change the description if your retention time is not 30 days. The default text says a copy may be kept for 30 days." ], "avoid": [ "Do not imply that nothing is stored if a copy is kept.", "Do not use amber. Private mode is a choice, not a problem.", "Do not offer to turn it into a regular chat unless your product can." ], "accessibility": [ "The full banner is a region named by its label, so screen readers can jump to it.", "The small pill's close button has only an icon, and its name includes the mode, such as \"Exit private chat\".", "The state is said in words, not by color or a border alone.", "The ghost icon is hidden from screen readers." ], "accessibilityYouDo": [ "Place the banner before the chat, so screen reader users meet it first. It is not read out when it appears.", "Move focus to a sensible place when Exit ends the private chat." ], "onPhone": [ "The banner fills the width and wraps: the text has a 224px base width, so the Exit button drops to its own line when the row is tight.", "The compact pill stays one line and keeps its desktop height. Its exit button keeps its size and has a 44px tap area on a touch screen." ], "importPath": "import { PrivateChatBanner } from \"./index\"", "sourcePath": "src/molecules/PrivateChatBanner.tsx", "props": [ { "name": "variant", "type": "\"banner\" | \"compact\"", "required": false, "default": "\"banner\"", "description": "Full-width strip or header pill." }, { "name": "label", "type": "string", "required": false, "default": "\"Private chat\"", "description": "Name of the mode." }, { "name": "description", "type": "ReactNode", "required": false, "default": null, "description": "Retention copy. The default says a copy may be kept for 30 days, so change it if your period differs." }, { "name": "onExit", "type": "() => void", "required": false, "default": null, "description": "Leaves the private chat. The action is hidden when omitted." }, { "name": "exitLabel", "type": "string", "required": false, "default": "\"Exit\"", "description": "Label of the banner exit button." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the wrapper." } ], "variantsHint": { "variant": [ "banner", "compact" ] }, "tokens": [ "--surface-sunken", "--border-strong", "--fg-muted", "--radius-control", "--radius-card" ], "related": [ "memory-notice", "memory-list", "callout" ], "composedOf": [ "button", "icon-button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Full banner", "description": "Full width. Says how long a copy is kept.", "code": " {}} />" }, { "title": "Small pill", "description": "Fits in the top bar next to the title.", "code": " {}} />" }, { "title": "Your own wording", "description": "Change the text to match what your product does.", "code": " {}} />" } ], "pageUrl": "https://lkb00.github.io/tattva/component-private-chat-banner/", "markdownUrl": "https://lkb00.github.io/tattva/docs/private-chat-banner.md" }, { "id": "checkpoint-list", "name": "CheckpointList", "level": "organism", "since": "0.5", "aka": [ "checkpoints", "restore points", "snapshots" ], "category": "agents", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "current", "note": "The checkpoint whose id matches currentId shows a Current badge in place of the Rewind button.", "source": "documented" }, { "name": "rewind options", "note": "Pressing Rewind opens the restore choices under that checkpoint.", "source": "documented" }, { "name": "confirm", "note": "Choosing a restore mode shows a plain warning with a Confirm and a Cancel button before anything happens.", "source": "documented" }, { "name": "no files changed", "note": "Restore work only is disabled for a checkpoint where files is 0.", "source": "documented" } ], "summary": "A list of earlier steps you can go back to, with restore and summarize buttons and a confirm step.", "description": "CheckpointList shows each earlier request with how long ago it was and how many files changed. Rewind on a row opens choices: Restore everything, Restore conversation only, Restore work only and Summarize from here. Restores ask for confirmation first. The current step is marked and has no choices. A note area can say what is not covered.", "purpose": "Lets people go back to an earlier step of their work or chat. Restores ask for confirmation inside the row, so people see what they are about to undo.", "useFor": [ "An agent or coding session where each request changes files.", "Undoing the conversation, the work, or both, back to one request.", "Shortening a long chat from one point with Summarize from here." ], "notFor": [ { "text": "Stepping between versions of one message", "use": "version-pager" }, { "text": "Named saves of a document or design", "use": "version-history" }, { "text": "Undoing one AI edit to a short piece of text", "use": "revert-toggle" } ], "whenToUse": [ "Keep the confirm step in the row so the person sees what they are acting on.", "Show the file count so people see what a restore will change.", "Fill in the limitations note when some changes are not tracked, so people know before they restore." ], "avoid": [ "Do not skip the confirm step for the restores.", "Do not use a pop-up window for the confirmation.", "Do not offer choices on the current step. There is nothing to restore." ], "accessibility": [ "The rows are a numbered list, and the current row is marked as the current step for screen readers.", "Rewind tells screen readers whether its choices are open.", "The confirm step is a named group that says what the restore will remove.", "Restore work only is turned off for a step with no changed files.", "Keyboard focus follows the choices: picking a restore moves it to the confirm step, so the warning is read; Cancel returns it to that choice; after a restore or a summary it returns to the row's Rewind button, or to the row itself if it became the current one." ], "accessibilityYouDo": [ "Pass currentId, so screen readers can tell which step is the current one." ], "onPhone": [ "Each row shows the prompt on one line and cuts it off with an ellipsis. The full text is in a title attribute, which a touch screen does not show, so on a phone it is not available.", "Rewind opens the restore choices under the row; they wrap, and every button has a 44px tap area on a touch screen.", "The confirm text and its warning wrap, so the destructive step stays readable on a narrow screen." ], "importPath": "import { CheckpointList } from \"./index\"", "sourcePath": "src/organisms/CheckpointList.tsx", "props": [ { "name": "checkpoints", "type": "Checkpoint[]", "required": true, "default": null, "description": "Rows with id, prompt, time and files. Rendered in the order given." }, { "name": "currentId", "type": "string", "required": false, "default": null, "description": "Id of the current checkpoint. It is marked and has no actions." }, { "name": "onRestore", "type": "(id: string, mode: RestoreMode) => void", "required": false, "default": null, "description": "Called after the person confirms. Mode is everything, conversation or work." }, { "name": "onSummarize", "type": "(id: string) => void", "required": false, "default": null, "description": "Called when Summarize from here is chosen. It has no confirm step." }, { "name": "limitations", "type": "ReactNode", "required": false, "default": null, "description": "Slot under the list for what checkpoints do not cover." }, { "name": "labels", "type": "Partial>", "required": false, "default": null, "description": "Overrides for visible labels." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the wrapper." } ], "variantsHint": {}, "tokens": [ "--surface", "--surface-sunken", "--danger", "--border", "--radius-card" ], "related": [ "version-pager", "context-meter", "checklist" ], "composedOf": [ "badge", "button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Rewind list", "description": "In this demo, restoring moves the marker to the chosen step. A step with no changed files cannot use Restore work only.", "code": " setCurrent(id)}\n limitations=\"Edits made by shell commands are not tracked.\"\n/>" }, { "title": "Your own wording", "description": "Change any visible label.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-checkpoint-list/", "markdownUrl": "https://lkb00.github.io/tattva/docs/checkpoint-list.md" }, { "id": "revert-toggle", "name": "RevertToggle", "level": "molecule", "since": "0.5", "aka": [ "undo", "restore previous", "before after toggle" ], "category": "trust", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "no edit", "note": "Without userValue only the AI value is shown and the switch and revert button are hidden.", "source": "documented" }, { "name": "reverted", "note": "Pressing the revert button switches back to the AI version and announces it to screen readers.", "source": "documented" } ], "summary": "Lets people flip between the AI's suggestion and their own edit, with a way back to the original.", "description": "RevertToggle shows one version at a time and lets people switch between the AI suggestion and their edit. Revert to original goes back to the AI version and tells your app to drop the edit. With no edit, it shows the AI version alone. Screen readers hear which version is showing.", "purpose": "Shows one version of a short text at a time, so people can flip between the AI suggestion and their own edit. The original is kept so they can always go back.", "useFor": [ "A short AI suggestion the person has edited, such as a reply draft or a title.", "Comparing the AI's wording with the person's own before they keep one.", "Dropping an edit and going back to the original suggestion." ], "notFor": [ { "text": "Long text where people need to see exactly what changed", "use": "diff-view" }, { "text": "Several versions of one chat message", "use": "version-pager" } ], "whenToUse": [ "Keep the AI version until the person reverts or discards it.", "Use it for short text where a side-by-side view would be too much.", "Clear the edit in onRevert. The part shows the AI version but does not remove your stored edit." ], "avoid": [ "Do not overwrite the AI version when the person edits.", "Do not use it for long documents. A view that highlights changes fits better.", "Do not show the switch before an edit exists." ], "accessibility": [ "The version switch is a set of choices: arrow keys move between them, and Home and End jump to the ends.", "After each change, screen readers hear \"Showing\" and the version name.", "Revert to original is a normal button.", "With no edit, the switch and button are not shown at all." ], "accessibilityYouDo": [ "Move focus to the text after a revert, because the switch and button go away once the edit is cleared." ], "onPhone": [ "The switch and the Revert button sit on one line and wrap when they do not fit.", "The two switch options keep their size and have a 44px tap area on a touch screen, and their labels do not wrap.", "The value card fills the width, so long text wraps inside it." ], "importPath": "import { RevertToggle } from \"./index\"", "sourcePath": "src/molecules/RevertToggle.tsx", "props": [ { "name": "aiValue", "type": "ReactNode", "required": true, "default": null, "description": "The original AI suggestion." }, { "name": "userValue", "type": "ReactNode", "required": false, "default": null, "description": "The person's edit. Without it only the AI value shows." }, { "name": "value", "type": "\"ai\" | \"user\"", "required": false, "default": null, "description": "Controlled active version." }, { "name": "defaultValue", "type": "\"ai\" | \"user\"", "required": false, "default": "\"user\" when an edit exists", "description": "Starting version when uncontrolled." }, { "name": "onChange", "type": "(value: \"ai\" | \"user\") => void", "required": false, "default": null, "description": "Called when the version changes." }, { "name": "onRevert", "type": "() => void", "required": false, "default": null, "description": "Called when Revert to original is chosen." }, { "name": "aiLabel", "type": "string", "required": false, "default": "\"AI suggestion\"", "description": "Label of the AI option." }, { "name": "userLabel", "type": "string", "required": false, "default": "\"Your edit\"", "description": "Label of the edit option." }, { "name": "revertLabel", "type": "string", "required": false, "default": "\"Revert to original\"", "description": "Label of the revert button." }, { "name": "label", "type": "string", "required": false, "default": "\"Version\"", "description": "Accessible name of the switch." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the wrapper." } ], "variantsHint": { "value": [ "ai", "user" ], "defaultValue": [ "ai", "user" ] }, "tokens": [ "--surface", "--surface-sunken", "--border", "--radius-card" ], "related": [ "version-pager", "feedback-bar" ], "composedOf": [ "segmented-control", "button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "After an edit", "description": "Reverting drops the edit here, and the switch goes away.", "code": " setEdit(undefined)}\n/>" }, { "title": "Starting on the AI version", "description": "Opens on the AI version even when an edit exists.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-revert-toggle/", "markdownUrl": "https://lkb00.github.io/tattva/docs/revert-toggle.md" }, { "id": "context-meter", "name": "ContextMeter", "level": "molecule", "since": "0.5", "aka": [ "context usage", "token meter", "context window meter" ], "category": "numbers", "status": "experimental", "lifecycle": { "stage": "experimental", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "near limit", "note": "At or above summarizeAt a warning line appears, and a Summarize button if onSummarize is passed.", "source": "documented" }, { "name": "summarizing", "note": "Pass summarizing to disable the button and change its text to Summarizing.", "source": "documented" }, { "name": "compacted", "note": "Pass compactionNote to add a check line below the bar saying what was condensed.", "source": "documented" } ], "summary": "Shows how full the chat is, with a Summarize button when it is nearly full.", "description": "ContextMeter shows how full the chat is, as a bar and short text. The assistant can only keep so much of a chat in mind. The bar stays neutral until it nears the limit. Then it turns amber, a line says why, and a Summarize button appears. A marker can show that earlier messages were summarized.", "purpose": "Shows how much of the chat the assistant can still keep in mind. It stays quiet until people can do something, then warns in amber and offers to summarize.", "useFor": [ "A long chat that may reach the limit of what the assistant can hold.", "Offering Summarize when the chat is nearly full.", "Leaving a note after earlier messages have been summarized." ], "notFor": [ { "text": "Credits or a plan allowance", "use": "usage-meter" }, { "text": "A limit that has already been reached", "use": "rate-limit-notice" }, { "text": "A plain bar with no warning text or actions", "use": "meter" } ], "whenToUse": [ "Keep the meter quiet until the person can do something about it.", "Show the reason and the button together with amber.", "Leave a marker after summarizing so the chat history stays honest.", "Pass onSummarize, or the warning appears with nothing to act on." ], "avoid": [ "Do not warn when there is plenty of room. Amber means act now.", "Do not show Summarize unless it works.", "Do not rely on the bar color alone. The text carries the state." ], "accessibility": [ "The bar is a named meter, so screen readers hear its value, such as \"68% of context\".", "The warning is written beside the bar, so it does not rely on color.", "Summarize turns off and reads \"Summarizing\" while a summary runs.", "The bar's grow-in motion stops when people turn off motion in their system settings." ], "accessibilityYouDo": [ "Tell people when summarizing ends. The button label changes, but nothing is read out." ], "onPhone": [ "The meter fills the width, and the amount and the warning share one row.", "The Summarize button appears under the bar when the limit is near, and has a 44px tap area on a touch screen.", "The bar is only 6px tall and carries no tap action, so the amount in text is the part to read." ], "importPath": "import { ContextMeter } from \"./index\"", "sourcePath": "src/molecules/ContextMeter.tsx", "props": [ { "name": "percent", "type": "number", "required": true, "default": null, "description": "Share of the context window in use, 0 to 100." }, { "name": "valueText", "type": "string", "required": false, "default": "\"N% of context\"", "description": "Text beside the bar and the meter's value text." }, { "name": "summarizeAt", "type": "number", "required": false, "default": "85", "description": "Percent at which the bar warns and Summarize appears." }, { "name": "onSummarize", "type": "() => void", "required": false, "default": null, "description": "Called on Summarize. The action stays hidden when omitted." }, { "name": "summarizing", "type": "boolean", "required": false, "default": null, "description": "Disables the action and changes its label while a summary runs." }, { "name": "compactionNote", "type": "string", "required": false, "default": null, "description": "Shows a marker row with this text." }, { "name": "warnText", "type": "string", "required": false, "default": "\"Close to the limit.\"", "description": "Reason shown beside the amber state." }, { "name": "summarizeLabel", "type": "string", "required": false, "default": "\"Summarize\"", "description": "Label of the action." }, { "name": "label", "type": "string", "required": false, "default": "\"Context used\"", "description": "Accessible name of the meter." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the wrapper." } ], "variantsHint": {}, "tokens": [ "--attention", "--attention-fg", "--fg", "--border" ], "related": [ "usage-meter", "checkpoint-list" ], "composedOf": [ "meter", "button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Normal", "description": "Far from the limit, there is no warning and no button.", "code": " {}} />" }, { "title": "Near the limit", "description": "Near the limit, the bar warns and Summarize appears.", "code": " {}} />" }, { "title": "After summarizing", "description": "Leave a marker once the conversation has been shortened.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-context-meter/", "markdownUrl": "https://lkb00.github.io/tattva/docs/context-meter.md" }, { "id": "usage-meter", "name": "UsageMeter", "level": "molecule", "since": "0.5", "aka": [ "quota meter", "usage bar", "progress bar" ], "category": "numbers", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "running low", "note": "When the used share reaches warnAt, the bar warns and a running-low message shows with the optional upgrade slot.", "source": "documented" }, { "name": "not enough", "note": "When estimate is more than remaining, the bar turns attention-coloured and says there is not enough left.", "source": "documented" }, { "name": "estimate", "note": "Pass estimate to show how much this action will use.", "source": "documented" } ], "summary": "How many credits are left, with an optional cost estimate, reset date and upgrade button.", "description": "UsageMeter shows how many credits are left and can say what the next action will cost. It stays neutral until most credits are used or the cost is more than what is left. Then it says why in amber and shows the upgrade button you provide.", "purpose": "Shows how many credits are left and what the next action will cost, before it runs. It warns only when the person may need to act.", "useFor": [ "Before a paid action, to show about how much it will use.", "A plan's remaining allowance, with when it resets.", "Offering an upgrade once credits run low." ], "notFor": [ { "text": "How full the current chat is", "use": "context-meter" }, { "text": "A limit that has been reached and blocks the next request", "use": "rate-limit-notice" } ], "whenToUse": [ "Show the estimate before the action runs.", "Show when the allowance resets.", "Offer the upgrade only when credits run low." ], "avoid": [ "Do not use amber while there is plenty left.", "Do not hide retries that use up credits.", "Do not give an exact estimate you cannot back up. Say about." ], "accessibility": [ "The bar is a named meter that screen readers read as \"N of M credits left\".", "The estimate and the warning are written out, so color is not the only clue.", "The warning says why, such as running low or not enough left for this.", "The bar's grow-in motion stops when people turn off motion in their system settings." ], "accessibilityYouDo": [ "Put a real button or link with a clear name in the upgrade slot.", "Place the meter before the action it estimates, so the cost is heard before the action." ], "onPhone": [ "The meter fills the width, with the amount on the left and the reset time on the right.", "The warning and your upgrade action share a row that wraps. A button gets a 44px tap area by itself. If your upgrade action is a small link, give it the tap class." ], "importPath": "import { UsageMeter } from \"./index\"", "sourcePath": "src/molecules/UsageMeter.tsx", "props": [ { "name": "remaining", "type": "number", "required": true, "default": null, "description": "Credits or quota left." }, { "name": "total", "type": "number", "required": true, "default": null, "description": "Full allowance for the period." }, { "name": "unit", "type": "string", "required": false, "default": "\"credits\"", "description": "Plural unit name used in the text." }, { "name": "estimate", "type": "number", "required": false, "default": null, "description": "Cost of the pending action. Shows This will use about N credits." }, { "name": "resetText", "type": "string", "required": false, "default": null, "description": "Reset time, for example Resets Nov 1." }, { "name": "warnAt", "type": "number", "required": false, "default": "0.8", "description": "Fraction used, 0 to 1, at which the meter warns." }, { "name": "upgrade", "type": "ReactNode", "required": false, "default": null, "description": "Slot for an upgrade action, shown only in the warn state." }, { "name": "warnText", "type": "string", "required": false, "default": null, "description": "Overrides the reason in the warn state." }, { "name": "label", "type": "string", "required": false, "default": "\"Usage\"", "description": "Accessible name of the meter." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the wrapper." } ], "variantsHint": {}, "tokens": [ "--attention", "--attention-fg", "--fg", "--fg-subtle" ], "related": [ "context-meter", "rate-limit-notice" ], "composedOf": [ "meter" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "With an estimate", "description": "Shows the cost before the person confirms an action.", "code": "" }, { "title": "Running low", "description": "When credits run low, the meter explains why and shows the upgrade button.", "code": "Upgrade} />" }, { "title": "Cost is more than what is left", "description": "The warning says so even when usage is moderate.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-usage-meter/", "markdownUrl": "https://lkb00.github.io/tattva/docs/usage-meter.md" }, { "id": "agent-status-icon", "name": "AgentStatusIcon", "level": "atom", "since": "0.5", "aka": [ "status icon", "run status" ], "category": "agents", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "status", "note": "Set with the status prop.", "source": "prop" } ], "summary": "A small icon that shows what an assistant is doing right now, with a different shape for each state.", "description": "AgentStatusIcon shows whether an assistant is working, needs you, is waiting, is done, has failed or has stopped. Each state has its own shape, so you do not need to see color. The working icon spins, and stays still if you turn motion off. Amber is only for \"needs you\", because only then must a person act.", "purpose": "A tiny picture of an assistant's state that still reads in a crowded row. Each state has its own shape so it works without color, and only \"needs you\" is amber, because only then must a person act.", "useFor": [ "Beside a task or run name, to show its state at a glance.", "In a compact header or row where there is no room for words.", "With showLabel on, when there is room to write the state as well." ], "notFor": [ { "text": "A run that people press to open its details", "use": "background-run-chip" }, { "text": "A general label, such as a category or a count", "use": "badge" }, { "text": "Showing how far along one long job is", "use": "generation-progress" } ], "whenToUse": [ "Put the icon next to the task name so they are read together.", "Show the text where there is room, such as a page header.", "Use \"needs you\" only when a person must act." ], "avoid": [ "Don't use it for anything except what an assistant is doing.", "Don't change its color. The color is part of the meaning.", "Don't put the words only in a hover tip." ], "accessibility": [ "Without visible text, screen readers hear the state as the icon's name, such as \"Needs input\".", "With showLabel on, the icon is hidden from screen readers and the words are read once.", "Each state has its own shape, so color is never the only clue.", "The working icon spins, and stops when people turn off motion in their system settings." ], "accessibilityYouDo": [ "Pass label in the person's language when your app is not in English.", "Turn on showLabel instead of writing the state beside the icon yourself, so it is not read twice." ], "onPhone": [ "It is a small icon that keeps its size on a phone, 16px by default.", "With showLabel the words sit beside the icon in 12px text, so the status is not shown by the icon alone.", "It has no tap action, so wrap it in a button if it must open something." ], "importPath": "import { AgentStatusIcon } from \"./index\"", "sourcePath": "src/atoms/AgentStatusIcon.tsx", "props": [ { "name": "status", "type": "\"working\" | \"needs-input\" | \"idle\" | \"completed\" | \"failed\" | \"stopped\"", "required": true, "default": null, "description": "Which state to show. Selects the shape, the tone and the default label." }, { "name": "size", "type": "number", "required": false, "default": "16", "description": "Glyph width and height in px." }, { "name": "label", "type": "string", "required": false, "default": null, "description": "Replaces the default accessible text, for example to translate it." }, { "name": "showLabel", "type": "boolean", "required": false, "default": "false", "description": "Render the label as visible text beside the glyph." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes. With showLabel they go on the wrapper, otherwise on the svg." } ], "variantsHint": { "status": [ "working", "needs-input", "idle", "completed", "failed", "stopped" ] }, "tokens": [ "--attention", "--success", "--danger", "--fg-muted", "--fg-subtle" ], "related": [ "agent-session-list", "task-tree", "spinner", "attention-dot" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "All six states", "description": "Each state has its own shape. The icon has a name for screen readers, so it works alone in a crowded row.", "code": "
\n \n \n \n \n \n \n
" }, { "title": "With words beside it", "description": "Show the text when there is room. A screen reader reads the text once and skips the icon.", "code": "
\n \n \n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-agent-status-icon/", "markdownUrl": "https://lkb00.github.io/tattva/docs/agent-status-icon.md" }, { "id": "permission-mode-switcher", "name": "PermissionModeSwitcher", "level": "molecule", "since": "0.5", "aka": [ "permission mode", "auto approve setting" ], "category": "agents", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "open", "note": "Pressing the trigger opens a list of modes, each with a risk label.", "source": "documented" }, { "name": "locked", "note": "Set lockedReason on a mode to dim it, explain why it is locked and make it unselectable.", "source": "documented" }, { "name": "high risk", "note": "A mode with risk high shows its risk label in the danger colour, plus its warning text if set.", "source": "documented" }, { "name": "keyboard", "note": "Up and down arrows move between modes and the chosen one is announced to screen readers.", "source": "documented" }, { "name": "shortcut hint", "note": "Pass shortcut to show a key hint at the bottom of the list.", "source": "documented" } ], "summary": "A button that always shows how much freedom the assistant has, and lets you change it.", "description": "PermissionModeSwitcher always shows the current mode, and its level of risk, on the button. Opening it lists each mode with a plain description and a risk label. A mode can have a warning, or be locked with a reason, such as a rule set by your admin. Put it below the box where people type.", "purpose": "Keeps the assistant's level of freedom in view at all times, on a button below the box where people type. Opening it lists every mode with what it allows and how risky it is, so nobody changes it by guesswork.", "useFor": [ "Below a chat or task input, to show and change how much the assistant may do without asking.", "Products where an admin may lock some modes and people need to see why.", "Offering a risky mode with a warning written next to it." ], "notFor": [ { "text": "Asking about one specific action", "use": "permission-prompt" }, { "text": "Choosing which model answers", "use": "model-picker" }, { "text": "Switching between two or three equal views", "use": "segmented-control" } ], "whenToUse": [ "Keep the button on screen the whole time, so the mode is never hidden.", "Describe each mode as what the assistant may do without asking.", "Add a warning to the riskiest mode.", "Tell people why a mode is locked and what they can do.", "Pass shortcut only if your app really binds that key." ], "avoid": [ "Don't show risk with only an icon or color. Keep the words.", "Don't hide locked modes. Showing them with a reason explains the limit.", "Don't show a shortcut the app does not have." ], "accessibility": [ "The button says whether the list is open, and names the current mode and its risk.", "The modes work as one set of options: Tab lands on the chosen one and the up and down arrow keys move between them.", "Locked modes are marked unavailable and show the reason in words.", "Screen readers hear the new mode after a change.", "Escape closes the list and returns you to the button." ], "accessibilityYouDo": [ "Write each lockedReason so it says who locked the mode and why." ], "onPhone": [ "The trigger is a pill that keeps its size and has a 44px tap area on a touch screen.", "On a phone the panel opens as a bottom sheet with a backdrop. On wider screens it floats above the trigger and is at most the screen width minus 32px.", "Each mode row is a button with its description visible, so nothing needs hover.", "The keyboard shortcut line is shown on a phone too, so leave the shortcut prop out of phone-only layouts." ], "importPath": "import { PermissionModeSwitcher } from \"./index\"", "sourcePath": "src/molecules/PermissionModeSwitcher.tsx", "props": [ { "name": "modes", "type": "PermissionMode[]", "required": false, "default": "defaultPermissionModes", "description": "Modes in display order. Each has id, label, description, risk (low, medium or high), and optional warning and lockedReason." }, { "name": "value", "type": "string", "required": false, "default": null, "description": "Selected mode id, for controlled use." }, { "name": "defaultValue", "type": "string", "required": false, "default": null, "description": "Initial mode id when uncontrolled. Defaults to the first mode." }, { "name": "onChange", "type": "(id: string) => void", "required": false, "default": null, "description": "Called when the person picks an unlocked mode." }, { "name": "label", "type": "string", "required": false, "default": "\"Permission mode\"", "description": "Name for the trigger text, the popover and the radio group." }, { "name": "shortcut", "type": "string", "required": false, "default": null, "description": "Shortcut shown at the foot of the panel. Pass it only if the app binds it." }, { "name": "shortcutLabel", "type": "string", "required": false, "default": "\"to cycle modes\"", "description": "Text beside the shortcut." }, { "name": "announcePrefix", "type": "string", "required": false, "default": "\"Mode changed to\"", "description": "Start of the polite announcement made after a change." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the wrapper." } ], "variantsHint": {}, "tokens": [ "--surface-raised", "--border", "--danger-fg", "--fg-muted", "--radius-control" ], "related": [ "popover", "segmented-control", "permission-prompt" ], "composedOf": [ "popover", "kbd" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "The five modes", "description": "The five default modes. The riskiest one shows a warning.", "code": "const [mode, setMode] = useState(\"manual\");\n\n" }, { "title": "Locked by your admin", "description": "A locked mode is switched off and says why.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-permission-mode-switcher/", "markdownUrl": "https://lkb00.github.io/tattva/docs/permission-mode-switcher.md" }, { "id": "diff-file-row", "name": "DiffFileRow", "level": "molecule", "since": "0.5", "aka": [ "changed file", "file diff row" ], "category": "agents", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "status", "note": "Set with the state prop.", "source": "prop" }, { "name": "selected", "note": "Set with the selected prop.", "source": "prop" } ], "summary": "One changed file in a review, with how much was added and removed, and buttons to keep or reject it.", "description": "DiffFileRow shows a file name, how many lines were added and removed, and buttons to keep or reject the file. After you choose, it shows a label with an icon and words. Undo puts it back. If you kept some changes in the file and not others, it says Partly kept. DiffView uses it for its file list. You can also use it alone in a short summary.", "purpose": "One line per changed file, so people can see the size of each change and decide on the whole file in one step. After a choice the buttons become a labelled result, so the list shows what is settled.", "useFor": [ "A short list of changed files in a summary, with Keep and Reject for each.", "A file list beside your own display of the changed lines.", "Showing which files are kept, rejected or partly kept after a review." ], "notFor": [ { "text": "Reviewing the changed lines themselves", "use": "diff-view" }, { "text": "A file the person attached to a message", "use": "attachment-chip" } ], "whenToUse": [ "Show both counts, even when one is zero.", "Keep the full file path available, since many files share a name.", "Pass onReset if people should be able to change their mind. Without it, decided rows have no Undo." ], "avoid": [ "Don't show the counts with only color. Keep the plus and minus signs.", "Don't hide Reject behind Keep. Show both until a choice is made.", "Don't drop the file name to save space. Shorten the folder part instead." ], "accessibility": [ "Keep, Reject and Undo include the file path in their names, so screen readers know which file they act on.", "The selected file is marked as the current one for screen readers.", "A decided file shows an icon and words, not only a color. A partly kept file shows a half-filled icon and the words Partly kept.", "The counts use plus and minus signs as well as color, and screen readers hear them as a sentence, such as \"12 lines added, 3 removed\".", "After Keep, Reject or Undo, keyboard focus moves to the file name, which now says the new state, such as \"Kept\"." ], "accessibilityYouDo": [], "onPhone": [ "The file name takes the first line and is cut with an ellipsis, with the Keep and Reject buttons wrapping under it when the row is narrow.", "Tapping the name selects the file, and every button has a 44px tap area on a touch screen.", "The row highlight on hover is only decoration, so selection is shown without hover." ], "importPath": "import { DiffFileRow } from \"./index\"", "sourcePath": "src/molecules/DiffFileRow.tsx", "props": [ { "name": "path", "type": "string", "required": true, "default": null, "description": "File path. The directory part is muted and the file name is emphasised." }, { "name": "added", "type": "number", "required": true, "default": null, "description": "Count of added lines." }, { "name": "removed", "type": "number", "required": true, "default": null, "description": "Count of removed lines." }, { "name": "state", "type": "\"pending\" | \"kept\" | \"rejected\" | \"partial\"", "required": false, "default": "\"pending\"", "description": "Review state. Pending shows the buttons, kept and rejected show a badge, and partial shows a Partly kept badge beside the buttons. DiffView derives partial from the hunks." }, { "name": "selected", "type": "boolean", "required": false, "default": null, "description": "Marks the row as the file currently shown. Sets aria-current on the name button." }, { "name": "onSelect", "type": "() => void", "required": false, "default": null, "description": "Called when the name is chosen." }, { "name": "onKeep", "type": "() => void", "required": false, "default": null, "description": "Called by the Keep button. In DiffView this decides every hunk in the file." }, { "name": "onReject", "type": "() => void", "required": false, "default": null, "description": "Called by the Reject button." }, { "name": "onReset", "type": "() => void", "required": false, "default": null, "description": "Adds an Undo button to decided and partly kept rows." }, { "name": "labels", "type": "{ keep, reject, kept, rejected, partial, undo, lines }", "required": false, "default": null, "description": "Replace the button and badge text, and lines(added, removed), the sentence screen readers hear for the counts." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the row." } ], "variantsHint": { "state": [ "pending", "kept", "rejected", "partial" ] }, "tokens": [ "--success-fg", "--danger-fg", "--surface-sunken", "--surface-hover", "--radius-control", "--radius-card" ], "related": [ "diff-view", "checklist-row", "tray-row" ], "composedOf": [ "badge", "button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Waiting, kept and rejected", "description": "Choose Keep or Reject to see the label. Undo puts the row back.", "code": "const [s, setS] = useState(\"pending\");\n\n setS(\"kept\")} onReject={() => setS(\"rejected\")} onReset={() => setS(\"pending\")} />" }, { "title": "Partly kept", "description": "Some changes in the file are kept and others are not. Keep and Reject still decide the whole file.", "code": "
\n {}} onReject={() => {}} onReset={() => {}} />\n
" }, { "title": "A new file", "description": "A file with nothing removed still shows both counts.", "code": "
\n {}} onReject={() => {}} />\n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-diff-file-row/", "markdownUrl": "https://lkb00.github.io/tattva/docs/diff-file-row.md" }, { "id": "diff-view", "name": "DiffView", "level": "organism", "since": "0.5", "aka": [ "diff viewer", "code diff", "compare changes" ], "category": "agents", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "pending", "note": "A file or change block with no decision yet shows Keep and Reject buttons.", "source": "documented" }, { "name": "kept", "note": "After Keep, the block shows a green Kept badge and an Undo button.", "source": "documented" }, { "name": "rejected", "note": "After Reject, the block shows a red Rejected badge, an Undo button and dimmed lines.", "source": "documented" }, { "name": "partly kept", "note": "A file with some blocks kept and others undecided shows as partly kept in the file list.", "source": "documented" }, { "name": "all reviewed", "note": "When nothing is left to review, the footer says so and Keep all, Reject all and Next file are disabled.", "source": "documented" }, { "name": "empty", "note": "With no files, only the line No changes to review is shown.", "source": "documented" }, { "name": "wide lines", "note": "Long lines scroll sideways inside each block, which can be focused with the keyboard.", "source": "documented" } ], "summary": "Review the changes an assistant made to your files, and keep or reject each one.", "description": "DiffView shows a list of changed files and the changes in the chosen file. Each group of changes has its own Keep and Reject. Each file also has Keep and Reject, which decide all its changes at once. A file is kept when every change is kept, rejected when every change is rejected, and partly kept when it is mixed. Added and removed lines have a plus or minus sign, so you do not need color to tell them apart. A bar at the bottom offers Keep all, Reject all and Next file, and counts the files still to review. Use it when an assistant has edited files and you decide what stays.", "purpose": "The place to decide what stays after an assistant edits files. Files are listed on one side and the chosen file's changes on the other, so people can decide one group of lines, a whole file, or everything at once.", "useFor": [ "Reviewing edits an assistant made before they are saved or shared.", "Letting people keep some changes in a file and reject others.", "Working through many changed files, with a count of how many are left." ], "notFor": [ { "text": "A short summary of changed files without the lines", "use": "diff-file-row" }, { "text": "Showing code that is not a change", "use": "code-block" }, { "text": "Going back to an earlier saved version of the whole work", "use": "version-history" } ], "whenToUse": [ "Show how many files are left, so people know how much remains.", "Give Keep all and Reject all the same visual weight.", "Save people's choices in your app if the review must survive a page reload.", "Show real line numbers so people can find each change." ], "avoid": [ "Don't mark lines with only color. Keep the plus and minus signs.", "Don't offer Keep all without showing how many files it affects. Changes already decided stay as they are.", "Don't use it to compare long paragraphs of writing. It shows lines in a fixed-width font." ], "accessibility": [ "Added and removed lines show a plus or minus sign, and screen readers hear \"Added:\" or \"Removed:\" before the text.", "Line numbers are hidden from screen readers so they do not interrupt the text.", "Every Keep, Reject and Undo button names the change and the file, for example \"Keep hunk 2 in notes/trip-plan.txt\".", "Screen readers hear each choice, and how many files are left to review.", "Each group of lines can be reached with Tab and scrolled sideways, so long lines can be read." ], "accessibilityYouDo": [ "If you translate the labels, also pass hunk, remaining, announceFile, announceHunk and announceAll, because they are spoken in button names and updates." ], "onPhone": [ "Below 768px wide the file list sits above the changes instead of beside them.", "Each block of lines scrolls sideways on its own, because the lines do not wrap, and the two line-number columns use 96px of a phone screen.", "Keep, Reject and Undo buttons keep their size and have a 44px tap area on a touch screen, and the footer buttons wrap onto more rows." ], "importPath": "import { DiffView } from \"./index\"", "sourcePath": "src/organisms/DiffView.tsx", "props": [ { "name": "files", "type": "DiffFile[]", "required": true, "default": null, "description": "Files to review. Each has id, path and hunks. Counts are computed from the hunk lines." }, { "name": "statuses", "type": "Record", "required": false, "default": null, "description": "Review state per file id, for controlled use. Missing ids are pending." }, { "name": "defaultStatuses", "type": "Record", "required": false, "default": null, "description": "Initial states when uncontrolled." }, { "name": "onStatusesChange", "type": "(next: Record) => void", "required": false, "default": null, "description": "Called after any decision at file or hunk level. File states are derived from the hunks, so a mixed file reports \"partial\"." }, { "name": "hunkStatuses", "type": "Record", "required": false, "default": null, "description": "Decision per hunk, by file id then hunk index, for controlled use. Missing entries follow the file's kept or rejected decision, or pending." }, { "name": "defaultHunkStatuses", "type": "Record", "required": false, "default": null, "description": "Initial hunk decisions when uncontrolled." }, { "name": "onHunkStatusesChange", "type": "(next: Record) => void", "required": false, "default": null, "description": "Called after any decision, with the decisions for every hunk." }, { "name": "onHunkChange", "type": "(fileId: string, hunkIndex: number, state: DiffHunkState) => void", "required": false, "default": null, "description": "Called when one hunk's Keep, Reject or Undo is chosen. The index starts at 0." }, { "name": "activeId", "type": "string", "required": false, "default": null, "description": "File whose hunks are shown, for controlled use." }, { "name": "defaultActiveId", "type": "string", "required": false, "default": null, "description": "Initial file when uncontrolled. Defaults to the first file." }, { "name": "onActiveChange", "type": "(id: string) => void", "required": false, "default": null, "description": "Called when the shown file changes." }, { "name": "labels", "type": "DiffViewLabels", "required": false, "default": null, "description": "Replace the visible text, including the remaining-count function, the hunk title function, the keep, reject, kept, rejected, partial and undo words, and announceFile, announceHunk and announceAll, the sentences screen readers hear after each decision." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the outer section." } ], "variantsHint": {}, "tokens": [ "--success-soft", "--success-fg", "--danger-soft", "--danger-fg", "--surface-sunken", "--border", "--radius-card" ], "related": [ "diff-file-row", "checklist", "approval-prompt" ], "composedOf": [ "diff-file-row", "badge", "button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Review two files", "description": "Decide per file, per change, or use the bottom bar. Next file jumps to a file you have not finished.", "code": "" }, { "title": "Review one change at a time", "description": "The first file has two changes. Keep one and reject the other, and the file shows Partly kept.", "code": "// The first file in files has two changes.\n" }, { "title": "Partly reviewed", "description": "Start with one file already decided. The bottom bar shows one file left.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-diff-view/", "markdownUrl": "https://lkb00.github.io/tattva/docs/diff-view.md" }, { "id": "plan-card", "name": "PlanCard", "level": "organism", "since": "0.5", "aka": [ "plan", "agent plan", "proposed plan" ], "category": "agents", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "status", "note": "Set with the state prop.", "source": "prop" } ], "summary": "Shows what the assistant plans to do before it starts, so you can approve or ask for changes.", "description": "PlanCard lays out what the assistant intends to do: a title, numbered steps with a short note each, and an optional time or cost estimate. A label says nothing has changed yet. You approve the plan or ask for a revision. While the plan is open, steps can be edited or removed. Use it when someone should agree to the approach before anything changes.", "purpose": "Shows the steps the assistant intends to take before anything changes, so a person can agree to the approach or ask for another. It does not take your place on the page when it appears, because a plan can wait.", "useFor": [ "Before a task that edits, sends or deletes things, so the person agrees first.", "Letting people edit or remove steps before they approve.", "Showing a time or cost estimate next to the steps." ], "notFor": [ { "text": "A yes or no on one single action", "use": "approval-prompt" }, { "text": "Showing progress through steps that are already running", "use": "step-timeline" }, { "text": "A to-do list people tick off themselves", "use": "checklist" } ], "whenToUse": [ "Show the plan before anything changes, and say so.", "Keep each step's note to one short sentence.", "Give an estimate when you can, in time or cost.", "Let people edit or remove a step while the plan can still change." ], "avoid": [ "Don't show a plan that has already run as if it were still waiting.", "Don't use amber on the card. A plan is not urgent.", "Don't pack a long list of tasks into one step." ], "accessibility": [ "The card is named by its title, and the steps are a numbered list.", "Edit and Remove buttons include the step number and title.", "Screen readers hear when the plan is approved or a revision is requested.", "It does not move your place on the page when it appears.", "The state is written in words, and Approved adds a check mark." ], "accessibilityYouDo": [ "Set headingLevel so the title fits your page outline. It is 3 unless you change it." ], "onPhone": [ "The card has 20px padding, and each step keeps its Edit button and remove icon on the same row as its text, so step text gets narrower when edit tools are on.", "The remove icon and buttons keep their size and have a 44px tap area on a touch screen.", "Approve and Revise wrap under each other if they do not fit on one row." ], "importPath": "import { PlanCard } from \"./index\"", "sourcePath": "src/organisms/PlanCard.tsx", "props": [ { "name": "title", "type": "string", "required": true, "default": null, "description": "Plan title, shown as the heading." }, { "name": "steps", "type": "PlanStep[]", "required": true, "default": null, "description": "Ordered steps. Each has id, title and an optional description." }, { "name": "estimate", "type": "ReactNode", "required": false, "default": null, "description": "Time or cost estimate shown under the title." }, { "name": "state", "type": "\"draft\" | \"awaiting\" | \"approved\" | \"revised\"", "required": false, "default": null, "description": "State, for controlled use." }, { "name": "defaultState", "type": "PlanState", "required": false, "default": "\"awaiting\"", "description": "Initial state when uncontrolled." }, { "name": "onStateChange", "type": "(state: PlanState) => void", "required": false, "default": null, "description": "Called when Approve or Revise changes the state." }, { "name": "onApprove", "type": "() => void", "required": false, "default": null, "description": "Called by Approve." }, { "name": "onRevise", "type": "() => void", "required": false, "default": null, "description": "Called by Revise." }, { "name": "onEditStep", "type": "(id: string) => void", "required": false, "default": null, "description": "Adds an Edit button to each step while the plan is draft or awaiting." }, { "name": "onRemoveStep", "type": "(id: string) => void", "required": false, "default": null, "description": "Adds a Remove button to each step while the plan is draft or awaiting." }, { "name": "readOnlyLabel", "type": "string | null", "required": false, "default": "\"Nothing has changed yet\"", "description": "Read-only badge text. Null hides it. It is hidden once approved." }, { "name": "labels", "type": "PlanCardLabels", "required": false, "default": null, "description": "Replace button text and the state notes." }, { "name": "headingLevel", "type": "2 | 3 | 4 | 5 | 6", "required": false, "default": "3", "description": "Level of the part's own heading, so it fits the page outline." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the section." } ], "variantsHint": { "state": [ "draft", "awaiting", "approved", "revised" ], "headingLevel": [ 2, 3, 4, 5, 6 ] }, "tokens": [ "--surface", "--border", "--surface-sunken", "--radius-card" ], "related": [ "approval-prompt", "step-timeline", "checklist", "permission-prompt" ], "composedOf": [ "badge", "button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Awaiting approval", "description": "The starting state. Approve and Revise work, and the \"nothing has changed\" label shows.", "code": "" }, { "title": "Editable steps", "description": "Each step gets Edit and Remove buttons. They go away once the plan is approved or revised.", "code": " {}}\n onRemoveStep={() => {}}\n/>" }, { "title": "Draft and approved", "description": "A draft keeps the buttons off while the plan is being written. An approved plan hides the \"nothing has changed\" label.", "code": "\n" } ], "pageUrl": "https://lkb00.github.io/tattva/component-plan-card/", "markdownUrl": "https://lkb00.github.io/tattva/docs/plan-card.md" }, { "id": "permission-prompt", "name": "PermissionPrompt", "level": "organism", "since": "0.5", "aka": [ "permission request", "allow deny", "access request" ], "category": "agents", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "status", "note": "Set with the state prop.", "source": "prop" } ], "summary": "Asks you to allow one thing the assistant wants to do, with a choice to always allow it and an optional note.", "description": "PermissionPrompt asks you to allow one thing the assistant wants to do. It shows what the step is, a plain description, the exact thing it will act on, and why it is asking. You can Allow once, Allow always for a clearly named group of things, or Deny. A saved rule lists exactly what it covers. While you are inside the prompt, Esc denies and N opens the note box. ApprovalPrompt is for one clear yes or no. This prompt adds saved choices and a note.", "purpose": "Asks before the assistant does one thing that needs a person's yes. It shows the exact command or target, so people approve what will really happen, and can save the choice for a clearly named group of actions.", "useFor": [ "Before a command, file change or web request that needs approval.", "Letting people allow an action once, for this session, or always for a named group.", "Letting people send a note with their decision to steer the assistant." ], "notFor": [ { "text": "A plain yes or no with no saved choices", "use": "approval-prompt" }, { "text": "Changing how much the assistant may do in general", "use": "permission-mode-switcher" }, { "text": "A question with several possible answers", "use": "agent-question-card" } ], "whenToUse": [ "Show the exact thing it will act on, not a loose summary.", "List everything a saved choice would allow.", "Offer only Allow once when you cannot show everything a saved choice would allow.", "Name the helper when a background task is asking.", "Tell people the note box is where they can adjust their choice." ], "avoid": [ "Don't pick Allow always for people. Allow once is selected first.", "Don't jump the cursor into the prompt unless the assistant is stuck waiting.", "Don't use it for a risky action that needs one clear yes or no. Use ApprovalPrompt.", "Don't rely on the keys alone. Deny, Add a note and Confirm also work with a mouse, a tap, or Tab.", "Don't change what Tab does. It keeps moving to the next control." ], "accessibility": [ "The prompt is named \"Permission needed\" plus the step, and the choices work with the arrow keys.", "Escape anywhere inside the prompt denies, and N opens the note box unless you are typing. Screen readers are told about both keys.", "The reason is read with the choices, and the note box has a label and a hint.", "The Add a note button says whether the note box is open.", "After a choice, the result is shown with an icon and words, not only a color, and keyboard focus moves to it.", "A decision made elsewhere, such as from another screen, is announced to screen readers." ], "accessibilityYouDo": [ "Set autoFocus only when the assistant cannot continue without an answer. Otherwise leave people where they are.", "Write a reason that says why this step needs a yes." ], "onPhone": [ "The Escape to deny and N for a note shortcuts need a keyboard, so on a phone people use the choices and the confirm button.", "Long commands and file paths scroll sideways inside their own boxes instead of wrapping.", "The note field is 44px tall with 16px text on a touch screen.", "The choice rows grow to at least 44px tall on touch screens." ], "importPath": "import { PermissionPrompt } from \"./index\"", "sourcePath": "src/organisms/PermissionPrompt.tsx", "props": [ { "name": "tool", "type": "string", "required": true, "default": null, "description": "Kind of action, such as \"Bash command\". Used as the title and the section name." }, { "name": "description", "type": "string", "required": true, "default": null, "description": "Plain description of what the action does." }, { "name": "target", "type": "string | string[]", "required": true, "default": null, "description": "The literal command or target. An array lists each subcommand of a compound command." }, { "name": "reason", "type": "string", "required": false, "default": "\"This command requires approval\"", "description": "Why the person is being asked." }, { "name": "requestedBy", "type": "string", "required": false, "default": null, "description": "Name of the subagent that asked, shown as a badge." }, { "name": "sessionScope", "type": "string", "required": false, "default": null, "description": "What a session-only approval covers. Adds the middle choice \"Allow for this session\" (choice \"session\", state \"allowed-session\", result \"Allowed for this session\"). Omit to hide it." }, { "name": "ruleScope", "type": "string", "required": false, "default": null, "description": "Scope of the saved rule, such as `npm test *`. Omit to offer only Allow once." }, { "name": "ruleCovers", "type": "string[]", "required": false, "default": null, "description": "Exactly what a saved rule covers, one entry per rule. Falls back to ruleScope." }, { "name": "ruleLifetime", "type": "string", "required": false, "default": null, "description": "Where and how long a saved rule lasts." }, { "name": "onceOnlyReason", "type": "string", "required": false, "default": null, "description": "Explains why there is no saved-rule option. Shown when ruleScope is omitted." }, { "name": "state", "type": "\"pending\" | \"allowed-once\" | \"allowed-session\" | \"allowed-rule\" | \"denied\"", "required": false, "default": null, "description": "State, for controlled use. Uncontrolled it starts pending and follows the choice." }, { "name": "onStateChange", "type": "(state: PermissionState) => void", "required": false, "default": null, "description": "Called after Confirm or Esc with the new state." }, { "name": "onDecide", "type": "(decision: { choice: \"once\" | \"session\" | \"always\" | \"deny\"; note: string }) => void", "required": false, "default": null, "description": "Called after Confirm, or after Esc with choice \"deny\". Carries the choice and the trimmed note." }, { "name": "autoFocus", "type": "boolean", "required": false, "default": "false", "description": "Move focus to the first choice on mount. Use only when the agent cannot continue until the person answers." }, { "name": "labels", "type": "PermissionPromptLabels", "required": false, "default": null, "description": "Replace choice text, the note label, hint and placeholder, and the scope heading. The Esc and N key hints are fixed." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the section." } ], "variantsHint": { "state": [ "pending", "allowed-once", "allowed-session", "allowed-rule", "denied" ] }, "tokens": [ "--code-bg", "--code-fg", "--surface-sunken", "--border", "--success", "--danger", "--radius-control", "--radius-field", "--radius-card" ], "related": [ "approval-prompt", "permission-mode-switcher", "tool-call-card" ], "composedOf": [ "badge", "button", "kbd" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Saving a choice for next time", "description": "Choose Allow always to see what the saved choice covers before you confirm.", "code": "" }, { "title": "A request with several parts", "description": "When a request has several parts, each part is listed, and a saved choice covers each one.", "code": "" }, { "title": "Allow once only", "description": "When a saved choice cannot show everything it would allow, offer only Allow once and say why.", "code": " Payment\"\n reason=\"This change needs your approval\"\n onceOnlyReason=\"You cannot save this choice for next time.\"\n/>" }, { "title": "Allow for this session", "description": "Add sessionScope to offer a middle choice. It lasts until the session ends and saves nothing for later.", "code": "" }, { "title": "Keyboard shortcuts", "description": "Click inside the prompt, then press N to open the note box or Esc to deny. The line below shows what you chose.", "code": " console.log(d.choice, d.note)}\n/>" }, { "title": "After you choose", "description": "The prompt shrinks to a short summary. These are the three results.", "code": "\n\n" } ], "pageUrl": "https://lkb00.github.io/tattva/component-permission-prompt/", "markdownUrl": "https://lkb00.github.io/tattva/docs/permission-prompt.md" }, { "id": "agent-session-list", "name": "AgentSessionList", "level": "organism", "since": "0.5", "aka": [ "agent runs", "sessions", "task list" ], "category": "agents", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "grouped", "note": "Sessions are grouped by status into Needs input, Working, Ready for review and Completed, and a group with no sessions is left out.", "source": "documented" }, { "name": "peek open", "note": "Pressing Peek on a session that has peek data opens its latest output or question and a reply box.", "source": "documented" }, { "name": "reply sent", "note": "Sending a reply calls onReply, clears the box and announces it to screen readers.", "source": "documented" }, { "name": "empty", "note": "With no sessions, nothing is shown.", "source": "documented" }, { "name": "focus", "note": "Peek, the reply box and the send button show a focus ring on keyboard focus.", "source": "documented" } ], "summary": "A list of assistant tasks grouped by what they need, with a Peek panel to read the latest and reply.", "description": "AgentSessionList groups tasks under Needs input, Working, Ready for review and Completed, each with a count. A row shows a status icon, the task name, a one-line summary marked as written by AI, how old it is and an optional link label. Peek opens the latest update or question, how long it has waited, and a box to reply. Use it as the home screen for assistants working in the background.", "purpose": "A home screen for assistants working in the background, sorted by what each one needs from you. Peek lets people read the latest and reply without leaving the list.", "useFor": [ "Showing several assistant tasks at once, grouped into needs input, working, ready for review and completed.", "Answering a waiting assistant straight from the list.", "Showing a one-line summary, written by the assistant, for each task." ], "notFor": [ { "text": "Only the items that are waiting on the person, across all runs", "use": "approval-inbox" }, { "text": "A list of past chats", "use": "conversation-list" }, { "text": "One task broken into smaller tasks", "use": "task-tree" } ], "whenToUse": [ "Keep the AI-written label on summaries written by AI.", "Put Needs input first so waiting tasks are easy to find.", "Show how long a task has waited in the Peek panel." ], "avoid": [ "Don't remove the AI-written label from summaries written by AI.", "Don't rely on heading color. The group name and count are words.", "Don't use amber on rows that are not waiting for a person." ], "accessibility": [ "Each group is named by its heading, and the count is read with the word sessions.", "Peek is a button that says whether it is open, and its name includes the task.", "The reply box and its send button are named with the task.", "Screen readers hear when a reply is sent.", "Each status icon has its own shape and a name for screen readers." ], "accessibilityYouDo": [ "Give every session a unique id: it links each Peek button to its panel.", "Set headingLevel so the group names fit your page outline. It is 3 unless you change it." ], "onPhone": [ "Each row wraps, and the age and Peek button move under the name when the row is narrow.", "Opening a peek shows a reply field that is 44px tall with 16px text on a touch screen, so the page does not zoom.", "The summary and peek panel are indented 28px to line up with the name, which narrows them a little." ], "importPath": "import { AgentSessionList } from \"./index\"", "sourcePath": "src/organisms/AgentSessionList.tsx", "props": [ { "name": "sessions", "type": "AgentSession[]", "required": true, "default": null, "description": "Sessions to list. Each has id, name, status, summary, age, and optional pr, peek and group." }, { "name": "onReply", "type": "(id: string, text: string) => void", "required": false, "default": null, "description": "Called when a reply is sent from Peek. The field clears afterwards." }, { "name": "labels", "type": "AgentSessionListLabels", "required": false, "default": null, "description": "Replace group names, button text and the AI badge text." }, { "name": "headingLevel", "type": "2 | 3 | 4 | 5 | 6", "required": false, "default": "3", "description": "Level of the part's own heading, so it fits the page outline." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the wrapper." } ], "variantsHint": { "headingLevel": [ 2, 3, 4, 5, 6 ] }, "tokens": [ "--surface", "--border", "--surface-sunken", "--fg-muted", "--fg-subtle", "--radius-field", "--radius-card" ], "related": [ "agent-status-icon", "task-tree", "conversation-list", "tray" ], "composedOf": [ "agent-status-icon", "ai-badge", "badge", "button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Tasks grouped by need", "description": "Groups with no tasks are left out. Peek works on any row that has something to show.", "code": "" }, { "title": "Reply from Peek", "description": "Open Peek on a task that is waiting, type a reply and send it.", "code": " send(id, text)} />" } ], "pageUrl": "https://lkb00.github.io/tattva/component-agent-session-list/", "markdownUrl": "https://lkb00.github.io/tattva/docs/agent-session-list.md" }, { "id": "task-tree", "name": "TaskTree", "level": "organism", "since": "0.5", "aka": [ "tree view", "subtasks", "task hierarchy" ], "category": "agents", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "running", "note": "A task with status running shows the working icon.", "source": "documented" }, { "name": "done", "note": "A task with status done shows the completed icon, and is removed after dismissAfterMs if that is set and its children are also done.", "source": "documented" }, { "name": "failed", "note": "A task with status failed shows the failed icon and a dismiss button that hides it.", "source": "documented" }, { "name": "stopped", "note": "A task with status stopped shows the stopped icon.", "source": "documented" }, { "name": "partial", "note": "A task with status partial shows a half-filled circle.", "source": "documented" }, { "name": "collapsed", "note": "A task with children can be collapsed to hide them; pass their ids in defaultCollapsed to start closed.", "source": "documented" }, { "name": "hover", "note": "A row gets a soft background under the pointer.", "source": "documented" } ], "summary": "A list of tasks and the smaller tasks inside them, each with a status and an Open button.", "description": "TaskTree lists tasks, with smaller tasks indented beneath them. Each row shows a name, a status in words beside an icon, a (+N) count of tasks inside it, and an Open button. Bigger tasks open and close. A failed row stays until you dismiss it. A finished row can remove itself after a short wait. Use it beside the box where people type, to show what helpers are doing.", "purpose": "Shows the helpers an assistant has started, with smaller tasks indented under the task that started them. Failed rows wait for you, and finished rows can tidy themselves away.", "useFor": [ "Beside the box where people type, to show what helpers are doing.", "A task that splits into smaller tasks, each with its own status.", "Letting people open one helper to see what it did." ], "notFor": [ { "text": "The steps of one task in the order they happen", "use": "step-timeline" }, { "text": "Separate tasks grouped by what they need from the person", "use": "agent-session-list" }, { "text": "A to-do list the person ticks off", "use": "checklist" } ], "whenToUse": [ "Keep failed rows visible until the person dismisses them.", "Remove the row from your own data when it is dismissed, so a later update does not bring it back.", "Let finished rows leave on their own when they would otherwise pile up.", "Use Open to take people to that task's own page." ], "avoid": [ "Don't show status with only color. Each row has an icon shape and words.", "Don't make the wait so short that a result vanishes before it can be read.", "Don't nest deeper than people can follow. Each level moves further right.", "Don't use it for a simple list of steps in order. Use StepTimeline." ], "accessibility": [ "Rows are list items, and bigger tasks have a button that says Expand or Collapse with the task name.", "Screen readers hear the (+N) count as the number of tasks inside.", "Status is an icon shape plus words. Partial uses a half-filled circle.", "Open and Dismiss buttons include the task name, and each removal, timed ones too, is announced.", "The running icon spins, and stops when people turn off motion in their system settings." ], "accessibilityYouDo": [ "Leave dismissAfterMs off if people need time to read finished rows." ], "onPhone": [ "Each level of nesting indents by 20px, so deep trees leave less width for the task name, which is cut with an ellipsis.", "The status word and Open button wrap under the name when the row is narrow.", "The expand, Open and dismiss controls keep their size and have a 44px tap area on a touch screen." ], "importPath": "import { TaskTree } from \"./index\"", "sourcePath": "src/organisms/TaskTree.tsx", "props": [ { "name": "tasks", "type": "TaskNode[]", "required": true, "default": null, "description": "Root tasks. Each has id, name, status (running, done, failed, stopped or partial) and optional children." }, { "name": "onOpen", "type": "(id: string) => void", "required": false, "default": null, "description": "Called by a row's Open button." }, { "name": "onDismiss", "type": "(id: string) => void", "required": false, "default": null, "description": "Called when a row is dismissed, either by the Dismiss button on a failed row or by dismissAfterMs on a done row. The tree hides the row at once, and your app removes it from its data here." }, { "name": "dismissAfterMs", "type": "number", "required": false, "default": "undefined", "description": "Milliseconds after which a done row is dismissed and onDismiss(id) is called. Off when undefined. Failed rows never auto-dismiss. A done parent waits until its nested rows are done. The timer is not motion, so reduced motion does not change it." }, { "name": "defaultCollapsed", "type": "string[]", "required": false, "default": "[]", "description": "Ids of parents that start collapsed." }, { "name": "labels", "type": "TaskTreeLabels", "required": false, "default": null, "description": "Replace status names and button text." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the wrapper." } ], "variantsHint": {}, "tokens": [ "--surface", "--border", "--surface-hover", "--danger", "--success", "--radius-control", "--radius-card" ], "related": [ "agent-status-icon", "step-timeline", "agent-session-list", "checklist" ], "composedOf": [ "agent-status-icon", "button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Tasks inside tasks", "description": "The (+N) count includes every task inside. Close a parent task to hide what is inside.", "code": " open(id)} />" }, { "title": "Dismissing a failed task", "description": "Failed rows have a Dismiss button and stay until you use it.", "code": "" }, { "title": "Finished tasks leave on their own", "description": "The finished row disappears after 4 seconds. The failed row stays.", "code": " setRows((r) => r.filter((x) => x.id !== id))}\n/>" } ], "pageUrl": "https://lkb00.github.io/tattva/component-task-tree/", "markdownUrl": "https://lkb00.github.io/tattva/docs/task-tree.md" }, { "id": "provenance-popover", "name": "ProvenancePopover", "level": "molecule", "since": "0.5", "aka": [ "content credentials", "origin info", "c2pa" ], "category": "trust", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "hover", "note": "The trigger pill gets a stronger tint under the pointer.", "source": "documented" }, { "name": "focus", "note": "The trigger shows a focus ring on keyboard focus.", "source": "documented" }, { "name": "edited by a person", "note": "Pass editedByPerson to add a row saying whether a person edited it.", "source": "documented" } ], "summary": "A label that says content was made with AI, and opens a short note on how.", "description": "ProvenancePopover shows an AI label in plain words, with the details one click away. The panel can show which tool made it, the date, what the AI did, whether a person edited it, why you are seeing it, and a link to more. Anything you do not know is left out.", "purpose": "A small AI label in plain words that opens a short note on how the content was made. The label is always visible and the details are one click away, so it informs without getting in the way.", "useFor": [ "Marking text, images or files that AI made or changed.", "Explaining which tool made something, when, and whether a person edited it.", "Telling people why they are seeing AI content." ], "notFor": [ { "text": "A plain AI label with nothing more to explain", "use": "ai-badge" }, { "text": "Showing where a single fact came from", "use": "citation-hover-card" }, { "text": "Showing how sure the AI is about an answer", "use": "confidence-indicator" } ], "whenToUse": [ "Show the label first and keep the details one click away.", "Fill in only what you are sure of. Missing details are left out.", "Say whether a person edited it, if you keep track.", "Explain why in one sentence." ], "avoid": [ "Do not label content AI did not touch. Too many labels weaken trust.", "Do not rely on the green color to show it is AI. The words do that.", "Do not put long policy text in the panel. Link to it.", "Do not make up details your system does not record." ], "accessibility": [ "The label is a button with words on it, so it is never only an icon.", "It tells screen readers whether the panel is open, and opens with Enter, Space, a click or a tap.", "Escape closes the panel and returns to the label. Clicking outside also closes it.", "The panel is named by its title, and the details are laid out as lists." ], "accessibilityYouDo": [ "Write a label that says what happened in plain words, such as AI-generated or Edited with AI.", "Translate the row labels with rowLabels if your product is not in English." ], "onPhone": [ "The label is a button. On touch screens it keeps its small badge size and has a 44px tap area.", "On a phone the panel opens as a bottom sheet with a backdrop, within thumb reach. On wider screens it opens under the label, flips above if there is no room below, and stays inside the screen edges.", "Tap outside the panel to close it. The View full details link is small text with no 44px target." ], "importPath": "import { ProvenancePopover } from \"./index\"", "sourcePath": "src/molecules/ProvenancePopover.tsx", "props": [ { "name": "label", "type": "string", "required": false, "default": "\"AI-generated\"", "description": "Visible text of the label and the accessible name of the trigger." }, { "name": "madeWith", "type": "string", "required": false, "default": null, "description": "Tool or model that produced the content." }, { "name": "date", "type": "string", "required": false, "default": null, "description": "When it was made, as display text." }, { "name": "actions", "type": "string[]", "required": false, "default": null, "description": "What the AI did, one short phrase each." }, { "name": "editedByPerson", "type": "boolean", "required": false, "default": null, "description": "Whether a person changed it afterwards. Omit to hide the row." }, { "name": "why", "type": "string", "required": false, "default": null, "description": "One line on why the person is seeing this content." }, { "name": "detailsHref", "type": "string", "required": false, "default": null, "description": "Link to a fuller record. The link is hidden when omitted." }, { "name": "detailsLabel", "type": "string", "required": false, "default": "\"View full details\"", "description": "Text of the details link." }, { "name": "title", "type": "string", "required": false, "default": "\"About this content\"", "description": "Panel heading and accessible name of the panel." }, { "name": "rowLabels", "type": "{ madeWith; date; actions; edited; yes; no }", "required": false, "default": null, "description": "Replaces the row labels for localisation." }, { "name": "open / onOpenChange", "type": "boolean / (open: boolean) => void", "required": false, "default": null, "description": "Controlled mode. Omit both for self-managed state." }, { "name": "align / side", "type": "\"start\" | \"end\" / \"bottom\" | \"top\"", "required": false, "default": "\"start\" / \"bottom\"", "description": "Which edge of the label the panel hangs from." } ], "variantsHint": {}, "tokens": [ "--lime", "--on-lime", "--surface-raised", "--surface-sunken", "--border", "--shadow-lg", "--radius-control" ], "related": [ "ai-badge", "confidence-indicator", "source-card" ], "composedOf": [ "popover" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Every detail filled in", "description": "Every detail filled in. Click, tap, or press Enter or Space on the label to open it.", "code": "" }, { "title": "Minimal", "description": "Only a tool and a reason. Use this when that is all you know.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-provenance-popover/", "markdownUrl": "https://lkb00.github.io/tattva/docs/provenance-popover.md" }, { "id": "citation-hover-card", "name": "CitationHoverCard", "level": "molecule", "since": "0.5", "aka": [ "hover card", "citation preview", "link preview" ], "category": "trust", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "hover", "note": "Moving the pointer onto the number opens a source card above it, and leaving closes it.", "source": "documented" }, { "name": "focus", "note": "Focusing the number with the keyboard opens the card too.", "source": "documented" }, { "name": "pinned", "note": "Clicking the number keeps the card open until you click it again, click outside or press Escape.", "source": "documented" } ], "summary": "A small number in a sentence that shows where a fact came from.", "description": "CitationHoverCard is a small number placed inside AI-written text. It opens a card with the source's title, website, a short quote, a trust label, and a link to the source. Point at it or tab to it to open the card. Click or tap to keep it open. Escape closes it.", "purpose": "A small number placed right after a fact that shows where it came from. The source card opens on pointing, tabbing or tapping, so checking a claim never needs a mouse.", "useFor": [ "A fact in an AI answer that comes from a web page or document.", "Showing a source's title, website, a short quote and a trust label without leaving the text." ], "notFor": [ { "text": "The full list of sources for an answer", "use": "source-list" }, { "text": "A plain numbered link to a source, with no card", "use": "citation-marker" }, { "text": "A source shown as a card of its own", "use": "source-card" } ], "whenToUse": [ "Put the number right after the fact it supports.", "Show a trust label only when you have a real reason.", "Keep quotes short and taken straight from the source.", "Add a Sources list too, so every source is in one place." ], "avoid": [ "Do not make pointing at it the only way to reach the source.", "Do not use a trust label as a score without saying how it is decided.", "Do not use it where the card would cover the text being read." ], "accessibility": [ "The number is a button named like \"Source 1: energy.example.gov\", and it tells screen readers whether the card is open.", "The card opens on pointing, on tabbing to it and on click. A click keeps it open, which is how touch screens use it.", "Escape closes the card and returns to the number. Moving focus away also closes it.", "The card's link can be reached with Tab, and the trust label is written in words." ], "accessibilityYouDo": [ "Also list every source in a Sources list, so people can reach them all without opening each card.", "Place the number right after the fact it supports, so the link between them is clear when read aloud." ], "onPhone": [ "A tap opens the card and pins it. Tap the number again or tap outside to close it.", "The number is a small inline button. On touch screens it keeps its size and has a 44px tap area, so the line it sits in does not get taller.", "On a phone the card is fixed along the bottom of the screen, 1rem in from each side and above the bottom safe area, so it cannot run off the edge. The Open source link is small text with no 44px target." ], "importPath": "import { CitationHoverCard } from \"./index\"", "sourcePath": "src/molecules/CitationHoverCard.tsx", "props": [ { "name": "n", "type": "number", "required": true, "default": null, "description": "Citation number shown in the marker." }, { "name": "title", "type": "string", "required": true, "default": null, "description": "Source title." }, { "name": "domain", "type": "string", "required": true, "default": null, "description": "Source domain. Part of the marker's accessible name." }, { "name": "url", "type": "string", "required": true, "default": null, "description": "Target of the open link." }, { "name": "snippet", "type": "string", "required": false, "default": null, "description": "Short excerpt, clamped to three lines." }, { "name": "trust", "type": "string", "required": false, "default": null, "description": "Trust label as text, such as Government or Academic." }, { "name": "favicon", "type": "ReactNode", "required": false, "default": null, "description": "Small mark for the source. Defaults to the first letter of the domain." }, { "name": "openLabel", "type": "string", "required": false, "default": "\"Open source\"", "description": "Text of the link." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the wrapper." } ], "variantsHint": {}, "tokens": [ "--accent-soft", "--accent-fg", "--surface-raised", "--border", "--shadow-lg", "--fg-muted", "--radius-overlay" ], "related": [ "citation-marker", "source-card", "source-list", "summary-card" ], "composedOf": [ "badge" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Inline in a sentence", "description": "Point at the number, tab to it, or tap it. Press Escape to close.", "code": "

\n Renewables supplied about a quarter of generation last year.\n \n

" }, { "title": "Without a quote or trust label", "description": "Only what you have. The site icon falls back to the first letter of the website.", "code": "

\n The report was updated in March.\n \n

" } ], "pageUrl": "https://lkb00.github.io/tattva/component-citation-hover-card/", "markdownUrl": "https://lkb00.github.io/tattva/docs/citation-hover-card.md" }, { "id": "suggestion-bar", "name": "SuggestionBar", "level": "organism", "since": "0.5", "aka": [ "inline suggestion", "accept reject bar" ], "category": "creating", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "status", "note": "Set with the status prop.", "source": "prop" } ], "summary": "A bar under an AI draft. Nothing changes in your document until you choose.", "description": "SuggestionBar sits under a draft the AI has written but not yet added. You can Keep it (or Replace), Insert below, Regenerate, or Discard. A \"Fine-tune this\" box lets you ask for a change. Regenerate asks for a fresh version of the same request. Fine-tune changes the current draft. A note beside Regenerate says what another try costs.", "purpose": "Sits under an AI draft that has not been added yet. Nothing changes in the document until the person chooses, and Regenerate and Fine-tune are kept clearly apart.", "useFor": [ "A draft paragraph the AI wrote for a document.", "Replacing selected text with a rewrite, with Replace as the main button.", "Showing what another try costs when tries count against a limit." ], "notFor": [ { "text": "One small edit with a before and after", "use": "suggestion-card" }, { "text": "An action the assistant wants to take that needs a yes", "use": "approval-prompt" }, { "text": "A suggested ending to the line being typed", "use": "ghost-text" } ], "whenToUse": [ "Keep the draft out of the document until the person chooses Keep, Replace or Insert below.", "Show what another try costs when tries count against a limit.", "Call the box Fine-tune this and the button Regenerate, so they are not confused.", "Return the cursor to the document after Keep or Discard." ], "avoid": [ "Do not add the draft just because time passed or the person clicked away.", "Do not call a request for a change Regenerate.", "Do not hide Discard. Closing the bar should never be the only way out." ], "accessibility": [ "Status changes, such as \"Added to the document\", are announced to screen readers separately from the draft.", "While the draft is being written, the spinner is named \"Writing a draft\" for screen readers. The draft text itself is not read out as it changes.", "The Fine-tune box has a name, and its send button is turned off while the box is empty.", "Every action is a real button, in reading order.", "Keyboard focus follows the buttons as they change: to Discard while a new draft is written, to the main action when it is ready, and back to the document after Keep, Replace, Insert below or Discard (the nearest text box or editor, else the bar itself). Pass focusAfter to choose the place." ], "accessibilityYouDo": [ "Set status to generating while a new draft is written and back to ready when it is done, so screen readers hear the right update." ], "onPhone": [ "The buttons wrap onto new rows, and Discard moves to the right edge of its row.", "The Fine-tune field is 16px on touch screens, so the page does not zoom when it takes focus, The field grows to 44px tall, and the Send button keeps its size and has a 44px tap area.", "The long placeholder is cut off in a narrow field. The bar does not move above the on-screen keyboard, so place it where the keyboard will not cover it." ], "importPath": "import { SuggestionBar } from \"./index\"", "sourcePath": "src/organisms/SuggestionBar.tsx", "props": [ { "name": "status", "type": "\"generating\" | \"ready\" | \"committed\" | \"discarded\"", "required": false, "default": "\"ready\"", "description": "Where the staged output is. The consumer owns this state." }, { "name": "children", "type": "ReactNode", "required": false, "default": null, "description": "Optional preview of the staged output." }, { "name": "primaryLabel", "type": "string", "required": false, "default": "\"Keep\"", "description": "Label of the primary action. Use Replace over a selection." }, { "name": "onKeep / onInsertBelow / onDiscard", "type": "() => void", "required": false, "default": null, "description": "Commit, commit as a new block below, or drop the draft." }, { "name": "onRegenerate", "type": "() => void", "required": false, "default": null, "description": "Ask for a fresh sample of the same request." }, { "name": "onRefine", "type": "(instruction: string) => void", "required": false, "default": null, "description": "Send a follow-up instruction typed in the Fine-tune field." }, { "name": "retryCost", "type": "ReactNode", "required": false, "default": null, "description": "Cost of a retry, shown next to Regenerate." }, { "name": "labels", "type": "Partial>", "required": false, "default": null, "description": "Overrides for every piece of copy, including the status messages." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the container." } ], "variantsHint": { "status": [ "generating", "ready", "committed", "discarded" ] }, "tokens": [ "--surface", "--surface-sunken", "--border", "--lime", "--on-lime", "--fg-subtle", "--radius-field", "--radius-card" ], "related": [ "selection-toolbar", "approval-prompt", "rate-limit-notice" ], "composedOf": [ "button", "spinner" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Try each button", "description": "Try each button. Regenerate and Fine-tune show a short wait. Keep and Discard finish it.", "code": "const [status, setStatus] = useState(\"ready\");\n\n setStatus(\"committed\")} onInsertBelow={() => setStatus(\"committed\")}\n onDiscard={() => setStatus(\"discarded\")}\n onRegenerate={() => setStatus(\"generating\")}\n onRefine={(text) => setStatus(\"generating\")}>\n Our quarterly numbers beat the forecast, driven by steady renewals and two large new accounts.\n" }, { "title": "Replace a selection", "description": "Use Replace as the main button when the draft takes the place of selected text.", "code": "A shorter version of the paragraph." }, { "title": "While the draft is written", "description": "The buttons are hidden while the draft is written. Discard stays.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-suggestion-bar/", "markdownUrl": "https://lkb00.github.io/tattva/docs/suggestion-bar.md" }, { "id": "ghost-text", "name": "GhostText", "level": "atom", "since": "0.5", "aka": [ "inline completion", "autocomplete text", "copilot suggestion" ], "category": "creating", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "accept button", "note": "Pass onAccept to turn the key hint into a button that accepts the suggestion.", "source": "documented" }, { "name": "dismiss button", "note": "Pass onDismiss to show a small close button beside the suggestion.", "source": "documented" }, { "name": "partial hint", "note": "Pass partialHint to show a short note about accepting only part of the suggestion.", "source": "documented" } ], "summary": "Faded suggested text that appears after what you typed, with a Tab key hint.", "description": "GhostText shows a suggested ending in faded type with a dotted underline, so it looks different from real text. A key hint shows which key accepts it. The component only reports when someone accepts or dismisses. Your editor decides which keys do that and what happens to the text.", "purpose": "A suggested ending shown faded after what someone typed, with a hint for the key that accepts it. It looks clearly different from real text and only becomes text when accepted.", "useFor": [ "Completing the sentence or line someone is typing.", "Offering a long suggestion that can be accepted a word at a time, with a hint that says how." ], "notFor": [ { "text": "A whole paragraph or a rewrite", "use": "suggestion-bar" }, { "text": "A correction to text already written", "use": "suggestion-card" }, { "text": "Ideas for what to ask next", "use": "suggestion-chips" } ], "whenToUse": [ "Make Tab, or your accept key, work from the keyboard as well as from the hint.", "Dismiss on Escape, and when the person keeps typing.", "For long suggestions, let people accept one word at a time and say how.", "Keep the suggestion looking different from real text." ], "avoid": [ "Do not put the suggestion into the real text before it is accepted.", "Do not make screen readers announce the suggestion. It changes with every key press.", "Do not use it for whole paragraphs. Use SuggestionBar." ], "accessibility": [ "Screen readers skip the faded text. A hidden description carries it instead, with the keys that accept or dismiss it.", "It announces nothing on its own, because the suggestion changes with every key press.", "When you give it actions, the key hint and the dismiss control are real buttons with names, such as \"Accept suggestion, Tab\"." ], "accessibilityYouDo": [ "Pass an id and point the text box's aria-describedby at it, so screen readers read the hidden description.", "Make the accept key, usually Tab, and Escape work in your editor. The component only shows the hint." ], "onPhone": [ "Phones have no Tab or Esc key, so pass onAccept and onDismiss. The key hint then becomes a tap target and a dismiss button appears.", "On touch screens both buttons keep their size and have a 44px tap area, so the line they sit in does not get taller.", "The hint shows the accept key as text, so set acceptKey to something a phone user understands or hide the hint." ], "importPath": "import { GhostText } from \"./index\"", "sourcePath": "src/atoms/GhostText.tsx", "props": [ { "name": "children", "type": "string", "required": true, "default": null, "description": "The suggested continuation." }, { "name": "typed", "type": "ReactNode", "required": false, "default": null, "description": "Text already typed, rendered in normal ink before the suggestion." }, { "name": "id", "type": "string", "required": false, "default": null, "description": "Id of the hidden description. Point the field's aria-describedby at it." }, { "name": "acceptKey", "type": "string", "required": false, "default": "\"Tab\"", "description": "Key shown in the hint and named in the description." }, { "name": "dismissKey", "type": "string", "required": false, "default": "\"Esc\"", "description": "Key named in the description." }, { "name": "partialHint", "type": "string", "required": false, "default": null, "description": "Text for a partial accept path, such as one word or one line." }, { "name": "description", "type": "string", "required": false, "default": null, "description": "Replaces the default hidden description." }, { "name": "onAccept", "type": "() => void", "required": false, "default": null, "description": "Called when the hint button is activated. Makes the hint a button." }, { "name": "onDismiss", "type": "() => void", "required": false, "default": null, "description": "Called when the dismiss button is activated. Shows the button." }, { "name": "acceptLabel / dismissLabel", "type": "string", "required": false, "default": "\"Accept suggestion\" / \"Dismiss suggestion\"", "description": "Accessible names of the two controls." } ], "variantsHint": {}, "tokens": [ "--surface-sunken", "--fg-subtle", "--border-strong", "--border", "--radius-control" ], "related": [ "kbd", "suggestion-bar", "suggestion-card" ], "composedOf": [ "kbd" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Accept or dismiss", "description": "Click the Tab hint to accept, or the close button to dismiss. In a real editor, Tab accepts and Escape dismisses.", "code": " accept()} onDismiss={() => dismiss()}>\n {\" I will review the draft tomorrow morning.\"}\n" }, { "title": "Display only", "description": "Without buttons the hint is plain text. Use it when your editor handles every key.", "code": "{\" thank you for your patience.\"}" } ], "pageUrl": "https://lkb00.github.io/tattva/component-ghost-text/", "markdownUrl": "https://lkb00.github.io/tattva/docs/ghost-text.md" }, { "id": "selection-toolbar", "name": "SelectionToolbar", "level": "molecule", "since": "0.5", "aka": [ "floating toolbar", "bubble menu", "text selection menu" ], "category": "creating", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "more open", "note": "Pressing the more button, or Arrow Down on it, opens a menu of extra edits.", "source": "documented" }, { "name": "empty instruction", "note": "The send button is disabled until something is typed in the ask box.", "source": "documented" }, { "name": "keyboard", "note": "Left and right arrows move between controls and Escape calls onClose.", "source": "documented" }, { "name": "hover", "note": "Each preset button gets a soft background under the pointer.", "source": "documented" } ], "summary": "A small bar that appears over highlighted text, with quick edits, a menu of more, and a box to ask for your own.", "description": "SelectionToolbar offers quick AI edits for highlighted text. It shows ready-made buttons, a More options menu and a box to ask AI for your own edit. It does not position itself, so you place it near the highlighted text. Real apps should offer the same actions in a right-click menu and a keyboard shortcut, because a floating bar is hard to reach.", "purpose": "A small bar of quick AI edits for highlighted text, with a menu of more and a box to ask for your own edit. It does not position itself, so it fits into any editor.", "useFor": [ "Rephrasing, shortening or changing the tone of highlighted text.", "Asking for a custom edit to a selection in your own words." ], "notFor": [ { "text": "Showing the result of an edit before it is applied", "use": "suggestion-bar" }, { "text": "Ideas for what to ask next in a chat", "use": "suggestion-chips" } ], "whenToUse": [ "Offer every action in a right-click menu and with a keyboard shortcut too.", "Show the result in a SuggestionBar, so nothing changes until it is chosen.", "Return the cursor to the text when the bar closes.", "Place the bar next to the highlighted text, because it does not position itself." ], "avoid": [ "Do not show it only when pointing.", "Do not apply an edit straight from a button without a preview.", "Do not add more than four or five quick edits. Put the rest in the menu." ], "accessibility": [ "Screen readers know it as a named toolbar laid out side to side.", "Tab stops once on the bar. Left and Right arrows, Home and End move between controls. In the text box, the arrows move the cursor first and leave the box only at its ends.", "The More options menu opens with Down or Up arrow and lands on the first item. Escape or Tab closes it and returns to its button.", "Escape closes the menu first. Pressing it again asks the bar to close.", "The More options button, the text box and the send button all have names for screen readers." ], "accessibilityYouDo": [ "Hide the bar and return focus to the text when onClose is called.", "Offer the same actions in a right-click menu and with a keyboard shortcut, because a floating bar is hard to reach." ], "onPhone": [ "The bar wraps onto new rows. The Ask AI field is at least 192px wide and takes its own row when the chips fill the first.", "The More menu opens as a bottom sheet with a backdrop on phones, and its items are at least 44px tall.", "The ask field is 16px on touch screens, so the page does not zoom. The bar does no measuring, so place it clear of the system selection menu and the keyboard, and note that onClose only runs on Escape, which a phone does not have." ], "importPath": "import { SelectionToolbar } from \"./index\"", "sourcePath": "src/molecules/SelectionToolbar.tsx", "props": [ { "name": "presets", "type": "SelectionAction[]", "required": false, "default": "Rephrase, Shorten, Change tone", "description": "Chips shown in the bar. Each has id, label and optional icon." }, { "name": "moreActions", "type": "SelectionAction[]", "required": false, "default": "Elaborate, More formal, More casual, Bulletize, Summarize", "description": "Overflow menu items. An empty array hides the menu." }, { "name": "onAction", "type": "(id: string) => void", "required": false, "default": null, "description": "Called for a preset or menu item." }, { "name": "onAsk", "type": "(instruction: string) => void", "required": false, "default": null, "description": "Called with the typed instruction. The field clears after sending." }, { "name": "onClose", "type": "() => void", "required": false, "default": null, "description": "Called on Escape when the menu is closed." }, { "name": "label", "type": "string", "required": false, "default": "\"Edit selected text\"", "description": "Accessible name of the toolbar." }, { "name": "moreLabel / askLabel / askPlaceholder / sendLabel", "type": "string", "required": false, "default": null, "description": "Copy and accessible names for the menu button, the field and the send button." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the bar." } ], "variantsHint": {}, "tokens": [ "--surface-raised", "--surface", "--surface-sunken", "--border", "--shadow-md", "--radius-control", "--radius-field", "--radius-overlay" ], "related": [ "suggestion-bar", "suggestion-chips", "popover" ], "composedOf": [ "popover", "button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "The standard bar", "description": "Tab once to enter the bar. Arrow keys move between controls. Escape closes it.", "code": " run(id)} onAsk={(text) => ask(text)} onClose={() => hide()} />" }, { "title": "Your own quick edits, no menu", "description": "Use your own quick edits, and drop the menu of more.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-selection-toolbar/", "markdownUrl": "https://lkb00.github.io/tattva/docs/selection-toolbar.md" }, { "id": "suggestion-card", "name": "SuggestionCard", "level": "molecule", "since": "0.5", "aka": [ "writing suggestion", "edit suggestion" ], "category": "creating", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "category", "note": "Set category to correctness, clarity, engagement or tone to change the badge colour and icon.", "source": "documented" }, { "name": "removal", "note": "When suggestion is empty, the card shows (remove) in place of the new text.", "source": "documented" }, { "name": "focus", "note": "Accept and Dismiss show a focus ring on keyboard focus.", "source": "documented" } ], "summary": "One writing suggestion with its type, the before and after, a reason, and Accept and Dismiss buttons.", "description": "SuggestionCard shows one suggestion to improve your writing. A label with an icon and a word names the kind of change. Your original text is crossed out next to the suggested text, and a short reason says why. Accept or Dismiss ends it. The types are Correctness, Clarity, Engagement and Tone, and you can swap the label and icon.", "purpose": "Shows one writing suggestion with its type, the original crossed out next to the new text, and a short reason. One card per suggestion keeps each decision small.", "useFor": [ "A spelling, grammar, clarity or tone fix for a phrase.", "A suggestion opened from an underlined phrase in the text." ], "notFor": [ { "text": "A whole AI draft", "use": "suggestion-bar" }, { "text": "A suggested ending to the line being typed", "use": "ghost-text" } ], "whenToUse": [ "Show one suggestion per card.", "Keep the explanation to a sentence.", "When you add a type, give it both a label and an icon.", "After Accept or Dismiss, move the cursor to the next suggestion or back to the text." ], "avoid": [ "Do not tell types apart by color alone.", "Do not accept just because someone pointed at it or tabbed to it.", "Do not use it for a whole draft. Use SuggestionBar." ], "accessibility": [ "The card is named by its type, such as \"Clarity suggestion\".", "The type is a word plus an icon. Color is only extra.", "Hidden words say \"Original\" and \"Suggested\" before each text, because screen readers may not mention crossed-out text.", "Accept and Dismiss are real buttons.", "After Accept or Dismiss, keyboard focus moves to the next suggestion, else the previous one, else the text. Pass focusAfter to choose another place." ], "accessibilityYouDo": [ "When you add your own type, give it both a categoryLabel and a categoryIcon, so it never relies on color." ], "onPhone": [ "The card fills the width up to 384px, so it fills a phone and does not grow on a tablet.", "Accept and Dismiss keep their size and have a 44px tap area on touch screens.", "The original and the suggestion wrap as one paragraph." ], "importPath": "import { SuggestionCard } from \"./index\"", "sourcePath": "src/molecules/SuggestionCard.tsx", "props": [ { "name": "category", "type": "\"correctness\" | \"clarity\" | \"engagement\" | \"tone\"", "required": false, "default": "\"correctness\"", "description": "Picks the default label, icon and badge tone." }, { "name": "categoryLabel", "type": "string", "required": false, "default": null, "description": "Replaces the category text, for document-specific categories." }, { "name": "categoryIcon", "type": "ReactNode", "required": false, "default": null, "description": "Replaces the category icon." }, { "name": "original", "type": "string", "required": true, "default": null, "description": "Text as written, shown struck through." }, { "name": "suggestion", "type": "string", "required": true, "default": null, "description": "Proposed replacement. An empty string shows (remove)." }, { "name": "explanation", "type": "string", "required": false, "default": null, "description": "Short reason for the change." }, { "name": "onAccept / onDismiss", "type": "() => void", "required": false, "default": null, "description": "Resolve the suggestion." }, { "name": "acceptLabel / dismissLabel", "type": "string", "required": false, "default": "\"Accept\" / \"Dismiss\"", "description": "Button text." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the card." } ], "variantsHint": { "category": [ "correctness", "clarity", "engagement", "tone" ] }, "tokens": [ "--surface", "--border", "--lime", "--danger", "--fg-muted", "--radius-card" ], "related": [ "suggestion-bar", "ghost-text", "confidence-indicator" ], "composedOf": [ "badge", "button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Try it", "description": "Accept or dismiss to see the result. The card shows one suggestion, like when you click an underlined phrase.", "code": " accept()} onDismiss={() => dismiss()} />" }, { "title": "The types", "description": "Each type has its own icon and word, so none depends on color.", "code": "
\n \n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-suggestion-card/", "markdownUrl": "https://lkb00.github.io/tattva/docs/suggestion-card.md" }, { "id": "summary-card", "name": "SummaryCard", "level": "organism", "since": "0.5", "aka": [ "ai summary", "overview card", "tldr" ], "category": "trust", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "status", "note": "Set with the status prop.", "source": "prop" }, { "name": "streaming", "note": "Set with the generating prop.", "source": "prop" } ], "summary": "An AI-written overview with its sources, a warning to double-check, and a way to give feedback.", "description": "SummaryCard holds an AI-written overview. The top has an AI label, a title and a status line. Below are the summary, optional extra detail, the list of sources, a note to double-check, and a way to give feedback. Put citation numbers inside the summary so each fact links to its source.", "purpose": "Holds an AI-written overview together with what people need to judge it: an AI label, what it is based on, its sources, a note to double-check and a way to give feedback.", "useFor": [ "A summary of a long thread, document or set of search results.", "An overview at the top of results, with sources and citations.", "A summary still being written, with a status line and a spinner." ], "notFor": [ { "text": "The closing point of a single answer", "use": "key-takeaway" }, { "text": "A normal assistant reply in a chat", "use": "message" }, { "text": "A list of sources on its own", "use": "source-list" } ], "whenToUse": [ "Say in the status line what the summary is based on.", "Put the note to double-check under the content, and make it specific for sensitive topics.", "Put citations in the text, so each fact can be checked.", "Keep the first view short. Put the depth behind Show more." ], "avoid": [ "Do not make screen readers read the summary as it appears. Update the status line instead.", "Do not remove the AI label.", "Do not leave out sources when the summary states facts." ], "accessibility": [ "The card is a section named by its title, and the AI label is written in words.", "The status line is announced when it changes. The summary text is not.", "Show more is a button that tells screen readers whether the detail is open. The detail is hidden when closed.", "Sources are a named, numbered list of links." ], "accessibilityYouDo": [ "Report progress by changing the status line, not the summary. Do not make screen readers read the summary as it arrives.", "Put citation numbers inside the summary, so each fact can be checked by keyboard." ], "onPhone": [ "The card fills the width with 20px padding. The title row wraps, and the status moves to its own line if it does not fit.", "The Show more button, the feedback buttons and the reasons keep their size and have a 44px tap area on touch screens.", "Sources stack in one column below 640px wide. Citation markers inside the text follow the Citation hover card rules." ], "importPath": "import { SummaryCard } from \"./index\"", "sourcePath": "src/organisms/SummaryCard.tsx", "props": [ { "name": "title", "type": "string", "required": false, "default": "\"Overview\"", "description": "Heading and accessible name of the section." }, { "name": "aiLabel", "type": "string", "required": false, "default": null, "description": "Replaces the text of the AI label." }, { "name": "status", "type": "ReactNode", "required": false, "default": null, "description": "Status line in the header. It is a polite status region." }, { "name": "generating", "type": "boolean", "required": false, "default": null, "description": "Shows a spinner beside the status." }, { "name": "children", "type": "ReactNode", "required": true, "default": null, "description": "The summary." }, { "name": "detail", "type": "ReactNode", "required": false, "default": null, "description": "Expandable detail. Omit to hide the control." }, { "name": "expandLabel / collapseLabel", "type": "string", "required": false, "default": "\"Show more\" / \"Show less\"", "description": "Text of the expand control." }, { "name": "defaultExpanded / expanded / onExpandedChange", "type": "boolean / boolean / (v: boolean) => void", "required": false, "default": "false", "description": "Uncontrolled or controlled expansion." }, { "name": "sources", "type": "Source[]", "required": false, "default": null, "description": "Source cards shown in a numbered list." }, { "name": "disclaimer", "type": "ReactNode", "required": false, "default": "\"AI responses may include mistakes. Check important information.\"", "description": "Disclaimer line. Pass null to remove it." }, { "name": "onFeedback", "type": "(rating, reason?) => void", "required": false, "default": null, "description": "Shows the feedback row when provided." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the section." } ], "variantsHint": {}, "tokens": [ "--surface", "--border", "--lime", "--fg-muted", "--fg-subtle", "--radius-control", "--radius-card" ], "related": [ "citation-hover-card", "source-list", "feedback-bar", "provenance-popover" ], "composedOf": [ "ai-badge", "spinner", "feedback-bar", "source-list", "citation-hover-card" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "With citations and detail", "description": "The numbers open source previews. Show more reveals the detail.", "code": " {}}>\n Renewables supplied about a quarter of national generation last year.\n \n" }, { "title": "While the draft is written", "description": "A spinner beside the status line shows work in progress. Screen readers announce the status words.", "code": "Writing a summary of the conversation." } ], "pageUrl": "https://lkb00.github.io/tattva/component-summary-card/", "markdownUrl": "https://lkb00.github.io/tattva/docs/summary-card.md" }, { "id": "parameter-panel", "name": "ParameterPanel", "level": "organism", "since": "0.5", "aka": [ "settings panel", "generation settings", "controls panel" ], "category": "creating", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "loading", "note": "Set with the busy prop.", "source": "prop" } ], "summary": "A set of choices for making something with AI, with a live cost and a Generate button.", "description": "ParameterPanel shows one control for each setting: a choice between a few options, shape buttons, style buttons, a number, or a repeat code with a Fixed switch. When you give it a cost, the cost under the controls updates as settings change, and screen readers hear it. Put it next to where people type their request, so the cost is clear before anything is made.", "purpose": "Gathers the settings for one thing being made, with the cost shown above Generate. People can change settings while they can still see what it will cost.", "useFor": [ "Settings for one image, video or other result, next to where the request is typed.", "Showing a cost that updates as the settings change.", "Letting people fix a repeat code so they can get similar results again." ], "notFor": [ { "text": "Settings that apply to the whole app" }, { "text": "Actions on a result that already exists", "use": "variation-actions" }, { "text": "Choosing which AI model to use", "use": "model-picker" } ], "whenToUse": [ "Show the cost before making anything, so people can change settings first.", "Keep the list short. Put the settings people change most at the top.", "Add a hint on the repeat code that says what it does and does not promise.", "Work out the cost from the same settings that Generate uses.", "Set busy while the result is being made, so Generate turns off and shows it is working." ], "avoid": [ "Do not use amber for the cost. Cost is just information until it blocks something.", "Do not bury the Generate button below a long list of settings.", "Do not keep the settings inside the panel. Your app owns them.", "Do not use it for settings that apply to the whole app. It is for one creation." ], "accessibility": [ "The panel is a form named by its title, and Generate submits it, so Enter in a number box generates.", "Each group of options is named by its label. Arrow keys move and choose, and Tab stops only on the chosen option.", "Shape options say the ratio in words. The small drawing beside them is hidden from screen readers.", "The Fixed switch and the number boxes are named from their labels.", "Screen readers hear the new cost when it changes, without losing their place." ], "accessibilityYouDo": [ "Pass estimateCost when there is a cost, so screen readers hear it change.", "Write labels that make sense on their own. Each control is named from its label, and the hint is not read with it." ], "onPhone": [ "The panel fills the width, and the option chips wrap onto new lines.", "Switches and number boxes grow to 44px tall on a touch screen, and the number boxes are 16px so the page does not zoom. Chips keep their size and have a 44px tap area.", "Option descriptions are set as a title only, which a finger cannot show, so put anything people must read in the label or hint.", "The cost line and Generate button stay on one row at the bottom." ], "importPath": "import { ParameterPanel } from \"./index\"", "sourcePath": "src/organisms/ParameterPanel.tsx", "props": [ { "name": "parameters", "type": "ParameterSpec[]", "required": true, "default": null, "description": "Schema in display order. Each entry has an id, a label, an optional hint and a kind of segmented, aspect, presets, number or seed." }, { "name": "values", "type": "Record", "required": true, "default": null, "description": "Current value for each parameter id. A seed is a number when Fixed is on and null when it is off." }, { "name": "onChange", "type": "(values: ParameterValues) => void", "required": true, "default": null, "description": "Called with a new values object whenever one control changes." }, { "name": "onGenerate", "type": "(values: ParameterValues) => void", "required": true, "default": null, "description": "Called with the current values when the form is submitted. Not called while busy." }, { "name": "estimateCost", "type": "(values: ParameterValues) => number", "required": false, "default": null, "description": "Returns the cost for the current values. Without it the readout is empty." }, { "name": "formatCost", "type": "(cost: number) => string", "required": false, "default": "`About ${cost} credits`", "description": "Formats the readout text." }, { "name": "title", "type": "string", "required": false, "default": "\"Settings\"", "description": "Heading, also the accessible name of the form." }, { "name": "generateLabel", "type": "string", "required": false, "default": "\"Generate\"", "description": "Text on the submit button." }, { "name": "busyLabel", "type": "string", "required": false, "default": "\"Generating…\"", "description": "Button text while busy." }, { "name": "busy", "type": "boolean", "required": false, "default": null, "description": "Disables Generate and shows a spinner." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the form, for width." } ], "variantsHint": {}, "tokens": [ "--surface", "--surface-sunken", "--border", "--lime", "--on-lime", "--fg-muted", "--shadow-sm", "--radius-control", "--radius-field", "--radius-card" ], "related": [ "prompt-box", "segmented-control", "variation-actions" ], "composedOf": [ "segmented-control", "switch", "button", "spinner" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Video settings with cost", "description": "Length, shape and a repeat code. The cost changes when the length changes.", "code": "const params: ParameterSpec[] = [\n { kind: \"segmented\", id: \"duration\", label: \"Duration\", options: [{ value: \"5\", label: \"5 s\" }, { value: \"10\", label: \"10 s\" }] },\n { kind: \"aspect\", id: \"ratio\", label: \"Shape\", options: [\"16:9\", \"9:16\", \"1:1\", \"4:3\"].map((r) => ({ value: r, label: r })) },\n { kind: \"seed\", id: \"seed\", label: \"Repeat code\", defaultSeed: 4821 },\n];\nconst [values, setValues] = useState({ duration: \"5\", ratio: \"16:9\", seed: null });\n\n {}} estimateCost={(v) => Number(v.duration) * 12} />" }, { "title": "Style buttons, a number and a busy state", "description": "Custom cost text and button text. While busy, the button is off and shows a spinner.", "code": "const params: ParameterSpec[] = [\n { kind: \"presets\", id: \"style\", label: \"Style\", options: [{ value: \"photo\", label: \"Photo\" }, { value: \"ink\", label: \"Ink\" }, { value: \"paper\", label: \"Paper cut\" }] },\n { kind: \"number\", id: \"count\", label: \"Images\", min: 1, max: 4, step: 1, unit: \"images\" },\n];\nconst [values, setValues] = useState({ style: \"photo\", count: 2 });\n\n {}} estimateCost={(v) => Number(v.count) * 4}\n formatCost={(c) => `${c} credits for this run`} generateLabel=\"Make images\" busy />" }, { "title": "One setting, no cost", "description": "With no cost given, that space stays empty. The repeat code starts fixed here, so the number shows.", "code": "const [values, setValues] = useState({ seed: 1234 });\n\n {}} />" } ], "pageUrl": "https://lkb00.github.io/tattva/component-parameter-panel/", "markdownUrl": "https://lkb00.github.io/tattva/docs/parameter-panel.md" }, { "id": "variation-actions", "name": "VariationActions", "level": "molecule", "since": "0.5", "aka": [ "more like this", "upscale", "variation buttons" ], "category": "creating", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "disabled", "note": "Set with the disabled prop.", "source": "prop" } ], "summary": "A row of things you can do with one AI result, each with a Subtle or Strong choice, and a line saying where it came from.", "description": "VariationActions lists things to do with one result, such as Vary, Upscale, Remix and Extend. Each has its own strength choice. A line says which result this one came from, and each action can show what it costs. You can change the list, and drop the strength choice where it is not needed.", "purpose": "A row of things to do with one result, such as Vary or Upscale. Each action keeps its own strength choice and shows its cost beside it, so nothing is charged by surprise.", "useFor": [ "Under a generated image or clip, to make a new take from it.", "Showing what each action costs before it runs.", "Saying which result this one came from, with the lineage line." ], "notFor": [ { "text": "Settings for something not made yet", "use": "parameter-panel" }, { "text": "Copy, retry and feedback on a chat reply", "use": "message-actions" }, { "text": "Choosing between several results side by side", "use": "variant-grid" } ], "whenToUse": [ "Say which result this one came from.", "Show what each action costs, if it costs anything.", "Keep the strength choice next to the action it changes.", "Hide the strength choice for actions that do not have one." ], "avoid": [ "Do not run an action when someone changes strength. Only the action button does that.", "Do not put more than a handful of actions in one row.", "Do not hide costs and charge afterward.", "Do not use the \"came from\" line as decoration. Leave it out when the result has no source." ], "accessibility": [ "Each strength choice is named after its action, such as \"Vary strength\". Arrow keys move and choose.", "Actions are real buttons with visible words.", "Each action keeps its own strength, so changing one never changes another.", "Changing a strength never runs an action. Only the action button does." ], "accessibilityYouDo": [ "Write each cost in words, such as \"About 4 credits\", so it reads clearly aloud.", "Tell people when an action starts and when it is done. The row does not announce anything." ], "onPhone": [ "Each action is its own row: the button, its strength switch and its cost wrap onto new lines when the row is full.", "Buttons and switch options keep their size and have a 44px tap area on a touch screen." ], "importPath": "import { VariationActions } from \"./index\"", "sourcePath": "src/molecules/VariationActions.tsx", "props": [ { "name": "actions", "type": "VariationAction[]", "required": false, "default": "Vary, Upscale, Remix, Extend", "description": "Each action has an id, a label, an optional cost node and an optional strength flag. Set strength to false to hide the choice." }, { "name": "onAction", "type": "(actionId: string, strength: string) => void", "required": true, "default": null, "description": "Called when an action button is pressed. Strength is an empty string for actions with no strength choice." }, { "name": "strengths", "type": "SegmentOption[]", "required": false, "default": "Subtle, Strong", "description": "Strength choices shared by all actions that have one." }, { "name": "defaultStrength", "type": "string", "required": false, "default": null, "description": "Strength each action starts on. Defaults to the first strength." }, { "name": "lineage", "type": "ReactNode", "required": false, "default": null, "description": "Line above the actions, for example Made from Variant B." }, { "name": "disabled", "type": "boolean", "required": false, "default": null, "description": "Disables the action buttons." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the wrapper." } ], "variantsHint": {}, "tokens": [ "--fg-muted", "--fg-subtle", "--border", "--surface-sunken" ], "related": [ "segmented-control", "variant-grid", "parameter-panel" ], "composedOf": [ "button", "segmented-control" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Standard actions, with where it came from", "description": "The standard list is Vary, Upscale, Remix and Extend. Extend has no strength choice.", "code": " {}} />" }, { "title": "Showing costs", "description": "Each action can show a cost. Use it to say what the action will spend.", "code": " {}}\n actions={[\n { id: \"vary\", label: \"Vary\", cost: \"About 4 credits\" },\n { id: \"upscale\", label: \"Upscale\", cost: \"About 8 credits\" },\n { id: \"remix\", label: \"Remix\", cost: \"About 4 credits\" },\n ]}\n/>" }, { "title": "Your own strengths, switched off", "description": "Your own strength choices, starting on the second one. Disabled turns the buttons off.", "code": " {}}\n strengths={[{ value: \"low\", label: \"Low\" }, { value: \"mid\", label: \"Medium\" }, { value: \"high\", label: \"High\" }]}\n defaultStrength=\"mid\"\n actions={[{ id: \"vary\", label: \"Vary\" }]}\n disabled\n/>" } ], "pageUrl": "https://lkb00.github.io/tattva/component-variation-actions/", "markdownUrl": "https://lkb00.github.io/tattva/docs/variation-actions.md" }, { "id": "version-history", "name": "VersionHistory", "level": "organism", "since": "0.5", "aka": [ "history", "revisions", "versions" ], "category": "creating", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "current", "note": "The version matching currentId (or the first one) shows a Current badge and has no Preview or Restore buttons.", "source": "documented" }, { "name": "previewing", "note": "Pressing Preview marks that row, and shows a bar above the list with Exit preview and Restore.", "source": "documented" }, { "name": "hover", "note": "A row that is not being previewed gets a soft background under the pointer.", "source": "documented" } ], "summary": "A list of earlier versions of your work, with who made each, when, and Preview and Restore buttons.", "description": "VersionHistory lists versions with the newest first. The oldest is Version 1. Each row shows who made it (AI or a person), when, and an optional short note. Preview shows an older version with a banner and an Exit preview button. Preview does not create a new version, and the list says so. Restore brings that version back.", "purpose": "Lists earlier versions of a piece of work, newest first, with who made each one. Preview and Restore are separate, so people can look without changing anything.", "useFor": [ "A document, design or page that both the AI and people edit.", "Looking at an older version before deciding to bring it back.", "Telling AI edits apart from people's edits." ], "notFor": [ { "text": "Versions of one chat message", "use": "version-pager" }, { "text": "Going back to an earlier step of an agent's work", "use": "checkpoint-list" }, { "text": "Undoing one AI edit to a short text", "use": "revert-toggle" } ], "whenToUse": [ "Mark the current version in words, with no buttons on it.", "Say that Preview does not create a version, so people feel safe trying it.", "Show who made each version, so AI edits and human edits are easy to tell apart.", "Show the previewed version in your own screen. The list only tells you which one through onPreviewChange." ], "avoid": [ "Do not restore when someone only previews. They are different actions.", "Do not put the oldest version first. The numbering expects newest first.", "Do not use amber on the preview banner. Nothing is waiting on the person.", "Do not hide the banner. People need a clear way out of a preview." ], "accessibility": [ "Versions are a numbered list, and the current one is marked for screen readers.", "Preview and Restore buttons include the version name, such as \"Preview Version 3\".", "Each Preview button tells screen readers whether it is on.", "Starting a preview is announced as \"Previewing\" and the version name.", "Who made each version and which one is current are said in words, not color.", "After a restore, keyboard focus moves to the restored version and screen readers hear \"Restored\" and its name. Leaving a preview from the bar returns focus to that version's Preview button." ], "accessibilityYouDo": [ "Keep version names and summaries short, so the button names stay easy to hear.", "Set restoredMessage when you translate." ], "onPhone": [ "Each version is a row whose text has a 192px minimum width, so Preview and Restore wrap below the text on a narrow screen.", "Preview and Restore keep their size and have a 44px tap area on a touch screen.", "The preview bar at the top wraps, with its buttons under the text when needed." ], "importPath": "import { VersionHistory } from \"./index\"", "sourcePath": "src/organisms/VersionHistory.tsx", "props": [ { "name": "versions", "type": "VersionEntry[]", "required": true, "default": null, "description": "Newest first. Each entry has an id, time, author (ai or person) and optional name, authorName and summary. A missing name becomes Version N." }, { "name": "currentId", "type": "string", "required": false, "default": null, "description": "Id of the current version. Defaults to the first entry." }, { "name": "previewId", "type": "string | null", "required": false, "default": null, "description": "Controlled preview. Omit to let the component manage it." }, { "name": "onPreviewChange", "type": "(id: string | null) => void", "required": false, "default": null, "description": "Called when a preview starts or exits." }, { "name": "onRestore", "type": "(id: string) => void", "required": true, "default": null, "description": "Called when Restore is pressed on a row or in the banner." }, { "name": "title", "type": "string", "required": false, "default": "\"Version history\"", "description": "Heading and accessible name of the section." }, { "name": "previewNote", "type": "string", "required": false, "default": "\"Preview does not create a new version.\"", "description": "Note under the list and in the preview banner." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the section." } ], "variantsHint": {}, "tokens": [ "--surface", "--surface-sunken", "--surface-hover", "--border", "--lime (via Badge)", "--radius-card" ], "related": [ "canvas-panel", "badge", "variation-actions" ], "composedOf": [ "badge", "button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "List with preview", "description": "Press Preview on any older version. The banner offers Exit preview and Restore. Restore makes that version the current one.", "code": "const [previewId, setPreviewId] = useState(null);\nconst [currentId, setCurrentId] = useState(versions[0].id);\n\n { setCurrentId(id); setPreviewId(null); }} />" }, { "title": "Already previewing", "description": "The same list already showing a preview, as when someone arrives from a link.", "code": "const [previewId, setPreviewId] = useState(\"v2\");\nconst [currentId, setCurrentId] = useState(versions[0].id);\n\n { setCurrentId(id); setPreviewId(null); }} />" }, { "title": "Your own names", "description": "The list handles previews itself. A name you give replaces the automatic one.", "code": "
\n {}}\n />\n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-version-history/", "markdownUrl": "https://lkb00.github.io/tattva/docs/version-history.md" }, { "id": "generation-progress", "name": "GenerationProgress", "level": "molecule", "since": "0.5", "aka": [ "progress", "generating", "render progress", "progress bar" ], "category": "creating", "status": "experimental", "lifecycle": { "stage": "experimental", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "status", "note": "Set with the status prop.", "source": "prop" }, { "name": "error", "note": "Set with the error prop.", "source": "prop" } ], "summary": "Shows how a slow AI task is going: waiting, making it, ready to listen early, finishing, done, failed or cancelled.", "description": "GenerationProgress shows where a slow task stands. While it works, it shows a bar with a percent, or a moving bar if the percent is not known. A gray placeholder holds the space for the result. It shows the time left and a Cancel button while work is under way, and swaps in the result when done. For audio, the placeholder is a flat waveform with a label, a streaming status lets people listen before the end is made, and a note can say what cancelling does to their credits. Screen readers hear the status only when it changes, never every percent.", "purpose": "Shows where a slow task stands, from waiting to done or failed. A placeholder the same shape as the result holds its place, so the page does not jump when it arrives.", "useFor": [ "Making an image, video or file that takes more than a few seconds.", "Waiting in line before the work starts: show the queue position.", "A task that can fail and be tried again.", "A song, voice-over or sound effect: use previewShape=\"audio\", and streaming when the start can be played early." ], "notFor": [ { "text": "A short wait for a chat reply", "use": "typing-indicator" }, { "text": "A list of steps an agent is working through", "use": "checklist" }, { "text": "An amount used out of a limit", "use": "meter" } ], "whenToUse": [ "Make the result area the same shape as the result, so the page does not jump.", "Offer Cancel for anything that takes more than a few seconds.", "Say why it failed.", "Pass percent only when you know the real progress. Without it, a moving bar shows instead.", "For audio, use previewShape=\"audio\" and say what is coming in previewLabel, such as \"Song, about 2 minutes\".", "Say what cancelling does to credits with refundNote, when you know it." ], "avoid": [ "Do not fake a percent. Use the moving bar instead.", "Do not announce every percent change. This component already avoids that.", "Do not use amber for waiting in line. Waiting is not something the person must act on.", "Do not remove Cancel once the task has started.", "Do not autoplay streaming audio. Offer Listen now and let the person press it.", "Do not draw a fake waveform in the placeholder. The flat bars say the sound is not there yet." ], "accessibility": [ "Screen readers hear the status only when it changes, such as \"Generating\" or \"Done\", never each percent.", "The visible status line is hidden from screen readers, so nothing is said twice.", "The percent bar is a meter named \"Generation progress\".", "A failure shows an icon and the words \"Generation failed\", not color alone.", "The placeholder is hidden from screen readers, and its shimmer stops when people turn off motion in their system settings.", "The audio placeholder's label is plain text; its flat bars are hidden from screen readers.", "Cancelled shows an icon and the word Cancelled, and the announcement includes the credits note.", "Listen now, Cancel, Retry and Start again are 44px tall on a touch screen." ], "accessibilityYouDo": [ "Pass error with a reason, so screen readers hear why it failed.", "Give the finished result its own text alternative.", "Pass refundNote only when your product knows whether cancelling returns credits. Never guess.", "Listen now must not start playback by itself somewhere off screen. Move focus to the player you show." ], "onPhone": [ "The preview area and the status line fill the width; the status text, time left and action wrap onto new lines.", "The preview area takes its height from the class you pass, so size it for a narrow screen.", "Action buttons are 44px tall on a touch screen and wrap onto a new line when space is short.", "The audio placeholder fills the width at a fixed short height, so it does not take a 16:9 block on a phone." ], "importPath": "import { GenerationProgress } from \"./index\"", "sourcePath": "src/molecules/GenerationProgress.tsx", "props": [ { "name": "status", "type": "\"queued\" | \"generating\" | \"streaming\" | \"finalising\" | \"done\" | \"failed\" | \"cancelled\"", "required": true, "default": null, "description": "Current state. streaming: the start can already be played while the rest is made. cancelled: the person stopped it." }, { "name": "percent", "type": "number", "required": false, "default": null, "description": "0 to 100. A bar shows while generating or streaming. Omit for an indeterminate bar." }, { "name": "queuePosition", "type": "number", "required": false, "default": null, "description": "Shown beside Queued." }, { "name": "eta", "type": "string", "required": false, "default": null, "description": "Time estimate, shown while queued, generating, streaming or finalising." }, { "name": "error", "type": "string", "required": false, "default": null, "description": "Message shown, and announced, when failed." }, { "name": "onCancel", "type": "() => void", "required": false, "default": null, "description": "Shows Cancel while queued, generating, streaming or finalising." }, { "name": "onRetry", "type": "() => void", "required": false, "default": null, "description": "Shows Retry when failed, and Start again when cancelled." }, { "name": "onListen", "type": "() => void", "required": false, "default": null, "description": "Shows Listen now while streaming. Start playback only from this press." }, { "name": "listenLabel", "type": "string", "required": false, "default": "\"Listen now\"", "description": "Text for the Listen now button." }, { "name": "preview", "type": "ReactNode", "required": false, "default": null, "description": "Result shown when done, and while streaming if you pass a player that can play early. A placeholder fills the area before then." }, { "name": "previewShape", "type": "\"media\" | \"audio\"", "required": false, "default": "\"media\"", "description": "audio swaps the 16:9 block for a flat waveform with a label." }, { "name": "previewLabel", "type": "string", "required": false, "default": "\"The audio will appear here\"", "description": "Words in the audio placeholder, such as \"Song, about 2 minutes\"." }, { "name": "previewClassName", "type": "string", "required": false, "default": "\"aspect-video\" (media), none (audio)", "description": "Classes for the preview area, to match the result shape." }, { "name": "refundNote", "type": "string", "required": false, "default": null, "description": "What cancelling does to credits. Shown next to Cancel while work runs and after cancelling, and read out with Cancelled." }, { "name": "labels", "type": "Partial>", "required": false, "default": null, "description": "Replaces the text for a status. Also used for the announcement." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the wrapper." } ], "variantsHint": { "status": [ "queued", "generating", "streaming", "finalising", "done", "failed", "cancelled" ], "previewShape": [ "media", "audio" ] }, "tokens": [ "--surface", "--surface-sunken", "--border", "--fg-subtle", "--danger-fg", "--radius-card" ], "related": [ "meter", "skeleton", "variant-grid" ], "composedOf": [ "meter", "skeleton", "button" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Try each state", "description": "Switch the state to see each one. The percent bar shows only while making it, with a percent.", "code": " {}} />" }, { "title": "Progress not known", "description": "Leave out the percent when progress is not known.", "code": " {}} />" }, { "title": "Waiting in line", "description": "Shows your place in line and no bar.", "code": " {}} />" }, { "title": "Failed", "description": "Failed shows the message in words and offers Retry.", "code": " {}} />" }, { "title": "Audio: listen before it is finished", "description": "Streaming means the start can be played while the rest is still being made. Listen now never plays on its own; the person presses it. The credits note sits next to Cancel.", "code": " {}} onCancel={() => {}}\n refundNote=\"Credits for started work are not returned.\" />" }, { "title": "Audio: queued and cancelled", "description": "previewShape audio swaps the 16:9 block for a flat waveform with a label. After Cancel the note says what happened to the credits, and Start again is offered.", "code": " {}} refundNote=\"Cancelling now returns your 40 credits.\" />\n {}}\n refundNote=\"Your 40 credits were returned.\" />" } ], "pageUrl": "https://lkb00.github.io/tattva/component-generation-progress/", "markdownUrl": "https://lkb00.github.io/tattva/docs/generation-progress.md" }, { "id": "starter-gallery", "name": "StarterGallery", "level": "organism", "since": "0.5", "aka": [ "prompt gallery", "templates", "examples gallery" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "no templates", "note": "Without templates, the templates section and its heading are left out.", "source": "documented" }, { "name": "hover", "note": "A template card gets a stronger border and a soft background under the pointer.", "source": "documented" }, { "name": "focus", "note": "Intent buttons and template cards show a focus ring on keyboard focus.", "source": "documented" } ], "summary": "A first screen that says what the assistant can do, and offers ideas to start with.", "description": "StarterGallery is for when nothing has been started yet. It opens with one sentence on what the assistant can and cannot do. Then it offers a few ideas as buttons, then template cards with a title, a short note and an optional category. A Shuffle button can sit beside the templates heading. Every control is a real button you can reach with Tab.", "purpose": "The first screen, before anything exists. It says plainly what the assistant can and cannot do, then offers ideas and templates so people do not face an empty box.", "useFor": [ "A first visit, or any time nothing has been made yet.", "Offering three to six ideas next to the box where people type.", "A set of templates people can start from." ], "notFor": [ { "text": "Ideas shown under a reply, partway through a chat", "use": "suggestion-chips" }, { "text": "A list or search that has nothing to show", "use": "empty-state" } ], "whenToUse": [ "Say what the assistant cannot do as well as what it can.", "Offer three to six starting ideas next to the box where people type.", "Write template notes that say what the person gets.", "Show it on the first screen and when nothing exists yet, not everywhere." ], "avoid": [ "Do not list more than six ideas. Move the rest into templates.", "Do not use the opening sentence for advertising.", "Do not use amber on cards. Nothing here needs action.", "Do not hide the box where people type behind the gallery." ], "accessibility": [ "The section is named by its heading.", "Ideas and templates are lists, so screen readers say how many there are.", "Ideas and template cards are real buttons, reached with Tab and used with Enter or Space.", "A template card is read as its category, then its title, then its note.", "When the templates change, for example after Shuffle, screen readers hear it.", "If the gallery goes away after an idea or template is chosen, keyboard focus moves to the nearest message box. Pass focusAfterChoose to choose another place." ], "accessibilityYouDo": [ "Give the Shuffle button a clear name, such as \"Show other templates\".", "Write the statement as one plain sentence that is clear when heard on its own." ], "onPhone": [ "The templates show in one column below 640px, then two columns, then three from 1024px.", "Each template card is a full-width button, and the intent buttons wrap across the width.", "The intent buttons keep their size and have a 44px tap area on a touch screen." ], "importPath": "import { StarterGallery } from \"./index\"", "sourcePath": "src/organisms/StarterGallery.tsx", "props": [ { "name": "heading", "type": "string", "required": false, "default": "\"What would you like to make?\"", "description": "Serif heading and accessible name of the section." }, { "name": "statement", "type": "ReactNode", "required": true, "default": null, "description": "One sentence on what the assistant can and cannot do." }, { "name": "intents", "type": "StarterIntent[]", "required": true, "default": null, "description": "Starter intents with an id and a label. Three to six works best." }, { "name": "onIntent", "type": "(id: string) => void", "required": true, "default": null, "description": "Called when an intent is pressed." }, { "name": "templates", "type": "StarterTemplate[]", "required": false, "default": "[]", "description": "Cards with an id, title, description and optional category. The section is hidden when empty." }, { "name": "onTemplate", "type": "(id: string) => void", "required": false, "default": null, "description": "Called when a template card is pressed." }, { "name": "intentsLabel", "type": "string", "required": false, "default": "\"Start with\"", "description": "Label above the intents." }, { "name": "templatesLabel", "type": "string", "required": false, "default": "\"Templates\"", "description": "Label above the templates." }, { "name": "randomize", "type": "ReactNode", "required": false, "default": null, "description": "Slot beside the templates label, for a Randomize button." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the section." } ], "variantsHint": {}, "tokens": [ "--surface", "--surface-hover", "--border", "--border-strong", "--fg-muted", "--radius-card" ], "related": [ "prompt-box", "suggestion-chips", "tray" ], "composedOf": [ "button", "badge" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Ideas and templates", "description": "A sentence on what it can do, three ideas and three templates with categories.", "code": " {}}\n templates={[\n { id: \"a\", title: \"Weekly update\", description: \"Share progress with your team.\", category: \"Writing\" },\n { id: \"b\", title: \"Meeting notes\", description: \"Turn rough notes into clear actions.\", category: \"Work\" },\n { id: \"c\", title: \"Product description\", description: \"Describe an item in a few lines.\", category: \"Marketing\" },\n ]}\n onTemplate={() => {}}\n/>" }, { "title": "With a Shuffle button", "description": "Add a button for shuffling. Here it swaps the templates.", "code": " {}}\n templates={picked.map((t, i) => ({ id: `${n}-${i}`, title: t, description: \"A starting point you can change.\" }))}\n onTemplate={() => {}}\n randomize={}\n/>" }, { "title": "Ideas only", "description": "Leave out the templates for a shorter first screen.", "code": " {}} />" } ], "pageUrl": "https://lkb00.github.io/tattva/component-starter-gallery/", "markdownUrl": "https://lkb00.github.io/tattva/docs/starter-gallery.md" }, { "id": "popover", "name": "Popover", "level": "atom", "since": "0.5", "aka": [ "popup", "flyout", "dropdown panel" ], "category": "controls", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "open or closed", "note": "Set with the open prop.", "source": "prop" }, { "name": "closing", "note": "After open turns false the panel stays for --dur-fast while it fades out, and it cannot be pressed. Under reduced motion it goes at once.", "source": "documented" } ], "summary": "A small panel that opens beside a button, for menus, pickers and short explanations.", "description": "Popover shows a button and, when open, a panel just below or above it. If the panel would run off the screen, it opens on the other side and stays a little away from the edges. When it opens, your cursor moves into the panel. When it closes, the cursor returns to the button and the panel fades out quickly. Menus and lists add arrow keys, Home and End, and Tab leaves the menu. It can manage itself, or your app can open and close it.", "purpose": "A small panel that opens beside a button, for menus, pickers and short explanations. Focus moves in when it opens and back when it closes, so keyboard users keep their place.", "useFor": [ "A menu of actions behind a button.", "A list of options to pick from, such as a style or a size.", "A short explanation or a few settings that open from a button." ], "notFor": [ { "text": "Something people must answer before going on. Use a dialog" }, { "text": "Actions on text the person has selected", "use": "selection-toolbar" } ], "whenToUse": [ "Give the button its screen reader details, so it says whether the panel is open.", "Give the panel a name that says what it holds.", "Use a menu for a list of actions and a list box for a list of options, so arrow keys work.", "Keep panels narrower than the screen. A panel wider than the screen still runs off the right edge.", "Open upward near the bottom of a screen. Automatic flipping covers cases you did not plan for." ], "avoid": [ "Do not use it for something people must answer. Use a dialog.", "Do not put one popover inside another.", "Do not use an icon-only button without a name.", "Do not rely on pointing to open it.", "Do not use a menu or list box for content that is not a list of items. Use the default panel." ], "accessibility": [ "When the panel opens, focus moves into it: to the chosen or first item in a menu or list, or to the first control in other panels.", "Escape closes the panel and returns focus to the button.", "In menus and lists, the up and down arrows move between items and wrap around. Home and End jump to the ends, and unavailable items are skipped.", "In a menu or list, Tab closes it and moves on from the button.", "The panel has a name, and it flips to the other side when it would run off the screen.", "Closing is a quick plain fade in --dur-fast, faster than opening. The panel cannot be pressed while it fades. When people turn off motion in their system settings, it goes at once." ], "accessibilityYouDo": [ "Spread triggerProps onto your button, so screen readers hear whether the panel is open.", "Give the button a name, even when it shows only an icon.", "Set role to \"menu\" for actions or \"listbox\" for options, and give each item the matching item role, so the arrow keys work." ], "onPhone": [ "Menus open as a bottom sheet with a backdrop on a narrow touch screen, kept within thumb reach and padded for the bottom safe area.", "Other roles, such as a dialog or listbox, stay anchored to the trigger unless you set phoneSheet; they are at least 224px wide and move to stay inside the screen edges.", "It closes when a finger touches outside it, and the sheet scrolls inside itself at up to 80% of the screen height.", "Give an anchored panel inside a scrolling or clipped parent the portal prop so it is not cut off." ], "importPath": "import { Popover } from \"./index\"", "sourcePath": "src/atoms/Popover.tsx", "props": [ { "name": "trigger", "type": "(api: PopoverTriggerApi) => ReactNode", "required": true, "default": null, "description": "Render function. Receives open, toggle and triggerProps with aria-expanded, aria-haspopup and aria-controls." }, { "name": "children", "type": "ReactNode | ((api: { close: () => void }) => ReactNode)", "required": true, "default": null, "description": "Panel content. A function receives close." }, { "name": "label", "type": "string", "required": true, "default": null, "description": "Accessible name for the panel." }, { "name": "align", "type": "\"start\" | \"end\"", "required": false, "default": "\"start\"", "description": "Which edge of the trigger the panel lines up with." }, { "name": "side", "type": "\"bottom\" | \"top\"", "required": false, "default": "\"bottom\"", "description": "Whether the panel opens below or above the trigger." }, { "name": "role", "type": "\"dialog\" | \"menu\" | \"listbox\"", "required": false, "default": "\"dialog\"", "description": "Role on the panel, also used for aria-haspopup on the trigger." }, { "name": "open", "type": "boolean", "required": false, "default": null, "description": "Controlled mode. Omit to let the popover manage itself." }, { "name": "onOpenChange", "type": "(open: boolean) => void", "required": false, "default": null, "description": "Called when the panel opens or closes." }, { "name": "autoFocus", "type": "boolean", "required": false, "default": "true", "description": "Moves focus into the panel when it opens. Menu and listbox panels focus the checked radio or selected option, or else the first enabled item. Dialog panels focus the first focusable element, or the panel itself if there is none. Set false when the opener manages focus." }, { "name": "flip", "type": "boolean", "required": false, "default": "true", "description": "After the panel mounts it is measured. If the preferred side overflows the viewport and the other side has more room, the panel opens there. It is also kept 8px inside the left and right viewport edges." }, { "name": "portal", "type": "boolean", "required": false, "default": "false", "description": "Draws the panel on the page itself (fixed position) so a scrolling or clipped parent can never cut it off. Use it for menus inside lists and side bars. The panel keeps its place as the page scrolls or resizes." }, { "name": "phoneSheet", "type": "boolean", "required": false, "default": "true for menus", "description": "On a phone (a narrow touch screen) the panel opens as a bottom sheet with a backdrop, within thumb reach. On by default when role is menu. Set false to keep it floating." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Classes for the wrapper." }, { "name": "panelClassName", "type": "string", "required": false, "default": null, "description": "Classes for the panel, for example to set a width." } ], "variantsHint": { "align": [ "start", "end" ], "side": [ "bottom", "top" ], "role": [ "dialog", "menu", "listbox" ] }, "tokens": [ "--surface-raised", "--border", "--shadow-lg", "--dur-fast", "--radius-overlay" ], "related": [ "segmented-control", "kbd" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Basic panel", "description": "Give the button its screen reader details and open the panel on click.", "code": " }>\n

Cost depends on duration.

\n" }, { "title": "A menu that closes when you pick", "description": "The panel can close itself when you pick something. Use a menu for a list of actions.", "code": " }>\n {({ close }) => (\n
\n \n \n
\n )}\n" }, { "title": "Opens upward", "description": "Open upward when the button is near the bottom of the screen. If the panel still does not fit, it opens downward.", "code": " }>\n

Press Esc to close.

\n" }, { "title": "Near the edge of the screen", "description": "A wide panel on a button at the right edge. It would run past the edge, so it shifts left to stay on screen.", "code": "
\n }>\n

Anyone with the link can view this. The panel shifts left to stay on screen.

\n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-popover/", "markdownUrl": "https://lkb00.github.io/tattva/docs/popover.md" }, { "id": "segmented-control", "name": "SegmentedControl", "level": "atom", "since": "0.5", "aka": [ "segmented button", "toggle group", "button group", "radio buttons" ], "category": "controls", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "selected", "note": "The option matching value gets a raised surface and is the one tab stop. When the choice changes, the raised surface slides to the new option in --dur-base. In forced colours the chosen option gets a border instead.", "source": "documented" }, { "name": "hover", "note": "An unselected option's text darkens under the pointer.", "source": "documented" }, { "name": "keyboard", "note": "Arrow keys, Home and End move to another option and select it.", "source": "documented" }, { "name": "focus", "note": "A visible focus ring appears on the focused option.", "source": "documented" } ], "summary": "A row of joined buttons where you pick one option, using clicks or arrow keys.", "description": "SegmentedControl is a set of options drawn as joined buttons. You can pick only one. Arrow keys move and choose, Home and End jump to the first and last, and Tab stops only on the chosen one. The raised background slides to the new choice. Options can have a short hint that shows on hover.", "purpose": "A row of joined buttons for picking one of a few short options. All the options stay in view, so people see their choice next to the others.", "useFor": [ "Two to five short options where only one can be chosen, such as a length or a view.", "A setting inside a crowded row: use the small size.", "Switching between two versions of the same content." ], "notFor": [ { "text": "Turning one thing on or off", "use": "switch" }, { "text": "Running an action", "use": "button" }, { "text": "Many options that will not fit on one line" } ], "whenToUse": [ "Use it for two to five short options where only one can be chosen.", "Give the group a name that says what is being chosen.", "Keep words short so the group stays on one line.", "Use the small size inside crowded rows." ], "avoid": [ "Do not use it for actions. Use buttons.", "Do not use it for many options. The group does not wrap to a new line.", "Do not choose a value that is not in the list. Nothing would be reachable with Tab.", "Do not use it for on and off. Use Switch." ], "accessibility": [ "Screen readers hear a named group of options, and which one is chosen.", "Arrow keys move and choose, and wrap around at the ends. Home and End jump to the first and last.", "Tab stops once on the chosen option, so the group takes one Tab to enter and one to leave.", "The chosen option is shown by a raised background and shadow, not by text color alone.", "The raised background slides to the new choice in --dur-base on --ease-arrive. It does not slide when it is first placed, and it moves at once when people turn off motion in their system settings.", "In forced-colors mode the sliding background is hidden and the chosen option gets a border in the system highlight color." ], "accessibilityYouDo": [ "Give the group a label that says what is being chosen.", "Keep option words short and clear on their own. The hint shows only on hover." ], "onPhone": [ "The options sit in one row that scrolls sideways when it is wider than the screen, so keep to two or three short labels to avoid hidden options.", "Each option keeps its size and has a 44px tap area on a touch screen.", "An option description is set as a title only, which a finger cannot show." ], "importPath": "import { SegmentedControl } from \"./index\"", "sourcePath": "src/atoms/SegmentedControl.tsx", "props": [ { "name": "options", "type": "SegmentOption[]", "required": true, "default": null, "description": "Each option has a value, a label and an optional description used as a title." }, { "name": "value", "type": "T", "required": true, "default": null, "description": "Selected value." }, { "name": "onChange", "type": "(value: T) => void", "required": true, "default": null, "description": "Called on click and on arrow, Home and End keys." }, { "name": "label", "type": "string", "required": true, "default": null, "description": "Accessible name for the group." }, { "name": "size", "type": "\"sm\" | \"md\"", "required": false, "default": "\"md\"", "description": "Pill size." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the group." } ], "variantsHint": { "size": [ "sm", "md" ] }, "tokens": [ "--surface-sunken", "--surface", "--border", "--fg-muted", "--shadow-sm", "--dur-fast", "--dur-base", "--ease-arrive", "--radius-control" ], "related": [ "switch", "parameter-panel", "variation-actions" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Default size", "description": "A group of three options.", "code": "const [v, setV] = useState(\"week\");\n\n" }, { "title": "Small size", "description": "The small size fits inside rows and panels.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-segmented-control/", "markdownUrl": "https://lkb00.github.io/tattva/docs/segmented-control.md" }, { "id": "meter", "name": "Meter", "level": "atom", "since": "0.5", "aka": [ "meter bar", "progress bar", "gauge", "capacity bar" ], "category": "numbers", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "warning", "note": "When warnAt is set and value divided by max reaches it, the fill changes to the attention colour.", "source": "documented" } ], "summary": "A thin bar that shows how much of something is used, and turns amber past a set point.", "description": "Meter is a thin bar that shows an amount out of a limit. It is dark by default and turns amber once it passes a set point. Use it for something with a limit, such as conversation space used. Show amber only when the person should act, and add words beside the bar that say why.", "purpose": "A thin bar for an amount out of a limit, such as space used in a chat. It stays dark and only turns amber past the point where the person should act.", "useFor": [ "Space used in a conversation, or credits used in a plan.", "Any amount with a known limit that people may need to act on.", "A building block inside a larger meter that adds words around it." ], "notFor": [ { "text": "A wait with no known end", "use": "spinner" }, { "text": "Progress of a slow AI task", "use": "generation-progress" }, { "text": "How full the chat is, with words and a Summarize button", "use": "context-meter" } ], "whenToUse": [ "Add words for the amount, so it makes sense when read aloud.", "Set a warning point only when the person can do something about it.", "Put words beside the bar that explain the warning.", "Set a limit for amounts that are not percents." ], "avoid": [ "Do not use it for a task with no known total. Use a moving indicator.", "Do not rely on amber alone for the warning.", "Do not use it for something with no limit.", "Do not announce every small change to screen readers." ], "accessibility": [ "Screen readers hear it as a meter with a name, a range and the current amount.", "When valueText is set, screen readers read it in place of the bare number.", "The grow-in motion stops when people turn off motion in their system settings." ], "accessibilityYouDo": [ "Give it a label that says what is measured.", "Pass valueText with words for the amount, such as \"68% of context\".", "Put words beside the bar that say why it turned amber. The color change is not announced." ], "onPhone": [ "The bar fills the width of its container and is 6px tall, which is a display, not a tap target.", "Show the value as text beside it, since a thumb covers a bar this thin." ], "importPath": "import { Meter } from \"./index\"", "sourcePath": "src/atoms/Meter.tsx", "props": [ { "name": "value", "type": "number", "required": true, "default": null, "description": "Current amount. The fill width is clamped between 0 and 100 percent of max." }, { "name": "max", "type": "number", "required": false, "default": "100", "description": "Amount that fills the bar." }, { "name": "label", "type": "string", "required": true, "default": null, "description": "Accessible name, such as Context used." }, { "name": "warnAt", "type": "number", "required": false, "default": null, "description": "Fraction of max, 0 to 1. At or above it the fill uses the attention color." }, { "name": "valueText", "type": "string", "required": false, "default": null, "description": "Text read out with the value, such as 68% of context." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the track." } ], "variantsHint": {}, "tokens": [ "--border", "--fg", "--attention", "--dur-base" ], "related": [ "generation-progress", "skeleton" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Plain", "description": "A dark fill, as wide as the amount used out of the limit.", "code": "" }, { "title": "Past the warning point", "description": "At 85 with a warning point of 80 percent, the fill turns amber. The words beside it say why.", "code": "
\n \n

85% used. Start a new chat soon.

\n
" }, { "title": "A limit other than 100", "description": "Set a limit when the amount is not a percent.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-meter/", "markdownUrl": "https://lkb00.github.io/tattva/docs/meter.md" }, { "id": "kbd", "name": "Kbd", "level": "atom", "since": "0.5", "aka": [ "key hint", "keyboard key", "keyboard shortcut", "shortcut hint", "hotkey" ], "category": "controls", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [], "summary": "A small key label, such as Tab or Esc, that shows which key to press.", "description": "Kbd shows a key name in a small outlined box. Put it next to the action the key does. The action must still be reachable without the key.", "purpose": "A small key label, such as Esc or Tab, set beside the action it triggers. It is only a hint: the action must also work without the key.", "useFor": [ "Beside a menu item or button that also has a keyboard shortcut.", "In help text that explains how to move around with the keyboard.", "Each key of a combination, one label per key." ], "notFor": [ { "text": "Something people click", "use": "button" }, { "text": "Labels that are not keyboard keys", "use": "badge" } ], "whenToUse": [ "Put it beside words that name the action.", "Use one label per key in a combination.", "Make every shortcut also work with a mouse or tap.", "Use short names such as Esc and Tab." ], "avoid": [ "Do not use it as a button. It does nothing when clicked.", "Do not show it on touch-only screens.", "Do not use it alone. Say what the key does.", "Do not use it for hints that are not about the keyboard." ], "accessibility": [ "It is marked up as a keyboard key, and screen readers read the key name as text.", "It cannot be reached with Tab and does nothing when clicked." ], "accessibilityYouDo": [ "Put words beside it that name the action. Screen readers read only the key name.", "Make the action work with a mouse or tap too.", "Hide it on touch-only screens, where there is no keyboard." ], "onPhone": [ "It is a small label for a keyboard key, and keyboard shortcuts do not apply on a phone, so hide it there or show it only where a keyboard is likely.", "Its text is 12px on a touch screen." ], "importPath": "import { Kbd } from \"./index\"", "sourcePath": "src/atoms/Kbd.tsx", "props": [ { "name": "children", "type": "ReactNode", "required": true, "default": null, "description": "Key label, such as Tab or Esc." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes merged onto the kbd element." } ], "variantsHint": {}, "tokens": [ "--surface", "--border-strong", "--fg-muted" ], "related": [ "popover", "segmented-control" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Single keys", "description": "Put the label next to the action it triggers.", "code": "

Press Esc to close

" }, { "title": "Combination", "description": "Use one label per key.", "code": "

Ctrl + EnterSend

" } ], "pageUrl": "https://lkb00.github.io/tattva/component-kbd/", "markdownUrl": "https://lkb00.github.io/tattva/docs/kbd.md" }, { "id": "illustration", "name": "Illustration", "level": "atom", "since": "0.5", "aka": [ "spot illustration", "artwork", "image" ], "category": "states", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [], "summary": "A small drawing for empty, error, permission and success screens, in dark lines with one green touch.", "description": "Illustration draws one idea for each name: a chat, a search, an error, a lock, a plug, an hourglass, a check, a tray or a flag. It uses dark lines on light fills and at most one green fill. Its colors follow light and dark mode. It is only decoration unless you give it a title.", "purpose": "A small drawing that sets the tone of an empty, error or success screen. It shows one idea in dark lines with one green touch, and follows light and dark mode.", "useFor": [ "An empty, first-use or cleared screen.", "An error, offline, permission or usage limit screen.", "Inside EmptyState, which picks a drawing for you." ], "notFor": [ { "text": "Small areas, headings or lists of features", "use": "pictogram" }, { "text": "A photo or generated image", "use": "media-frame" }, { "text": "An icon inside a button", "use": "icon-button" } ], "whenToUse": [ "Use it to support the words on a screen, never to replace them.", "Pick the drawing that matches the message, so the picture and words agree.", "Leave it as decoration when the words beside it already say everything.", "Show one drawing per area." ], "avoid": [ "Do not use it as decoration on busy screens.", "Do not add robots, brains, glowing orbs or sparkles to new drawings.", "Do not give it fixed colors. Use the theme colors so dark mode works.", "Do not use amber in the drawing. Amber is for words that ask a person to act." ], "accessibility": [ "Without a title, screen readers skip the drawing.", "With a title, screen readers read it as a picture and say the title.", "The keyboard never stops on it.", "The drawing does not move, so there is no motion to turn off." ], "accessibilityYouDo": [ "Leave out the title when the nearby words already say what happened, which should be almost always.", "Give a title only when the drawing adds meaning that the words do not." ], "onPhone": [ "Illustration is a fixed 64, 96 or 160px and does not scale with the screen, so choose 64 or 96 on a phone.", "It is not tappable and has no text, so nothing changes on touch screens." ], "importPath": "import { Illustration } from \"./index\"", "sourcePath": "src/atoms/Illustration.tsx", "props": [ { "name": "name", "type": "IllustrationName", "required": true, "default": null, "description": "One of empty-chat, no-results, error, permission, offline, rate-limit, success, upload, first-run." }, { "name": "size", "type": "64 | 96 | 160", "required": false, "default": "96", "description": "Rendered size in px. Sets the stroke weight too." }, { "name": "title", "type": "string", "required": false, "default": null, "description": "Accessible name. Without it the art is aria-hidden." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the svg element." } ], "variantsHint": { "size": [ 64, 96, 160 ] }, "tokens": [ "--fg", "--surface", "--surface-sunken", "--lime" ], "related": [ "pictogram", "empty-state" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Three sizes", "description": "Line thickness grows with size, so the drawing looks balanced at each size.", "code": "\n\n" }, { "title": "All names", "description": "Each name has one job. Pick the one that matches what is happening, not the one you like best.", "code": "{spotIllustrations.map((s) => (\n \n))}" }, { "title": "When the picture says something", "description": "A title lets screen readers describe the picture. Use it only when the picture says something the nearby words do not.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-illustration/", "markdownUrl": "https://lkb00.github.io/tattva/docs/illustration.md" }, { "id": "pictogram", "name": "Pictogram", "level": "atom", "since": "0.5", "aka": [ "icon illustration", "symbol" ], "category": "states", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [], "summary": "A one-color line icon, larger than a button icon, for small areas and lists of features.", "description": "Pictogram is a bigger, more detailed cousin of an icon. It is made of lines only and takes its color from the text around it. Use it where a full drawing is too much, such as small empty areas or a row of things the assistant can do.", "purpose": "A line drawing larger than an icon, for spots where a full illustration is too much. It takes the color of the text around it.", "useFor": [ "A row or grid of things the assistant can do.", "A small empty area where a full drawing would not fit.", "Beside a heading, to mark its topic." ], "notFor": [ { "text": "A full empty, error or success screen", "use": "illustration" }, { "text": "An icon inside a button", "use": "icon-button" } ], "whenToUse": [ "Put a visible label beside it.", "Use it in small empty areas where a full drawing would crowd the words.", "Use one size within a group." ], "avoid": [ "Do not use it as a button icon. Use a small icon.", "Do not fill its shapes. Pictograms stay as lines.", "Do not add any color except the text color." ], "accessibility": [ "Without a title, screen readers skip it.", "With a title, screen readers read it as a picture and say the title.", "The keyboard never stops on it.", "It uses the surrounding text color, so it follows the theme." ], "accessibilityYouDo": [ "Check that the text color it takes stands out against the background.", "Give a title only when it means something the nearby words do not say." ], "onPhone": [ "Pictogram is a fixed 32, 48 or 64px and looks the same on a phone.", "It is not tappable. If it starts something, wrap it in a button, which gets a 44px target on touch screens." ], "importPath": "import { Pictogram } from \"./index\"", "sourcePath": "src/atoms/Pictogram.tsx", "props": [ { "name": "name", "type": "PictogramName", "required": true, "default": null, "description": "One of chat, agent, document, image, code, data, search, shield, memory, voice, plan, tools." }, { "name": "size", "type": "32 | 48 | 64", "required": false, "default": "32", "description": "Rendered size in px." }, { "name": "title", "type": "string", "required": false, "default": null, "description": "Accessible name. Without it the pictogram is aria-hidden." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the svg element." } ], "variantsHint": { "size": [ 32, 48, 64 ] }, "tokens": [ "--fg", "--fg-muted" ], "related": [ "illustration", "empty-state" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Sizes", "description": "The lines get thicker as the picture grows, so it looks balanced at each size.", "code": "\n\n" }, { "title": "All names", "description": "", "code": "{pictogramNames.map((n) => )}" }, { "title": "Takes the text color", "description": "Set a text color on the area around it and the pictogram follows.", "code": "
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-pictogram/", "markdownUrl": "https://lkb00.github.io/tattva/docs/pictogram.md" }, { "id": "empty-state", "name": "EmptyState", "level": "molecule", "since": "0.5", "aka": [ "blank slate", "zero state", "no results", "no data", "first use" ], "category": "states", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "first use", "note": "The default variant shows an empty-chat drawing, a title and a short body for a first visit.", "source": "documented" }, { "name": "no results", "note": "Set variant to no-results for a search drawing; it is announced to screen readers as a status.", "source": "documented" }, { "name": "cleared", "note": "Set variant to cleared for a success drawing when everything is done.", "source": "documented" }, { "name": "error", "note": "Set variant to error for an error drawing and a message that the work is safe.", "source": "documented" }, { "name": "permission", "note": "Set variant to permission for a lock drawing and an Action needed tag.", "source": "documented" }, { "name": "offline", "note": "Set variant to offline for a plug drawing; it is announced as a status.", "source": "documented" }, { "name": "rate limit", "note": "Set variant to rate-limit for an hourglass drawing and an Action needed tag.", "source": "documented" }, { "name": "compact", "note": "Pass compact to drop the drawing and tighten the padding.", "source": "documented" } ], "summary": "A message for an area with nothing in it: a drawing, a title that says why, one line, and one button.", "description": "EmptyState has up to five parts: a drawing, a title, one line of text, one main button and an optional second link. Seven ready-made versions cover first use, no results, cleared, error, permission, offline and usage limit. Each says why the area is empty first, then what to do next. You can change every word.", "purpose": "Fills an area that has nothing to show with a reason and one next step. Saying the cause first stops people wondering whether something broke.", "useFor": [ "A first visit, before anything has been made.", "A search or filter with no results.", "An area where everything is done, or that cannot load, is private or is offline." ], "notFor": [ { "text": "A short error inside a page or reply", "use": "error-state" }, { "text": "A usage limit inside a chat", "use": "rate-limit-notice" }, { "text": "Content that is still loading", "use": "skeleton" } ], "whenToUse": [ "Say why in the title and what to do next on the button.", "Treat a filtered list differently from one that is truly empty.", "Offer one main button and at most one second link.", "Keep words short and plain, and never point to another part of the app as the only way out." ], "avoid": [ "Do not leave a dead end. Every screen needs a way forward, or a reason there is none.", "Do not use amber unless a person must act.", "Do not let the drawing be the only explanation.", "Do not use several drawings on one screen." ], "accessibility": [ "The title is a real heading.", "Screen readers announce it only for no results and offline, which follow something the person did or a change in the connection. The others are not announced every time a page loads.", "The built-in drawing is hidden from screen readers. A drawing you pass keeps its own name.", "The amber \"Action needed\" tag has an icon and words, so the need to act is not shown by color alone." ], "accessibilityYouDo": [ "Set headingLevel so the title fits the headings around it.", "Give the button or link you add words that name the next step.", "Turn on live when your own empty state appears after something the person did." ], "onPhone": [ "The panel fills the width, with the art, text and buttons stacked in one column.", "Text is capped at 44 characters wide and the title breaks anywhere, so long titles do not overflow.", "The action and secondary buttons wrap onto separate lines when they do not fit, and each button has a 44px tap area on touch screens." ], "importPath": "import { EmptyState } from \"./index\"", "sourcePath": "src/molecules/EmptyState.tsx", "props": [ { "name": "variant", "type": "\"first-use\" | \"no-results\" | \"cleared\" | \"error\" | \"permission\" | \"offline\" | \"rate-limit\"", "required": false, "default": "\"first-use\"", "description": "Sets default art, copy, tone and live behavior." }, { "name": "art", "type": "ReactNode | null", "required": false, "default": null, "description": "Replaces the variant's illustration. Pass an Illustration or a Pictogram, or null for none." }, { "name": "title", "type": "string", "required": false, "default": null, "description": "Names the cause or invites the first step. Defaults per variant." }, { "name": "children", "type": "ReactNode", "required": false, "default": null, "description": "One-line body with the next step. Defaults per variant." }, { "name": "action", "type": "ReactNode", "required": false, "default": null, "description": "The one primary action, usually a Button." }, { "name": "secondary", "type": "ReactNode", "required": false, "default": null, "description": "Optional secondary link or ghost button." }, { "name": "layout", "type": "\"center\" | \"start\"", "required": false, "default": "\"center\"", "description": "Center for full panels. Start left-aligns text in small areas." }, { "name": "compact", "type": "boolean", "required": false, "default": "false", "description": "Omits the art and tightens spacing." }, { "name": "headingLevel", "type": "2 | 3 | 4", "required": false, "default": "3", "description": "Heading level of the title." }, { "name": "live", "type": "boolean", "required": false, "default": null, "description": "Overrides role=\"status\". By default it is on for no-results and offline only." }, { "name": "attentionLabel", "type": "string", "required": false, "default": "\"Action needed\"", "description": "Text of the amber chip in the permission and rate-limit variants." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the container." } ], "variantsHint": { "variant": [ "first-use", "no-results", "cleared", "error", "permission", "offline", "rate-limit" ], "layout": [ "center", "start" ], "headingLevel": [ 2, 3, 4 ] }, "tokens": [ "--surface", "--border", "--fg-muted", "--attention-soft", "--attention-fg", "--radius-control", "--radius-card" ], "related": [ "illustration", "pictogram", "error-state", "rate-limit-notice", "callout" ], "composedOf": [ "illustration" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "First use", "description": "A truly empty area invites the first step. The title is positive and the button does what it says.", "code": "Add a document}\n secondary={}\n>\n Documents give the assistant something to read.\n" }, { "title": "No results, left-aligned", "description": "A filtered list is not the same as an empty one. Say the filters caused it and offer to clear them. Left-align the text in small areas.", "code": "Clear filters} />" }, { "title": "Permission", "description": "A person has to act here, so this version adds an amber tag with an icon and words, next to a line that says why.", "code": "Request access} />" }, { "title": "Compact, no art", "description": "Crowded places such as a table or a menu skip the drawing.", "code": "\n New tasks will show up as they arrive.\n" } ], "pageUrl": "https://lkb00.github.io/tattva/component-empty-state/", "markdownUrl": "https://lkb00.github.io/tattva/docs/empty-state.md" }, { "id": "media-frame", "name": "MediaFrame", "level": "molecule", "since": "0.5", "aka": [ "image", "aspect ratio", "image frame", "thumbnail" ], "category": "creating", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "status", "note": "Set with the status prop.", "source": "prop" } ], "summary": "An image in a fixed shape, with a placeholder while it loads, a message if it fails, and an optional caption and AI label.", "description": "MediaFrame saves a box in one of four shapes before the image arrives, so the page does not jump. While loading, it shows the image's main color if you give one, or a shimmer if you do not. If the image fails, it shows an icon and a Retry button. A description of the image is required, unless the image is only decoration.", "purpose": "Shows an image without making the page jump. It saves the space first, fills it with a placeholder, and offers Retry if the image fails.", "useFor": [ "A photo or generated image in a reply or a card.", "An image that may load slowly or fail.", "An AI-made image that needs a label saying where it came from." ], "notFor": [ { "text": "Several images in a gallery", "use": "media-grid" }, { "text": "A drawing for an empty or error screen", "use": "illustration" }, { "text": "An AI-made option the person picks from", "use": "variant-tile" } ], "whenToUse": [ "Describe what the image shows.", "Give the main color when you have it, so the placeholder matches the image.", "Label AI-made images with the visible AI label.", "Use one shape for a group of images." ], "avoid": [ "Do not use the AI request as the image description. Describe what is in the picture.", "Do not leave out the description unless the image is only decoration.", "Do not hide the AI label to make an image look cleaner.", "Do not let images pick their own size. Without a set shape, the page jumps." ], "accessibility": [ "The description is required. With decorative, the image gets an empty one and screen readers skip it.", "With a caption, the image and caption form one figure, so screen readers read them together.", "If the image fails, the message is real text and Retry is a real button.", "The AI label is written in words. With provenance, it is a button: Enter, Space or a tap opens it, and Escape closes it.", "The placeholder shimmer and the fade-in stop when people turn off motion in their system settings." ], "accessibilityYouDo": [ "Write alt text that says what the image shows, not how it was made.", "Set decorative only when the image adds nothing the text does not.", "Announce a failed load yourself if people must know. The error message appears without being announced." ], "onPhone": [ "The frame fills the width of its container and keeps its ratio, so the height follows the width.", "The AI label sits at the bottom left of the image, and with provenance it opens a popover from a button that has a 44px tap area on touch screens.", "The Retry button keeps its size on touch screens and has a 44px tap area. Keep errorLabel short so the error tile fits a small frame." ], "importPath": "import { MediaFrame } from \"./index\"", "sourcePath": "src/molecules/MediaFrame.tsx", "props": [ { "name": "src", "type": "string", "required": true, "default": null, "description": "Image URL." }, { "name": "alt", "type": "string", "required": true, "default": null, "description": "What the image shows. Ignored when decorative is set." }, { "name": "decorative", "type": "boolean", "required": false, "default": null, "description": "Renders alt=\"\"." }, { "name": "ratio", "type": "\"1:1\" | \"4:3\" | \"16:9\" | \"3:2\"", "required": false, "default": "\"4:3\"", "description": "Fixed aspect ratio that is reserved before load." }, { "name": "dominantColor", "type": "string", "required": false, "default": null, "description": "Average color as a CSS color. Used as the placeholder. Without it a shimmer shows while loading." }, { "name": "caption", "type": "string", "required": false, "default": null, "description": "Wraps the frame in figure and adds a figcaption." }, { "name": "aiGenerated", "type": "boolean", "required": false, "default": null, "description": "Shows the AI label on the image." }, { "name": "aiLabel", "type": "string", "required": false, "default": "\"AI-generated\"", "description": "Text of the label." }, { "name": "provenance", "type": "Omit", "required": false, "default": null, "description": "When set, the label opens a ProvenancePopover with these details." }, { "name": "onRetry", "type": "() => void", "required": false, "default": null, "description": "Called when Retry is pressed. The image is requested again either way." }, { "name": "status", "type": "\"loading\" | \"error\"", "required": false, "default": null, "description": "Forces a state, for previews or controlled loading." }, { "name": "errorLabel", "type": "string", "required": false, "default": "\"Image could not load\"", "description": "Text in the error tile." }, { "name": "retryLabel", "type": "string", "required": false, "default": "\"Retry\"", "description": "Text of the retry button." }, { "name": "flush", "type": "boolean", "required": false, "default": "false", "description": "Edge to edge inside a card: no corners or border of its own, so the card's corners clip the picture." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the frame wrapper." } ], "variantsHint": { "ratio": [ "1:1", "4:3", "16:9", "3:2" ], "status": [ "loading", "error" ] }, "tokens": [ "--surface-sunken", "--border", "--dur-base", "--lime-soft", "--radius-control", "--radius-card" ], "related": [ "media-grid", "ai-badge", "provenance-popover", "skeleton" ], "composedOf": [ "ai-badge", "provenance-popover", "button", "skeleton" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Ratios", "description": "Pick the shape that fits the content. The frame crops the image to fill it.", "code": "
\n \n \n \n \n
" }, { "title": "Loading and failed", "description": "With a main color, the placeholder uses it. Without one, it shimmers. The error message offers Retry.", "code": "
\n \n \n {}} caption=\"Error\" />\n
" }, { "title": "Made by AI, with details", "description": "The label is written on the image. With details added, it opens a panel with more.", "code": "
\n \n
" }, { "title": "Decorative", "description": "Decorative images have an empty description, so screen readers skip them.", "code": "
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-media-frame/", "markdownUrl": "https://lkb00.github.io/tattva/docs/media-frame.md" }, { "id": "media-grid", "name": "MediaGrid", "level": "organism", "since": "0.5", "aka": [ "gallery", "image gallery", "masonry", "photo grid" ], "category": "creating", "status": "experimental", "lifecycle": { "stage": "experimental", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "selected", "note": "Set with the selected prop.", "source": "prop" }, { "name": "empty", "note": "Set with the empty prop.", "source": "prop" } ], "summary": "A gallery of images in even rows that adjusts to the screen, with optional selecting and an empty message.", "description": "MediaGrid lays out images with the same spacing and the same shape. It uses 2 columns on small screens, 3 on medium and 4 on large, up to the limit you set. Selecting is optional, with a checkbox button on each image. With no images, it shows an empty message.", "purpose": "Lays out many images in even rows with one gap and one shape, so they are easy to scan. It can let people pick several, and shows an empty message when there is nothing.", "useFor": [ "A gallery of uploads or generated images.", "Picking several images to download, delete or reuse: turn on selectable." ], "notFor": [ { "text": "Picking one of several AI-made options", "use": "variant-grid" }, { "text": "A single image", "use": "media-frame" } ], "whenToUse": [ "Give the grid a name that says what the images are.", "Use one shape for the whole grid.", "Replace the empty message when you know the reason, such as a filter." ], "avoid": [ "Do not mix shapes in one grid.", "Do not show what is chosen with color alone. The check mark does that.", "Do not use it for a single image. Use MediaFrame." ], "accessibility": [ "The grid is a named list, so screen readers say how many images there are.", "Each select button is a checkbox named \"Select\" plus the image description. It works with Tab, Enter and Space.", "A chosen image shows a check mark and a ring, not just color.", "The count line is announced and updates when the choice changes." ], "accessibilityYouDo": [ "Give the grid a label that says what the images are, such as \"Your uploads\".", "Write a description for every image. A decorative image's select button is named only by its id." ], "onPhone": [ "The grid is two columns on a phone, and three or four only from the md and xl breakpoints.", "In select mode, each check button sits in the top right corner of the image. On touch screens it keeps its 28px size and has a 44px by 44px tap area.", "The count line is 12px text above the grid, and it is announced as a status when the count changes." ], "importPath": "import { MediaGrid } from \"./index\"", "sourcePath": "src/organisms/MediaGrid.tsx", "props": [ { "name": "items", "type": "MediaGridItem[]", "required": true, "default": null, "description": "Each item is the MediaFrame props except ratio and className, plus an id." }, { "name": "label", "type": "string", "required": true, "default": null, "description": "Accessible name of the list." }, { "name": "columns", "type": "2 | 3 | 4", "required": false, "default": "4", "description": "Maximum columns. Fewer show on narrower screens." }, { "name": "ratio", "type": "MediaRatio", "required": false, "default": "\"4:3\"", "description": "Ratio shared by every tile." }, { "name": "selectable", "type": "boolean", "required": false, "default": null, "description": "Adds a checkbox button to each tile." }, { "name": "selected", "type": "string[]", "required": false, "default": null, "description": "Controlled selection as item ids." }, { "name": "onSelectedChange", "type": "(ids: string[]) => void", "required": false, "default": null, "description": "Called with the new selection." }, { "name": "empty", "type": "ReactNode", "required": false, "default": null, "description": "Replaces the default EmptyState." }, { "name": "countLabel", "type": "(count: number, selected: number) => string", "required": false, "default": null, "description": "Builds the count line. Defaults to a count of images and selected." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the wrapper." } ], "variantsHint": { "columns": [ 2, 3, 4 ] }, "tokens": [ "--lime", "--border-strong", "--fg", "--bg", "--radius-card" ], "related": [ "media-frame", "empty-state", "variant-grid" ], "composedOf": [ "media-frame", "empty-state" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Gallery", "description": "Every image has the same shape, so rows stay even.", "code": "" }, { "title": "Selectable", "description": "Each image has a checkbox button. A check mark shows what is chosen, not only a ring. The count line announces changes.", "code": "" }, { "title": "Empty", "description": "With no images, the grid shows an empty message. You can replace it.", "code": "" } ], "pageUrl": "https://lkb00.github.io/tattva/component-media-grid/", "markdownUrl": "https://lkb00.github.io/tattva/docs/media-grid.md" }, { "id": "scene-illustration", "name": "SceneIllustration", "level": "molecule", "since": "0.26.0", "aka": [ "animation", "lottie", "animated illustration" ], "category": "states", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [], "summary": "An animated scene for empty, waiting, trust and success moments, told with objects and one lime shape.", "description": "SceneIllustration plays one of 35 Tattva scenes from a Lottie file. Each scene tells a small story with objects, and its lime shape shows part of that story: a phone screen, a highlighter, a door, a moon. It plays a short entrance, then a calm loop that carries the meaning, and pauses while off screen. Its colours follow light and dark mode, and it holds still when a person asks for less motion.", "purpose": "A larger, moving picture for the moments that matter in an AI product: the first message, waiting, asking first, showing sources, a polite no, done. It helps people read the moment at a glance.", "useFor": [ "The art slot of an EmptyState on a full page or a large panel.", "Onboarding, first-use and success screens.", "Explaining an AI moment, such as asking before acting or showing sources, on a page or in a guide." ], "notFor": [ { "text": "Small areas, dense panels or lists", "use": "illustration" }, { "text": "A heading or a list of features", "use": "pictogram" }, { "text": "A spinner while something loads for a second or two", "use": "spinner" } ], "whenToUse": [ "Use a scene to support the words on a screen, never to replace them.", "Pick the scene whose story matches the message, so the picture and the words agree.", "Show at most one moving scene on a screen.", "Use the still picture on busy pages and in long lists." ], "avoid": [ "Do not use a scene where a spinner or a short status line is enough.", "Do not recolour scenes. They take their colours from the theme so dark mode works.", "Do not put two moving scenes next to each other.", "Do not add text inside a scene. Put the words beside it." ], "accessibility": [ "Without a label, screen readers skip the scene.", "With a label, screen readers read it as a picture and say the label.", "The keyboard never stops on it.", "When a person asks for less motion, the scene shows its finished picture and never moves.", "It pauses while off screen and never flashes." ], "accessibilityYouDo": [ "Leave out the label when the words beside the scene already say what it shows, which should be almost always.", "Give a label only when the scene adds meaning the words do not.", "Show one moving scene per screen at most, so motion never competes for attention." ], "onPhone": [ "Choose size sm or fill on a phone; the height follows at four by three.", "The scene is not tappable and has no text, so nothing changes on touch screens.", "It pauses while scrolled out of view, which saves battery." ], "importPath": "import { SceneIllustration } from \"./index\"", "sourcePath": "src/molecules/SceneIllustration.tsx", "props": [ { "name": "data", "type": "object", "required": false, "default": null, "description": "The scene's Lottie data, for example imported from @tattva/ui/scenes/.json." }, { "name": "src", "type": "string", "required": false, "default": null, "description": "Address of a scene's Lottie file. Used when data is not given." }, { "name": "label", "type": "string", "required": false, "default": null, "description": "Accessible name. Without it the scene is hidden from assistive tech." }, { "name": "motion", "type": "\"loop\" | \"once\" | \"still\"", "required": false, "default": "\"loop\"", "description": "Entrance then a calm loop, entrance only, or the finished picture. Reduced motion always shows the still picture." }, { "name": "size", "type": "\"sm\" | \"md\" | \"lg\" | \"fill\"", "required": false, "default": "\"md\"", "description": "Width 12rem, 18rem, 30rem or the container's width. Height follows at 4:3." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the scene's box." } ], "variantsHint": { "motion": [ "loop", "once", "still" ], "size": [ "sm", "md", "lg", "fill" ] }, "tokens": [ "--fg", "--surface", "--lime" ], "related": [ "illustration", "empty-state", "pictogram" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "In an empty screen", "description": "Put the scene in EmptyState's art slot. The words say what happened; the scene sets the tone.", "code": "import firstUse from \"@tattva/ui/scenes/first-use.json\";\n\n}\n action={}\n/>" }, { "title": "Loop, once or still", "description": "Loop suits a waiting screen. Once suits a success that should settle. Still suits pages with a lot going on. Reduced motion always shows the still picture.", "code": "\n\n" }, { "title": "Loading the file by address", "description": "The scene files are also served on the Tattva site and ship in the npm package, so you can load one by address instead of importing it.", "code": "" }, { "title": "All scenes", "description": "Each scene has one job. Pick the one that matches the moment, not the one you like best.", "code": "{sceneNames.map((name) => (\n \n))}" } ], "pageUrl": "https://lkb00.github.io/tattva/component-scene-illustration/", "markdownUrl": "https://lkb00.github.io/tattva/docs/scene-illustration.md" }, { "id": "ai-mark", "name": "AIMark", "level": "atom", "since": "0.5", "aka": [ "ai icon", "sparkle", "ai logo" ], "category": "trust", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [], "summary": "A small four-point shape that tells people something was made by AI.", "description": "AIMark is a small shape that matches the color of the text beside it. By default it is just decoration. Give it a title and screen readers will read it out. Many people know the sparkle means AI, but not what the AI does. So add words whenever the action matters.", "purpose": "The one shape this system uses to mean AI. It takes the color of the text beside it, and its arms are slightly uneven, so it reads as our own mark rather than a generic sparkle.", "useFor": [ "Beside the words on a button that starts an AI action, like Summarize.", "On its own, with a title, inside a small badge or circle.", "Inside other AI labels that need a symbol." ], "notFor": [ { "text": "Labelling a piece of content as made by AI", "use": "ai-badge" }, { "text": "Explaining how AI content was made", "use": "ai-label" }, { "text": "Showing who wrote a message", "use": "avatar" } ], "whenToUse": [ "Add words when the action is specific, like Summarize or Rewrite.", "Use one mark for AI everywhere so people learn it.", "Match its size to the text beside it.", "Give it a title when it stands alone." ], "avoid": [ "Put it alone on every button. Too many marks lose their meaning.", "Use a second AI symbol in the same product.", "Make it lime on a plain page background. Lime is a fill that holds dark text.", "Use it as decoration where nothing is made by AI." ], "accessibility": [ "Without a title, screen readers skip it and read only the words beside it.", "With a title, screen readers read it as an image with that name.", "It never takes keyboard focus." ], "accessibilityYouDo": [ "Give it a title when it stands alone, so screen readers can say what it means.", "Check that it stands out from its background when alone. It copies the text color.", "Keep a button around it at least 24 pixels wide." ], "onPhone": [ "The mark is a fixed pixel size and looks the same on a phone.", "It is not tappable. Put it inside a button if it starts something, and that button gets a 44px target on touch screens." ], "importPath": "import { AIMark } from \"./index\"", "sourcePath": "src/atoms/AIMark.tsx", "props": [ { "name": "size", "type": "16 | 18 | 22 | 24 | 32", "required": false, "default": "18", "description": "Pixel size of the square mark." }, { "name": "title", "type": "string", "required": false, "default": null, "description": "Accessible name. When set the mark has role img and this label. When omitted it is hidden from assistive technology." }, { "name": "...svg props", "type": "SVGProps", "required": false, "default": null, "description": "Other props go to the svg element, except width, height and title." } ], "variantsHint": { "size": [ 16, 18, 22, 24, 32 ] }, "tokens": [ "currentColor", "--lime", "--on-lime" ], "related": [ "ai-label", "ai-badge", "avatar" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Sizes", "description": "Five sizes. The first three match small, medium and large text. The last two are for use on their own.", "code": "
\n \n
" }, { "title": "Paired with text", "description": "The mark sits beside words that say what will happen. A screen reader reads only the words.", "code": "" }, { "title": "Named image", "description": "When the mark stands alone, give it a title so screen readers can say what it means.", "code": "\n \n" } ], "pageUrl": "https://lkb00.github.io/tattva/component-ai-mark/", "markdownUrl": "https://lkb00.github.io/tattva/docs/ai-mark.md" }, { "id": "ai-presence", "name": "AIPresence", "level": "atom", "since": "0.5", "aka": [ "voice orb", "ai avatar", "assistant indicator", "orb" ], "category": "conversation", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "status", "note": "Set with the state prop.", "source": "prop" } ], "summary": "A moving lime disc that shows whether the assistant is waiting, listening, thinking, speaking, or has hit a problem.", "description": "AIPresence is a flat lime disc with the AI mark in its centre, on a soft lime halo. It uses only theme colours, so it changes with the theme like every other part. Each state moves differently: Ready breathes slowly, Listening sends rings outward, Thinking turns an arc around the mark, Speaking pulses with the voice, and an error turns the disc red. When the state changes, it glides smoothly to the new look. The state is always written out in words too. For people who turn off motion, it stays still and switches instantly. It is not a button, so place a labelled Stop button next to it.", "purpose": "A drawn disc that shows what a voice assistant is doing: waiting, listening, thinking, speaking or stuck. It glides between states instead of restarting, and the state is always given in words too.", "useFor": [ "A voice conversation, to show whether the assistant is listening or speaking.", "The pause while the assistant thinks between voice turns.", "Reacting to how loud the speaker is: pass level." ], "notFor": [ { "text": "Showing who wrote a message", "use": "avatar" }, { "text": "A whole voice screen with its controls", "use": "voice-panel" }, { "text": "The wait before a text reply", "use": "typing-indicator" } ], "whenToUse": [ "Place a labelled Stop button beside the disc whenever the person can interrupt.", "Ask for microphone permission when the person presses a button, then start the disc.", "Keep the label showing unless the state is written out nearby.", "Pass the raw volume and let the disc smooth it." ], "avoid": [ "Make the disc the only button or the only sign of what is happening.", "Change the state many times a second. Screen readers announce only real changes.", "Use amber for the problem state. Amber is only for when a person has to act.", "Add a glow outside the disc, or use rainbow or purple gradients." ], "accessibility": [ "Screen readers hear the state in words, politely, each time it changes.", "The drawing is hidden from screen readers.", "For people who turn off motion, the disc stays still, ignores volume and changes state instantly.", "The problem state shows the words \"Something went wrong\", not only a red center." ], "accessibilityYouDo": [ "Put a labelled Stop button next to it whenever people can interrupt. The disc is not a button.", "Change state only when the assistant really changes what it is doing. Screen readers hear each change.", "Keep the visible label on, unless the state is written out nearby." ], "onPhone": [ "The disc is a fixed size (32, 64 or 112px) and does not scale with the screen, so pick the size that fits a narrow screen.", "The disc and its label sit on one row, so a long label can squeeze a small screen. Keep the label short.", "It is not a control. Place a Stop button beside it, which has a 44px tap area on touch screens.", "Under reduced motion it draws a still frame instead of the animation." ], "importPath": "import { AIPresence } from \"./index\"", "sourcePath": "src/atoms/AIPresence.tsx", "props": [ { "name": "state", "type": "\"idle\" | \"listening\" | \"thinking\" | \"speaking\" | \"error\"", "required": false, "default": "\"idle\"", "description": "Current state. Each state is a row of animation targets." }, { "name": "size", "type": "\"sm\" | \"md\" | \"lg\"", "required": false, "default": "\"md\"", "description": "32, 64 or 112 pixels." }, { "name": "level", "type": "number", "required": false, "default": "0", "description": "Audio amplitude from 0 to 1. Smoothed inside the component. Ignored under reduced motion." }, { "name": "showLabel", "type": "boolean", "required": false, "default": "true", "description": "Show the state as visible text. The status region is present either way." }, { "name": "labels", "type": "Partial>", "required": false, "default": null, "description": "Replace the text for any state." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the wrapper." } ], "variantsHint": { "state": [ "idle", "listening", "thinking", "speaking", "error" ], "size": [ "sm", "md", "lg" ] }, "tokens": [ "--code-bg", "--fg-subtle", "--lime", "--danger", "--fg-muted", "--danger-fg" ], "related": [ "voice-panel", "avatar", "ai-mark" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Switch between states", "description": "The disc glides between states. The label and the hidden message for screen readers change only when the state does.", "code": "const [state, setState] = useState(\"listening\");\n\n\n{([\"idle\", \"listening\", \"thinking\", \"speaking\", \"error\"] as const).map((s) => (\n \n))}\n" }, { "title": "Audio level", "description": "Pass the sound volume from 0 to 1. The disc smooths it, rising fast and falling slowly.", "code": "" }, { "title": "Sizes", "description": "", "code": "\n\n" } ], "pageUrl": "https://lkb00.github.io/tattva/component-ai-presence/", "markdownUrl": "https://lkb00.github.io/tattva/docs/ai-presence.md" }, { "id": "ai-label", "name": "AILabel", "level": "molecule", "since": "0.5", "aka": [ "ai generated label", "made with ai" ], "category": "trust", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "hover", "note": "The lime pill darkens slightly under the pointer.", "source": "documented" }, { "name": "focus", "note": "A visible focus ring appears on the label button on keyboard focus.", "source": "documented" }, { "name": "open", "note": "Pressing the label opens a popover with the overview, details, resources and actions you pass, or a default line if none are passed.", "source": "documented" }, { "name": "edited", "note": "Pass edited to replace the pill with a small revert button that calls onRevert.", "source": "documented" }, { "name": "placed", "note": "Pass placed to pin the label to a corner or edge of its parent, depending on level.", "source": "documented" } ], "summary": "A small lime tag that says content was made by AI and explains how. Once a person edits the content, it becomes an undo button.", "description": "AILabel marks content as made by AI. Pressing it opens a small note with up to four parts: overview, details, links and buttons. It only labels and explains. It never starts AI work. The level setting picks where it sits: on a feature, a message, a field or an image. After an edit, the lime color goes away and an icon button brings back the AI version.", "purpose": "A small lime tag that marks content as made by AI and opens a note explaining how. Once a person edits the content it turns into an undo button, because the content is no longer purely AI.", "useFor": [ "A box, message, field or image whose content the AI made.", "Explaining what the AI did, with details, links or buttons.", "Letting people go back to the AI version after they edit it." ], "notFor": [ { "text": "A button that starts AI work", "use": "button" }, { "text": "A simple mark with no explanation", "use": "ai-badge" }, { "text": "A full record of where content came from", "use": "provenance-popover" } ], "whenToUse": [ "Put one label on the whole box, not one on every line.", "Keep the label away from the edge of the box.", "Use the buttons part for things like Learn more or Turn off.", "Set edited to true as soon as a person changes the content, so the undo button appears.", "In onRevert, restore the AI version and set edited back to false." ], "avoid": [ "Use the label as a button that starts AI work.", "Put it on content a person wrote.", "Make the label amber. Amber is only for when a person has to act.", "Push the label right up against the edge of a box." ], "accessibility": [ "The tag is a real button. Screen readers hear its words, then \"About this AI content\", and whether the note is open.", "Opening the note moves the keyboard into it. Escape closes it and returns the keyboard to the tag; tabbing away or clicking outside also closes it.", "Each part of the note is named, such as Overview and Details.", "The undo button shows only an icon, but screen readers hear \"Revert to AI version\".", "The pressable area is at least 24 pixels tall, and 44 on touch screens." ], "accessibilityYouDo": [ "Give buttons and links you put in the note their own clear words." ], "onPhone": [ "On touch screens the pill keeps its size and has a 44px tap area. The revert button grows to 44px square.", "The explainer opens on tap and closes by tapping outside, and its panel is at most the screen width minus 2rem.", "Buttons in the Actions section wrap onto more lines on a narrow screen." ], "importPath": "import { AILabel } from \"./index\"", "sourcePath": "src/molecules/AILabel.tsx", "props": [ { "name": "level", "type": "\"feature\" | \"message\" | \"field\" | \"image\"", "required": false, "default": "\"feature\"", "description": "Where the label sits. Feature is the upper right of a container. Field is the right side, vertically centred. Message and image are our own placements." }, { "name": "size", "type": "16 | 18 | 22", "required": false, "default": "18", "description": "Pill and mark size. Match the adjacent text size." }, { "name": "text", "type": "string", "required": false, "default": "\"AI\"", "description": "Word in the pill." }, { "name": "placed", "type": "boolean", "required": false, "default": "false", "description": "Apply absolute placement for the level. The parent must be positioned." }, { "name": "overview", "type": "ReactNode", "required": false, "default": null, "description": "Toggletip section: what the AI did." }, { "name": "details", "type": "ReactNode", "required": false, "default": null, "description": "Toggletip section: specifics for this instance." }, { "name": "resources", "type": "ReactNode", "required": false, "default": null, "description": "Toggletip section: links." }, { "name": "actions", "type": "ReactNode", "required": false, "default": null, "description": "Toggletip section: buttons. The label itself never triggers AI work." }, { "name": "edited", "type": "boolean", "required": false, "default": "false", "description": "Drops the tint and shows the icon-only revert button." }, { "name": "onRevert", "type": "() => void", "required": false, "default": null, "description": "Called when revert is pressed. The app restores the AI version." }, { "name": "revertLabel", "type": "string", "required": false, "default": "\"Revert to AI version\"", "description": "Accessible name of the revert button." }, { "name": "popoverLabel", "type": "string", "required": false, "default": "\"About this AI content\"", "description": "Accessible name of the toggletip panel." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes for the wrapper." } ], "variantsHint": { "level": [ "feature", "message", "field", "image" ], "size": [ 16, 18, 22 ] }, "tokens": [ "--lime", "--lime-hover", "--on-lime", "--border", "--surface-raised", "--radius-control" ], "related": [ "ai-mark", "ai-badge", "provenance-popover", "revert-toggle" ], "composedOf": [ "ai-mark", "popover" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Feature container", "description": "Sits at the upper right of a box, a little away from the edge.", "code": "
\n Draft reply to the supplier.\n \n
" }, { "title": "Toggletip sections", "description": "All four parts filled in. Buttons are plain buttons and links are links. Escape or a click outside closes the note.", "code": "How summaries are made}\n actions={}\n/>" }, { "title": "Edited, with revert", "description": "After an edit, the tag turns into an icon button named Revert to AI version. Pressing it brings the tag back.", "code": " setEdited(false)} overview=\"Written from the three documents you attached.\" />" }, { "title": "Sizes", "description": "Match the size to the text around it.", "code": "\n\n" } ], "pageUrl": "https://lkb00.github.io/tattva/component-ai-label/", "markdownUrl": "https://lkb00.github.io/tattva/docs/ai-label.md" }, { "id": "chart-frame", "name": "ChartFrame", "level": "molecule", "since": "0.5", "aka": [ "chart container", "chart card", "chart wrapper" ], "category": "numbers", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "status", "note": "Set with the state prop.", "source": "prop" }, { "name": "empty", "note": "Set with the empty prop.", "source": "prop" } ], "summary": "The box every chart sits in. It adds a title, a short written summary, a table view and clear messages when data is loading or missing.", "description": "ChartFrame gives a chart a title, a line saying what is measured and over what time, and a short summary in words. A View as table button swaps the chart for the same numbers in a table. It also shows messages while data loads, when there is none, or when something fails. In a very narrow space it shows a tiny trend line instead.", "purpose": "The box every chart sits in. It puts the title, what is measured and a summary in words above the chart, so the point is clear before anyone reads the lines.", "useFor": [ "Any chart on a page, so it gets a title, a summary and a table view.", "Showing clear messages while data loads, when there is none, or when loading fails.", "A chart that may land in a narrow space: pass a small trend line as the fallback." ], "notFor": [ { "text": "One headline number", "use": "stat-tile" }, { "text": "A table of numbers with no chart", "use": "data-table" } ], "whenToUse": [ "Write the summary as a sentence that says what the data shows, with the key number.", "Say what is measured and over what time in the subtitle.", "Give every chart a table, so the table button is always there.", "When there is nothing to show, say why and what to do next.", "Pass onRetry, so the error message offers a Try again button." ], "avoid": [ "Don't skip the summary because the chart looks obvious. Some people need the words.", "Don't hide numbers in a pop-up. Put them in the table.", "Don't put filters inside the box. Keep them in one row above the charts they control.", "Don't make the box shorter than the chart and its labels." ], "accessibility": [ "The title and summary sit in the chart's caption, so screen readers hear them with the chart.", "View as table swaps in a real table with the same numbers, and the button label changes to match the view.", "While data loads, screen readers hear \"Loading chart\".", "A failure is announced right away." ], "accessibilityYouDo": [ "Write a summary that says what the data shows, with the key number. Some people only get the words.", "Pass table data for every chart, or the View as table button does not appear." ], "onPhone": [ "The chart is drawn at the width of the frame, and below minWidth (280px unless you change it) it is replaced by your fallback, usually a Sparkline, with a note to use the table view.", "Cards use 16px padding and the title wraps instead of being cut off.", "The View as table button swaps in a DataTable that scrolls sideways inside the frame, so give the table a narrow column set for phones." ], "importPath": "import { ChartFrame } from \"./index\"", "sourcePath": "src/molecules/ChartFrame.tsx", "props": [ { "name": "title", "type": "string", "required": true, "default": null, "description": "Chart title, set in the display style." }, { "name": "subtitle", "type": "string", "required": false, "default": null, "description": "States the unit and the time window." }, { "name": "summary", "type": "ReactNode", "required": false, "default": null, "description": "Plain-language reading of the chart, shown above it in body text." }, { "name": "children", "type": "ReactNode", "required": false, "default": null, "description": "The chart. It receives the full width of the frame." }, { "name": "table", "type": "DataTableProps", "required": false, "default": null, "description": "Data for the table view. Without it the toggle is hidden. Each chart exports a helper that builds it." }, { "name": "source", "type": "string", "required": false, "default": null, "description": "Source line shown under the chart." }, { "name": "note", "type": "string", "required": false, "default": null, "description": "Caveat shown after the source, for example that the latest point is still streaming." }, { "name": "legend", "type": "ReactNode", "required": false, "default": null, "description": "Rendered above the chart. Charts draw their own legend, so use this only for a shared legend." }, { "name": "state", "type": "\"ready\" | \"loading\" | \"empty\" | \"error\"", "required": false, "default": "\"ready\"", "description": "Anything other than ready replaces the chart." }, { "name": "empty", "type": "ChartEmptyState", "required": false, "default": null, "description": "What is missing, why, and an optional action. Shown in the empty state." }, { "name": "errorMessage", "type": "string", "required": false, "default": null, "description": "Message for the error state. A default says nothing was lost." }, { "name": "onRetry", "type": "() => void", "required": false, "default": null, "description": "Called by the retry button in the error state." }, { "name": "fallback", "type": "ReactNode", "required": false, "default": null, "description": "Shown instead of the chart when the frame is narrower than minWidth." }, { "name": "minWidth", "type": "number", "required": false, "default": "280", "description": "Narrowest width in px at which the chart is drawn." }, { "name": "defaultView", "type": "\"chart\" | \"table\"", "required": false, "default": "\"chart\"", "description": "Which view is shown first." }, { "name": "onDownload", "type": "() => void", "required": false, "default": null, "description": "Adds a Download data button and calls this when pressed." }, { "name": "stateHeight", "type": "number", "required": false, "default": "200", "description": "Height in px of the loading, empty and error states, so the layout does not jump." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the figure." } ], "variantsHint": { "state": [ "ready", "loading", "empty", "error" ], "defaultView": [ "chart", "table" ] }, "tokens": [ "--surface", "--border", "--fg", "--fg-muted", "--fg-subtle", "--chart-axis", "--font-serif", "--radius-card" ], "related": [ "data-table", "line-chart", "bar-chart", "sparkline" ], "composedOf": [ "button", "skeleton", "error-state", "data-table" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "A chart with a summary and a table", "description": "The summary says what the chart shows. View as table swaps the chart for the same numbers in a table.", "code": "\n \n" }, { "title": "Loading, nothing to show, and a problem", "description": "Loading shows a grey placeholder. When there is nothing to show, it says what is missing, why and what to do. A problem offers a retry.", "code": "\nClear filters,\n }}\n/>\n {}} />" }, { "title": "A tiny version in narrow spaces", "description": "This box is too narrow for a full chart, so it shows a tiny trend line. The table view still has every value.", "code": "
\n }\n >\n \n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-chart-frame/", "markdownUrl": "https://lkb00.github.io/tattva/docs/chart-frame.md" }, { "id": "data-table", "name": "DataTable", "level": "molecule", "since": "0.5", "aka": [ "table", "data grid", "grid table" ], "category": "numbers", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "focus", "note": "The scrollable table region can be focused with the keyboard and shows a focus ring.", "source": "documented" }, { "name": "sticky header", "note": "Pass stickyHeader (with maxHeight) to keep the column headings in view while the body scrolls.", "source": "documented" }, { "name": "scrolling", "note": "A table wider or taller than its box scrolls inside it instead of stretching the page.", "source": "documented" }, { "name": "empty", "note": "With no rows, a single line (emptyText, \"No rows.\" by default) is shown under the headings.", "source": "documented" }, { "name": "sorted", "note": "A sortable heading (sortable on the column) cycles none, ascending, descending when pressed; the table shows arrows and says how it is sorted.", "source": "documented" }, { "name": "dense", "note": "Pass density=\"dense\" for tighter rows.", "source": "documented" }, { "name": "up or down", "note": "A column's direction function adds an arrow and the up or down colour to a cell.", "source": "documented" }, { "name": "current row", "note": "The row matching activeRowKey is marked with aria-current and a sunken background.", "source": "documented" }, { "name": "row hover", "note": "When onRowClick is set, rows highlight on hover and the row name is a button.", "source": "documented" } ], "summary": "The numbers behind a chart, in a plain table with digits lined up.", "description": "DataTable shows numbers as a table. The first column names each row. Numbers line up on the right so they are easy to compare. Headings can sort, a cell can carry an up or down marker, and rows can be dense for screens people read all day. On a narrow screen the table scrolls sideways. ChartFrame uses it for the View as table view.", "purpose": "The numbers behind a chart, in a plain table. Numbers line up on the right with equal-width digits, so a column can be compared at a glance.", "useFor": [ "The table view of a chart, inside ChartFrame.", "A small set of numbers that people need to read and compare exactly.", "Giving every value that a chart shows only in a pop-up a place to be read.", "A watchlist, a positions list or any list of numbers people sort and scan: turn on sortable headings, dense rows and the up or down marker." ], "notFor": [ { "text": "Laying out a page or a form" }, { "text": "A side-by-side comparison of products or plans", "use": "comparison-table" }, { "text": "One headline number", "use": "stat-tile" } ], "whenToUse": [ "Put the unit in each number column heading.", "Use commas in big numbers and the same decimals down a column.", "Include every number the chart shows, even ones that only appear in a pop-up.", "Mark missing values with words such as \"No data\"." ], "avoid": [ "Don't line text up on the right.", "Don't merge cells or stack headings. Keep one row of headings.", "Don't use it to lay out a page. It is for data." ], "accessibility": [ "It is a real table: the first column names each row, and screen readers pair each number with its headings.", "The caption is read by screen readers and also names the scrolling area.", "The scrolling area can be reached with the Tab key, so keyboard users can scroll it sideways.", "Number columns line up on the right with equal-width digits.", "A sortable heading is a real button inside the heading cell. The heading carries aria-sort, and a polite message says how the table is now sorted.", "An up or down marker has an arrow shape and a hidden word, so direction is not colour alone.", "When rows can be chosen, the row name is a real button and the chosen row has aria-current." ], "accessibilityYouDo": [ "Write a caption that says what the table holds. It is hidden on screen, and screen readers use it as the table's name.", "Put the unit in each number column heading, so each number is heard with its unit.", "Write missing values as words, such as \"No data\", not as an empty cell.", "The up or down marker adds an arrow and a hidden word, but your text must still carry its own sign (+ or −). Do not leave the number unsigned and rely on the colour.", "If you keep the sort in your own code, pass sort and onSortChange together, or the headings will look broken." ], "onPhone": [ "By default the table keeps its columns and scrolls sideways inside its own box, so the page itself never scrolls sideways.", "Set responsive=\"stack\" and a narrow container turns each row into a card with the column name before each value, so nothing scrolls.", "Sort buttons in the header and the first-column row button are 44px tall on touch screens.", "Tapping anywhere on a row calls onRowClick, so there is no hover state to rely on." ], "importPath": "import { DataTable } from \"./index\"", "sourcePath": "src/molecules/DataTable.tsx", "props": [ { "name": "columns", "type": "DataTableColumn[]", "required": true, "default": null, "description": "Column definitions: key, header, numeric, sortable, sortValue and direction. The first column is the row header. sortValue gives the raw number or text to sort by when the cell shows formatted text. direction returns \"up\", \"down\" or \"flat\" for a cell, which adds an arrow and the up or down colour." }, { "name": "rows", "type": "Record[]", "required": true, "default": null, "description": "One object per row, keyed by column key. Values are already formatted." }, { "name": "caption", "type": "string", "required": true, "default": null, "description": "Names the table and states what it holds. It is also the accessible name of the scroll region." }, { "name": "stickyHeader", "type": "boolean", "required": false, "default": null, "description": "Keeps the header row visible while the body scrolls. Pair it with maxHeight." }, { "name": "maxHeight", "type": "number", "required": false, "default": null, "description": "Maximum height in px before the table scrolls vertically." }, { "name": "density", "type": "\"comfortable\" | \"dense\"", "required": false, "default": "\"comfortable\"", "description": "Row spacing. Dense fits more rows." }, { "name": "sort", "type": "SortState | null", "required": false, "default": null, "description": "The current sort, when your code keeps it. SortState is { key, direction: \"asc\" | \"desc\" }. Use with onSortChange." }, { "name": "defaultSort", "type": "SortState | null", "required": false, "default": "null", "description": "The starting sort when the table keeps it itself." }, { "name": "onSortChange", "type": "(sort: SortState | null) => void", "required": false, "default": null, "description": "Called when a sortable heading is pressed. Each press goes none, ascending, descending, none." }, { "name": "onRowClick", "type": "(row: DataRow, index: number) => void", "required": false, "default": null, "description": "Called when a row is chosen. The row name becomes a button, so the keyboard works. Clicking elsewhere on the row also calls it." }, { "name": "activeRowKey", "type": "string", "required": false, "default": null, "description": "Key of the row to mark as the current one (aria-current). Matches rowKey." }, { "name": "rowKey", "type": "(row: DataRow, index: number) => string", "required": false, "default": null, "description": "A stable key per row. Defaults to the row's id value, then its position. Needed for activeRowKey when rows reorder." }, { "name": "responsive", "type": "\"scroll\" | \"stack\"", "required": false, "default": "\"scroll\"", "description": "What a narrow container does with the table. scroll keeps the columns and scrolls sideways. stack turns each row into a card, with the column name before each value, so nothing scrolls. It follows the width of the table's own container, not the screen." }, { "name": "emptyText", "type": "string", "required": false, "default": "\"No rows.\"", "description": "Shown when there are no rows." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the scroll region." } ], "variantsHint": { "density": [ "comfortable", "dense" ], "responsive": [ "scroll", "stack" ] }, "tokens": [ "--surface", "--surface-sunken", "--border", "--fg", "--fg-muted", "--up-fg", "--down-fg", "--surface-hover", "--radius-card" ], "related": [ "chart-frame", "bar-chart", "line-chart", "stat-tile", "sparkline" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Wait times by shop", "description": "Number columns line up on the right. Values are already formatted.", "code": "
\n \n
" }, { "title": "A long table with fixed headings", "description": "For long tables, headings stay in view while the rows scroll.", "code": "
\n ({ day: d, cost: \"$\" + [310, 325, 298, 340, 352, 365, 380][i] }))}\n />\n
" }, { "title": "Cards on a phone", "description": "Set responsive to stack and each row becomes a card when the table is narrow, with the column name before each value. Nothing scrolls sideways. This frame is narrow on purpose, so you see the phone layout here.", "code": "
\n \n
" }, { "title": "Sortable, dense, with up and down", "description": "A watchlist. Headings sort (none, then ascending, then descending). The change column gets an arrow and a colour. Pressing a row name chooses that row.", "code": "function Example() {\n const [active, setActive] = useState(\"TCS\");\n return (\n setActive(String(r.id))}\n columns={[\n { key: \"name\", header: \"Stock\", sortable: true },\n { key: \"price\", header: \"Price (₹)\", numeric: true, sortable: true,\n sortValue: (r) => Number(String(r.price).replace(/,/g, \"\")) },\n { key: \"chg\", header: \"Change\", numeric: true, sortable: true,\n sortValue: (r) => Number(String(r.chg).replace(\"−\", \"-\").replace(\"%\", \"\")),\n direction: (r) => String(r.chg).startsWith(\"+\") ? \"up\" : String(r.chg).startsWith(\"−\") ? \"down\" : \"flat\" },\n ]}\n rows={[\n { id: \"RELIANCE\", name: \"Reliance\", price: \"2,874.50\", chg: \"+1.42%\" },\n { id: \"TCS\", name: \"TCS\", price: \"3,912.10\", chg: \"−0.63%\" },\n { id: \"INFY\", name: \"Infosys\", price: \"1,688.25\", chg: \"0.00%\" },\n { id: \"HDFCBANK\", name: \"HDFC Bank\", price: \"1,642.80\", chg: \"−1.18%\" },\n ]}\n />\n );\n}" } ], "pageUrl": "https://lkb00.github.io/tattva/component-data-table/", "markdownUrl": "https://lkb00.github.io/tattva/docs/data-table.md" }, { "id": "stat-tile", "name": "StatTile", "level": "molecule", "since": "0.5", "aka": [ "statistic", "stat", "kpi", "metric", "metric card", "kpi card", "number card" ], "category": "numbers", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "better", "note": "When the delta direction matches goodDirection, the change is shown in green with the word better.", "source": "documented" }, { "name": "worse", "note": "When the delta direction is the opposite of goodDirection, the change is shown in red with the word worse.", "source": "documented" }, { "name": "flat or neutral", "note": "A flat change, or goodDirection set to neutral, is shown in the muted colour with no verdict.", "source": "documented" }, { "name": "needs action", "note": "Pass needsAction to add an attention tag and turn the threshold bar to the warning colour.", "source": "documented" }, { "name": "threshold", "note": "Pass threshold to show a meter bar with a marker at the limit and its label below.", "source": "documented" } ], "summary": "One big number with how it changed, an optional tiny trend line and an optional limit.", "description": "StatTile shows a name, a big number and how much it changed. The change has an arrow, a plus or minus, and the word \"better\" or \"worse\", so color is never the only clue. You say which direction is good, so a drop in wait time reads as good. Amber shows only when a person has to act.", "purpose": "One headline number with how it changed. The change says \"better\" or \"worse\" in words, and you choose which direction is good, so a drop in wait time reads as good news.", "useFor": [ "A row of the few numbers that matter most, above the charts.", "A number with its change since the last period.", "A number measured against a limit or target, shown on a small scale." ], "notFor": [ { "text": "A change over time that people need to read point by point", "use": "line-chart" }, { "text": "Comparing several amounts", "use": "bar-chart" }, { "text": "How much of an allowance is used or left", "use": "usage-meter" } ], "whenToUse": [ "Say which direction is good on every tile, so lower-is-better numbers read correctly.", "Say what the change is compared to, such as the previous 7 days.", "For rates from small groups, show the range or group size in the detail line.", "Put one row of tiles above the charts for the numbers that matter most." ], "avoid": [ "Don't use amber for a number that just got worse. Amber means a person must act.", "Don't rely on color for the change. The arrow, the plus or minus and the word \"better\" or \"worse\" carry the meaning.", "Don't draw a chart with one bar when a tile says it.", "Don't add labels to the trend line. The tile's number and change say it." ], "accessibility": [ "Each tile is a group named by its label.", "Screen readers hear the change as a direction word, such as \"up\", then the amount and \"better\" or \"worse\".", "The arrow is hidden from screen readers. Color only repeats what the words say.", "The limit scale is a meter, read with the value and the limit's label." ], "accessibilityYouDo": [ "Set goodDirection on every tile where lower is better, or a drop is called \"worse\".", "Say what the change is compared to in versus, such as \"vs previous 7 days\".", "Pass a trend line with decorative set, so screen readers do not hear the numbers twice." ], "onPhone": [ "The tile fills the width of its container and the value breaks onto a new line instead of overflowing.", "The sparkline stays at its own size on the right and the text on the left shrinks first.", "Nothing in the tile needs hover or a tap." ], "importPath": "import { StatTile } from \"./index\"", "sourcePath": "src/molecules/StatTile.tsx", "props": [ { "name": "label", "type": "string", "required": true, "default": null, "description": "Metric name in sentence case, without a trailing colon." }, { "name": "value", "type": "string", "required": true, "default": null, "description": "Formatted value, for example 1.24 s or $4.2K." }, { "name": "serif", "type": "boolean", "required": false, "default": null, "description": "Sets the value in the display style." }, { "name": "delta", "type": "StatDelta", "required": false, "default": null, "description": "text (signed, with unit), direction (up, down or flat) and an optional versus period." }, { "name": "goodDirection", "type": "\"up\" | \"down\" | \"neutral\"", "required": false, "default": "\"up\"", "description": "Which direction of change is an improvement. Use down for latency, cost and error rate. Neutral shows no better or worse word." }, { "name": "detail", "type": "string", "required": false, "default": null, "description": "Visible line under the value, such as an interval and sample size." }, { "name": "spark", "type": "ReactNode", "required": false, "default": null, "description": "Slot for a Sparkline. Pass it with decorative set." }, { "name": "threshold", "type": "StatThreshold", "required": false, "default": null, "description": "value, max, at and label. Draws a thin scale with a tick at the threshold." }, { "name": "needsAction", "type": "boolean", "required": false, "default": null, "description": "Shows the amber chip and turns the threshold fill amber. Use only when a person has to act." }, { "name": "actionText", "type": "string", "required": false, "default": "\"Needs review\"", "description": "Text of the amber chip." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the tile." } ], "variantsHint": { "goodDirection": [ "up", "down", "neutral" ] }, "tokens": [ "--success-fg", "--danger-fg", "--attention-soft", "--attention-fg", "--fg", "--fg-muted", "--border", "--radius-control", "--radius-card" ], "related": [ "sparkline", "meter", "line-chart" ], "composedOf": [ "meter" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "A row of shop numbers", "description": "Seven tiles for a shop dashboard. For wait time, sales cost and refunds, lower is better. The happy-customer tile shows its range and sample size.", "code": "
\n } />\n } />\n } />\n } />\n } />\n } />\n \n
" }, { "title": "A limit and a call to act", "description": "The tick marks the limit on a thin scale. The amber chip and amber fill are for when a person has to review.", "code": "
\n \n \n
" }, { "title": "A headline number", "description": "Use the larger style for the one tile that leads a page.", "code": "
\n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-stat-tile/", "markdownUrl": "https://lkb00.github.io/tattva/docs/stat-tile.md" }, { "id": "sparkline", "name": "Sparkline", "level": "organism", "since": "0.5", "aka": [ "mini chart", "trend line" ], "category": "numbers", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "empty", "note": "With an empty data array, nothing is drawn.", "source": "documented" }, { "name": "single point", "note": "With one value, only the end dot is drawn and no line.", "source": "documented" }, { "name": "min and max", "note": "Pass showMinMax to mark the lowest and highest points with small rings.", "source": "documented" }, { "name": "decorative", "note": "Pass decorative to hide it from screen readers when the number beside it already says the same thing.", "source": "documented" } ], "summary": "A tiny trend line that highlights the latest value and can be read aloud.", "description": "Sparkline draws a small line and marks the latest value with a bigger dot. Optional dots mark the lowest and highest points. A screen reader hears the first, last, lowest and highest values. Inside a StatTile it is only decoration, because the tile already shows the number.", "purpose": "A tiny trend line with the latest value marked, for places with no room for a full chart. It has no axes or labels, so it always sits beside a number.", "useFor": [ "Beside a headline number, inside a StatTile.", "A table cell or list row that shows a trend.", "The fallback in a ChartFrame that is too narrow for the full chart." ], "notFor": [ { "text": "A trend people need to read exact values from", "use": "line-chart" }, { "text": "The only place the numbers appear", "use": "data-table" } ], "whenToUse": [ "Put it beside a number that gives the current value.", "Cover the same time as the number beside it.", "Use it in place of a chart that is too narrow to draw." ], "avoid": [ "Don't add axes, grid lines or labels. Use a LineChart for that.", "Don't let a screen reader read it inside a tile. It would repeat the tile.", "Don't compare trend lines as if they share a scale when they do not." ], "accessibility": [ "On its own, screen readers hear the label with the first, last, lowest and highest values.", "With decorative set, it is hidden from screen readers.", "The latest point is larger, with a ring that keeps it clear of the line." ], "accessibilityYouDo": [ "Set decorative when the number beside it already says the same thing, such as inside a StatTile.", "Give it a label and unit that say what it measures. Screen readers use them.", "Put the full numbers in a table somewhere on the page." ], "onPhone": [ "It is a fixed-size picture, 96 by 28px unless you pass width and height, so it does not resize with its container.", "It has no hover or tap behaviour, so put the numbers next to it in text.", "Set width yourself if you need it larger on a phone." ], "importPath": "import { Sparkline } from \"./index\"", "sourcePath": "src/organisms/Sparkline.tsx", "props": [ { "name": "data", "type": "number[]", "required": true, "default": null, "description": "Values in time order." }, { "name": "label", "type": "string", "required": true, "default": null, "description": "What the line measures. Used in the accessible name." }, { "name": "unit", "type": "string", "required": false, "default": "\"\"", "description": "Unit appended to values in the accessible name. Include a leading space if needed." }, { "name": "formatValue", "type": "(n: number) => string", "required": false, "default": "formatNumber", "description": "Formats values in the accessible name." }, { "name": "width", "type": "number", "required": false, "default": "96", "description": "Width in px." }, { "name": "height", "type": "number", "required": false, "default": "28", "description": "Height in px." }, { "name": "showMinMax", "type": "boolean", "required": false, "default": null, "description": "Marks the minimum and maximum with hollow dots." }, { "name": "decorative", "type": "boolean", "required": false, "default": null, "description": "Hides the sparkline from assistive technology. Use when a visible number carries the same information." }, { "name": "color", "type": "string", "required": false, "default": "\"var(--chart-1)\"", "description": "Color of the emphasized end point." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the svg." } ], "variantsHint": {}, "tokens": [ "--chart-axis", "--chart-1", "--surface" ], "related": [ "stat-tile", "line-chart", "chart-frame" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Plain, and with lowest and highest points", "description": "The latest point has the main chart color. The line stays grey so the latest value stands out.", "code": "\n" }, { "title": "Inside a tile", "description": "Here it is decoration only, so screen readers skip it.", "code": "
\n } />\n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-sparkline/", "markdownUrl": "https://lkb00.github.io/tattva/docs/sparkline.md" }, { "id": "line-chart", "name": "LineChart", "level": "organism", "since": "0.5", "aka": [ "line graph", "time series chart" ], "category": "numbers", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "streaming", "note": "Set with the streaming prop.", "source": "prop" } ], "summary": "A line chart for change over time. Lines are named at their ends and can be explored with the keyboard.", "description": "LineChart draws up to five lines. Solid lines are real numbers and dotted lines are guesses about the future. From the third line on, a dash pattern and a marker shape back up the color. With two to four lines, each is named at its end. You can tab to the chart and use the arrow keys to move between points.", "purpose": "Shows change over time for up to five lines. Lines are named at their ends where there is room, so people do not have to look back and forth at a key.", "useFor": [ "A measure tracked over days, hours or months.", "Comparing a few groups over the same time.", "A forecast after real values: set where the projection starts.", "Live data where the latest point may still change: turn on streaming." ], "notFor": [ { "text": "Comparing amounts at one point in time", "use": "bar-chart" }, { "text": "A trend in a very small space", "use": "sparkline" }, { "text": "A best guess with a range", "use": "dot-plot" } ], "whenToUse": [ "Use it for change over time. Keep to four lines where you can.", "Use solid lines for real numbers and dotted lines only for forecasts.", "Put it in a ChartFrame with a summary and a table.", "Switch to several small charts when lines bunch up and their names would overlap.", "Group extra lines into one \"Other\" line. Lines after the fifth are not drawn." ], "avoid": [ "Don't put two different measures on one chart. Use two charts.", "Don't add a sixth line. Group the smallest into one grey \"Other\" line.", "Don't change the other colors when a filter removes a line. Each line keeps its color.", "Don't use amber for a line. It is saved for things that need a person." ], "accessibility": [ "You can tab to the chart. Left and Right move between points, Up and Down switch lines, Home and End jump to the ends, and Escape clears.", "Each step is read out as line, time, value and unit, with \"projected\" or \"provisional\" added when it applies.", "From the third line on, a dash pattern and a marker shape back up the color.", "The pop-up is hidden from screen readers, because the same values are read out as you move.", "The draw-in animation is skipped when people turn off motion in their system settings." ], "accessibilityYouDo": [ "Put it in a ChartFrame with a summary and a table.", "Give it an ariaLabel and a unit, so each point is read with what it measures." ], "onPhone": [ "The chart measures its container and redraws at that width, so it fills a phone screen.", "Touch or drag on the chart to show the tooltip. Vertical swipes still scroll the page, and the tooltip stays until you tap elsewhere.", "The tooltip flips to the left of your finger past the middle of the chart, and axis labels at the edges are pulled inward so they are not cut off.", "Give the chart a height of about 200 to 240px on a phone, and it never goes below 160px." ], "importPath": "import { LineChart } from \"./index\"", "sourcePath": "src/organisms/LineChart.tsx", "props": [ { "name": "series", "type": "LineSeries[]", "required": true, "default": null, "description": "Up to five series. Each has id, label, data (numbers or null) and optional projectionFrom. Color follows position." }, { "name": "x", "type": "string[]", "required": true, "default": null, "description": "X labels, one per data position, already formatted." }, { "name": "formatValue", "type": "(n: number) => string", "required": false, "default": "formatNumber", "description": "Formats the axis, labels and tooltip." }, { "name": "unit", "type": "string", "required": false, "default": "\"\"", "description": "Unit word read after each value by screen readers." }, { "name": "height", "type": "number", "required": false, "default": "240", "description": "Plot height in px including the x axis band. Minimum 160." }, { "name": "yDomain", "type": "[number, number]", "required": false, "default": null, "description": "Fixed y domain. Overrides zeroBaseline." }, { "name": "zeroBaseline", "type": "boolean", "required": false, "default": "true", "description": "Start the y axis at zero when all values are non-negative." }, { "name": "streaming", "type": "boolean", "required": false, "default": null, "description": "Makes the latest point of each series hollow because it is not final." }, { "name": "animate", "type": "boolean", "required": false, "default": null, "description": "Reveals the lines once on mount, from left to right in --dur-slow on --ease-arrive. Skipped when the person prefers reduced motion." }, { "name": "ariaLabel", "type": "string", "required": false, "default": "\"Line chart\"", "description": "Name for the chart region." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the wrapper." } ], "variantsHint": {}, "tokens": [ "--chart-1", "--chart-2", "--chart-3", "--chart-4", "--chart-5", "--chart-grid", "--chart-axis", "--surface", "--fg", "--fg-muted", "--dur-slow", "--ease-arrive", "--radius-overlay" ], "related": [ "chart-frame", "chart-legend", "sparkline", "bar-chart" ], "composedOf": [ "chart-legend", "chart-frame" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Two lines, named at their ends", "description": "A key shows for two or more lines. The names at the line ends repeat it. Click or tap the chart, or tab to it and use the arrow keys.", "code": "
\n \n
" }, { "title": "Four lines that differ by more than color", "description": "The third and fourth lines have a dash pattern and a square or triangle dot, so you can tell them apart without color.", "code": "
\n \n
" }, { "title": "Real numbers and a forecast", "description": "Forecast points are dotted. Here Saturday and Sunday are forecast.", "code": "
\n \"$\" + n.toLocaleString(\"en-US\")} unit=\"dollars\" ariaLabel=\"Daily sales\" />\n
" }, { "title": "A number still coming in", "description": "While the latest point is still coming in, it is hollow. The pop-up and screen reader both call it not final.", "code": "
\n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-line-chart/", "markdownUrl": "https://lkb00.github.io/tattva/docs/line-chart.md" }, { "id": "bar-chart", "name": "BarChart", "level": "organism", "since": "0.5", "aka": [ "bar graph", "column chart", "histogram", "stacked bar" ], "category": "numbers", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "hover", "note": "Moving the pointer over a bar or touching it shades its row and shows a tooltip with the values.", "source": "documented" }, { "name": "focus", "note": "The chart can be focused with the keyboard; arrow keys step through bars, Home and End jump to the ends and Escape clears the tooltip.", "source": "documented" }, { "name": "highlight", "note": "Pass highlight with a category label to colour that bar and grey out the rest.", "source": "documented" }, { "name": "stacked", "note": "Pass series with values per row to stack segments, add a legend and let arrow keys move between segments.", "source": "documented" }, { "name": "empty", "note": "With no data, only the axis is drawn.", "source": "documented" }, { "name": "truncated labels", "note": "Category labels that do not fit are cut off with an ellipsis, and totals too wide for a vertical bar are left out.", "source": "documented" } ], "summary": "Bars that compare amounts. Highlight one bar, or stack up to four parts.", "description": "BarChart compares amounts. Bars always start at zero. You can highlight one bar in the main color and leave the rest grey. A stacked version splits each bar into up to four parts, with a key in the same order.", "purpose": "Compares amounts with bars that always start at zero. One bar can be highlighted while the rest stay grey, so the bar that tells the story stands out.", "useFor": [ "Comparing amounts across categories, such as shops or months.", "Pointing at one category: set highlight.", "Showing what an amount is made of, with up to four stacked parts." ], "notFor": [ { "text": "Change over time across many points", "use": "line-chart" }, { "text": "A single number", "use": "stat-tile" }, { "text": "A best guess with a range", "use": "dot-plot" } ], "whenToUse": [ "Start every bar at zero. Never cut the scale.", "Highlight a bar when it is the story, and leave the rest grey.", "Lay bars sideways for long names or more than a handful of bars.", "Keep stacks to four parts, and list the key in the same order as the stack." ], "avoid": [ "Don't give every bar its own color. One set of bars takes one color.", "Don't draw a chart with one bar. Use a StatTile.", "Don't squeeze numbers inside bars that are too small. They sit at the bar end, and the table has them all.", "Don't use a pie or donut to show parts of a whole. Use a stacked bar." ], "accessibility": [ "You can tab to the chart. Arrow keys move between bars and, in a stacked chart, between parts. Home and End jump to the first and last bar.", "Each step is read out as the part or measure, the category, the value and the unit.", "Stacked parts have a small gap between them, and the key names each part in stack order.", "The pop-up is hidden from screen readers, because the same values are read out as you move." ], "accessibilityYouDo": [ "Put it in a ChartFrame with a summary and a table.", "Give it an ariaLabel, a measure and a unit, so each bar is read with what it measures." ], "onPhone": [ "The chart measures its container and redraws at that width. Long category labels are shortened with an ellipsis to fit.", "Touch or drag on a bar to show the tooltip. Vertical swipes still scroll the page, and the tooltip stays until you tap elsewhere.", "Horizontal bars suit a phone best, because labels have room to the left and the chart grows downward." ], "importPath": "import { BarChart } from \"./index\"", "sourcePath": "src/organisms/BarChart.tsx", "props": [ { "name": "data", "type": "BarDatum[]", "required": true, "default": null, "description": "One entry per category: label, and value (single series) or values (stacked). Values must be zero or more." }, { "name": "orientation", "type": "\"horizontal\" | \"vertical\"", "required": false, "default": "\"horizontal\"", "description": "Horizontal reads best for long labels and many categories." }, { "name": "series", "type": "BarSeries[]", "required": false, "default": null, "description": "Stack segment definitions, at most four. When set the chart is stacked and each datum uses values." }, { "name": "highlight", "type": "string", "required": false, "default": null, "description": "Label of the one category to emphasize. Others use the neutral." }, { "name": "measure", "type": "string", "required": false, "default": "\"Value\"", "description": "Name of the measure for single series charts, used in announcements and the tooltip." }, { "name": "formatValue", "type": "(n: number) => string", "required": false, "default": "formatNumber", "description": "Formats axis ticks, value labels and the tooltip." }, { "name": "unit", "type": "string", "required": false, "default": "\"\"", "description": "Unit word read after each value by screen readers." }, { "name": "height", "type": "number", "required": false, "default": null, "description": "Total height in px. Vertical charts default to 240. Horizontal charts size to their rows." }, { "name": "ariaLabel", "type": "string", "required": false, "default": "\"Bar chart\"", "description": "Name for the chart region." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the wrapper." } ], "variantsHint": { "orientation": [ "horizontal", "vertical" ] }, "tokens": [ "--chart-1", "--chart-2", "--chart-3", "--chart-4", "--chart-neutral", "--chart-grid", "--chart-axis", "--surface", "--surface-hover", "--radius-overlay" ], "related": [ "chart-frame", "chart-legend", "dot-plot", "stat-tile" ], "composedOf": [ "chart-legend" ], "plan": "free", "codeAvailable": true, "examples": [ { "title": "One bar stands out", "description": "One bar is the point, so it gets the main color and the rest are grey. Numbers sit at the ends of the bars.", "code": "
\n \"$\" + n.toLocaleString(\"en-US\")}\n unit=\"dollars\"\n ariaLabel=\"Sales by shop\"\n />\n
" }, { "title": "Upright bars", "description": "Use upright bars for a short list with short names. Names that do not fit are cut short. The full name is in the pop-up and table.", "code": "
\n \n
" }, { "title": "Stacked bars", "description": "Parts follow the key from left to right. The total sits at the end of each bar. Each part's number is in the pop-up and table.", "code": "
\n \n
" }, { "title": "With a table view", "description": "A helper builds the table data for ChartFrame.", "code": "
\n \"$\" + n.toLocaleString(\"en-US\") })}\n >\n \"$\" + n.toLocaleString(\"en-US\")} unit=\"dollars\" ariaLabel=\"Sales by shop\" />\n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-bar-chart/", "markdownUrl": "https://lkb00.github.io/tattva/docs/bar-chart.md" }, { "id": "dot-plot", "name": "DotPlot", "level": "organism", "since": "0.5", "aka": [ "scatter", "strip plot", "dot chart" ], "category": "numbers", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "hover", "note": "Moving the pointer over a row shades it and shows a tooltip with the estimate, interval and sample size.", "source": "documented" }, { "name": "focus", "note": "The chart can be focused with the keyboard; arrow keys step through rows and Escape clears the tooltip.", "source": "documented" }, { "name": "reference line", "note": "Pass reference to draw a labelled vertical line at that value.", "source": "documented" }, { "name": "narrow", "note": "Below about 440px wide, the value text beside each row is hidden, though the tooltip still shows it.", "source": "documented" }, { "name": "sample size", "note": "Pass showN to print each row's sample size when the data has n.", "source": "documented" } ], "summary": "Shows a best guess and how sure it is, with a caption that explains the marks.", "description": "DotPlot draws one row for each result. A dot shows the best guess and a thin line shows the range it likely falls in. A caption above says what the dot and line mean and how many people or cases it covers. The numbers are printed beside each row when there is room.", "purpose": "Shows a best guess and the range it likely falls in, one row per result. A caption says what the dot and line mean, because a bare range line means little to most readers.", "useFor": [ "Survey or test results where how sure you are matters.", "Comparing groups of different sizes: turn on showN.", "Results measured against a target, with a reference line." ], "notFor": [ { "text": "Amounts that should be compared by bar length", "use": "bar-chart" }, { "text": "Change over time", "use": "line-chart" } ], "whenToUse": [ "Write the caption so a reader can say what the line means, how sure it is and how many people are behind it.", "Show group sizes when groups are small or differ between rows.", "Print the numbers as text, so no one has to read them off the scale.", "When the question is how two things differ, show that difference directly." ], "avoid": [ "Don't leave the range line unexplained. A bare line means nothing.", "Don't treat overlapping lines as proof that two results are the same. They are not.", "Don't show scores with no range and no group size. At least show how many were asked.", "Don't cut a bar chart to fit a range. This chart marks positions, not bar lengths, so its scale can start above zero." ], "accessibility": [ "The caption is shown above the chart and is also part of the chart's name for screen readers.", "You can tab to the chart. Arrow keys move between rows, and Home and End jump to the first and last.", "Each row is read out as measure, row, value and unit, then the range and group size.", "The range line has end caps, and the dot has a ring that keeps it clear." ], "accessibilityYouDo": [ "Write a caption that says what the dot and line mean and how many people are behind them. Screen readers hear it as part of the chart's name.", "Set measure, intervalLabel and unit, so each row is read in full.", "Put it in a ChartFrame with a table. The numbers beside each row are dropped when the chart is narrow." ], "onPhone": [ "The chart measures its container and redraws at that width. Long row labels are shortened with an ellipsis to fit.", "Touch a row to show the tooltip. Vertical swipes still scroll the page, and the tooltip stays until you tap elsewhere.", "The caption above the chart wraps, so write it in plain words." ], "importPath": "import { DotPlot } from \"./index\"", "sourcePath": "src/organisms/DotPlot.tsx", "props": [ { "name": "data", "type": "DotDatum[]", "required": true, "default": null, "description": "One row per estimate: label, estimate, low, high and an optional n." }, { "name": "caption", "type": "string", "required": true, "default": null, "description": "Says what the dot and line mean, with the interval level and sample size. Rendered above the chart." }, { "name": "showN", "type": "boolean", "required": false, "default": null, "description": "Prints n beside each row. Use it for small samples." }, { "name": "measure", "type": "string", "required": false, "default": "\"Estimate\"", "description": "Name of the estimate in announcements and the tooltip." }, { "name": "intervalLabel", "type": "string", "required": false, "default": "\"interval\"", "description": "Names the interval, for example 95% confidence interval." }, { "name": "formatValue", "type": "(n: number) => string", "required": false, "default": "formatNumber", "description": "Formats the axis, text column and tooltip." }, { "name": "unit", "type": "string", "required": false, "default": "\"\"", "description": "Unit word read after each value by screen readers." }, { "name": "domain", "type": "[number, number]", "required": false, "default": null, "description": "Fixed value axis. Defaults to the interval extent. The axis does not need to start at zero." }, { "name": "reference", "type": "{ value: number; label: string }", "required": false, "default": null, "description": "A named reference line, such as the current model." }, { "name": "ariaLabel", "type": "string", "required": false, "default": "\"Dot plot\"", "description": "Name for the chart region." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the wrapper." } ], "variantsHint": {}, "tokens": [ "--chart-1", "--chart-grid", "--chart-axis", "--surface", "--surface-hover", "--fg", "--fg-muted", "--radius-overlay" ], "related": [ "bar-chart", "chart-frame", "stat-tile", "data-table" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "Happy customers, with a range", "description": "The caption says what is measured, how sure we are and how many customers. The text column gives the numbers.", "code": "
\n Math.round(n * 1000) / 10 + \"%\"}\n unit=\"percent\"\n ariaLabel=\"Happy customers by shop\"\n />\n
" }, { "title": "Different group sizes and a goal line", "description": "Each row prints how many customers were asked, so a wide range from a small group makes sense. The line marks the current shop.", "code": "
\n Math.round(n * 1000) / 10 + \"%\"}\n unit=\"percent\"\n ariaLabel=\"Happy customers by shop\"\n />\n
" }, { "title": "With a table view", "description": "A helper lists the best guess, both ends of the range and the group size.", "code": "
\n Math.round(n * 1000) / 10 + \"%\" })}\n >\n Math.round(n * 1000) / 10 + \"%\"} unit=\"percent\" />\n \n
" } ], "pageUrl": "https://lkb00.github.io/tattva/component-dot-plot/", "markdownUrl": "https://lkb00.github.io/tattva/docs/dot-plot.md" }, { "id": "chart-legend", "name": "ChartLegend", "level": "organism", "since": "0.5", "aka": [ "legend", "key" ], "category": "numbers", "status": "stable", "lifecycle": { "stage": "stable", "since": null, "replacedBy": null, "removeIn": null, "note": null }, "states": [ { "name": "hidden series", "note": "An item whose id is in hidden is shown struck through and dimmed.", "source": "documented" }, { "name": "toggle", "note": "Pass onToggle to turn each entry into a button that shows or hides its series.", "source": "documented" }, { "name": "hover", "note": "A toggle entry gets a soft background under the pointer.", "source": "documented" }, { "name": "focus", "note": "A toggle entry shows a focus ring on keyboard focus.", "source": "documented" } ], "summary": "A key that explains each color, dash and marker in a chart, in the chart's order. It can also switch lines on and off.", "description": "ChartLegend lists each line or bar with the same color, dash and marker the chart uses. Items follow the chart's order. They can become buttons that show or hide a line. Charts draw their own key when they have two or more lines. Use this one for custom layouts or a key shared by several charts.", "purpose": "A key that shows the same color, dash and marker as each line or bar, in the chart's order. It can also turn lines on and off.", "useFor": [ "One key shared by several charts.", "A custom layout where the key sits apart from the chart.", "Letting people show or hide lines: pass onToggle." ], "notFor": [ { "text": "A chart with only one line. The title names it" }, { "text": "A LineChart or stacked BarChart on its own. They draw their own key" } ], "whenToUse": [ "Show a key for two or more lines, and none for one.", "Keep the key in the same order as the lines or stack.", "Let a hidden line keep its color. Hiding one line must not recolor the others.", "Hide the line in the chart when its item is turned off. The key only tells you through onToggle." ], "avoid": [ "Don't color the name text. The sample beside it shows which is which.", "Don't make the key the only way to tell lines apart. With four or fewer, name the lines at their ends too.", "Don't add a key for one line. The title names it." ], "accessibility": [ "It is a list named \"Legend\" by default, and every item has a written name.", "With onToggle, each item is a button that screen readers hear as pressed or not, with the word \"shown\" or \"hidden\".", "The color samples are hidden from screen readers, because the name says the same thing.", "From the third item on, a dash pattern and a marker shape back up the color." ], "accessibilityYouDo": [ "List items in the same order as the chart's lines or stack.", "Give it a label that says which chart it belongs to when a page has more than one key." ], "onPhone": [ "The legend wraps onto more lines when the chart is narrow.", "When the items are toggle buttons they are 24px tall. On touch screens they keep that size and have a 44px tap area." ], "importPath": "import { ChartLegend } from \"./index\"", "sourcePath": "src/organisms/ChartLegend.tsx", "props": [ { "name": "items", "type": "LegendItem[]", "required": true, "default": null, "description": "Items in the chart's series or stack order. Each has id, label and an optional style." }, { "name": "kind", "type": "\"line\" | \"bar\"", "required": false, "default": "\"line\"", "description": "Line shows the dash and marker. Bar shows a rounded swatch." }, { "name": "hidden", "type": "string[]", "required": false, "default": "[]", "description": "Ids currently hidden. Only used with onToggle." }, { "name": "onToggle", "type": "(id: string) => void", "required": false, "default": null, "description": "Makes items toggle buttons. Pressed means shown." }, { "name": "label", "type": "string", "required": false, "default": "\"Legend\"", "description": "Accessible name for the list." }, { "name": "className", "type": "string", "required": false, "default": null, "description": "Extra classes on the list." } ], "variantsHint": { "kind": [ "line", "bar" ] }, "tokens": [ "--chart-1", "--chart-2", "--chart-3", "--chart-4", "--chart-5", "--surface", "--fg-muted", "--fg-subtle", "--radius-control" ], "related": [ "line-chart", "bar-chart", "chart-frame" ], "composedOf": [], "plan": "free", "codeAvailable": true, "examples": [ { "title": "A key with dashes and dots", "description": "The first two lines are solid with round dots. From the third on, the dash and dot shape change too, not only the color.", "code": "" }, { "title": "A key for bars", "description": "Use this for bars and stacks. List items in the order the stack is read.", "code": "" }, { "title": "Switch lines on and off", "description": "Pressed means the line is shown. A hidden line keeps its place and color, and its name is crossed out.", "code": "function LegendToggleDemo() {\n const [hidden, setHidden] = useState([]);\n return (\n