AI Insight
⋯
The AI insight primitives mark AI-generated content in Teal and explain how it was made. They
render the Figma AI Label, .AI Meta Line, .AI Feedback, AI Inline Insight, AI Expected Range,
and AI Chart Marker components, and the AI Insights, AI Explanation Popover, AI Recommendation Card,
and AI Driver Breakdown compositions built from them. Loading states use the Teal or Neutral tone of
Skeleton.
import { AiInlineInsight, AiLabel } from "@nesra/ui/ai";
export function EngagementInsight() { return ( <AiInlineInsight> <AiLabel description="Based on your data for Oct 1–7, compared with Sep 24–30." /> <AiInlineInsight.Content> <AiInlineInsight.Text> Engagement rose <AiInlineInsight.Value tone="success">+18.2%</AiInlineInsight.Value> vs last week. </AiInlineInsight.Text> </AiInlineInsight.Content> </AiInlineInsight> );}Every export on this page is also exported from @nesra/ui.
Composition
Section titled “Composition”AiInlineInsight├── AiLabel└── AiInlineInsight.Content (or AiInlineInsight.Loading, or AiInlineInsight.Empty) ├── AiInlineInsight.Text │ └── AiInlineInsight.Value ├── TooltipTrigger ("Why?", optional) └── AiInlineInsight.Footer (optional) ├── AiMetaLine │ ├── AiMetaLine.Item │ └── AiMetaLine.Stale └── AiFeedback
LineChart, AreaChart, BarChart, ComboChart, or LineChartPlot├── AiExpectedRange└── AiChartMarker
AiInsights (title, state, meta, feedback props)└── AiInsights.Insight └── AiInsights.Value
AiExplanationPopover (anchor or trigger, drivers, meta props)└── AiExplanationPopover.Value
AiDriverBreakdown (Sheet; trigger, drivers, meta, feedback props)└── AiDriverBreakdown.Value
AiRecommendationCard (state, impact, meta props)The popover and the breakdown render the Figma .AI Driver Row and .AI Share Bar parts from the
drivers data, so the share and change columns line up across rows. These parts are not exported.
AiLabel.Mark is the decorative Nesra mark used inside AiLabel. Use it alone where Figma shows the
mark without a label.
Examples
Section titled “Examples”AI Label
Section titled “AI Label”size="sm" uses a 16px mark and Body/XSmall/Medium. size="md" uses a 20px mark and
Body/Small/Medium. The mark is Categorical/Teal/strong and the text is
Categorical/Teal/foreground. Hover, focus, or press a label to open its Rich Tooltip.
showText={false} keeps only the mark visible.
import { AiLabel } from "@nesra/ui/ai";
const description = "Based on your data for Oct 1–7, compared with Sep 24–30. Statistical change detection finds the biggest shifts, then AI writes the summary. Updated 2 hours ago.";
export function AiLabelExample() { return ( <div className="flex flex-wrap items-center gap-8"> <AiLabel description={description} title="How this insight was generated" /> <AiLabel description={description} size="md" title="How this insight was generated" /> <AiLabel description={description} title="How this summary was generated"> Summarized with AI </AiLabel> <AiLabel description={description} showText={false} title="How this insight was generated" /> </div> );}AI Meta Line
Section titled “AI Meta Line”AiMetaLine.Item renders the Figma Fresh state. Each item after the first starts with a 16px
divider. AiMetaLine.Stale renders the Stale state, and onRefresh adds the Refresh button.
import { AiMetaLine } from "@nesra/ui/ai";
export function AiMetaLineExample() { return ( <div className="grid gap-4"> <AiMetaLine> <AiMetaLine.Item>Oct 1–7 vs Sep 24–30</AiMetaLine.Item> <AiMetaLine.Item>Updated 2 hours ago</AiMetaLine.Item> </AiMetaLine> <AiMetaLine> <AiMetaLine.Stale onRefresh={() => console.log("Regenerate the insight")}> Filters changed since this was generated </AiMetaLine.Stale> </AiMetaLine> </div> );}AI Feedback
Section titled “AI Feedback”The selected thumb switches from Ghost to Outline and sets aria-pressed="true". The prompt
changes to “Thanks for the feedback”. Pressing the selected thumb again clears the selection. Your
application sends the feedback from onValueChange.
import { useState } from "react";import { AiFeedback, type AiFeedbackValue } from "@nesra/ui/ai";
export function AiFeedbackExample() { const [value, setValue] = useState<AiFeedbackValue | null>(null); return ( <div className="grid gap-2"> <AiFeedback onValueChange={(next) => { setValue(next); // Send `next` with the insight ID to your feedback endpoint here. }} value={value} /> <p className="m-0 type-nesra-body-xsmall-regular text-nesra-text-support"> Selected: {value ?? "none"} </p> </div> );}AI Inline Insight
Section titled “AI Inline Insight”Place the insight next to the number it explains. A muted xs Tooltip Trigger
renders the Figma “Why?” link.
import { AiInlineInsight, AiLabel } from "@nesra/ui/ai";import { TooltipTrigger } from "@nesra/ui/tooltip";
export function AiInlineInsightExample() { return ( <div className="w-full max-w-xs"> <AiInlineInsight> <AiLabel description="Based on your data for Oct 1–7, compared with Sep 24–30. Updated 2 hours ago." title="How this insight was generated" /> <AiInlineInsight.Content> <AiInlineInsight.Text> Engagement rose <AiInlineInsight.Value tone="success">+18.2%</AiInlineInsight.Value> vs last week, mostly from one segment. </AiInlineInsight.Text> <TooltipTrigger description="Mobile sessions from the Social channel drove most of the rise." size="xs" tone="muted" > Why? </TooltipTrigger> </AiInlineInsight.Content> </AiInlineInsight> </div> );}Styles and sizes
Section titled “Styles and sizes”variant="tinted" fills with Categorical/Teal/subtle and pads 8px by 12px. variant="plain" has
no fill or padding. size="sm" uses Body/XSmall text and size="md" Body/Small text.
import { AiInlineInsight, AiLabel } from "@nesra/ui/ai";
const description = "Based on your data for Oct 1–7, compared with Sep 24–30.";
export function AiInlineInsightVariantsExample() { return ( <div className="grid w-full gap-4 sm:grid-cols-2"> {(["tinted", "plain"] as const).map((variant) => (["sm", "md"] as const).map((size) => ( <AiInlineInsight key={`${variant}-${size}`} size={size} variant={variant}> <AiLabel description={description} /> <AiInlineInsight.Content> <AiInlineInsight.Text> Cost per click rose{" "} <AiInlineInsight.Value tone="destructive">+12%</AiInlineInsight.Value> vs last week ({variant}, {size}). </AiInlineInsight.Text> </AiInlineInsight.Content> </AiInlineInsight> )), )} </div> );}Loading and empty
Section titled “Loading and empty”AiInlineInsight.Loading shows two 10px skeleton lines in a busy status region. The lines are Teal on
tinted and Neutral on plain. AiInlineInsight.Empty shows “Not enough data for insights yet.”
in Text/text-support.
import { AiInlineInsight, AiLabel } from "@nesra/ui/ai";
const description = "Based on your data for Oct 1–7, compared with Sep 24–30.";
export function AiInlineInsightStatesExample() { return ( <div className="grid w-full gap-4 sm:grid-cols-2"> <AiInlineInsight> <AiLabel description={description} /> <AiInlineInsight.Loading /> </AiInlineInsight> <AiInlineInsight variant="plain"> <AiLabel description={description} /> <AiInlineInsight.Loading /> </AiInlineInsight> <AiInlineInsight> <AiLabel description={description} /> <AiInlineInsight.Empty /> </AiInlineInsight> <AiInlineInsight variant="plain"> <AiLabel description={description} /> <AiInlineInsight.Empty /> </AiInlineInsight> </div> );}Meta line and feedback
Section titled “Meta line and feedback”AiInlineInsight.Footer places a meta line and feedback on one wrapping row.
import { AiFeedback, AiInlineInsight, AiLabel, AiMetaLine } from "@nesra/ui/ai";
export function AiInlineInsightFooterExample() { return ( <div className="w-full max-w-md"> <AiInlineInsight size="md"> <AiLabel description="Based on your data for Oct 1–7, compared with Sep 24–30." title="How this insight was generated" /> <AiInlineInsight.Content> <AiInlineInsight.Text> Sign-ups fell <AiInlineInsight.Value tone="destructive">−6.4%</AiInlineInsight.Value> vs last week, likely from a slower landing page on mobile. </AiInlineInsight.Text> <AiInlineInsight.Footer> <AiMetaLine> <AiMetaLine.Item>Oct 1–7 vs Sep 24–30</AiMetaLine.Item> <AiMetaLine.Item>Updated 2 hours ago</AiMetaLine.Item> </AiMetaLine> <AiFeedback onValueChange={(value) => console.log("Feedback", value)} /> </AiInlineInsight.Footer> </AiInlineInsight.Content> </AiInlineInsight> </div> );}Expected range and chart markers
Section titled “Expected range and chart markers”AiExpectedRange draws a Categorical/Teal/base band at 15% opacity with dashed
Categorical/Teal/border edges. AiChartMarker type="anomaly" uses the Teal roles and
type="event" the neutral Event roles.
The interactive marker opens a controlled Popover anchored to the marker’s ref. active shows the
halo and sets aria-expanded while the popover is open. The finalFocus function returns focus to
the marker when the popover closes, because the marker is not a Popover trigger. Select or focus the
Oct 5 marker and press Enter.
import { useRef, useState } from "react";import { AiChartMarker, AiExpectedRange } from "@nesra/ui/ai";import { LineChartPlot, type LineChartPoint, type LineChartSeries } from "@nesra/ui/line-chart";import { Popover } from "@nesra/ui/popover";
// Synthetic values for this documentation example.const data: LineChartPoint[] = [ { id: "oct-1", label: "Oct 1", values: { sessions: 6100 } }, { id: "oct-2", label: "Oct 2", values: { sessions: 5900 } }, { id: "oct-3", label: "Oct 3", values: { sessions: 6400 } }, { id: "oct-4", label: "Oct 4", values: { sessions: 7000 } }, { id: "oct-5", label: "Oct 5", values: { sessions: 9800 } }, { id: "oct-6", label: "Oct 6", values: { sessions: 7100 } }, { id: "oct-7", label: "Oct 7", values: { sessions: 6800 } },];const series: LineChartSeries[] = [{ key: "sessions", label: "Sessions", color: "blue" }];
export function AiChartExample() { const marker = useRef<SVGGElement>(null); const [open, setOpen] = useState(false); return ( <div className="w-full"> <LineChartPlot data={data} formatValue={(value) => value.toLocaleString("en-US")} label="Daily sessions" series={series} summary="Daily sessions, Oct 1 to Oct 7. Select the Oct 5 marker for an explanation." > <AiExpectedRange from={5500} to={7500} /> <AiChartMarker category="oct-2" label="Budget raised on Oct 2" type="event" value={5900} /> <AiChartMarker active={open} category="oct-5" label="Anomaly on Oct 5" onClick={() => setOpen(true)} ref={marker} value={9800} /> </LineChartPlot> <Popover onOpenChange={setOpen} open={open}> <Popover.Content anchor={marker} finalFocus={() => { marker.current?.focus(); return false; }} side="right" > <Popover.Title>Unusual spike on Oct 5</Popover.Title> <Popover.Description> 9,800 sessions, above the expected range of 5,500 to 7,500. </Popover.Description> </Popover.Content> </Popover> </div> );}AI Insights
Section titled “AI Insights”A collapsible banner in Categorical/Teal/subtle with a Categorical/Teal/base border. In the
ready state, Show more and Show less expand the insights, the meta line, the disclaimer, and the
optional feedback. Label each insight in Semibold Text/text-headline, and color values by
sentiment with AiInsights.Value.
import { AiFeedback, AiInsights, AiMetaLine } from "@nesra/ui/ai";
export function AiInsightsExample() { return ( <AiInsights feedback={<AiFeedback />} meta={ <AiMetaLine> <AiMetaLine.Item>Oct 1–7 vs Sep 24–30</AiMetaLine.Item> <AiMetaLine.Item>Updated 2 hours ago</AiMetaLine.Item> </AiMetaLine> } title="Performance insights" > <AiInsights.Insight label="Strong growth:"> Engagement rose <AiInsights.Value tone="success">+24.5%</AiInsights.Value> compared with the previous period, driven by a <AiInsights.Value tone="success">+18.2%</AiInsights.Value>{" "} increase in new visitors. Keep investing in the channels behind this growth. </AiInsights.Insight> <AiInsights.Insight label="Needs attention:"> Cost per result increased <AiInsights.Value tone="destructive">+12.4%</AiInsights.Value>{" "} versus the previous period. Review underperforming segments to bring it back down. </AiInsights.Insight> </AiInsights> );}AI Insights states
Section titled “AI Insights states”Only ready has the toggle. In the other states, open chooses the compact or expanded layout.
loading shows a disabled “Generating…” button and three Teal skeleton lines. empty shows “No
significant changes this period”. error shows the error and, with onRetry, a Try again button.
import { AiInsights, AiMetaLine } from "@nesra/ui/ai";
const meta = ( <AiMetaLine> <AiMetaLine.Item>Oct 1–7 vs Sep 24–30</AiMetaLine.Item> <AiMetaLine.Item>Updated 2 hours ago</AiMetaLine.Item> </AiMetaLine>);
export function AiInsightsStatesExample() { return ( <div className="grid w-full gap-4"> <AiInsights state="loading" title="Performance insights" /> <AiInsights defaultOpen state="loading" title="Performance insights" /> <AiInsights state="empty" title="Performance insights" /> <AiInsights defaultOpen meta={meta} state="empty" title="Performance insights" /> <AiInsights onRetry={() => {}} state="error" title="Performance insights" /> <AiInsights defaultOpen onRetry={() => {}} state="error" title="Performance insights" /> </div> );}AI Explanation Popover
Section titled “AI Explanation Popover”A 320px popover with radius-xl, shadow-lg, and padding-2xl, and no arrow. It shows the
finding, the likely drivers, the meta line, and View details. no-clear-cause says so plainly
instead of listing drivers, and loading shows Neutral skeleton lines. Pass trigger for a button
that opens it, or anchor for an AI Chart Marker.
import { AiExplanationPopover, AiMetaLine, type AiDriver } from "@nesra/ui/ai";import { Button } from "@nesra/ui/button";
// Cost per result: a rise is bad, so each driver uses lower-is-better.const drivers: AiDriver[] = [ { id: "mobile", label: "Device: Mobile", share: 58, direction: "up", change: "+41%", polarity: "lower-is-better", }, { id: "social", label: "Channel: Social", share: 27, direction: "up", change: "+22%", polarity: "lower-is-better", }, { id: "new", label: "Audience: New", share: 15, direction: "up", change: "+9%", polarity: "lower-is-better", },];
const meta = ( <AiMetaLine> <AiMetaLine.Item>Oct 1–7 vs Sep 24–30</AiMetaLine.Item> <AiMetaLine.Item>Updated 2 hours ago</AiMetaLine.Item> </AiMetaLine>);
export function AiExplanationPopoverExample() { return ( <div className="flex flex-wrap gap-3"> {(["ready", "no-clear-cause", "loading"] as const).map((state) => ( <AiExplanationPopover drivers={drivers} key={state} meta={meta} onViewDetails={() => {}} side="bottom" state={state} title="Unusual spike on Oct 5" trigger={<Button variant="outline">Open {state}</Button>} > <AiExplanationPopover.Value tone="destructive">+32%</AiExplanationPopover.Value> above the expected range for this day of the week. </AiExplanationPopover> ))} </div> );}AI Recommendation Card
Section titled “AI Recommendation Card”Apply always asks first. Confirm moves to Applied with Undo, and Dismiss moves to Dismissed with
Undo. The card shows no scores. Control state with onStateChange, and apply or revert the change
in onApply and onUndo.
import { useState } from "react";import { AiMetaLine, AiRecommendationCard, type AiRecommendationState } from "@nesra/ui/ai";import { Users } from "lucide-react";
export function AiRecommendationCardExample() { const [state, setState] = useState<AiRecommendationState>("default"); return ( <div className="w-full max-w-[360px]"> <AiRecommendationCard affected="Affects 3 active campaigns" category="Audience" categoryIcon={<Users />} confirmMessage="Apply to 3 active campaigns? You can undo this later." impact={{ direction: "up", value: "+8–12%", unit: "engagement per week" }} meta={ <AiMetaLine> <AiMetaLine.Item>Based on Oct 1–7</AiMetaLine.Item> <AiMetaLine.Item>Updated 2 hours ago</AiMetaLine.Item> </AiMetaLine> } onApply={() => { // Apply the change to the campaigns here. }} onReview={() => {}} onStateChange={setState} onUndo={() => { // Revert the change here. }} state={state} title="Focus on mobile audiences" > Because mobile drove <strong className="font-semibold text-nesra-text-headline">58%</strong>{" "} of last week's engagement growth, while other devices stayed flat. </AiRecommendationCard> </div> );}Recommendation states and sizes
Section titled “Recommendation states and sizes”size="full" uses the Metric Chart Card shell: Surface/card-bg-neutral, a Stroke/stroke-border
border, radius-2xl, and padding-4xl. size="compact" is one row for table Actions columns and
dense lists. Applied uses the outline Verified status Badge.
import { AiRecommendationCard } from "@nesra/ui/ai";import { Users } from "lucide-react";
const states = ["default", "confirm", "applied", "dismissed"] as const;
export function AiRecommendationCardStatesExample() { return ( <div className="grid w-full gap-6"> <div className="grid gap-4 sm:grid-cols-2"> {states.map((state) => ( <AiRecommendationCard category="Audience" categoryIcon={<Users />} confirmMessage="Apply to 3 active campaigns? You can undo this later." defaultState={state} impact={{ direction: "up", value: "+8–12%", unit: "engagement per week" }} key={state} title="Focus on mobile audiences" > Because mobile drove 58% of last week's engagement growth. </AiRecommendationCard> ))} <AiRecommendationCard category="Audience" categoryIcon={<Users />} loading title="Focus on mobile audiences" /> </div> <div className="grid max-w-[320px] gap-2"> {states.map((state) => ( <AiRecommendationCard confirmMessage="Apply to 3 campaigns?" defaultState={state} key={state} size="compact" title="Focus on mobile audiences" /> ))} <AiRecommendationCard loading size="compact" title="Focus on mobile audiences" /> </div> </div> );}AI Driver Breakdown
Section titled “AI Driver Breakdown”The full driver list in a right-side Sheet. Figma defines the content only;
the drawer is not part of the design system yet. Each row adds an .AI Share Bar: a 64px
Foundation/bg-disabled track with a Categorical/Blue/base fill at the nearest 5%. The text keeps
the exact share.
import { AiDriverBreakdown, AiFeedback, AiMetaLine, type AiDriver } from "@nesra/ui/ai";import { Button } from "@nesra/ui/button";
const drivers: AiDriver[] = [ { id: "mobile", label: "Device: Mobile", share: 46, direction: "up", change: "+41%" }, { id: "social", label: "Channel: Social", share: 24, direction: "up", change: "+22%" }, { id: "new", label: "Audience: New", share: 14, direction: "up", change: "+9%" }, { id: "west", label: "Region: West", share: 10, direction: "up", change: "+6%" }, { id: "weekend", label: "Time: Weekend", share: 6, direction: "up", change: "+3%" },];
export function AiDriverBreakdownExample() { return ( <div className="flex flex-wrap gap-3"> {(["ready", "no-clear-cause", "loading"] as const).map((state) => ( <AiDriverBreakdown drivers={drivers} feedback={<AiFeedback />} key={state} meta={ <AiMetaLine> <AiMetaLine.Item>Oct 1–7 vs Sep 24–30</AiMetaLine.Item> <AiMetaLine.Item>Updated 2 hours ago</AiMetaLine.Item> </AiMetaLine> } state={state} title="Why did engagement rise?" trigger={<Button variant="outline">Open {state}</Button>} > Engagement rose <AiDriverBreakdown.Value tone="success">+18.2%</AiDriverBreakdown.Value>{" "} vs last week. Five segments explain the change. </AiDriverBreakdown> ))} </div> );}From chart marker to breakdown
Section titled “From chart marker to breakdown”The AI Chart Marker opens the AI Explanation Popover beside it. View details closes the popover and
opens the AI Driver Breakdown. finalFocus returns focus to the marker when the sheet closes,
because the View details button is gone by then. Focus the Oct 5 marker and press Enter.
import { useRef, useState } from "react";import { AiChartMarker, AiDriverBreakdown, AiExpectedRange, AiExplanationPopover, AiFeedback, AiMetaLine, type AiDriver,} from "@nesra/ui/ai";import { LineChartPlot, type LineChartPoint, type LineChartSeries } from "@nesra/ui/line-chart";
// Synthetic values for this documentation example.const data: LineChartPoint[] = [ { id: "oct-1", label: "Oct 1", values: { cost: 410 } }, { id: "oct-2", label: "Oct 2", values: { cost: 395 } }, { id: "oct-3", label: "Oct 3", values: { cost: 430 } }, { id: "oct-4", label: "Oct 4", values: { cost: 445 } }, { id: "oct-5", label: "Oct 5", values: { cost: 610 } }, { id: "oct-6", label: "Oct 6", values: { cost: 452 } }, { id: "oct-7", label: "Oct 7", values: { cost: 438 } },];const series: LineChartSeries[] = [{ key: "cost", label: "Cost per result", color: "blue" }];
// Cost per result: a rise is bad, so each driver uses lower-is-better.const drivers: AiDriver[] = [ { id: "mobile", label: "Device: Mobile", share: 58, direction: "up", change: "+41%", polarity: "lower-is-better", }, { id: "social", label: "Channel: Social", share: 27, direction: "up", change: "+22%", polarity: "lower-is-better", }, { id: "new", label: "Audience: New", share: 9, direction: "up", change: "+9%", polarity: "lower-is-better", }, { id: "west", label: "Region: West", share: 4, direction: "up", change: "+3%", polarity: "lower-is-better", }, { id: "weekend", label: "Time: Weekend", share: 2, direction: "flat", change: "0%", polarity: "lower-is-better", },];
const meta = ( <AiMetaLine> <AiMetaLine.Item>Oct 1–7 vs Sep 24–30</AiMetaLine.Item> <AiMetaLine.Item>Updated 2 hours ago</AiMetaLine.Item> </AiMetaLine>);
export function AiExplanationFlowExample() { const marker = useRef<SVGGElement>(null); const [popoverOpen, setPopoverOpen] = useState(false); const [breakdownOpen, setBreakdownOpen] = useState(false); return ( <div className="w-full"> <LineChartPlot data={data} formatValue={(value) => `$${value}`} label="Daily cost per result" series={series} summary="Daily cost per result, Oct 1 to Oct 7. Select the Oct 5 marker for an explanation." > <AiExpectedRange from={380} to={470} /> <AiChartMarker active={popoverOpen || breakdownOpen} category="oct-5" label="Anomaly on Oct 5" onClick={() => setPopoverOpen(true)} ref={marker} value={610} /> </LineChartPlot> <AiExplanationPopover anchor={marker} drivers={drivers.slice(0, 3)} meta={meta} onOpenChange={setPopoverOpen} onViewDetails={() => { setPopoverOpen(false); setBreakdownOpen(true); }} open={popoverOpen} title="Unusual spike on Oct 5" > <AiExplanationPopover.Value tone="destructive">+32%</AiExplanationPopover.Value> above the expected range for this day of the week. </AiExplanationPopover> <AiDriverBreakdown drivers={drivers} feedback={<AiFeedback />} finalFocus={() => { // "View details" is gone by now, so return focus to the marker. marker.current?.focus(); return false; }} meta={meta} onOpenChange={setBreakdownOpen} open={breakdownOpen} title="Why did cost per result rise on Oct 5?" > Cost per result was{" "} <AiDriverBreakdown.Value tone="destructive">+32%</AiDriverBreakdown.Value> above the expected range. Five segments explain the change. </AiDriverBreakdown> </div> );}Light and Dark
Section titled “Light and Dark”All parts follow the page theme through .dark or data-theme="dark". The Teal categorical roles
have their own Dark values. For example, Categorical/Teal/subtle is teal-50 in Light and teal-950
in Dark, and Categorical/Teal/foreground is teal-700 in Light and teal-300 in Dark. The Rich
Tooltip and the AI Explanation Popover use Surface/popover-bg-neutral, and the AI Recommendation
Card and AI Driver Breakdown use Surface/card-bg-neutral. Use the theme select in the header to
compare both modes.
Accessibility
Section titled “Accessibility”AiLabelis a button named by its text, including hidden text. Itsdescriptionis also its accessible description. Keyboard focus and Enter or Space open the tooltip. Escape and blur close it, and focus stays on the label.AiLabel.Markand the AI Meta Line divider and history icon are hidden from assistive technology.AiFeedbackis a group labelled by its prompt. Each thumb is a toggle button named “Helpful” or “Not helpful” witharia-pressed. Arrow keys move between thumbs, and Tab leaves the group. The prompt is a polite live region, so the thank-you text is announced.AiInlineInsight.Loadingis astatusregion witharia-busy="true"and screen-reader text. The skeleton pulse stops when the user prefers reduced motion.AiInsightsis a region named by its title. Inready, the toggle is a disclosure button witharia-expandedandaria-controls. Enter and Space toggle it. A polite status region announces “Generating insights” and the error summary when the state changes.AiExplanationPopoveris a non-modal dialog named by its title and described by the finding. Focus moves to the dialog on open, so the AI Label’s tooltip does not cover it. Escape, outside press, and the close button close it. Focus returns to thetrigger, or to theanchorwhen it is focusable, such as an AI Chart Marker.- Driver rows are list items under the drivers heading. Each row reads its label, its exact share, and its change, such as “Up +41%”. The share bar is hidden from assistive technology, because the text carries the exact value.
AiDriverBreakdownis a modal dialog named by its title and described by its summary. Focus moves to the panel, Tab stays inside, and Escape closes it. Focus returns to thetrigger. When the sheet opens from a control that is gone, such as View details, setfinalFocus.AiRecommendationCardis an article named by its title. After Apply, Confirm, Cancel, Dismiss, or Undo, focus moves to the control that replaced the pressed one. A polite status region announces “Applied”, “Dismissed”, and “Undone” with the title, including changes the parent makes.- Loading states are busy
statusregions with screen-reader text. The skeleton pulse stops when the user prefers reduced motion. - Insight text and range values remain the application’s responsibility. Keep numbers identical to the source data.
AiExpectedRangeis decorative in the plot. Its text, such as “Expected range: 5,500 to 7,500”, is listed with the chart data.AiChartMarkerwithonClickis a focusable button witharia-haspopup="dialog". Enter and Space activate it. WithoutonClick, it is an image named bylabel. Give each marker a text label, such as “Anomaly on Oct 5”.
API reference
Section titled “API reference”AiLabel
Section titled “AiLabel”| Prop | Type | Default | Description |
|---|---|---|---|
description |
ReactNode |
Required | Tooltip text and the label’s accessible description. Say which data, method, and update time were used. |
title |
ReactNode |
— | Tooltip heading that names the dialog. |
children |
string |
"AI insights" |
Label text. The default is localized. |
size |
"sm" | "md" |
"sm" |
Mark and text size. Inside AiInlineInsight, the insight size. |
showText |
boolean |
true |
Shows the text beside the mark. Inside AiInlineInsight, false. |
side |
"top" | "bottom" | "left" | "right" |
"top" |
Preferred tooltip side. |
align |
"start" | "center" | "end" |
"start" |
Preferred tooltip alignment. |
className |
string |
— | Trigger classes. |
AiLabel also accepts the Rich Tooltip open, defaultOpen, onOpenChange, delay,
closeDelay, container, and popupClassName props. Its ref points to the button.
AiLabel.Mark forwards native SVG props and its ref, and its default size is 16px.
AiMetaLine
Section titled “AiMetaLine”AiMetaLine forwards native div props. AiMetaLine.Item forwards native span props.
AiMetaLine.Stale prop |
Type | Default | Description |
|---|---|---|---|
children |
ReactNode |
— | Stale message. |
onRefresh |
(event: MouseEvent<HTMLButtonElement>) => void |
— | Shows the Refresh icon button and handles its press. |
refreshLabel |
string |
"Refresh insight" |
Refresh button name. The default is localized. |
AiFeedback
Section titled “AiFeedback”| Prop | Type | Default | Description |
|---|---|---|---|
value |
"helpful" | "not-helpful" | null |
— | Controlled selection. |
defaultValue |
"helpful" | "not-helpful" | null |
null |
Initial selection when uncontrolled. |
onValueChange |
(value: AiFeedbackValue | null) => void |
— | Called on each press. Reports null when a selection clears. |
prompt |
ReactNode |
"Was this helpful?" |
Prompt before a selection. |
thanks |
ReactNode |
"Thanks for the feedback" |
Prompt after a selection. |
disabled |
boolean |
false |
Disables both thumbs. |
AiFeedback forwards other native div props and its ref to the root.
AiInlineInsight
Section titled “AiInlineInsight”| Prop | Type | Default | Description |
|---|---|---|---|
variant |
"tinted" | "plain" |
"tinted" |
Figma Style. tinted adds the Teal fill and padding. |
size |
"sm" | "md" |
"sm" |
Figma Size. Sets text size and the default size of AiLabel. |
The root and Content, Footer, and Loading forward native div props. Text and Empty
forward native p props, and Value forwards native strong props. Each part forwards its ref.
| Part prop | Type | Default | Description |
|---|---|---|---|
Value tone |
"neutral" | "success" | "destructive" |
"neutral" |
Number color by sentiment, not by sign. |
Loading label |
string |
"Loading AI insight" |
Screen-reader status text. |
Empty children |
ReactNode |
"Not enough data for insights yet." |
Empty message. |
AiExpectedRange
Section titled “AiExpectedRange”| Prop | Type | Default | Description |
|---|---|---|---|
from |
number |
Required | Expected low value, in plotted units. |
to |
number |
Required | Expected high value, in plotted units. |
label |
string |
"Expected range" |
Text listed with the chart data. The default is localized. |
Render it as a child of a Nesra cartesian chart. It is ChartBand with axis="value" and
color="teal".
AiChartMarker
Section titled “AiChartMarker”| Prop | Type | Default | Description |
|---|---|---|---|
category |
string |
Required | Point ID of the marked category. |
label |
string |
Required | Accessible name and data-list text. |
value |
number |
— | Places the dot at this value. Without it, only a dashed guide is drawn. |
type |
"anomaly" | "event" |
"anomaly" |
anomaly uses Teal roles. event uses neutral Event roles. |
active |
boolean |
false |
Shows the halo. With onClick, also sets aria-expanded. |
onClick |
MouseEventHandler |
— | Makes the marker a focusable button with aria-haspopup="dialog". |
AiChartMarker forwards other SVG group attributes, such as aria-controls, and its ref points to
the SVG group. Render it as a child of a Nesra cartesian chart.
AiInsights
Section titled “AiInsights”| Prop | Type | Default | Description |
|---|---|---|---|
title |
ReactNode |
Required | Header text. Names the region. |
state |
"ready" | "loading" | "empty" | "error" |
"ready" |
Figma State. Only ready has the toggle. |
open |
boolean |
— | Controlled Figma Open. |
defaultOpen |
boolean |
false |
Initial Open when uncontrolled. |
onOpenChange |
(open: boolean) => void |
— | Called when the toggle is pressed. |
children |
ReactNode |
— | Up to three AiInsights.Insight paragraphs, shown in ready. |
meta |
ReactNode |
— | An AiMetaLine. Shown in open ready and empty. |
feedback |
ReactNode |
— | An AiFeedback. Shown in open ready. |
disclaimer |
ReactNode |
Localized AI disclaimer | Text under the insights in open ready and loading. null hides it. |
onRetry |
(event: MouseEvent<HTMLButtonElement>) => void |
— | Shows Try again in error. |
emptySummary |
ReactNode |
Localized short empty text | Closed empty header text. |
emptyMessage |
ReactNode |
Localized empty text | Open empty body text. |
errorSummary |
ReactNode |
Localized short error text | Closed error header text and status announcement. |
errorMessage |
ReactNode |
Localized error text | Open error body text. |
icon |
ReactNode |
AiLabel.Mark |
Replaces the 24px mark. Keep Categorical/Teal/strong on a swapped icon. |
AiInsights forwards other native section props and its ref. AiInsights.Insight forwards
native p props and takes label?: ReactNode, rendered in Semibold Text/text-headline.
AiInsights.Value forwards native strong props and takes tone?: "neutral" | "success" | "destructive". neutral, the default, is Semibold Text/text-headline. success and
destructive keep the regular weight.
AiDriver
Section titled “AiDriver”Both AiExplanationPopover and AiDriverBreakdown take drivers: AiDriver[]. Give each driver a
unique id, and never invent a driver: use state="no-clear-cause" instead.
| Field | Type | Default | Description |
|---|---|---|---|
id |
string |
Required | Unique key. |
label |
string |
Required | Dimension and segment. Truncates to one line. |
share |
number |
Required | Exact share of the change, 0 to 100. The bar rounds to 5%. |
shareLabel |
string |
"{share}% of change" |
Visible share text. The default is localized. |
direction |
"up" | "down" | "flat" |
Required | Real direction of the driver’s change. |
change |
string |
Required | Preformatted change, such as "+41%". |
polarity |
"higher-is-better" | "lower-is-better" |
"higher-is-better" |
Use lower-is-better for cost metrics. |
changeLabel |
string |
Trend Indicator text | Accessible text for the change. |
AiExplanationPopover
Section titled “AiExplanationPopover”| Prop | Type | Default | Description |
|---|---|---|---|
title |
ReactNode |
Required | What changed and when. Names the dialog. |
children |
ReactNode |
— | The finding. Describes the dialog. Hidden while loading. |
state |
"ready" | "no-clear-cause" | "loading" |
"ready" |
Figma State. |
drivers |
AiDriver[] |
— | Likely drivers, shown in ready. |
open |
boolean |
— | Controlled open state. |
defaultOpen |
boolean |
false |
Initial open state when uncontrolled. |
onOpenChange |
(open, details) => void |
— | Base UI Popover open change. |
anchor |
RefObject<Element | null> | Element | null |
— | Places the popover beside this element and returns focus to it. |
trigger |
ReactElement |
— | Element rendered as the Popover trigger, such as a Button. |
meta |
ReactNode |
— | An AiMetaLine. |
onViewDetails |
(event: MouseEvent<HTMLButtonElement>) => void |
— | Shows View details. |
viewDetailsLabel |
string |
"View details" |
Action text. The default is localized. |
driversHeading |
ReactNode |
"Likely drivers" |
Drivers heading. The default is localized. |
noClearCauseMessage |
ReactNode |
Localized no-clear-cause text | Message in no-clear-cause. |
label |
string |
"AI explanation" |
AI Label text. The default is localized. |
about |
ReactNode |
— | Makes the AI Label a Rich Tooltip trigger with this description. |
side |
"top" | "bottom" | "left" | "right" |
"right" |
Preferred side. |
align |
"start" | "center" | "end" |
"center" |
Preferred alignment. |
sideOffset |
number |
8 |
Distance from the anchor in pixels. |
container |
Portal container | document.body |
Where the popup is portaled. |
className |
string |
— | Popup classes. |
AiExplanationPopover.Value is AiInlineInsight.Value: a Semibold number with tone.
AiDriverBreakdown
Section titled “AiDriverBreakdown”| Prop | Type | Default | Description |
|---|---|---|---|
title |
ReactNode |
Required | The question. Names the dialog. |
children |
ReactNode |
— | Summary with the exact change. Describes the dialog. |
state |
"ready" | "no-clear-cause" | "loading" |
"ready" |
Figma State. |
drivers |
AiDriver[] |
— | All drivers, each with a share bar, shown in ready. |
open |
boolean |
— | Controlled open state. |
defaultOpen |
boolean |
false |
Initial open state when uncontrolled. |
onOpenChange |
(open, details) => void |
— | Base UI Dialog open change. |
trigger |
ReactElement |
— | Element rendered as the Sheet trigger. |
finalFocus |
Base UI Dialog finalFocus |
The trigger | Where focus goes on close. |
meta |
ReactNode |
— | An AiMetaLine. |
feedback |
ReactNode |
— | An AiFeedback. |
driversHeading |
ReactNode |
"Top drivers" |
Drivers heading. The default is localized. |
noClearCauseMessage |
ReactNode |
Localized no-clear-cause text | Message in no-clear-cause. |
label |
string |
"AI explanation" |
AI Label text. The default is localized. |
about |
ReactNode |
— | Makes the AI Label a Rich Tooltip trigger with this description. |
className |
string |
— | Sheet panel classes. The default width is 448px. |
AiDriverBreakdown.Value is AiInlineInsight.Value.
AiRecommendationCard
Section titled “AiRecommendationCard”| Prop | Type | Default | Description |
|---|---|---|---|
title |
string |
Required | Verb-led action without “AI”. Names the card and the announcements. |
children |
ReactNode |
— | Reason. Start with “Because”. |
size |
"full" | "compact" |
"full" |
Figma Size. |
state |
"default" | "confirm" | "applied" | "dismissed" |
— | Controlled Figma State. |
defaultState |
Same as state |
"default" |
Initial state when uncontrolled. |
onStateChange |
(state) => void |
— | Called with the next state on each step. |
loading |
boolean |
false |
Shows the Loading skeleton. |
category |
ReactNode |
— | Category text. |
categoryIcon |
ReactNode |
— | 16px icon in Icon/icon-muted. |
impact |
{ direction, value, polarity?, unit?, label? } |
— | Est. impact as a Trend Indicator and unit. |
affected |
ReactNode |
— | What will change. |
confirmMessage |
ReactNode |
"Apply this recommendation?" |
Question in confirm. The default is localized. |
meta |
ReactNode |
— | An AiMetaLine, shown in full. |
onApply |
() => void |
— | Called on Confirm. |
onDismiss |
() => void |
— | Called on Dismiss. |
onUndo |
(undone: "applied" | "dismissed") => void |
— | Called on Undo. |
onReview |
(event: MouseEvent<HTMLButtonElement>) => void |
— | Shows Review in full. |
dismissible |
boolean |
true |
Shows Dismiss in full. |
label |
string |
"Suggested by AI" |
AI Label text. The default is localized. |
about |
ReactNode |
— | Makes the AI Label a Rich Tooltip trigger with this description. |
AiRecommendationCard forwards other native article props and its ref.