Skip to content

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.

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.

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.

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.

Oct 1–7 vs Sep 24–30Updated 2 hours ago
Filters changed since this was generated

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.

Was this helpful?

Selected: none

Place the insight next to the number it explains. A muted xs Tooltip Trigger renders the Figma “Why?” link.

Engagement rose +18.2% vs last week, mostly from one segment.

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.

Cost per click rose +12% vs last week (tinted, sm).

Cost per click rose +12% vs last week (tinted, md).

Cost per click rose +12% vs last week (plain, sm).

Cost per click rose +12% vs last week (plain, md).

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.

Loading AI insight
Loading AI insight

Not enough data for insights yet.

Not enough data for insights yet.

AiInlineInsight.Footer places a meta line and feedback on one wrapping row.

Sign-ups fell −6.4% vs last week, likely from a slower landing page on mobile.

Oct 1–7 vs Sep 24–30Updated 2 hours ago
Was this helpful?

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.

Daily sessions Daily sessions, Oct 1 to Oct 7. Select the Oct 5 marker for an explanation.
Daily sessions data
CategorySessions
Oct 16,100
Oct 25,900
Oct 36,400
Oct 47,000
Oct 59,800
Oct 67,100
Oct 76,800

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.

Performance insights

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.

Performance insights

Generating insights

Performance insights

AI-generated insights can be inaccurate. Use them as a reference, not as definitive guidance.

Generating insights

Performance insights

No significant changes this period

Performance insights

No significant changes this period. Insights appear here when your metrics move.

Oct 1–7 vs Sep 24–30Updated 2 hours ago

Performance insights

Couldn't generate insights

Couldn't generate insights

Performance insights

Couldn't generate insights. Check your connection and try again.

Couldn't generate insights

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.

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.

AudienceSuggested by AI

Focus on mobile audiences

Because mobile drove 58% of last week's engagement growth, while other devices stayed flat.

Est. impactUp +8–12%engagement per week

Affects 3 active campaigns

Based on Oct 1–7Updated 2 hours ago

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.

AudienceSuggested by AI

Focus on mobile audiences

Because mobile drove 58% of last week's engagement growth.

Est. impactUp +8–12%engagement per week

AudienceSuggested by AI

Focus on mobile audiences

Because mobile drove 58% of last week's engagement growth.

Est. impactUp +8–12%engagement per week

Apply to 3 active campaigns? You can undo this later.

AudienceSuggested by AI

Focus on mobile audiences

Because mobile drove 58% of last week's engagement growth.

Est. impactUp +8–12%engagement per week

Applied
AudienceSuggested by AI

Focus on mobile audiences

Dismissed
AudienceSuggested by AI
Loading recommendation
Suggested by AI

Focus on mobile audiences

Focus on mobile audiences

Apply to 3 campaigns?

Applied

Focus on mobile audiences

Focus on mobile audiences

Dismissed
Suggested by AIFocus on mobile audiencesLoading recommendation

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.

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.

Daily cost per result Daily cost per result, Oct 1 to Oct 7. Select the Oct 5 marker for an explanation.
Daily cost per result data
CategoryCost per result
Oct 1$410
Oct 2$395
Oct 3$430
Oct 4$445
Oct 5$610
Oct 6$452
Oct 7$438

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.

  • AiLabel is a button named by its text, including hidden text. Its description is 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.Mark and the AI Meta Line divider and history icon are hidden from assistive technology.
  • AiFeedback is a group labelled by its prompt. Each thumb is a toggle button named “Helpful” or “Not helpful” with aria-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.Loading is a status region with aria-busy="true" and screen-reader text. The skeleton pulse stops when the user prefers reduced motion.
  • AiInsights is a region named by its title. In ready, the toggle is a disclosure button with aria-expanded and aria-controls. Enter and Space toggle it. A polite status region announces “Generating insights” and the error summary when the state changes.
  • AiExplanationPopover is 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 the trigger, or to the anchor when 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.
  • AiDriverBreakdown is 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 the trigger. When the sheet opens from a control that is gone, such as View details, set finalFocus.
  • AiRecommendationCard is 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 status regions 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.
  • AiExpectedRange is decorative in the plot. Its text, such as “Expected range: 5,500 to 7,500”, is listed with the chart data.
  • AiChartMarker with onClick is a focusable button with aria-haspopup="dialog". Enter and Space activate it. Without onClick, it is an image named by label. Give each marker a text label, such as “Anomaly on Oct 5”.
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 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.
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.

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.
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".

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.

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.

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.
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.

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.

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.

  • Tooltip for RichTooltip and TooltipTrigger
  • Metrics for ChartBand, ChartMarker, and LineChartPlot
  • Skeleton for the Teal tone
  • Sheet and Popover for the AI Driver Breakdown and AI Explanation Popover containers
  • Metric Card for TrendIndicator
  • Colors for the Categorical Teal roles