# Tessli library item — Dashboard overview Opens on the one question the dashboard exists to answer, gives the answer in a sentence, backs it with two or three compared metrics and a trend, and lists what needs attention. Kind: page Category: dashboards Status: community (not yet reviewed by a maintainer) Tessli page: /library/dashboard-overview Preview: /preview/dashboard-overview ## Install ```sh npx shadcn@latest add online-scope-lab/tessli/dashboard-overview ``` ## Use when - People open the dashboard with one recurring question, such as whether work is on time, money is on budget or a service is healthy. - The figures have a meaningful baseline (last period, a target) and there are specific items someone can act on. ## Avoid when - People come to explore many unrelated metrics; give them a report builder or a data table with filters instead. - The data is real-time operations monitoring where seconds matter; use a status board with alerts. - There is no baseline or target to compare against yet; show the raw list until there is one. ## Rules - H-01 — Give each section, card or dialog at most one primary-styled action. (/rules/H-01) - W-01 — Write headings that make the product's point, not labels like "Features" or "FAQ". (/rules/W-01) - W-03 — Show no ratings, counts, logos, quotes or metrics you can't source. (/rules/W-03) - W-04 — Lead answers, errors and notices with the answer or consequence, then the detail. (/rules/W-04) - T-03 — Set prices, counts and numeric columns in tabular figures. (/rules/T-03) - C-02 — Pair every colour-coded meaning (error, selected, status) with text or shape. (/rules/C-02) - ST-01 — Design empty, loading and error states for every region that loads or lists data. (/rules/ST-01) - R-01 — On phones, restack content by priority and adapt components; don't shrink the desktop. (/rules/R-01) ## Common AI default A "Dashboard" heading over four identical KPI cards (total users, revenue, sessions, conversion) each with a big number and a green or red "+12.5%" badge with an arrow, a large area chart with a gradient fill and no stated baseline, a "Recent activity" feed, and no loading, empty or error state. ## Why this is better - The heading is the question people open the page to answer, and the first sentence answers it, so most visits end after one line. - Three metrics instead of four interchangeable cards, each with its baseline and target written out ("Up 8 points from 74% last week", "Target 80% or more"), so a change can be judged without guessing what it is compared with. - Changes are written in words that say which way is better ("0.5 days faster"), not a coloured percentage with an arrow, so meaning survives greyscale and screen readers. - The trend is a table with a bar in each row and the value written beside it, so the chart is its own text alternative and needs no chart library. - A short list of the items that need action, longest wait first, with one primary action that clears it, turns the answer into something to do. - Loading keeps metric labels and row positions in place; empty and error each say why and offer one way forward. ## Common failures when adapting it - Adding a fourth and fifth metric until the answer is buried in a KPI grid again. - Showing a change without its baseline ("+8") or colouring it green when lower would be better. - Writing a heading like "Overview" that answers nothing, or an answer sentence that no longer matches the figures. - Turning the attention list into an activity feed of everything that happened. - Shipping the demo figures, or a target nobody agreed, as if they were real. ## States - default - loading - empty - error ## Responsive behaviour - Desktop: The question, answer and period run across the top at reading width; the metrics form one bordered strip of aligned columns; below, the attention list takes the wider column beside the trend chart. - Mobile: One column in priority order (question and answer first), then metrics stacked with dividers, the attention list with full-width 44px rows and a full-width action, then the trend as compact horizontal bars that fit 320px. ## Accessibility - The question is the page heading (h1 by default, h2 under a page title); every region is a section labelled by its own heading. - Metrics are a description list; changes and targets are text, never colour or an arrow alone. - The chart is a table with row headers for each period and the value as text; bars, the dashed target line and its legend swatch are hidden from assistive technology, and the target is stated in text. - Loading is announced through a status region and marked aria-busy; empty and error messages appear in a polite live region, and the error names its cause in text as well as colour. - Each item that needs attention is one link at least 44px tall with a visible focus ring. ## Notes Most dashboards answer a question nobody asked: four totals, a chart and a feed. People open a dashboard because they want to know one thing, such as whether reviews are happening on time. This item makes that question the heading and puts the answer in the first sentence. Every metric carries its comparison in words, with the baseline and the target, so readers can tell whether a change is good without decoding colours. The trend is a plain table with a bar in each row: it reads as a chart, works at 320px and is already its own text alternative. The attention list turns the answer into work, with one primary action. When you adapt it, keep it to two or three metrics, write the answer from the real figures, and replace every demo number before shipping. Design the loading, empty and error states with the real copy; they are part of the item, not extras. ## Credits - Contributors: none credited yet - Provenance: original - Licence: MIT ## Source `web/registry/items/dashboard-overview/dashboard-overview.tsx` ```tsx import * as React from "react"; import { cn } from "@/registry/shadcn/lib/utils"; export type DashboardStatus = "ready" | "loading" | "empty" | "error"; export type DashboardMetric = { id: string; /** What is measured, in plain words: "Reviewed within 2 days". */ label: string; /** The current value, formatted: "82%", "14 notes", "1.4 days". */ value: React.ReactNode; /** * The change against a named baseline, in words that say which way is * better: "Up 8 points from 74% last week", "0.5 days faster than last * week". Never a bare "+8%" in green. */ comparison?: React.ReactNode; /** A target, definition or caveat: "Target: 80% or more". */ context?: React.ReactNode; }; export type AttentionItem = { id: string; /** The thing that needs attention, named as people know it. */ title: React.ReactNode; /** Where to deal with it. Each row is one link. */ href: string; /** Where it lives and who it belongs to: "Field research · Priya N." */ detail?: React.ReactNode; /** A short status written as text, e.g. "Unassigned". */ flag?: string; /** How long, how much or how late, formatted: "9 days". */ measure: React.ReactNode; }; export type DashboardAttention = { /** Says what the list holds: "Waiting more than a week". */ title: React.ReactNode; description?: React.ReactNode; /** Longest-waiting or highest-impact first. Show five at most. */ items: AttentionItem[]; /** Read before each row's measure by screen readers, e.g. "Waiting". */ measureLabel?: string; /** Shown when items is empty: say that nothing needs attention, and why. */ emptyText?: React.ReactNode; /** The one action that clears the list. The page's only primary button. */ action?: React.ReactNode; /** The full list, when there are more items than shown. */ moreLink?: { label: string; href: string }; }; export type TrendPoint = { /** The period: "14 Sep", "This week". */ label: string; value: number; /** The value as written in text; defaults to value + unit. */ display?: string; /** Marks the period the metrics describe. Shown in bold text, not colour. */ current?: boolean; }; export type DashboardTrend = { /** Make the point: "Above target for three weeks running". */ title: React.ReactNode; /** One sentence that states what the chart shows, for everyone. */ description?: React.ReactNode; /** Column heading for the periods. */ periodHeading?: string; /** Column heading for the values: "Reviewed within 2 days". */ valueHeading: string; /** Oldest first. Eight to twelve periods read well. */ points: TrendPoint[]; /** The value at the full bar width. Defaults to 100. */ max?: number; unit?: string; /** Drawn as a dashed line and named in text below the chart. */ target?: { value: number; label: React.ReactNode }; }; export type DashboardMessage = { /** Shown before the title for errors, in text: "Couldn’t load figures". */ label?: string; title: React.ReactNode; /** Empty: why and what next. Error: what failed and what is still safe. */ description?: React.ReactNode; /** One primary action, at most one secondary. */ actions?: React.ReactNode; }; export type DashboardOverviewProps = Omit< React.ComponentProps<"div">, "title" > & { /** Product or area, shown small above the question. */ context?: React.ReactNode; /** The one question this dashboard answers. Rendered as the page heading. */ question: React.ReactNode; /** The answer in one or two sentences, answer first. */ answer?: React.ReactNode; /** The period, the comparison baseline and when the data was updated. */ period?: React.ReactNode; status?: DashboardStatus; /** Two or three metrics. Labels stay visible while values load. */ metrics: DashboardMetric[]; attention: DashboardAttention; trend: DashboardTrend; /** Replaces the figures when status is "empty" or "error". */ message?: DashboardMessage; /** Read out while loading. */ loadingLabel?: string; /** Screen-reader heading for the metrics strip. */ metricsHeading?: string; /** 1 when the dashboard is the page; 2 when it sits under a page title. */ headingLevel?: 1 | 2; /** Data sources, definitions or a demo-data notice. */ footnote?: React.ReactNode; }; const skeleton = "block rounded-sm bg-muted"; const linkClass = "inline-flex min-h-11 items-center rounded-sm text-sm font-medium underline underline-offset-4 outline-none hover:decoration-2 focus-visible:ring-[3px] focus-visible:ring-ring/50"; export function DashboardOverview({ context, question, answer, period, status = "ready", metrics, attention, trend, message, loadingLabel = "Loading figures", metricsHeading = "Key figures", headingLevel = 1, footnote, className, ...props }: DashboardOverviewProps) { const id = React.useId(); const Title = `h${headingLevel}` as const; const Section = `h${headingLevel + 1}` as "h2" | "h3"; const loading = status === "loading"; const hasFigures = status === "ready" || loading; const ids = { title: `${id}-title`, metrics: `${id}-metrics`, attention: `${id}-attention`, trend: `${id}-trend`, trendDescription: `${id}-trend-description`, message: `${id}-message`, }; return (
{context ? (

{context}

) : null} {question} {loading ? (

{loading ? loadingLabel : ""}

{!hasFigures && message ? (
{message.label ? ( {message.label} ) : null} {message.title}
{message.description ? (
{message.description}
) : null} {message.actions ? (
{message.actions}
) : null}
) : null}
{hasFigures ? (
{metricsHeading}
{metrics.map((metric) => (
{metric.label}
{loading ? (
{metric.comparison ? (
{loading ? (
) : null} {metric.context ? (
{metric.context}
) : null}
))}
{attention.title}
{attention.description ? (

{attention.description}

) : null} {loading ? ( ) : attention.items.length ? ( ) : (

{attention.emptyText ?? "Nothing needs attention."}

)} {!loading && (attention.action || attention.moreLink) ? (
{attention.action} {attention.moreLink ? ( {attention.moreLink.label} ) : null}
) : null}
) : null} {footnote ? (
{footnote}
) : null}
); } /** * A horizontal bar chart that is also its own text alternative: a table with * one row per period, the value written out beside each bar. */ function TrendChart({ trend, loading, headingId, descriptionId, Heading, }: { trend: DashboardTrend; loading: boolean; headingId: string; descriptionId: string; Heading: "h2" | "h3"; }) { const { title, description, periodHeading = "Week", valueHeading, points, unit = "%", target, } = trend; const max = trend.max ?? 100; const percent = (value: number) => `${Math.min(100, Math.max(0, (value / max) * 100))}%`; return (
{title} {loading ? (
); } ``` ## Interpretation boundaries - Community items are merged and pass automated checks (schema, build, accessibility, overflow and console errors in three themes at five widths); only items with status reviewed have been checked by a maintainer. - Each rule id links to its page at /rules/; every rule is a draft until a maintainer signs it. - Tessli does not claim that using an item improves AI-generated UI; that claim waits for a published evaluation.