# Nesra UI documentation # Nesra UI Accessible React components from Nesra AI. Components Compare the rendered variant, size, and state with Figma, then copy the matching public React API. Foundations Look up the semantic colors, typography, layout, and shape values behind the components. Accessibility Check the interaction contract and what an application must provide, such as labels and focus behavior. The component catalog includes implemented and upcoming pages. Upcoming pages have no supported import yet. See [Installation](/installation/) to set up the package and find its Markdown reference pages for AI agents. --- # Accessibility Understand the accessibility foundation and responsibilities of Nesra UI. Nesra UI’s [Button](/components/button/) uses [Base UI](https://base-ui.com/react/overview/accessibility) for button semantics and interaction. [Text](/components/text/) renders the HTML element selected through `as`. The application supplies meaningful content, labels, page structure, and end-to-end checks. ## Keyboard interaction Button can be reached with Tab and activated with Enter or Space. `disabled` and `loading` prevent activation. `loading` also sets `aria-busy`. Keep buttons for actions and native links for navigation, even when a Button uses the visual `link` variant. Test the entire task with a keyboard, including where focus moves after an action. For more complex widgets, follow the [WAI-ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/) rather than assuming every key works like a button. ## Focus Button shows a `focus-visible` state for keyboard focus. Preserve it when extending styles with `className`. In the application, check that focus is visible, follows the expected order, and lands somewhere useful after an action. For dialogs and other overlays, also check initial focus and focus restoration when they close. See [WCAG focus visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible) and [focus appearance](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance). ## Accessible names Prefer visible labels that describe the action. Button hides its decorative `startIcon`, `endIcon`, and loading icon from assistive technology. Icon-only buttons still need a name: ```tsx import { Button } from "@nesra/ui/button"; export function CloseButton() { return ( ); } ``` Keep `aria-label` on an icon-only Button while it is loading: the icon is replaced by a loader, and there is no visible text to name the control. See [WAI-ARIA naming guidance](https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/) for other naming methods. ## Content semantics Text’s `variant` controls appearance. Its `as` prop controls the HTML element. Choose heading levels from the page outline, regardless of their visual size. If text is truncated, make essential content available in full elsewhere. See [Text](/components/text/) for rendered roles and examples. ## Color and contrast Check text against its actual background, including when tokens are overridden or placed on a new surface. Also check the visible parts of controls and their focus indicators. Follow WCAG guidance for [text contrast](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html), [non-text contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast), and [use of color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color). A status needs a text or shape cue in addition to color. ## Testing Nesra UI tests Button activation, disabled and loading behavior, accessible names, and a representative automated accessibility scan. Those checks do not cover an application’s content, custom colors, or complete workflow. When using a component, verify its accessible name and state, complete the task with a keyboard, inspect focus and contrast in the browser, and test critical flows with assistive technology. See [W3C’s evaluation guide](https://www.w3.org/WAI/test-evaluate/) for methods and tools. --- # Changelog Track user-visible changes to Nesra UI. Changes to the package are tracked here. ## 0.8.0 * Added expanded child header rows and trailing disclosure controls to Table Tree for nested account tables. * Gave read-only inputs the light gray surface from the Figma design while preserving native focus and form behavior. * Kept Sheet backdrops and panels above page tabs and other locally stacked controls. ## 0.7.0 * Added controlled Pagination with optional page-size selection and bounded page navigation. * Added `Table.SortButton` for controlled column sorting and an opt-in directory density with content-driven header and row heights. ## 0.6.0 * Added a compact InputGroup button for trailing actions that inherits the group’s disabled state. * Added `Sidebar.AccountMenu.Item` with built-in action styling and optional icon and shortcut slots. * Allowed `Sidebar.MenuButton` and `Sidebar.MenuSubButton` directly inside their lists; Sidebar wraps simple navigation rows in list items. ## 0.5.0 * Changed Breadcrumb to a compound-only API; use `Breadcrumb.Root` and its parts instead of the callable root or standalone part exports. * Added compound InputOtp with paste, autofill, controlled values, and configurable alphanumeric codes. * Added a searchable single-value Combobox with custom options and form support. * Added StepperItem arrow separators and optional supporting text and subtitles. * Removed the vertical divider from indented Sidebar submenu items. ## 0.4.0 * Added a compound Sidebar AccountMenu with composable trigger, content, account choices, and application actions. ## 0.3.0 * Added searchable Multi Select with controlled and uncontrolled selection, form submission, option counts, bulk actions, and empty results. * Added a composable Date Picker calendar presentation with Nesra Select navigation and responsive presets. * Added responsive Filters layout and trigger parts for filter bars and advanced editors. * Added Timeline for chronological activity and audit entries. * Added a compound Sidebar with controlled state, cookie persistence, keyboard shortcuts, collapsed navigation, nested items, and a mobile drawer. * Added Empty State with configurable visuals, content, and actions. * Added breadcrumb, step indicator, progress bar, and stepper parts to Indicator. * Replaced the native Tabs mobile selector with Nesra Select and animated the desktop selection indicator. * Removed the Popover arrow and aligned its anchor and viewport spacing with Select. * Moved the default Toast viewport and stack to the top right. * Aligned the Select trigger chevron and selected-option check icon with semantic trigger colors. ## 0.2.0 * Added Avatar with image fallback, sizes, actions, and Avatar Group composition. * Added Badge label, indicator, status, course, XP, and level variants. * Added Card surfaces with neutral and gray background variants. * Added composable Dialog, Popover, and right-side Sheet overlays. * Added Select and Switch form controls. * Added Skeleton placeholders with semantic styling and reduced-motion support. * Added Toast notifications with a scoped manager, accessible viewport, status styling, actions, and dismissal controls. * Removed the browser’s default border from Button variants without an explicit border. ## 0.1.1 * Kept ref handling and form event types compatible with React 18 and React 19. ## 0.1.0 * Established the `@nesra/ui` package with Base UI, Tailwind CSS v4, semantic theme tokens, and the Button component. * Added root and granular Button exports. * Added Tailwind stylesheet entrypoints that leave Tailwind CSS and Preflight under application control. * Exposed the approved Figma primitive colors and Light Mode roles through namespaced CSS tokens and Tailwind utilities. * Applied semantic color roles to representative Button states. * Added Text with heading and body typography roles, explicit HTML semantics, and root and granular exports. * Added Figma-backed layout, radius, stroke, and shadow values for the supported light theme. * Aligned Button variants, sizes, icon placement, loading, focus, and disabled states with the approved design. * Added Input, Textarea, File Input, File Upload Card, Field, and InputGroup for text and file entry. * Added Checkbox, Radio Group, Tabs, Tooltip, Dropdown Menu, and inline Date Picker with their documented interaction and accessibility contracts. * Added the native Table family, reusable data cells, sticky columns, and expandable Table Tree rows. * Added Line, Area, Bar, Pie, and Bar + Line Combo charts with semantic colors and native data tables. * Exported named Dropdown Menu part prop types for consumer wrappers and fixed Button and Tabs refs under React 18. --- # Colors Nesra's Figma color roles, CSS tokens, and usage guidance. Nesra UI exposes the semantic color roles from Figma in **Light Mode** and **Dark Mode**. Light is the default. Add `dark` as a class, or `data-theme="dark"`, to `` or to any container to switch that subtree to Dark. Add `light`, or `data-theme="light"`, inside a Dark subtree to switch back. ```html … ``` The roles change value per mode, and their names stay the same. Components therefore need no `dark:` variants. Your app owns the theme switch and any saved preference. Nesra UI does not follow `prefers-color-scheme` on its own. ## Usage Use semantic roles rather than primitive colors in components. ```tsx

Account details

Your current profile information.

``` ## Naming CSS token names normalize Figma variables to kebab-case under `nesra`: | Exact Figma variable | CSS value token | | --- | --- | | `Colors/Semantic/gray/gray-50` | `--nesra-gray-50` | | `Text/text-staticWhite` | `--nesra-text-static-white` | | `Foundation/bg-overlay` | `--nesra-foundation-bg-overlay` | | `Categorical/Blue/subtle-hover` | `--nesra-categorical-blue-subtle-hover` | | `Icon/icon-brand-primary` | `--nesra-icon-brand-primary` | | `Text/text-body` | `--nesra-text-body` | When the leaf repeats its group, the group is dropped. For example, `Text/text-body` becomes `--nesra-text-body`. camelCase becomes kebab-case. Each token has a matching Tailwind binding, so `--nesra-text-body` is used as `text-nesra-text-body`. ## Choosing roles Version 1.0 removed the role names that Figma renamed or deleted on 29 October 2026. Their replacements are listed in [Upgrading to 1.0](/upgrading-to-1-0/). Pick the role by the surface the content sits on: * On `Foundation/bg-brand-primary` and the primary button, use `text-on-brand` and `icon-on-brand`. * On `Foundation/bg-inverse` (tooltips), use the `*-inverse` roles. * On fixed dark or photo surfaces, use `*-static-white`. On fixed light fills such as yellow, use `*-static-dark`. ## Primitive palette All 200 primitive values have `--nesra-*` CSS tokens and `--color-nesra-*` Tailwind bindings. Components use the semantic roles below. ### Colors/Semantic/neutral | Figma variable | Value | | --- | --- | | Colors/Semantic/neutral/neutral-50 | `#FAFAFA` | | Colors/Semantic/neutral/neutral-100 | `#F5F5F5` | | Colors/Semantic/neutral/neutral-200 | `#E5E5E5` | | Colors/Semantic/neutral/neutral-300 | `#D4D4D4` | | Colors/Semantic/neutral/neutral-400 | `#A3A3A3` | | Colors/Semantic/neutral/neutral-500 | `#737373` | | Colors/Semantic/neutral/neutral-600 | `#525252` | | Colors/Semantic/neutral/neutral-700 | `#404040` | | Colors/Semantic/neutral/neutral-800 | `#262626` | | Colors/Semantic/neutral/neutral-900 | `#171717` | | Colors/Semantic/neutral/neutral-950 | `#0A0A0A` | ### Colors | Figma variable | Value | | --- | --- | | Colors/white | `#FFFFFF` | | Colors/black | `#000000` | ### Colors/Semantic/gray | Figma variable | Value | | --- | --- | | Colors/Semantic/gray/gray-50 | `#F9FAFB` | | Colors/Semantic/gray/gray-100 | `#F3F4F6` | | Colors/Semantic/gray/gray-200 | `#E5E7EB` | | Colors/Semantic/gray/gray-300 | `#D1D5DB` | | Colors/Semantic/gray/gray-400 | `#9CA3AF` | | Colors/Semantic/gray/gray-500 | `#6B7280` | | Colors/Semantic/gray/gray-600 | `#4B5563` | | Colors/Semantic/gray/gray-700 | `#374151` | | Colors/Semantic/gray/gray-800 | `#1F2937` | | Colors/Semantic/gray/gray-900 | `#111827` | | Colors/Semantic/gray/gray-950 | `#030712` | ### Colors/Semantic/state | Figma variable | Value | | --- | --- | | Colors/Semantic/state/state-50 | `#F8FAFC` | | Colors/Semantic/state/state-100 | `#F1F5F9` | | Colors/Semantic/state/state-200 | `#E2E8F0` | | Colors/Semantic/state/state-300 | `#CBD5E1` | | Colors/Semantic/state/state-400 | `#94A3B8` | | Colors/Semantic/state/state-500 | `#64748B` | | Colors/Semantic/state/state-600 | `#475569` | | Colors/Semantic/state/state-700 | `#334155` | | Colors/Semantic/state/state-800 | `#1E293B` | | Colors/Semantic/state/state-900 | `#0F172A` | | Colors/Semantic/state/state-950 | `#020617` | ### Colors/Semantic/red | Figma variable | Value | | --- | --- | | Colors/Semantic/red/red-50 | `#FEF2F2` | | Colors/Semantic/red/red-100 | `#FEE2E2` | | Colors/Semantic/red/red-200 | `#FECACA` | | Colors/Semantic/red/red-300 | `#FCA5A5` | | Colors/Semantic/red/red-400 | `#F87171` | | Colors/Semantic/red/red-500 | `#EF4444` | | Colors/Semantic/red/red-600 | `#DC2626` | | Colors/Semantic/red/red-700 | `#B91C1C` | | Colors/Semantic/red/red-800 | `#991B1B` | | Colors/Semantic/red/red-900 | `#7F1D1D` | | Colors/Semantic/red/red-950 | `#450A0A` | ### Colors/Semantic/orange | Figma variable | Value | | --- | --- | | Colors/Semantic/orange/orange-50 | `#FFF7ED` | | Colors/Semantic/orange/orange-100 | `#FFEDD5` | | Colors/Semantic/orange/orange-200 | `#FED7AA` | | Colors/Semantic/orange/orange-300 | `#FDBA74` | | Colors/Semantic/orange/orange-400 | `#FB923C` | | Colors/Semantic/orange/orange-500 | `#F97316` | | Colors/Semantic/orange/orange-600 | `#EA580C` | | Colors/Semantic/orange/orange-700 | `#C2410C` | | Colors/Semantic/orange/orange-800 | `#9A3412` | | Colors/Semantic/orange/orange-900 | `#7C2D12` | | Colors/Semantic/orange/orange-950 | `#431407` | ### Colors/Semantic/green | Figma variable | Value | | --- | --- | | Colors/Semantic/green/green-50 | `#F0FDF4` | | Colors/Semantic/green/green-100 | `#DCFCE7` | | Colors/Semantic/green/green-200 | `#BBF7D0` | | Colors/Semantic/green/green-300 | `#86EFAC` | | Colors/Semantic/green/green-400 | `#4ADE80` | | Colors/Semantic/green/green-500 | `#22C55E` | | Colors/Semantic/green/green-600 | `#16A34A` | | Colors/Semantic/green/green-700 | `#15803D` | | Colors/Semantic/green/green-800 | `#166534` | | Colors/Semantic/green/green-900 | `#14532D` | | Colors/Semantic/green/green-950 | `#052E16` | ### Colors/Semantic/yellow | Figma variable | Value | | --- | --- | | Colors/Semantic/yellow/yellow-50 | `#FEFCE8` | | Colors/Semantic/yellow/yellow-100 | `#FEF9C3` | | Colors/Semantic/yellow/yellow-200 | `#FEF08A` | | Colors/Semantic/yellow/yellow-300 | `#FDE047` | | Colors/Semantic/yellow/yellow-400 | `#FACC15` | | Colors/Semantic/yellow/yellow-500 | `#EAB308` | | Colors/Semantic/yellow/yellow-600 | `#CA8A04` | | Colors/Semantic/yellow/yellow-700 | `#A16207` | | Colors/Semantic/yellow/yellow-800 | `#854D0E` | | Colors/Semantic/yellow/yellow-900 | `#713F12` | | Colors/Semantic/yellow/yellow-950 | `#422006` | ### Colors/Semantic/teal | Figma variable | Value | | --- | --- | | Colors/Semantic/teal/teal-50 | `#F0FDFA` | | Colors/Semantic/teal/teal-100 | `#CCFBF1` | | Colors/Semantic/teal/teal-200 | `#99F6E4` | | Colors/Semantic/teal/teal-300 | `#5EEAD4` | | Colors/Semantic/teal/teal-400 | `#2DD4BF` | | Colors/Semantic/teal/teal-500 | `#14B8A6` | | Colors/Semantic/teal/teal-600 | `#0D9488` | | Colors/Semantic/teal/teal-700 | `#0F766E` | | Colors/Semantic/teal/teal-800 | `#115E59` | | Colors/Semantic/teal/teal-900 | `#134E4A` | | Colors/Semantic/teal/teal-950 | `#042F2E` | ### Colors/Semantic/cyan | Figma variable | Value | | --- | --- | | Colors/Semantic/cyan/cyan-50 | `#ECFEFF` | | Colors/Semantic/cyan/cyan-100 | `#CFFAFE` | | Colors/Semantic/cyan/cyan-200 | `#A5F3FC` | | Colors/Semantic/cyan/cyan-300 | `#67E8F9` | | Colors/Semantic/cyan/cyan-400 | `#22D3EE` | | Colors/Semantic/cyan/cyan-500 | `#06B6D4` | | Colors/Semantic/cyan/cyan-600 | `#0891B2` | | Colors/Semantic/cyan/cyan-700 | `#0E7490` | | Colors/Semantic/cyan/cyan-800 | `#155E75` | | Colors/Semantic/cyan/cyan-900 | `#164E63` | | Colors/Semantic/cyan/cyan-950 | `#083344` | ### Colors/Semantic/sky | Figma variable | Value | | --- | --- | | Colors/Semantic/sky/sky-50 | `#F0F9FF` | | Colors/Semantic/sky/sky-100 | `#E0F2FE` | | Colors/Semantic/sky/sky-200 | `#BAE6FD` | | Colors/Semantic/sky/sky-300 | `#7DD3FC` | | Colors/Semantic/sky/sky-400 | `#38BDF8` | | Colors/Semantic/sky/sky-500 | `#0EA5E9` | | Colors/Semantic/sky/sky-600 | `#0284C7` | | Colors/Semantic/sky/sky-700 | `#0369A1` | | Colors/Semantic/sky/sky-800 | `#075985` | | Colors/Semantic/sky/sky-900 | `#0C4A6E` | | Colors/Semantic/sky/sky-950 | `#082F49` | ### Colors/Semantic/indigo | Figma variable | Value | | --- | --- | | Colors/Semantic/indigo/indigo-50 | `#EEF2FF` | | Colors/Semantic/indigo/indigo-100 | `#E0E7FF` | | Colors/Semantic/indigo/indigo-200 | `#C7D2FE` | | Colors/Semantic/indigo/indigo-300 | `#A5B4FC` | | Colors/Semantic/indigo/indigo-400 | `#818CF8` | | Colors/Semantic/indigo/indigo-500 | `#6366F1` | | Colors/Semantic/indigo/indigo-600 | `#4F46E5` | | Colors/Semantic/indigo/indigo-700 | `#4338CA` | | Colors/Semantic/indigo/indigo-800 | `#3730A3` | | Colors/Semantic/indigo/indigo-900 | `#312E81` | | Colors/Semantic/indigo/indigo-950 | `#1E1B4B` | ### Colors/Semantic/violet | Figma variable | Value | | --- | --- | | Colors/Semantic/violet/violet-50 | `#F5F3FF` | | Colors/Semantic/violet/violet-100 | `#EDE9FE` | | Colors/Semantic/violet/violet-200 | `#DDD6FE` | | Colors/Semantic/violet/violet-300 | `#C4B5FD` | | Colors/Semantic/violet/violet-400 | `#A78BFA` | | Colors/Semantic/violet/violet-500 | `#8B5CF6` | | Colors/Semantic/violet/violet-600 | `#7C3AED` | | Colors/Semantic/violet/violet-700 | `#6D28D9` | | Colors/Semantic/violet/violet-800 | `#5B21B6` | | Colors/Semantic/violet/violet-900 | `#4C1D95` | | Colors/Semantic/violet/violet-950 | `#2E1065` | ### Colors/Semantic/purple | Figma variable | Value | | --- | --- | | Colors/Semantic/purple/purple-50 | `#FAF5FF` | | Colors/Semantic/purple/purple-100 | `#F3E8FF` | | Colors/Semantic/purple/purple-200 | `#E9D5FF` | | Colors/Semantic/purple/purple-300 | `#D8B4FE` | | Colors/Semantic/purple/purple-400 | `#C084FC` | | Colors/Semantic/purple/purple-500 | `#A855F7` | | Colors/Semantic/purple/purple-600 | `#9333EA` | | Colors/Semantic/purple/purple-700 | `#7E22CE` | | Colors/Semantic/purple/purple-800 | `#6B21A8` | | Colors/Semantic/purple/purple-900 | `#581C87` | | Colors/Semantic/purple/purple-950 | `#3B0764` | ### Colors/Semantic/pink | Figma variable | Value | | --- | --- | | Colors/Semantic/pink/pink-50 | `#FDF2F8` | | Colors/Semantic/pink/pink-100 | `#FCE7F3` | | Colors/Semantic/pink/pink-200 | `#FBCFE8` | | Colors/Semantic/pink/pink-300 | `#F9A8D4` | | Colors/Semantic/pink/pink-400 | `#F472B6` | | Colors/Semantic/pink/pink-500 | `#EC4899` | | Colors/Semantic/pink/pink-600 | `#DB2777` | | Colors/Semantic/pink/pink-700 | `#BE185D` | | Colors/Semantic/pink/pink-800 | `#9D174D` | | Colors/Semantic/pink/pink-900 | `#831843` | | Colors/Semantic/pink/pink-950 | `#500724` | ### Colors/Semantic/rose | Figma variable | Value | | --- | --- | | Colors/Semantic/rose/rose-50 | `#FFF1F2` | | Colors/Semantic/rose/rose-100 | `#FFE4E6` | | Colors/Semantic/rose/rose-200 | `#FECDD3` | | Colors/Semantic/rose/rose-300 | `#FDA4AF` | | Colors/Semantic/rose/rose-400 | `#FB7185` | | Colors/Semantic/rose/rose-500 | `#F43F5E` | | Colors/Semantic/rose/rose-600 | `#E11D48` | | Colors/Semantic/rose/rose-700 | `#BE123C` | | Colors/Semantic/rose/rose-800 | `#9F1239` | | Colors/Semantic/rose/rose-900 | `#881337` | | Colors/Semantic/rose/rose-950 | `#4C0519` | ### Colors/Semantic/lime | Figma variable | Value | | --- | --- | | Colors/Semantic/lime/lime-50 | `#F7FEE7` | | Colors/Semantic/lime/lime-100 | `#ECFCCB` | | Colors/Semantic/lime/lime-200 | `#D9F99D` | | Colors/Semantic/lime/lime-300 | `#BEF264` | | Colors/Semantic/lime/lime-400 | `#A3E635` | | Colors/Semantic/lime/lime-500 | `#84CC16` | | Colors/Semantic/lime/lime-600 | `#65A30D` | | Colors/Semantic/lime/lime-700 | `#4D7C0F` | | Colors/Semantic/lime/lime-800 | `#3F6212` | | Colors/Semantic/lime/lime-900 | `#365314` | | Colors/Semantic/lime/lime-950 | `#1A2E05` | ### Colors/Semantic/blue | Figma variable | Value | | --- | --- | | Colors/Semantic/blue/blue-50 | `#EFF6FF` | | Colors/Semantic/blue/blue-100 | `#DBEAFE` | | Colors/Semantic/blue/blue-200 | `#BFDBFE` | | Colors/Semantic/blue/blue-300 | `#93C5FD` | | Colors/Semantic/blue/blue-400 | `#60A5FA` | | Colors/Semantic/blue/blue-500 | `#3B82F6` | | Colors/Semantic/blue/blue-600 | `#2563EB` | | Colors/Semantic/blue/blue-700 | `#1D4ED8` | | Colors/Semantic/blue/blue-800 | `#1E40AF` | | Colors/Semantic/blue/blue-900 | `#1E3A8A` | | Colors/Semantic/blue/blue-950 | `#172554` | ### Colors/Brand/primary | Figma variable | Value | | --- | --- | | Colors/Brand/primary/primary-50 | `#F9FAFB` | | Colors/Brand/primary/primary-100 | `#F3F4F6` | | Colors/Brand/primary/primary-200 | `#E5E7EB` | | Colors/Brand/primary/primary-300 | `#D1D5DB` | | Colors/Brand/primary/primary-400 | `#9CA3AF` | | Colors/Brand/primary/primary-500 | `#6B7280` | | Colors/Brand/primary/primary-600 | `#4B5563` | | Colors/Brand/primary/primary-700 | `#374151` | | Colors/Brand/primary/primary-800 | `#1F2937` | | Colors/Brand/primary/primary-900 | `#111827` | | Colors/Brand/primary/primary-950 | `#030712` | ## Semantic token reference All 162 roles use their Light and Dark values from `packages/ui/src/styles.css`. The docs build checks that they match. ### Foundation | Figma variable | CSS token | Value | | --- | --- | --- | | Foundation/bg-neutral | `--nesra-foundation-bg-neutral` | `Light#FFFFFFDark#030712` | | Foundation/bg-gray | `--nesra-foundation-bg-gray` | `Light#F9FAFBDark#1F2937` | | Foundation/bg-brand-primary | `--nesra-foundation-bg-brand-primary` | `Light#030712Dark#F9FAFB` | | Foundation/bg-brand-primary-50 | `--nesra-foundation-bg-brand-primary-50` | `Light#F3F4F6Dark#374151` | | Foundation/bg-disabled | `--nesra-foundation-bg-disabled` | `Light#F3F4F6Dark#1F2937` | | Foundation/bg-overlay | `--nesra-foundation-bg-overlay` | `Light#0A0A0ADark#0A0A0A` | | Foundation/bg-brand-solid | `--nesra-foundation-bg-brand-solid` | `Light#4B5563Dark#9CA3AF` | | Foundation/bg-success-solid | `--nesra-foundation-bg-success-solid` | `Light#15803DDark#15803D` | | Foundation/bg-inverse | `--nesra-foundation-bg-inverse` | `Light#030712Dark#F9FAFB` | | Foundation/bg-info-solid | `--nesra-foundation-bg-info-solid` | `Light#2563EBDark#2563EB` | ### Surface | Figma variable | CSS token | Value | | --- | --- | --- | | Surface/card-bg-neutral | `--nesra-surface-card-bg-neutral` | `Light#FFFFFFDark#111827` | | Surface/card-bg-gray | `--nesra-surface-card-bg-gray` | `Light#F9FAFBDark#1F2937` | | Surface/card-bg-brand-primary-50 | `--nesra-surface-card-bg-brand-primary-50` | `Light#F9FAFBDark#1F2937` | | Surface/popover-bg-neutral | `--nesra-surface-popover-bg-neutral` | `Light#FFFFFFDark#111827` | ### Action | Figma variable | CSS token | Value | | --- | --- | --- | | Action/primary-default | `--nesra-action-primary-default` | `Light#030712Dark#F9FAFB` | | Action/primary-hover | `--nesra-action-primary-hover` | `Light#374151Dark#E5E7EB` | | Action/primary-disabled | `--nesra-action-primary-disabled` | `Light#E5E7EBDark#1F2937` | | Action/secondary-default | `--nesra-action-secondary-default` | `Light#FFFFFFDark#111827` | | Action/secondary-hover | `--nesra-action-secondary-hover` | `Light#F9FAFBDark#1F2937` | | Action/tertiary-default | `--nesra-action-tertiary-default` | `Light#FFFFFF00Dark#FFFFFF00` | | Action/tertiary-hover | `--nesra-action-tertiary-hover` | `Light#F9FAFBDark#1F2937` | | Action/destructive-default | `--nesra-action-destructive-default` | `Light#DC2626Dark#DC2626` | | Action/destructive-hover | `--nesra-action-destructive-hover` | `Light#B91C1CDark#B91C1C` | ### Text | Figma variable | CSS token | Value | | --- | --- | --- | | Text/text-headline | `--nesra-text-headline` | `Light#111827Dark#FFFFFF` | | Text/text-body | `--nesra-text-body` | `Light#111827Dark#FFFFFF` | | Text/text-secondary | `--nesra-text-secondary` | `Light#374151Dark#D1D5DB` | | Text/text-tertiary | `--nesra-text-tertiary` | `Light#4B5563Dark#9CA3AF` | | Text/text-support | `--nesra-text-support` | `Light#6B7280Dark#9CA3AF` | | Text/text-disabled | `--nesra-text-disabled` | `Light#9CA3AFDark#6B7280` | | Text/text-staticWhite | `--nesra-text-static-white` | `Light#FFFFFFDark#FFFFFF` | | Text/text-brand-primary | `--nesra-text-brand-primary` | `Light#6B7280Dark#9CA3AF` | | Text/text-link | `--nesra-text-link` | `Light#2563EBDark#60A5FA` | | Text/text-destructive | `--nesra-text-destructive` | `Light#DC2626Dark#F87171` | | Text/text-success | `--nesra-text-success` | `Light#15803DDark#22C55E` | | Text/text-on-brand | `--nesra-text-on-brand` | `Light#FFFFFFDark#030712` | | Text/text-inverse | `--nesra-text-inverse` | `Light#FFFFFFDark#030712` | | Text/text-staticDark | `--nesra-text-static-dark` | `Light#030712Dark#030712` | ### Icon | Figma variable | CSS token | Value | | --- | --- | --- | | Icon/icon-neutral | `--nesra-icon-neutral` | `Light#111827Dark#FFFFFF` | | Icon/icon-muted | `--nesra-icon-muted` | `Light#6B7280Dark#9CA3AF` | | Icon/icon-disabled | `--nesra-icon-disabled` | `Light#9CA3AFDark#6B7280` | | Icon/icon-destructive | `--nesra-icon-destructive` | `Light#EF4444Dark#EF4444` | | Icon/icon-warning | `--nesra-icon-warning` | `Light#A16207Dark#EAB308` | | Icon/icon-success | `--nesra-icon-success` | `Light#16A34ADark#22C55E` | | Icon/icon-info | `--nesra-icon-info` | `Light#3B82F6Dark#3B82F6` | | Icon/icon-brand-primary | `--nesra-icon-brand-primary` | `Light#6B7280Dark#9CA3AF` | | Icon/icon-staticWhite | `--nesra-icon-static-white` | `Light#FFFFFFDark#FFFFFF` | | Icon/icon-on-brand | `--nesra-icon-on-brand` | `Light#FFFFFFDark#030712` | | Icon/icon-inverse | `--nesra-icon-inverse` | `Light#FFFFFFDark#030712` | | Icon/icon-staticDark | `--nesra-icon-static-dark` | `Light#030712Dark#030712` | ### Stroke | Figma variable | CSS token | Value | | --- | --- | --- | | Stroke/stroke-border-strong | `--nesra-stroke-border-strong` | `Light#D1D5DBDark#374151` | | Stroke/stroke-border | `--nesra-stroke-border` | `Light#E5E7EBDark#374151` | | Stroke/stroke-divider | `--nesra-stroke-divider` | `Light#F3F4F6Dark#1F2937` | | Stroke/stroke-brand-primary | `--nesra-stroke-brand-primary` | `Light#6B7280Dark#9CA3AF` | | Stroke/stroke-destructive | `--nesra-stroke-destructive` | `Light#EF4444Dark#EF4444` | | Stroke/stroke-warning | `--nesra-stroke-warning` | `Light#A16207Dark#EAB308` | | Stroke/stroke-success | `--nesra-stroke-success` | `Light#16A34ADark#22C55E` | | Stroke/stroke-link | `--nesra-stroke-link` | `Light#3B82F6Dark#3B82F6` | | Stroke/stroke-inverse | `--nesra-stroke-inverse` | `Light#1F2937Dark#E5E7EB` | ### Shadow | Figma variable | CSS token | Value | | --- | --- | --- | | Shadow/shadow-xs | `--nesra-shadow-xs` | `Light#0000000DDark#0000001A` | | Shadow/shadow-xl-01 | `--nesra-shadow-xl-01` | `Light#00000014Dark#00000028` | | Shadow/shadow-xl-02 | `--nesra-shadow-xl-02` | `Light#00000008Dark#00000010` | | Shadow/shadow-xl-03 | `--nesra-shadow-xl-03` | `Light#0000000ADark#00000014` | | Shadow/shadow-lg-01 | `--nesra-shadow-lg-01` | `Light#00000014Dark#00000028` | | Shadow/shadow-lg-02 | `--nesra-shadow-lg-02` | `Light#00000008Dark#00000010` | | Shadow/shadow-lg-03 | `--nesra-shadow-lg-03` | `Light#0000000ADark#00000014` | | Shadow/shadow-skeuomorphic-inner | `--nesra-shadow-skeuomorphic-inner` | `Light#0000000DDark#0000001A` | | Shadow/shadow-skeuomorphic-inner-border | `--nesra-shadow-skeuomorphic-inner-border` | `Light#0000002EDark#0000005C` | | Shadow/shadow-02 | `--nesra-shadow-02` | `Light#00000005Dark#0000000A` | | Shadow/shadow-06 | `--nesra-shadow-06` | `Light#0000000FDark#0000001F` | | Shadow/shadow-10 | `--nesra-shadow-10` | `Light#0000001ADark#00000033` | | Shadow/shadow-15 | `--nesra-shadow-15` | `Light#00000026Dark#0000004D` | ### Effects | Figma variable | CSS token | Value | | --- | --- | --- | | Effects/focus-ring | `--nesra-effects-focus-ring` | `Light#4B5563Dark#9CA3AF` | | Effects/focus-ring-destructive | `--nesra-effects-focus-ring-destructive` | `Light#DC262633Dark#F8717133` | ### Alpha | Figma variable | CSS token | Value | | --- | --- | --- | | Alpha/alpha-white-10 | `--nesra-alpha-white-10` | `Light#FFFFFF1ADark#FFFFFF1A` | | Alpha/alpha-black-50 | `--nesra-alpha-black-50` | `Light#00000080Dark#00000080` | | Alpha/alpha-transparent | `--nesra-alpha-transparent` | `Light#FFFFFF00Dark#FFFFFF00` | ### Component | Figma variable | CSS token | Value | | --- | --- | --- | | Component/Avatar/background-1 | `--nesra-component-avatar-background-1` | `Light#E9DCBBDark#E9DCBB` | | Component/Avatar/background-2 | `--nesra-component-avatar-background-2` | `Light#C7D1B0Dark#C7D1B0` | | Component/Avatar/background-3 | `--nesra-component-avatar-background-3` | `Light#CED1E5Dark#CED1E5` | | Component/Avatar/background-4 | `--nesra-component-avatar-background-4` | `Light#DDD0BEDark#DDD0BE` | | Component/Avatar/background-5 | `--nesra-component-avatar-background-5` | `Light#DFC2C0Dark#DFC2C0` | ### Categorical | Figma variable | CSS token | Value | | --- | --- | --- | | Categorical/Neutral/subtle | `--nesra-categorical-neutral-subtle` | `Light#FAFAFADark#0A0A0A` | | Categorical/Neutral/border | `--nesra-categorical-neutral-border` | `Light#E5E5E5Dark#262626` | | Categorical/Neutral/base | `--nesra-categorical-neutral-base` | `Light#737373Dark#737373` | | Categorical/Neutral/foreground | `--nesra-categorical-neutral-foreground` | `Light#404040Dark#D4D4D4` | | Categorical/Neutral/strong | `--nesra-categorical-neutral-strong` | `Light#525252Dark#A3A3A3` | | Categorical/Violet/subtle | `--nesra-categorical-violet-subtle` | `Light#F5F3FFDark#2E1065` | | Categorical/Violet/border | `--nesra-categorical-violet-border` | `Light#DDD6FEDark#5B21B6` | | Categorical/Violet/base | `--nesra-categorical-violet-base` | `Light#8B5CF6Dark#8B5CF6` | | Categorical/Violet/foreground | `--nesra-categorical-violet-foreground` | `Light#6D28D9Dark#C4B5FD` | | Categorical/Violet/strong | `--nesra-categorical-violet-strong` | `Light#7C3AEDDark#A78BFA` | | Categorical/Pink/base | `--nesra-categorical-pink-base` | `Light#EC4899Dark#EC4899` | | Categorical/Teal/base | `--nesra-categorical-teal-base` | `Light#14B8A6Dark#14B8A6` | | Categorical/Blue/base | `--nesra-categorical-blue-base` | `Light#3B82F6Dark#3B82F6` | | Categorical/Indigo/base | `--nesra-categorical-indigo-base` | `Light#6366F1Dark#6366F1` | | Categorical/Purple/base | `--nesra-categorical-purple-base` | `Light#A855F7Dark#A855F7` | | Categorical/Orange/base | `--nesra-categorical-orange-base` | `Light#F97316Dark#F97316` | | Categorical/Yellow/base | `--nesra-categorical-yellow-base` | `Light#EAB308Dark#EAB308` | | Categorical/Pink/subtle | `--nesra-categorical-pink-subtle` | `Light#FDF2F8Dark#500724` | | Categorical/Pink/border | `--nesra-categorical-pink-border` | `Light#FBCFE8Dark#9D174D` | | Categorical/Pink/foreground | `--nesra-categorical-pink-foreground` | `Light#BE185DDark#F9A8D4` | | Categorical/Pink/strong | `--nesra-categorical-pink-strong` | `Light#DB2777Dark#F472B6` | | Categorical/Teal/subtle | `--nesra-categorical-teal-subtle` | `Light#F0FDFADark#042F2E` | | Categorical/Teal/border | `--nesra-categorical-teal-border` | `Light#99F6E4Dark#115E59` | | Categorical/Teal/foreground | `--nesra-categorical-teal-foreground` | `Light#0F766EDark#5EEAD4` | | Categorical/Teal/strong | `--nesra-categorical-teal-strong` | `Light#0D9488Dark#2DD4BF` | | Categorical/Blue/subtle | `--nesra-categorical-blue-subtle` | `Light#EFF6FFDark#172554` | | Categorical/Blue/border | `--nesra-categorical-blue-border` | `Light#BFDBFEDark#1E40AF` | | Categorical/Blue/foreground | `--nesra-categorical-blue-foreground` | `Light#1D4ED8Dark#93C5FD` | | Categorical/Blue/strong | `--nesra-categorical-blue-strong` | `Light#2563EBDark#60A5FA` | | Categorical/Indigo/subtle | `--nesra-categorical-indigo-subtle` | `Light#EEF2FFDark#1E1B4B` | | Categorical/Indigo/border | `--nesra-categorical-indigo-border` | `Light#C7D2FEDark#3730A3` | | Categorical/Indigo/foreground | `--nesra-categorical-indigo-foreground` | `Light#4338CADark#A5B4FC` | | Categorical/Indigo/strong | `--nesra-categorical-indigo-strong` | `Light#4F46E5Dark#818CF8` | | Categorical/Purple/subtle | `--nesra-categorical-purple-subtle` | `Light#FAF5FFDark#3B0764` | | Categorical/Purple/border | `--nesra-categorical-purple-border` | `Light#E9D5FFDark#6B21A8` | | Categorical/Purple/foreground | `--nesra-categorical-purple-foreground` | `Light#7E22CEDark#D8B4FE` | | Categorical/Purple/strong | `--nesra-categorical-purple-strong` | `Light#9333EADark#C084FC` | | Categorical/Orange/subtle | `--nesra-categorical-orange-subtle` | `Light#FFF7EDDark#431407` | | Categorical/Orange/border | `--nesra-categorical-orange-border` | `Light#FED7AADark#9A3412` | | Categorical/Orange/foreground | `--nesra-categorical-orange-foreground` | `Light#C2410CDark#FDBA74` | | Categorical/Orange/strong | `--nesra-categorical-orange-strong` | `Light#EA580CDark#FB923C` | | Categorical/Yellow/subtle | `--nesra-categorical-yellow-subtle` | `Light#FEFCE8Dark#422006` | | Categorical/Yellow/border | `--nesra-categorical-yellow-border` | `Light#FEF08ADark#854D0E` | | Categorical/Yellow/foreground | `--nesra-categorical-yellow-foreground` | `Light#A16207Dark#FDE047` | | Categorical/Yellow/strong | `--nesra-categorical-yellow-strong` | `Light#CA8A04Dark#FACC15` | | Categorical/Neutral/subtle-hover | `--nesra-categorical-neutral-subtle-hover` | `Light#F5F5F5Dark#171717` | | Categorical/Violet/subtle-hover | `--nesra-categorical-violet-subtle-hover` | `Light#EDE9FEDark#4C1D95` | | Categorical/Pink/subtle-hover | `--nesra-categorical-pink-subtle-hover` | `Light#FCE7F3Dark#831843` | | Categorical/Teal/subtle-hover | `--nesra-categorical-teal-subtle-hover` | `Light#CCFBF1Dark#134E4A` | | Categorical/Blue/subtle-hover | `--nesra-categorical-blue-subtle-hover` | `Light#DBEAFEDark#1E3A8A` | | Categorical/Indigo/subtle-hover | `--nesra-categorical-indigo-subtle-hover` | `Light#E0E7FFDark#312E81` | | Categorical/Purple/subtle-hover | `--nesra-categorical-purple-subtle-hover` | `Light#F3E8FFDark#581C87` | | Categorical/Orange/subtle-hover | `--nesra-categorical-orange-subtle-hover` | `Light#FFEDD5Dark#7C2D12` | | Categorical/Yellow/subtle-hover | `--nesra-categorical-yellow-subtle-hover` | `Light#FEF9C3Dark#713F12` | | Categorical/Green/subtle | `--nesra-categorical-green-subtle` | `Light#F0FDF4Dark#052E16` | | Categorical/Green/border | `--nesra-categorical-green-border` | `Light#BBF7D0Dark#166534` | | Categorical/Green/base | `--nesra-categorical-green-base` | `Light#22C55EDark#22C55E` | | Categorical/Green/foreground | `--nesra-categorical-green-foreground` | `Light#15803DDark#86EFAC` | | Categorical/Green/strong | `--nesra-categorical-green-strong` | `Light#16A34ADark#4ADE80` | | Categorical/Green/subtle-hover | `--nesra-categorical-green-subtle-hover` | `Light#DCFCE7Dark#14532D` | | Categorical/Red/subtle | `--nesra-categorical-red-subtle` | `Light#FEF2F2Dark#450A0A` | | Categorical/Red/border | `--nesra-categorical-red-border` | `Light#FECACADark#991B1B` | | Categorical/Red/base | `--nesra-categorical-red-base` | `Light#EF4444Dark#EF4444` | | Categorical/Red/foreground | `--nesra-categorical-red-foreground` | `Light#B91C1CDark#FCA5A5` | | Categorical/Red/strong | `--nesra-categorical-red-strong` | `Light#DC2626Dark#F87171` | | Categorical/Red/subtle-hover | `--nesra-categorical-red-subtle-hover` | `Light#FEE2E2Dark#7F1D1D` | ### Chart | Figma variable | CSS token | Value | | --- | --- | --- | | Chart/mono-1 | `--nesra-chart-mono-1` | `Light#F3F4F6Dark#111827` | | Chart/mono-2 | `--nesra-chart-mono-2` | `Light#E5E7EBDark#1F2937` | | Chart/mono-3 | `--nesra-chart-mono-3` | `Light#D1D5DBDark#374151` | | Chart/mono-4 | `--nesra-chart-mono-4` | `Light#9CA3AFDark#4B5563` | | Chart/mono-5 | `--nesra-chart-mono-5` | `Light#6B7280Dark#6B7280` | | Chart/mono-6 | `--nesra-chart-mono-6` | `Light#4B5563Dark#9CA3AF` | | Chart/mono-7 | `--nesra-chart-mono-7` | `Light#374151Dark#D1D5DB` | | Chart/mono-8 | `--nesra-chart-mono-8` | `Light#1F2937Dark#E5E7EB` | | Chart/mono-9 | `--nesra-chart-mono-9` | `Light#111827Dark#F3F4F6` | | Chart/blue-1 | `--nesra-chart-blue-1` | `Light#DBEAFEDark#172554` | | Chart/blue-2 | `--nesra-chart-blue-2` | `Light#93C5FDDark#1E40AF` | | Chart/blue-3 | `--nesra-chart-blue-3` | `Light#3B82F6Dark#2563EB` | | Chart/blue-4 | `--nesra-chart-blue-4` | `Light#2563EBDark#3B82F6` | | Chart/blue-5 | `--nesra-chart-blue-5` | `Light#1E40AFDark#93C5FD` | | Chart/blue-6 | `--nesra-chart-blue-6` | `Light#172554Dark#DBEAFE` | --- # AI Insight AI Label, AI Meta Line, AI Feedback, AI Inline Insight, AI Expected Range, AI Chart Marker, AI Insights, AI Explanation Popover, AI Recommendation Card, and AI Driver Breakdown from the Figma AI insight page. 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](/components/skeleton/). ## Usage ```tsx import { AiInlineInsight, AiLabel } from "@nesra/ui/ai"; export function EngagementInsight() { return ( Engagement rose +18.2% vs last week. ); } ``` Every export on this page is also exported from `@nesra/ui`. ## Composition ```text 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 ### 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. ```tsx 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 (
Summarized with AI
); } ``` ### 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. ```tsx import { AiMetaLine } from "@nesra/ui/ai"; export function AiMetaLineExample() { return (
Oct 1–7 vs Sep 24–30 Updated 2 hours ago console.log("Regenerate the insight")}> Filters changed since this was generated
); } ``` ### 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`. ```tsx import { useState } from "react"; import { AiFeedback, type AiFeedbackValue } from "@nesra/ui/ai"; export function AiFeedbackExample() { const [value, setValue] = useState(null); return (
{ setValue(next); // Send `next` with the insight ID to your feedback endpoint here. }} value={value} />

Selected: {value ?? "none"}

); } ``` ### AI Inline Insight Place the insight next to the number it explains. A muted `xs` [Tooltip Trigger](/components/tooltip/) renders the Figma “Why?” link. ```tsx import { AiInlineInsight, AiLabel } from "@nesra/ui/ai"; import { TooltipTrigger } from "@nesra/ui/tooltip"; export function AiInlineInsightExample() { return (
Engagement rose +18.2% vs last week, mostly from one segment. Why?
); } ``` ### 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. ```tsx 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 (
{(["tinted", "plain"] as const).map((variant) => (["sm", "md"] as const).map((size) => ( Cost per click rose{" "} +12% vs last week ({variant}, {size}). )), )}
); } ``` ### 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`. ```tsx 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 (
); } ``` ### Meta line and feedback `AiInlineInsight.Footer` places a meta line and feedback on one wrapping row. ```tsx import { AiFeedback, AiInlineInsight, AiLabel, AiMetaLine } from "@nesra/ui/ai"; export function AiInlineInsightFooterExample() { return (
Sign-ups fell −6.4% vs last week, likely from a slower landing page on mobile. Oct 1–7 vs Sep 24–30 Updated 2 hours ago console.log("Feedback", value)} />
); } ``` ### 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. ```tsx 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(null); const [open, setOpen] = useState(false); return (
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." > setOpen(true)} ref={marker} value={9800} /> { marker.current?.focus(); return false; }} side="right" > Unusual spike on Oct 5 9,800 sessions, above the expected range of 5,500 to 7,500.
); } ``` ### 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`. ```tsx import { AiFeedback, AiInsights, AiMetaLine } from "@nesra/ui/ai"; export function AiInsightsExample() { return ( } meta={ Oct 1–7 vs Sep 24–30 Updated 2 hours ago } title="Performance insights" > Engagement rose +24.5% compared with the previous period, driven by a +18.2%{" "} increase in new visitors. Keep investing in the channels behind this growth. Cost per result increased +12.4%{" "} versus the previous period. Review underperforming segments to bring it back down. ); } ``` ### 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. ```tsx import { AiInsights, AiMetaLine } from "@nesra/ui/ai"; const meta = ( Oct 1–7 vs Sep 24–30 Updated 2 hours ago ); export function AiInsightsStatesExample() { return (
{}} state="error" title="Performance insights" /> {}} state="error" title="Performance insights" />
); } ``` ### 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. ```tsx 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 = ( Oct 1–7 vs Sep 24–30 Updated 2 hours ago ); export function AiExplanationPopoverExample() { return (
{(["ready", "no-clear-cause", "loading"] as const).map((state) => ( {}} side="bottom" state={state} title="Unusual spike on Oct 5" trigger={} > +32% above the expected range for this day of the week. ))}
); } ``` ### 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`. ```tsx 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("default"); return (
} confirmMessage="Apply to 3 active campaigns? You can undo this later." impact={{ direction: "up", value: "+8–12%", unit: "engagement per week" }} meta={ Based on Oct 1–7 Updated 2 hours ago } 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 58%{" "} of last week's engagement growth, while other devices stayed flat.
); } ``` ### 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](/components/badge/). ```tsx import { AiRecommendationCard } from "@nesra/ui/ai"; import { Users } from "lucide-react"; const states = ["default", "confirm", "applied", "dismissed"] as const; export function AiRecommendationCardStatesExample() { return (
{states.map((state) => ( } 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. ))} } loading title="Focus on mobile audiences" />
{states.map((state) => ( ))}
); } ``` ### AI Driver Breakdown The full driver list in a right-side [Sheet](/components/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. ```tsx 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 (
{(["ready", "no-clear-cause", "loading"] as const).map((state) => ( } key={state} meta={ Oct 1–7 vs Sep 24–30 Updated 2 hours ago } state={state} title="Why did engagement rise?" trigger={} > Engagement rose +18.2%{" "} vs last week. Five segments explain the change. ))}
); } ``` ### 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. ```tsx 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 = ( Oct 1–7 vs Sep 24–30 Updated 2 hours ago ); export function AiExplanationFlowExample() { const marker = useRef(null); const [popoverOpen, setPopoverOpen] = useState(false); const [breakdownOpen, setBreakdownOpen] = useState(false); return (
`$${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." > setPopoverOpen(true)} ref={marker} value={610} /> { setPopoverOpen(false); setBreakdownOpen(true); }} open={popoverOpen} title="Unusual spike on Oct 5" > +32% above the expected range for this day of the week. } 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{" "} +32% above the expected range. Five segments explain the change.
); } ``` ## 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 * `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”. ## API reference ### 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 `AiMetaLine` forwards native `div` props. `AiMetaLine.Item` forwards native `span` props. | `AiMetaLine.Stale` prop | Type | Default | Description | | --- | --- | --- | --- | | `children` | `ReactNode` | — | Stale message. | | `onRefresh` | `(event: MouseEvent) => void` | — | Shows the Refresh icon button and handles its press. | | `refreshLabel` | `string` | `"Refresh insight"` | Refresh button name. The default is localized. | ### 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 | 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 | 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 | 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 | 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) => 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 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 | 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` | — | 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) => 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 | 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 | 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) => 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. ## Related * [Tooltip](/components/tooltip/) for `RichTooltip` and `TooltipTrigger` * [Metrics](/components/metrics/) for `ChartBand`, `ChartMarker`, and `LineChartPlot` * [Skeleton](/components/skeleton/) for the Teal tone * [Sheet](/components/sheet/) and [Popover](/components/popover/) for the AI Driver Breakdown and AI Explanation Popover containers * [Metric Card](/components/metric-card/) for `TrendIndicator` * [Colors](/colors/) for the Categorical Teal roles --- # Avatar A named person image with fallback, optional action, and group composition. Avatar renders the Figma single-person image, initials, or icon anatomy. `Avatar.Group` renders the 32px overlapping group shown in Figma with data supplied by the consuming application. ## Usage ```tsx import { Avatar } from "@nesra/ui/avatar"; export function TeamMember() { return ; } ``` `Avatar` is also exported from `@nesra/ui`. ```tsx import { Avatar } from "@nesra/ui/avatar"; export function AvatarBasicExample() { return ; } ``` ## Composition Nest visible members inside `Avatar.Group`. Each member remains an independently named `Avatar`. ```tsx import { Avatar } from "@nesra/ui/avatar"; export function ProjectMembers() { return ( ); } ``` ## Examples ### Image `src` shows a circular photo. The photo is decorative; `name` labels the avatar. The image below is a Figma example asset. Replace its URL with an image URL from your application. ```tsx import { Avatar } from "@nesra/ui/avatar"; export function AvatarImageExample() { return ; } ``` ### Initials and icon fallbacks When `src` is absent or fails to load, `initials` appear. Omit `initials` for the person icon. ```tsx import { Avatar } from "@nesra/ui/avatar"; export function AvatarFallbacksExample() { return (
); } ``` ### Sizes `sm`, `md`, and `lg` have diameters of 24, 32, and 40px. The default is `sm`. ```tsx import { Avatar } from "@nesra/ui/avatar"; export function AvatarSizesExample() { return (
); } ``` ### Action `onAction` makes the entire avatar a button with a circle-plus badge. `actionLabel` names the button. This example reports clicks; the application owns the actual edit behavior. ```tsx import { Avatar } from "@nesra/ui/avatar"; import { useState } from "react"; export function AvatarActionsExample() { const [requests, setRequests] = useState(0); return (
setRequests((count) => count + 1)} size="lg" src="/avatar/portrait.png" /> Edit requests: {requests}
); } ``` ### Disabled `disabled` mutes an image, initials, or icon. It also prevents an `onAction` button from activating. ```tsx import { Avatar } from "@nesra/ui/avatar"; export function AvatarDisabledExample() { return (
{}} size="md" />
); } ``` ### Group of members `Avatar.Group` overlaps its children. Give each Avatar a name and `size="md"` to match Figma’s 32px group. These photos are Figma example assets; replace their URLs and names with application data. ```tsx import { Avatar } from "@nesra/ui/avatar"; export function AvatarGroupBasicExample() { return ( ); } ``` ### One to five members The Figma group shows one to five visible people. The application chooses which members to render. ```tsx import { Avatar } from "@nesra/ui/avatar"; const members = [ { name: "Member one", src: "/avatar/member-1.png", className: "bg-nesra-component-avatar-background-1", }, { name: "Member two", src: "/avatar/member-2.png", className: "bg-nesra-component-avatar-background-2", }, { name: "Member three", src: "/avatar/member-3.png", className: "bg-nesra-component-avatar-background-3", }, { name: "Member four", src: "/avatar/member-4.png", className: "bg-nesra-component-avatar-background-4", }, { name: "Member five", src: "/avatar/member-5.png", className: "bg-nesra-component-avatar-background-5", }, ]; export function AvatarGroupCountsExample() { return (
{members.map((member, index) => (
{index + 1} {members.slice(0, index + 1).map((visible) => ( ))}
))}
); } ``` ### Overflow count `overflowCount` is the number of additional members beyond the rendered children. The initials avatar in this example is a visible member, while `+5` represents five more members. ```tsx import { Avatar } from "@nesra/ui/avatar"; export function AvatarGroupExample() { return ( ); } ``` ### Add action `onAdd` displays a separate dashed add button. `addLabel` names it. This example reports requests; the application owns any member creation or picker. ```tsx import { Avatar } from "@nesra/ui/avatar"; import { useState } from "react"; export function AvatarGroupAddExample() { const [requests, setRequests] = useState(0); return (
setRequests((count) => count + 1)} > Add requests: {requests}
); } ``` ## Light and Dark Avatar follows the page theme. Dark applies when an ancestor has the `dark` class or `data-theme="dark"`. * Initials and the person icon use `Text/text-brand-primary` and `Icon/icon-brand-primary` on `Surface/card-bg-brand-primary-50`, with a `Stroke/stroke-divider` border. The overflow count uses the same roles. * Disabled avatars use `Surface/card-bg-gray` with `Text/text-disabled` and `Icon/icon-disabled`. * The action badge is a `Foundation/bg-neutral` circle with `Box Shadow/shadow-sm`, so it matches the page in both modes. Its plus icon uses `Icon/icon-brand-primary`, or `Icon/icon-disabled` when disabled. * The group add button uses `Surface/popover-bg-neutral`, a dashed `Stroke/stroke-border`, and an `Icon/icon-muted` plus. * Keyboard focus shows `Box Shadow/Focus ring offset` on an avatar action and `Box Shadow/Focus ring` on the add button. * Photos are not recolored. The `bg-nesra-component-avatar-background-*` backdrops in the group examples keep the same color in both modes. ## Accessibility * `name` labels a static avatar. Its photo has an empty `alt` to avoid repeating the name. * With `onAction`, the avatar is a native button named by `actionLabel`; the visual avatar and badge are decorative to assistive technology. Provide a label that describes the action. * `Avatar.Group` requires `label` for the group and `addLabel` when `onAdd` is present. Each child Avatar retains its own name. The add control is a native button. * Keep member names and `overflowCount` accurate as application data changes. ## API reference ### Avatar | Prop | Type | Default | Description | | --- | --- | --- | --- | | `name` | `string` | required | Accessible name for a static avatar. | | `src` | `string` | — | Image URL. Failed images show the fallback. | | `initials` | `string` | — | Fallback text; otherwise a person icon appears. | | `size` | `"sm" \| "md" \| "lg"` | `"sm"` | Diameter of 24, 32, or 40px. | | `disabled` | `boolean` | `false` | Muted appearance; also disables the action. | | `onAction` | button click handler | — | Makes the whole avatar a button. | | `actionLabel` | `string` | — | Required accessible name when `onAction` is used. | | `className` | `string` | — | Adds or overrides classes. | Other Base UI Avatar Root span props are forwarded. A ref points to that span. ### Avatar.Group | Prop | Type | Default | Description | | --- | --- | --- | --- | | `label` | `string` | required | Accessible name for the group. | | `children` | `ReactNode` | required | Visible Avatar members. | | `overflowCount` | `number` | `0` | Count of additional members beyond the children. | | `onAdd` | button click handler | — | Shows the add button. | | `addLabel` | `string` | — | Required accessible name when `onAdd` is used. | | `className` | `string` | — | Adds or overrides classes. | The group uses the `AvatarGroupProps` type. Other native div props are forwarded. A ref points to the group div. Colors use the Light and Dark [semantic color roles](/colors/). --- # Badge One Badge API for labels, indicators, status, course, XP, and level treatments. `Badge` is the single display component for the Figma Badge and Badge & Chip/Tag designs. `variant` selects the visual anatomy. The consumer supplies visible text and any course logo. ## Usage ```tsx import { Badge } from "@nesra/ui/badge"; export function Status() { return ( Terverifikasi ); } ``` `Badge` is also exported from `@nesra/ui`. ## Examples ### Label colors and appearances The Figma `Soft` and `Fill` label treatments map to `appearance="soft"` and `appearance="fill"`. Figma colors map to lowercase `color` values. Figma `Purple` is bound to the Categorical Violet roles. ```tsx import { Badge } from "@nesra/ui/badge"; export function BadgeVariantsExample() { return (
{(["brand", "info", "success", "warning", "error", "neutral", "purple"] as const).map( (color) => (
{color} {color}
), )}
); } ``` ### Label sizes and icons `sm` targets 20px height and 12px text. `md` targets 24px height and 14px text. `startIcon` and `endIcon` render decorative content. ```tsx import { Badge } from "@nesra/ui/badge"; import { Circle } from "lucide-react"; export function BadgeSizesExample() { return (
Small Medium }> With icon
); } ``` ### With icons `startIcon` and `endIcon` are decorative. Keep the visible label meaningful without them. ```tsx import { Badge } from "@nesra/ui/badge"; import { ArrowUpRight, CheckCircle2, CircleAlert } from "lucide-react"; export function BadgeIconsExample() { return (
}> Verified }> Attention }> Details } endIcon={} > Complete
); } ``` ### Removable `onRemove` adds a remove button after a label badge. With `onRemove`, `endIcon` becomes the button’s icon, and the default icon is `X`. The page removes the badge from its own state in the handler. ```tsx import { Badge } from "@nesra/ui/badge"; import { Button } from "@nesra/ui/button"; import { Trash2 } from "lucide-react"; import { useState } from "react"; const initialDates = ["03 Oct 2026", "10 Oct 2026", "17 Oct 2026"]; export function BadgeRemovableExample() { const [dates, setDates] = useState(initialDates); if (dates.length === 0) { return ( ); } return (
    {dates.map((date) => (
  • } onRemove={() => setDates((current) => current.filter((item) => item !== date))} > {date}
  • ))}
); } ``` ### In a sentence Badges can sit beside ordinary text without changing the text’s semantics. ```tsx import { Badge } from "@nesra/ui/badge"; export function BadgeInlineExample() { return (

Course catalog{" "} New

Payment{" "} Terverifikasi

); } ``` ### Linked badge Wrap a Badge in a native anchor for navigation. The anchor owns the destination and keyboard focus. ```tsx import { Badge } from "@nesra/ui/badge"; export function BadgeLinkedExample() { return ( View changelog ); } ``` ### Indicator The Figma Mini Badge is `variant="indicator"`. It has `dot` and `check` treatments with 8, 12, 16, and 20px diameters. ```tsx import { Badge } from "@nesra/ui/badge"; export function BadgeIndicatorsExample() { return (
); } ``` ### Status `status` selects the pending, verified, or canceled palette and icon. `appearance` selects filled or outlined treatment. The text is supplied through `children`. ```tsx import { Badge } from "@nesra/ui/badge"; const statuses = [ { status: "pending", label: "Menunggu Pembayaran" }, { status: "verified", label: "Terverifikasi" }, { status: "canceled", label: "Dibatalkan" }, ] as const; export function BadgeStatusExample() { return (
{statuses.map(({ status, label }) => (
{label} {label}
))}
); } ``` ### Course categories `course` uses three sizes. Pass the course logo through `startIcon`; the preview uses a generic spreadsheet icon. ```tsx import { Badge } from "@nesra/ui/badge"; import { FileSpreadsheet } from "lucide-react"; export function BadgeCourseExample() { return (
} variant="course"> Microsoft Excel } variant="course"> Microsoft Excel } variant="course"> Microsoft Excel
} variant="course"> Google Sheets } variant="course"> Google Sheets } variant="course"> Google Sheets
); } ``` ### XP states `xpState` changes the visual state. `active` shares the default blue treatment; the supplied text distinguishes the claim prompt. A claimed badge shows a check. An actual claim action needs a separate control. ```tsx import { Badge } from "@nesra/ui/badge"; export function BadgeXpExample() { return (
50XP Klaim 50XP 50XP
50XP Klaim 50XP 50XP
); } ``` ### Levels `level` changes the highlighted bars. `sm` and `md` change padding around the same 12px text. ```tsx import { Badge } from "@nesra/ui/badge"; export function BadgeLevelExample() { return (
Mudah Sedang Sulit
Mudah Sedang Sulit
); } ``` ## Light and Dark Badge follows the page theme. Dark applies when an ancestor has the `dark` class or `data-theme="dark"`. | Badge | Fill | Text | | --- | --- | --- | | Brand soft | `Foundation/bg-brand-primary-50` | `Text/text-body` | | Brand fill | `Foundation/bg-brand-primary` | `Text/text-on-brand` | | Info soft | `Categorical/Blue/subtle` | `Text/text-link`, icons `Icon/icon-info` | | Info fill, XP, Verified | `Foundation/bg-info-solid` | `Text/text-staticWhite` | | Success soft | `Categorical/Green/subtle` | `Categorical/Green/foreground` | | Success fill | `Foundation/bg-success-solid` | `Text/text-staticWhite` | | Warning soft | `Categorical/Yellow/subtle` | `Categorical/Yellow/foreground`, icons `Icon/icon-warning` | | Warning fill, Pending | `Categorical/Yellow/base` | `Text/text-staticDark` | | Error soft | `Categorical/Red/subtle` | `Categorical/Red/foreground`, icons `Icon/icon-destructive` | | Error fill | `Action/destructive-default` | `Text/text-staticWhite` | | Neutral soft | `Foundation/bg-gray` | `Text/text-body` | | Neutral fill | `Categorical/Neutral/base` | `Text/text-staticWhite` | | Purple soft | `Categorical/Violet/subtle` | `Text/text-body`, icons `Icon/icon-neutral` | | Purple fill | `Categorical/Violet/base` | `Text/text-staticDark`, icons `Icon/icon-staticDark` | | Canceled status | `Foundation/bg-disabled` | `Text/text-tertiary`, icon `Icon/icon-muted` | | Claimed XP | `Surface/card-bg-gray` | `Text/text-support` | The soft fills and the Brand fill change between modes. The solid Info, Success, Warning, Error, Neutral, and Purple fills keep the same color in both modes, so their static text colors stay readable. The indicator is `Foundation/bg-success-solid` with a `Foundation/bg-neutral` border and check, so it stays separated from the page in both modes. The remove button shows `Box Shadow/Focus ring` on soft badges and `Box Shadow/Focus ring offset` on fill badges, where a plain ring would blend into the fill. ## Accessibility `Badge` renders a native span. The span itself never acts as a button. With `onRemove`, a label badge contains one native `; } ``` `Button` is also exported from `@nesra/ui`. For navigation that should look like a button, style a native anchor with the exported `buttonVariants` helper. This preserves link semantics and browser link behavior: ```tsx import { buttonVariants } from "@nesra/ui/button"; export function ReportsLink() { return ( View reports ); } ``` ## Examples ### Variants ```tsx import { Button } from "@nesra/ui/button"; export function ButtonVariantsExample() { return ( <> ); } ``` ### Sizes `sm`, `md`, and `lg` are 32, 40, and 44px tall. `icon-*` sizes are square. Default: `md`. ```tsx import { Button } from "@nesra/ui/button"; export function ButtonSizesExample() { return ( <> ); } ``` ### Icons `startIcon` and `endIcon` are decorative. Icon-only buttons need an accessible name. ```tsx import { Button } from "@nesra/ui/button"; import { ArrowRight, CircleCheck } from "lucide-react"; export function ButtonIconsExample() { return ( <> ); } ``` ### Loading and disabled `loading` sets `aria-busy` and prevents activation. It hides the child of an icon-only button, so keep its `aria-label`. ```tsx import { Button } from "@nesra/ui/button"; export function ButtonStatesExample() { return ( <> ); } ``` ## Light and Dark Button follows the page theme. Dark applies when an ancestor has the `dark` class or `data-theme="dark"`. No prop is needed. * **Primary** uses `Action/primary-default` with `Text/text-on-brand` and `Icon/icon-on-brand`. It is near-black with white content in Light and near-white with near-black content in Dark. * **Destructive** keeps `Text/text-staticWhite` on `Action/destructive-default` in both modes, because the red fill does not change. * **Outline**, **Ghost**, and **Link** use `Text/text-body` or `Text/text-link` on mode-aware surfaces. Ghost has a transparent fill (`Action/tertiary-default`). Link hovers and focuses with `Categorical/Blue/subtle`, and its icons use `Icon/icon-info`. * **Disabled** buttons use `Text/text-disabled` and `Icon/icon-disabled`. Primary, Outline, and Destructive sit on `Action/primary-disabled`; Ghost and Link have no fill. * **Loading** Outline, Ghost, and Link buttons use `Text/text-support`. Primary and Destructive keep their default fill and content colors. * **Focus** uses `Box Shadow/Focus ring offset` (`shadow-nesra-focus-ring-offset`) in every variant: a 2px `Foundation/bg-neutral` gap, then a 2px `Effects/focus-ring` ring. ## Accessibility * Use an anchor for navigation. The `link` variant changes appearance, not button semantics. * Use `type="button"` for an in-page action inside a form and `type="submit"` when the button submits that form. `Button` defaults to `type="button"`. * Keep the keyboard focus state visible when extending styles. ## API reference | Prop | Type | Default | Description | | --- | --- | --- | --- | | `variant` | `"primary" \| "outline" \| "ghost" \| "destructive" \| "link"` | `"primary"` | Visual style. | | `size` | `"sm" \| "md" \| "lg" \| "icon-sm" \| "icon-md" \| "icon-lg"` | `"md"` | Height and padding. Icon sizes are square. | | `children` | `ReactNode` | — | Label or icon-only content. | | `startIcon` | `ReactNode` | — | Decorative icon before the label. | | `endIcon` | `ReactNode` | — | Decorative icon after the label. | | `loading` | `boolean` | `false` | Shows a loader, sets `aria-busy`, and prevents activation. | | `disabled` | `boolean` | `false` | Prevents interaction. | | `className` | `string` | — | Adds or overrides classes. | | `type` | `"button" \| "submit" \| "reset"` | `"button"` | Native button behavior in forms. | Other Base UI Button props and native button attributes, such as `onClick` and `aria-label`, are forwarded. A ref points to the button element. `buttonVariants` accepts the same `variant` and `size` values and returns a class string for styling another element. It does not add button behavior. The Button’s visual values come from the [semantic color roles](/colors/) and [shape and elevation tokens](/shape-and-elevation/). --- # Calendar Date Icon A 56px tile that shows a month abbreviation over a day number. `CalendarDateIcon` renders the Figma `.Calendar date icon` from the Calendar page: a 64px wide tile, at least 56px tall, with the month on a gray band above the day number. The [Calendar](/components/calendar/) header renders this component for today. ## Usage ```tsx import { CalendarDateIcon } from "@nesra/ui/calendar-date-icon"; export function NextEvent() { return ; } ``` `CalendarDateIcon` and `CalendarDateIconProps` are also exported from `@nesra/ui`. ## Examples ### Beside an event ```tsx import { CalendarDateIcon } from "@nesra/ui/calendar-date-icon"; export function CalendarDateIconBasicExample() { return (
Quarterly review 10:00 – 11:30 · Room 4
); } ``` ### Locale `locale` formats the month abbreviation and the accessible date with `Intl.DateTimeFormat`. The month is shown in uppercase, as in Figma. ```tsx import { CalendarDateIcon } from "@nesra/ui/calendar-date-icon"; export function CalendarDateIconLocaleExample() { return (
); } ``` ## Figma mapping | Part | Figma value | CSS | | --- | --- | --- | | Tile | 64px wide, min height `unit-27` (56px), `radius-sm`, 1px border | `w-nesra-spacing-7xl min-h-nesra-unit-27 rounded-nesra-sm border-nesra-stroke-border` | | Tile | `Surface/popover-bg-neutral` | `bg-nesra-surface-popover-bg-neutral` | | Month | `Foundation/bg-gray`, padding 4 / 8 / 2 / 8, `Body/XSmall/Semibold` | `bg-nesra-foundation-bg-gray type-nesra-body-xsmall-semibold text-nesra-text-support` | | Day | `Body/Large/Bold`, `Text/text-brand-primary` | `type-nesra-body-large-bold text-nesra-text-brand-primary` | All roles have Light and Dark values. The tile was checked in both modes. The Figma Calendar page also has a **Calendar Icon** set (`Name=Calendar`, `Clock`, `Bell`, `Copy`, `Trash`, `Edit`). Those are 16px `Icon/icon-muted` glyphs, not a package export. Use the Lucide `Calendar`, `Clock`, `BellRing`, `Copy`, `Trash2`, and `Pencil` icons with `text-nesra-icon-muted`. ## Accessibility * The tile is a `