Dashboard Components#

@sero-ai/ui ships a set of shared dashboard components for building compact dashboard widgets and data-dense plugin views. They give widgets one visual foundation — consistent spacing, typography, semantic status colours and overflow behaviour — without every plugin re-declaring layout and colours.

Import everything from the package root:

import { WidgetContent, Stack, Metric, Status, ItemList } from '@sero-ai/ui';

The root is for primitives, dashboard components, hooks and theme utilities. Import AI elements from their stable subpaths so plugins only load the editor and rendering dependencies they use:

import { Message } from '@sero-ai/ui/ai-elements/message';

Federated plugins that use AI elements should also import their Tailwind source entry after the base plugin stylesheet. The same rule applies to model-selection and context-editor components:

@import "@sero-ai/ui/styles/plugin.css";
@import "@sero-ai/ui/styles/ai-elements.css";
@import "@sero-ai/ui/styles/model-selection.css";
@import "@sero-ai/ui/styles/context-editor.css";

Only import the specialized stylesheets for component families the plugin uses.

Detailed props are canonical in the exported TypeScript types. The machine-readable catalogue (the data behind the tables below) ships as plain JSON at a stable subpath — read it directly:

Worked, glass-styled example widgets ship on their own subpath — import them to preview, or copy one as a starting point:

import { StarterExample, SchedulerExample } from '@sero-ai/ui/reference';

kind: primitive = existing @sero-ai/ui primitive recommended for widgets; composite = a dashboard component. All are stable unless noted.

Layout#

Typography#

Data display#

Runtime states & feedback#

Actions#

Boundary: shared vs plugin-local#

Shared dashboard components are presentation only — they hold no plugin state, actions or domain types. Keep domain-specific components and types in the plugin. Add a component to @sero-ai/ui only when the pattern is reused across more than one widget or plugin.

Sizes and overflow#

Widgets stay legible at their declared minimum and default sizes using CSS and container queries. Provide compact defaults; let the plugin choose which data to show at each size. Use Stack's scroll and the list components' overflowCount for "+N more" rather than hand-rolling overflow.

Loading, empty and error#

Wire runtime states through DataBoundary, with a skeleton pattern for loading, EmptyState for empty, and Alert for error. The boundary selects presentation; the plugin owns fetching and retry.

Glass styling#

The dashboard is a frosted glass board. WidgetContent applies the glass token scope automatically, so these components render as translucent surfaces — raised cards, flat rows — that read as part of the tile. You write nothing extra; there are no glass classes to add and no backdrop-filter to set (the host tile provides the single blur).

For a full plugin view that should stay solid rather than glass, opt out with <WidgetContent glass={false}>. Form controls and portalled menus stay solid inside glass regardless, so inputs and dropdowns remain readable.

Styling setup#

An external plugin's ui/styles.css must import the shared stylesheet and scan its own files:

@import "@sero-ai/ui/styles/plugin.css";
@source "./**/*.{ts,tsx}";

plugin.css already scans the dashboard components, so their utility classes are emitted for you. Import ../styles.css from every directly-exposed Module Federation entry.

Contributing a reusable component#

When a pattern proves useful in more than one widget or plugin, add it under packages/ui/src/components/dashboard/, build it from existing primitives and design tokens, export it from the package root, add a catalog.ts entry, and keep this page and the sero-dashboard-ui skill catalogue in step.