@siyahi/ui 0.1.9-next.30 → 0.1.9-next.32

package/DESIGN.md

@@ -51,9 +51,10 @@ a meaning:
   colour, not separate hues.
 - **Colour marks exceptions.** The one stat tile or table row that needs a look
   is marked by the page: `tone: "negative"` or `"warning"` on a `SectionCards`
-  item, `data-tone="negative"` or `"warning"` on a `TableRow`. It takes a faint
-  wash of the colour over the card (7% in light, 12% in dark), and a tile an
-  outline of it. The page decides, never the sign: a falling cost is good news.
+  or `MetricStrip` item, `data-tone="negative"` or `"warning"` on a `TableRow`,
+  and `getRowTone` on a `DataTableBody`, returning the tone for the row. It
+  takes a faint wash of the colour over the card (7% in light, 12% in dark),
+  and a tile or figure an outline of it. The page decides, never the sign: a falling cost is good news.
   Mark one or two; a page where every row is washed marks nothing.
 
 ## Surfaces
@@ -100,6 +101,87 @@ An app page opens on its masthead, `PageHero`: a small mark and eyebrow in the
 mono face and link colour, the title, one muted line saying what the page is,
 the actions at the right, and a hairline under it. One per page; no hero card.
 
+## Words
+
+A page is read by someone who acts on its figures. Its words are plain English,
+in sentence case, and explain themselves: a reader needs no other page to know
+what a figure is, where it came from and what to do next. These rules bind what
+a page's reader sees. The catalogue's own notes (the text that introduces a
+component, its rules and its captions) teach the package and are exempt from
+them, and so are the words in a demo that only name a component's variant or API
+("Ghost", "moneyCompact") or show a bare state (a field disabled with no reason
+given). Everything else in an example is bound like any app's copy, including
+the error, empty, loading and busy text of a state demo. Each rule's example is
+from the catalogue.
+
+- **A title states the finding** when the block makes one point: "Search is
+  near its slowest of the month, login near its fastest". In an app, work its
+  figures out from the data the block draws, so it cannot go stale. When the
+  finding changes with the reader's choice (a toggle, a filter, a pick), the
+  title names the topic instead: "Revenue by channel and quarter". No full
+  stop, no pun or metaphor.
+- **A description says what the figures are**: the measure, its scope and
+  period, how it was counted, whatever the title left out. A single fragment
+  takes no full stop: "Each month's revenue against its target". Once there are
+  two parts, each ends with one: "Each week's balance against the highest it
+  had been so far. At zero the bakery was at a new high." Page copy never names
+  a component, a token or a prop.
+- **Explain what the reader cannot guess.** Say how to read a mark that is not
+  obvious ("Money in above the line, money out below it"), and define a term
+  on first use, in the description, a tooltip or a popover: "Churn counts
+  customers who did not renew this month."
+- **Say where the figures come from and how fresh they are**: the system or
+  report they are read from, "From sar -r", and when, "Prices as of the last
+  market close."
+- **Labels and column heads are short nouns, written in full.** The theme sets
+  them in small mono capitals, so write them in sentence case and never
+  abbreviate to fit: no "vs", "p95", "Qty". Name what the figure is, then its
+  period if the block has several: "Cash flow this year". A note on a plot or
+  beside a figure is lowercase: "new limit, 50%", "new this year".
+- **Units.** A figure from the formatters carries its unit (₹2.4L, 14.2%,
+  14:30 IST). Any other unit is named once: after a label in brackets, "Hour of
+  day (IST)", or after a title with a comma, "Memory in use, GiB". Keep the
+  symbols readers know (%, ₹, ms, s, GiB); anything else is a word. A
+  difference between two percentages is in points, to one decimal, as no
+  formatter writes them: "Sales is 5.6 points under its budget".
+- **Numbers** go through `useFormat()` and `Delta`. In the default locale that
+  is Indian grouping (1,53,110), compact rupees (₹3.1Cr) and amounts under a
+  lakh in full; a page under another locale keeps its forms. A figure on its
+  own (a cell, a tick, a tooltip) carries its sign, as Colour says; a sign you
+  write is `+` or the minus `−`, never a hyphen: "+₹21,300", "−₹18,400". In a
+  phrase a word may carry the direction instead: "5.6 points under". A range
+  takes an en dash, "0–12 GiB"; a multiple takes ×, "about 1.5× a month". A
+  missing figure is —, and a page that leaves items out says how many.
+- **Dates and times** read as the formatters write them, in the default locale
+  day before month: "20 Oct 2026, 14:30 IST". Every block says its time zone
+  once, on its axis title, its description or each time: "Hour of day (IST)". A
+  period is in words, "Last 30 days", "April to March"; a financial year is
+  "FY26", with the block saying when it ends: "FY26 ends in March 2026". A
+  tooltip's heading says more than the tick under it: "Week ending 1 Nov 2026"
+  against "Nov".
+- **A status names a state, not a task**, in a few words that match its tone:
+  "Paid", "Out for delivery", "Needs review".
+- **The components write the chart and staleness notes**: FORECAST, TODAY and
+  "Stale · 3 Nov". The page passes the point or the date and nothing more, and
+  says in its description which stretch is a forecast: "November and December
+  are a forecast". It never writes a note of its own for the same thing.
+- **A button or menu item says what happens**, as a verb, in one to three
+  words: "Export CSV", "Copy order number". A busy button keeps its label as
+  "Saving"; a finished one says so briefly, "Copied". An icon-only button names
+  its action in `aria-label`: "Refresh". A toggle names its options in words
+  ("Cumulative growth", "Last year"); only a range toggle in a card's header
+  shortens them, to 1M, 6M, 1Y and All. A control disabled for a reason the
+  page does not show says why beside it, as a chart's Log button does.
+- **Empty, loading and error states say what happened and what to do.** Empty
+  names what is missing and why: "No holding matches the search." Loading is
+  a `Skeleton` in the block's shape; long work names itself, "Orders imported",
+  with its progress, and a waiting line ends in one "…". An error's title says
+  what happened, "Import failed"; its line says why and what the reader can
+  do: "The CSV could not be read. Export it again and retry." A field's error
+  states the rule with an example: "A PIN code is six digits, such as 560001".
+- **Address the reader as you and the business as we**: "What you own, what it
+  is worth today", "Our store".
+
 ## Labels and totals
 
 - **Labels are small monospaced capitals**: a stat tile's label and footer

package/agents/examples/bar-list-labels.tsx

@@ -12,7 +12,7 @@ export default function BarListLabelsExample() {
     <Card>
       <CardHeader>
         <CardTitle>Orders by category, ranked</CardTitle>
-        <CardDescription>Full labels and order counts stay readable in narrow panels</CardDescription>
+        <CardDescription>Orders placed this month in each category</CardDescription>
       </CardHeader>
       <CardContent>
         <BarList data={categories} valueFormatter={count} />

package/agents/examples/card.tsx

@@ -21,7 +21,7 @@ export default function CardExample() {
         <CardAction>
           <Button variant="outline" size="sm">
             <DownloadIcon />
-            CSV
+            Export CSV
           </Button>
         </CardAction>
       </CardHeader>
@@ -29,7 +29,7 @@ export default function CardExample() {
         <p className="text-3xl font-semibold">{money(4512300)}</p>
       </CardContent>
       <CardFooter>
-        <p className="text-muted-foreground">Updated every night at midnight</p>
+        <p className="text-muted-foreground">Updated every night at midnight IST</p>
       </CardFooter>
     </Card>
   );

package/agents/examples/change-grid.tsx

@@ -4,16 +4,16 @@ import { Card, CardContent, CardDescription, CardHeader, CardTitle, ChangeGrid,
 const months = ["Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec", "Jan", "Feb", "Mar"];
 const growth: Omit<ChangeGridRow, "total">[] = [
   {
-    label: "FY24",
+    label: "FY25",
     values: [0.031, 0.012, -0.024, 0.008, 0.017, -0.006, 0.041, 0.052, 0.063, -0.038, 0.004, 0.022],
   },
   {
-    label: "FY25",
+    label: "FY26",
     values: [0.018, -0.011, -0.032, 0.014, 0.009, 0, 0.036, 0.047, 0.071, -0.044, -0.008, 0.019],
   },
   // The year is under way: months still to come have no figure.
   {
-    label: "FY26",
+    label: "FY27",
     values: [0.026, 0.015, -0.018, 0.021, 0.012, 0.007, 0.044, null, null, null, null, null],
   },
 ];
@@ -31,7 +31,8 @@ export default function ChangeGridExample() {
       <CardHeader>
         <CardTitle>Sales growth by month</CardTitle>
         <CardDescription>
-          Each month against the one before. Deeper tints are larger changes; the year compounds its months.
+          Each month against the one before, by financial year; FY27 ends in March 2027. Deeper tints are larger
+          changes; the year compounds its months.
         </CardDescription>
       </CardHeader>
       <CardContent>

package/agents/examples/chart-bar-losses.tsx

@@ -17,7 +17,7 @@ export default function ChartBarLossesExample() {
   return (
     <BarChartCard
       title="Operating loss by financial year"
-      description="A loss every year, so every bar runs down from zero"
+      description="FY26 ends in March 2026. A loss every year, so every bar runs down from zero."
       data={data}
       xKey="fy"
       series={series}

package/agents/examples/chart-bar-teams.tsx

@@ -33,7 +33,7 @@ export default function ChartBarTeamsExample() {
   ];
   const gap = (row: Row) => {
     const points = Math.abs(row.actual - row.comparison) * 100;
-    return row.actual >= row.comparison ? `+${points.toFixed(1)} pts over` : `\u2212${points.toFixed(1)} pts under`;
+    return `${row.actual >= row.comparison ? "+" : "\u2212"}${points.toFixed(1)} points`;
   };
   return (
     <BarChartCard
@@ -57,7 +57,7 @@ export default function ChartBarTeamsExample() {
       horizontal
       data={rows}
       xKey="team"
-      xTickDetail={(row) => `${pct(row.actual)} vs ${pct(row.comparison)} · ${gap(row)}`}
+      xTickDetail={(row) => `${pct(row.actual)} against ${pct(row.comparison)}, ${gap(row)}`}
       series={series}
       valueFormatter={(v) => pct(v)}
       // A tick format puts the value axis along the bottom of the sideways bars.

package/agents/examples/chart-bar-years.tsx

@@ -24,7 +24,9 @@ export default function ChartBarYearsExample() {
     <BarChartCard
       title="Profit by financial year"
       description={
-        year ? `${year} picked; click it again for every year` : "April to March, before tax. Click a year to pick it."
+        year
+          ? `${year} picked (April to March, before tax). Click it again for every year.`
+          : "April to March, before tax; FY26 ends in March 2026. Click a year to pick it."
       }
       data={data}
       xKey="fy"

package/agents/examples/chart-bar.tsx

@@ -26,8 +26,8 @@ export default function ChartBarExample() {
       title="Revenue by channel and quarter"
       description={
         layout === "grouped"
-          ? "All five chart colours side by side, in series order"
-          : "All five chart colours stacked into the quarter's total"
+          ? "Each channel's revenue, side by side"
+          : "Each channel's revenue, stacked into the quarter's total"
       }
       action={
         <ToggleGroup

package/agents/examples/chart-line-events.tsx

@@ -22,7 +22,7 @@ export default function ChartLineEventsExample() {
   return (
     <LineChartCard
       title="Memory pressure of a test group, %"
-      description="avg10, sampled every 15 s"
+      description="Share of time the group stalled waiting for memory, as the kernel's 10 s average (avg10), sampled every 15 s, times in IST"
       data={data}
       xKey="second"
       // A numeric axis: ticks fall on whole minutes, 2 s after the first sample.

package/agents/examples/chart-line-timeline.tsx

@@ -14,7 +14,7 @@ const data = [
 
 const series: ChartSeries<(typeof data)[number]> = [
   { key: "used", label: "Used", color: "var(--chart-1)" },
-  { key: "anon", label: "Anon", color: "var(--chart-2)" },
+  { key: "anon", label: "Program memory", color: "var(--chart-2)" },
 ];
 
 const clock = (minute: number) => `${Math.floor(15 + minute / 60)}:${String(minute % 60).padStart(2, "0")}`;
@@ -23,7 +23,7 @@ export default function ChartLineTimelineExample() {
   return (
     <LineChartCard
       title="Memory in use, GiB"
-      description="sar -r. Used excludes cache; anon is program memory."
+      description="From sar -r, times in IST. Used excludes the page cache; program memory is what sar calls anon."
       data={data}
       xKey="minute"
       // Ticks on both ends of the domain: the first sits at the plot's left edge.

package/agents/examples/data-bar.tsx

@@ -41,6 +41,12 @@ function Money({ amount }: { amount: number }) {
   return useFormat().money(amount);
 }
 
+// The formatters print a bare hyphen, so a change in plain text writes its own + or −.
+function SignedMoney({ amount }: { amount: number }) {
+  const sign = amount > 0 ? "+" : amount < 0 ? "\u2212" : "";
+  return `${sign}${useFormat().money(Math.abs(amount))}`;
+}
+
 const header = () => <DataTableSortHeader />;
 
 const columns: DataTableColumnDef<Store>[] = [
@@ -60,16 +66,16 @@ const columns: DataTableColumnDef<Store>[] = [
     accessorKey: "change",
     header,
     size: 170,
-    meta: { label: "vs last month", variant: "number" },
+    meta: { label: "Change on last month", variant: "number" },
     cell: ({ row }) => (
       <DataBar value={row.original.change} max={largestChange} tone="sign">
-        <Money amount={row.original.change} />
+        <SignedMoney amount={row.original.change} />
       </DataBar>
     ),
   },
   {
     id: "daily",
-    header: "10 days",
+    header: "Last 10 days",
     size: 110,
     enableSorting: false,
     cell: ({ row }) => {

package/agents/examples/data-table-compact.tsx

@@ -36,7 +36,7 @@ const products: Product[] = [
 
 const header = () => <DataTableSortHeader />;
 
-// While the Week column is hidden to fit, the week's change rides under the revenue it belongs to.
+// While the change column is hidden to fit, the week's change rides under the revenue it belongs to.
 function RevenueCell({ product }: { product: Product }) {
   const format = useFormat();
   const { compactColumns } = useDataTable<Product>();
@@ -64,7 +64,7 @@ const columns: DataTableColumnDef<Product>[] = [
     accessorKey: "change",
     header,
     size: 110,
-    meta: { label: "Week", variant: "number" },
+    meta: { label: "Change", variant: "number" },
     cell: ({ row }) => <Delta value={row.original.change} />,
   },
 ];
@@ -73,11 +73,8 @@ export default function DataTableCompactExample() {
   return (
     <Card>
       <CardHeader>
-        <CardTitle>Products on a phone</CardTitle>
-        <CardDescription>
-          Product and revenue are the key columns. When the columns do not fit, the others hide from the right, and the
-          week's change rides under the revenue once its column is gone; All columns brings back the rest
-        </CardDescription>
+        <CardTitle>Revenue by product</CardTitle>
+        <CardDescription>This week's revenue for each product, with the change on last week</CardDescription>
       </CardHeader>
       <CardContent>
         <DataTableRoot data={products} columns={columns}>
@@ -85,7 +82,7 @@ export default function DataTableCompactExample() {
             <DataTableCompactColumnsToggle />
             <DataTableRowCount unit="products" />
           </DataTableToolbarSection>
-          <DataTable aria-label="Products on a phone">
+          <DataTable aria-label="Revenue by product">
             <DataTableHeader />
             <DataTableBody />
           </DataTable>

package/agents/examples/data-table-filters.tsx

@@ -77,22 +77,22 @@ export default function DataTableFiltersExample() {
   return (
     <Card>
       <CardHeader>
-        <CardTitle>Orders with compact filters</CardTitle>
-        <CardDescription>Search stays visible; secondary filters move into a panel in narrow space.</CardDescription>
+        <CardTitle>Open orders</CardTitle>
+        <CardDescription>Orders packed or out for delivery, by warehouse</CardDescription>
       </CardHeader>
       <CardContent>
         {/* The closed filter panel is absent at first render, so configure its features explicitly. */}
         <DataTableRoot data={data} columns={columns} config={{ enableFilters: true, enableSorting: true }}>
           <DataTableToolbarSection>
             <DataTableSearchFilter
-              label="Search compact example"
+              label="Search orders"
               placeholder="Search orders…"
               className="w-full flex-none sm:w-64"
             />
             <Filters />
             <DataTableRowCount unit="orders" />
           </DataTableToolbarSection>
-          <DataTable aria-label="Orders with compact filters">
+          <DataTable aria-label="Open orders">
             <DataTableHeader />
             <DataTableBody />
           </DataTable>

package/agents/examples/data-table.tsx

@@ -36,6 +36,9 @@ const products: Product[] = [
   { product: "Desk lamp", category: "Lighting", units: 900, revenue: 255600, change: 0.009 },
 ];
 
+// The page's own rule for a product that needs a look; a falling figure alone would not be one.
+const tone = (product: Product): "warning" | undefined => (product.units < 50 ? "warning" : undefined);
+
 // One click sorts largest (or Z) first; the title comes from meta.label.
 const header = () => <DataTableSortHeader />;
 
@@ -58,7 +61,7 @@ const columns: DataTableColumnDef<Product>[] = [
     accessorKey: "change",
     header,
     size: 110,
-    meta: { label: "Week", variant: "number" },
+    meta: { label: "Change", variant: "number" },
     cell: ({ row }) => <Delta value={row.original.change} />,
   },
 ];
@@ -68,10 +71,7 @@ export default function DataTableExample() {
     <Card>
       <CardHeader>
         <CardTitle>Products</CardTitle>
-        <CardDescription>
-          Search every column, filter by category, sort any column in one click; the product stays put when the table
-          scrolls in wide panels. In narrow panels every column scrolls, leaving room for the figures
-        </CardDescription>
+        <CardDescription>This week's units and revenue for each product, with the change on last week</CardDescription>
       </CardHeader>
       <CardContent>
         <DataTableRoot
@@ -90,7 +90,7 @@ export default function DataTableExample() {
           </DataTableToolbarSection>
           <DataTable aria-label="Products">
             <DataTableHeader />
-            <DataTableBody />
+            <DataTableBody getRowTone={tone} />
           </DataTable>
         </DataTableRoot>
       </CardContent>

package/agents/examples/distribution-bar-tug.tsx

@@ -30,7 +30,7 @@ export default function DistributionBarTugExample() {
   return (
     <Card>
       <CardHeader>
-        <CardTitle>The tug-of-war</CardTitle>
+        <CardTitle>Campaigns earned ₹70,000 more than they lost</CardTitle>
         <CardDescription>Each finished campaign, losses left of break-even and gains right</CardDescription>
       </CardHeader>
       <CardContent>

package/agents/examples/heatmap-calendar.tsx

@@ -30,7 +30,7 @@ export default function HeatmapCalendarExample() {
     <Card>
       <CardHeader>
         <CardTitle>Deploys per day</CardTitle>
-        <CardDescription>The last 12 months; counts use a single-hue fade of --chart-1</CardDescription>
+        <CardDescription>The last 12 months; the stronger the colour, the more deploys</CardDescription>
       </CardHeader>
       <CardContent>
         <CalendarHeatmap data={data} labels={{ heatmapLabel: "Deploys per day over the last 12 months" }}>

package/agents/examples/histogram-chart.tsx

@@ -14,7 +14,7 @@ export default function HistogramChartExample() {
   return (
     <HistogramChartCard
       title="Checkout response times"
-      description="The last 2,000 requests, counted in 100 ms buckets. Lines mark the median and the 95th percentile."
+      description="The last 2,000 requests, counted in 100 ms buckets. Lines mark the median and the 95th percentile (95 in 100 requests were faster)."
       values={times}
       valueFormatter={(ms) => `${count(ms)} ms`}
       tickFormatter={count}

package/agents/examples/metric-strip.tsx

@@ -8,7 +8,7 @@ export default function MetricStripExample() {
       label: "Revenue",
       value: money(4512300),
       change: 0.031,
-      note: "vs Sep",
+      note: "against September",
       trend: [3820000, 3950000, 4110000, 4020000, 4380000, 4512300],
     },
     {
@@ -25,6 +25,8 @@ export default function MetricStripExample() {
       change: -61200,
       changeFormat: "money",
       trend: [14200, -3800, 9100, 2600, -18400, -61200],
+      // The one figure on the strip that needs a look, marked by the page: a falling margin alone would not be.
+      tone: "negative",
     },
     { label: "Gift cards", value: moneyCompact(38400), change: 0.18, trend: [4100, 0, 12800, 3300, 9900, 8300] },
     { label: "Products", value: count(42), note: "3 added in Oct", trend: [38, 39, 39, 40, 39, 42] },

package/agents/examples/overview-dashboard.tsx

@@ -40,7 +40,7 @@ interface Holding {
 const holdings: Holding[] = [
   { name: "Nifty 50 index fund", kind: "Equity", status: "On track", tone: "positive", value: 1840000, change: 0.124 },
   { name: "Flexi cap fund", kind: "Equity", status: "On track", tone: "positive", value: 962000, change: 0.087 },
-  { name: "Gold bonds, 2031", kind: "Gold", status: "Review", tone: "warning", value: 410500, change: 0.211 },
+  { name: "Gold bonds, 2031", kind: "Gold", status: "Needs review", tone: "warning", value: 410500, change: 0.211 },
   { name: "Short-term debt fund", kind: "Debt", status: "On track", tone: "positive", value: 655000, change: 0.031 },
   { name: "Small cap fund", kind: "Equity", status: "Below plan", tone: "negative", value: 318200, change: -0.064 },
 ];
@@ -76,7 +76,7 @@ function Holdings({ rows }: { rows: Holding[] }) {
               <TableHead>Holding</TableHead>
               <TableHead>Status</TableHead>
               <TableHead data-numeric>Value</TableHead>
-              <TableHead data-numeric>12 months</TableHead>
+              <TableHead data-numeric>Change over 12 months</TableHead>
             </TableRow>
           </TableHeader>
           <TableBody>

package/agents/examples/range-position-table.tsx

@@ -43,8 +43,28 @@ const services: Service[] = [
   service("login", 175, 161, 203),
 ];
 
+function useMilliseconds(): (value: number) => string {
+  const { count } = useFormat();
+  return (value) => `${count(value)} ms`;
+}
+
 function Milliseconds({ value }: { value: number }) {
-  return `${useFormat().count(value)} ms`;
+  return useMilliseconds()(value);
+}
+
+function Range({ row }: { row: Service }) {
+  const ms = useMilliseconds();
+  return (
+    <RangePosition
+      variant="compact"
+      low={row.low}
+      high={row.high}
+      value={row.today}
+      valueFormatter={ms}
+      lowLabel="30-day fastest"
+      highLabel="30-day slowest"
+    />
+  );
 }
 
 const header = () => <DataTableSortHeader />;
@@ -54,8 +74,8 @@ const columns: DataTableColumnDef<Service>[] = [
   {
     accessorKey: "today",
     header,
-    size: 120,
-    meta: { label: "p95 today", variant: "number" },
+    size: 170,
+    meta: { label: "95th percentile today", variant: "number" },
     cell: ({ row }) => <Milliseconds value={row.original.today} />,
   },
   {
@@ -63,16 +83,7 @@ const columns: DataTableColumnDef<Service>[] = [
     header,
     size: 200,
     meta: { label: "30-day range", compact: true },
-    cell: ({ row }) => (
-      <RangePosition
-        variant="compact"
-        low={row.original.low}
-        high={row.original.high}
-        value={row.original.today}
-        lowLabel="30-day fastest"
-        highLabel="30-day slowest"
-      />
-    ),
+    cell: ({ row }) => <Range row={row.original} />,
   },
 ];
 
@@ -82,7 +93,8 @@ export default function RangePositionTableExample() {
       <CardHeader>
         <CardTitle>Search is near its slowest of the month, login near its fastest</CardTitle>
         <CardDescription>
-          Each service's response time today on a track from its fastest day to its slowest; sort to rank them
+          Each service's 95th-percentile response time today (95 in 100 requests were faster) on a track from its
+          fastest day to its slowest; sort to rank them
         </CardDescription>
       </CardHeader>
       <CardContent>

package/agents/examples/target-rows.tsx

@@ -30,14 +30,14 @@ const teams: Team[] = [
 const NEAR = 0.02;
 const FAR = 0.05;
 
-const pts = (value: number) => `${(value * 100).toFixed(1)} pts`;
+const points = (value: number) => `${(value * 100).toFixed(1)} points`;
 
 function statusOf({ weight, target }: Team): TargetStatus {
   const gap = weight - target;
-  const size = `${pts(Math.abs(gap))} ${gap > 0 ? "over" : "under"}`;
+  const size = `${points(Math.abs(gap))} ${gap > 0 ? "over" : "under"}`;
   if (Math.abs(gap) <= NEAR) return { kind: "met", label: "On target" };
   if (Math.abs(gap) <= FAR) return { kind: "missed", label: size };
-  return { kind: "warning", label: `${size}, review` };
+  return { kind: "warning", label: `${size}, needs review` };
 }
 
 export default function TargetRowsExample() {

package/dist/components/registry/dashboardcn/kpi-row-card.d.ts

@@ -13,6 +13,8 @@ export interface MetricStripItem {
   note?: React$1.ReactNode;
   /** Recent values, oldest first, drawn as a sparkline beside the figure. */
   trend?: number[];
+  /** Marks the figure as the exception on the page: a faint wash of the colour and an outline of it. */
+  tone?: "negative" | "warning";
 }
 export interface MetricStripProps extends Omit<React$1.ComponentProps<typeof Card>, "title"> {
   title?: React$1.ReactNode;

package/dist/components/registry/dashboardcn/kpi-row-card.js

@@ -39,6 +39,7 @@ function MetricStrip({ title, description, action, items, footer, className, ...
 					className: "-me-px -mb-px flex flex-wrap",
 					children: items.map((item) => /* @__PURE__ */ jsxs("div", {
 						"data-slot": "metric-strip-item",
+						"data-tone": item.tone,
 						className: cn("flex min-w-0 flex-col gap-1.5 border-e border-b px-4 py-4", columns),
 						children: [/* @__PURE__ */ jsx("div", {
 							className: "truncate font-mono text-2xs tracking-wider text-muted-foreground uppercase",

package/dist/components/registry/niko-table/core/data-table-structure.d.ts

@@ -40,8 +40,15 @@ export interface DataTableBodyProps<TData extends RowData> {
    * Wrap the callback in `useCallback` so memoized rows don't re-render.
    */
   renderRowContextMenu?: (row: TData) => React.ReactNode;
+  /**
+   * Mark the row that needs a look, such as a holding in deep loss: return
+   * `"negative"` or `"warning"` and the row takes a faint wash of that
+   * colour, as a `TableRow` with `data-tone` does; `undefined` leaves it
+   * plain. The page decides, never the sign. Mark one or two rows.
+   */
+  getRowTone?: (row: TData) => "negative" | "warning" | undefined;
 }
-export declare function DataTableBody<TData extends RowData>({ children, className, onScroll, onScrolledTop, onScrolledBottom, scrollThreshold, onRowClick, getRowMemoKey, renderRowContextMenu }: DataTableBodyProps<TData>): React.JSX.Element;
+export declare function DataTableBody<TData extends RowData>({ children, className, onScroll, onScrolledTop, onScrolledBottom, scrollThreshold, onRowClick, getRowMemoKey, renderRowContextMenu, getRowTone }: DataTableBodyProps<TData>): React.JSX.Element;
 export declare namespace DataTableBody {
   var displayName: string;
 }

package/dist/components/registry/niko-table/core/data-table-structure.js

@@ -27,7 +27,7 @@ const DataTableHeader = React.memo(function DataTableHeader({ className, sticky
 	const flexColumnIds = resolveFlexColumnIds(table, !isCompact);
 	const columnSizing = table.state.columnSizing;
 	return /* @__PURE__ */ jsx(TableHeader, {
-		className: cn(sticky && "sticky top-0 z-30 bg-card", sticky && "after:absolute after:right-0 after:bottom-0 after:left-0 after:h-px after:bg-border", className),
+		className: cn(sticky && "sticky top-0 z-30 bg-(--table-fill)", sticky && "after:absolute after:right-0 after:bottom-0 after:left-0 after:h-px after:bg-border", className),
 		children: headerGroups.map((headerGroup) => /* @__PURE__ */ jsx(TableRow, { children: headerGroup.headers.map((header) => {
 			const isFlex = flexColumnIds.has(header.column.id);
 			const headerStyle = {
@@ -62,7 +62,7 @@ const DataTableHeader = React.memo(function DataTableHeader({ className, sticky
 DataTableHeader.displayName = "DataTableHeader";
 /** Fade-pulse animation applied to a flashing cell (keyframe in the provider). */
 const FLASH_ANIMATION = "niko-row-flash 1.2s ease-out";
-const BodyRow = React.memo(function BodyRow({ row, displayIndex, expandColumnId, isCompact, isClickable, isExpanded, isSelected, columnWidths, isRowFlashing, flashingCellKeys, renderRowContextMenu }) {
+const BodyRow = React.memo(function BodyRow({ row, displayIndex, expandColumnId, isCompact, isClickable, isExpanded, isSelected, columnWidths, isRowFlashing, flashingCellKeys, renderRowContextMenu, tone }) {
 	const expandCell = isExpanded && expandColumnId ? row.getAllCells().find((c) => c.column.id === expandColumnId) : void 0;
 	const visibleCells = row.getVisibleCells();
 	const rowElement = /* @__PURE__ */ jsx(TableRow, {
@@ -72,8 +72,10 @@ const BodyRow = React.memo(function BodyRow({ row, displayIndex, expandColumnId,
 		"data-parity": displayIndex % 2 === 0 ? "even" : "odd",
 		"data-expanded": isExpanded ? "true" : void 0,
 		"data-state": isSelected ? "selected" : void 0,
+		"data-tone": tone,
 		className: cn(isClickable && "cursor-pointer", "group data-[context-menu-open]:bg-muted/50"),
 		children: visibleCells.map((cell) => {
+			const pinned = !isCompact && cell.column.getIsPinned();
 			const flashing = isRowFlashing || flashingCellKeys.has(flashCellKey(row.id, cell.column.id));
 			const cellStyle = {
 				width: columnWidths.get(cell.column.id),
@@ -84,8 +86,9 @@ const BodyRow = React.memo(function BodyRow({ row, displayIndex, expandColumnId,
 				"data-flash": flashing ? "true" : void 0,
 				"data-col-id": cell.column.id,
 				"data-numeric": cell.column.columnDef.meta?.variant === "number" || void 0,
+				"data-pinned": pinned || void 0,
 				style: cellStyle,
-				className: cn(!cell.getIsGrouped() && "truncate", !isCompact && cell.column.getIsPinned() && "bg-linear-to-r group-hover:from-muted/50 group-hover:to-muted/50 group-data-[context-menu-open]:from-muted/50 group-data-[context-menu-open]:to-muted/50 group-data-[state=selected]:from-muted group-data-[state=selected]:to-muted"),
+				className: cn(!cell.getIsGrouped() && "truncate", pinned && "bg-linear-to-r group-hover:from-muted/50 group-hover:to-muted/50 group-data-[context-menu-open]:from-muted/50 group-data-[context-menu-open]:to-muted/50 group-data-[state=selected]:from-muted group-data-[state=selected]:to-muted"),
 				children: renderCellContent(cell)
 			}, cell.id);
 		})
@@ -102,7 +105,7 @@ const BodyRow = React.memo(function BodyRow({ row, displayIndex, expandColumnId,
 	}) })] });
 });
 BodyRow.displayName = "BodyRow";
-function DataTableBody({ children, className, onScroll, onScrolledTop, onScrolledBottom, scrollThreshold = 50, onRowClick, getRowMemoKey, renderRowContextMenu }) {
+function DataTableBody({ children, className, onScroll, onScrolledTop, onScrolledBottom, scrollThreshold = 50, onRowClick, getRowMemoKey, renderRowContextMenu, getRowTone }) {
 	const { table, columns, isLoading, flashingRowIds, flashingCellKeys, registerRowScroller, headerMinWidths, isCompact } = useDataTable();
 	const { rows } = table.getRowModel();
 	const containerRef = React.useRef(null);
@@ -245,7 +248,8 @@ function DataTableBody({ children, className, onScroll, onScrolledTop, onScrolle
 			rowMemoKey: getRowMemoKey ? getRowMemoKey(row.original) : "",
 			isRowFlashing: flashingRowIds.has(row.id),
 			flashingCellKeys,
-			renderRowContextMenu: resolvedRenderRowContextMenu
+			renderRowContextMenu: resolvedRenderRowContextMenu,
+			tone: getRowTone?.(row.original)
 		}, row.id)) : null, children]
 	});
 }

package/dist/components/registry/niko-table/lib/styles.js

@@ -16,7 +16,7 @@ const getCommonPinningStyles = (column, isHeader = false, pinningEnabled = true)
 		maxWidth: columnSize,
 		flexShrink: 0,
 		zIndex: isHeader ? 20 : 10,
-		backgroundColor: "var(--card)",
+		backgroundColor: "var(--table-fill)",
 		boxShadow: isLeft ? "inset -1px 0 0 0 var(--border)" : "inset 1px 0 0 0 var(--border)"
 	};
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siyahi/ui",
-  "version": "0.1.9-next.30",
+  "version": "0.1.9-next.32",
   "description": "Stock shadcn/ui on Base UI and Tailwind v4, a finance theme, a few compositions and formatters.",
   "keywords": [
     "base-ui",

package/styles/siyahi.css

@@ -555,12 +555,13 @@ svg :is(rect, circle, path)[tabindex]:focus-visible,
 }
 
 /*
- * An exception the page marks, a stat tile (SectionCard's tone) or a table
- * row (<TableRow data-tone="negative">), takes a faint wash of its colour over
- * the card, and a tile an outline of it, so the one figure needing attention
+ * An exception the page marks, a stat tile (SectionCard's tone), a MetricStrip
+ * figure (its item's tone) or a table row (<TableRow data-tone="negative">, a
+ * DataTableBody's getRowTone), takes a faint wash of its colour over the card,
+ * and a tile or figure an outline of it, so the one figure needing attention
  * stands out of a run of neutral ones. Unlayered, to outrank a row's hover band.
  */
-:is([data-slot="card"], [data-slot="table-row"]) {
+:is([data-slot="card"], [data-slot="metric-strip-item"], [data-slot="table-row"]) {
   &[data-tone="negative"] {
     --exception: var(--negative);
   }
@@ -568,12 +569,33 @@ svg :is(rect, circle, path)[tabindex]:focus-visible,
     --exception: var(--warning);
   }
 }
-[data-slot="card"]:is([data-tone="negative"], [data-tone="warning"]) {
+:is([data-slot="card"], [data-slot="metric-strip-item"]):is([data-tone="negative"], [data-tone="warning"]) {
   background-color: color-mix(in oklab, var(--exception) var(--wash), var(--card));
+}
+[data-slot="card"]:is([data-tone="negative"], [data-tone="warning"]) {
   --tw-ring-color: color-mix(in oklab, var(--exception) var(--wash-edge), transparent);
 }
+/*
+ * A figure's outline lies on the four hairlines around it, as a tile's ring does: its neighbours' rules before and
+ * above it, and its own end and bottom rules, which sit outside the padding box the inset counts from.
+ */
+[data-slot="metric-strip-item"]:is([data-tone="negative"], [data-tone="warning"]) {
+  position: relative;
+  &::after {
+    content: "";
+    position: absolute;
+    inset: -1px;
+    border: 1px solid color-mix(in oklab, var(--exception) var(--wash-edge), transparent);
+    pointer-events: none;
+  }
+}
+/* A pinned cell paints the card under itself (niko-table's lib/styles), so it lays the row's wash over that. */
 [data-slot="table-row"]:is([data-tone="negative"], [data-tone="warning"]) {
-  background-color: color-mix(in oklab, var(--exception) var(--wash), transparent);
+  --row-wash: color-mix(in oklab, var(--exception) var(--wash), transparent);
+  background-color: var(--row-wash);
+  & > [data-pinned] {
+    background-image: linear-gradient(var(--row-wash), var(--row-wash));
+  }
 }
 
 /*
@@ -615,6 +637,14 @@ svg :is(rect, circle, path)[tabindex]:focus-visible,
     border-color: transparent;
   }
 }
+/*
+ * The opaque fill a data table's sticky header and pinned cells paint, so rows
+ * scrolling under them stay hidden: the colour under the table, the card it
+ * sits in or, on an open surface, whose cards have no fill, the page.
+ */
+[data-slot="table-container"] {
+  --table-fill: var(--card);
+}
 
 /*
  * A series in a forecast is drawn twice (LineChartCard, AreaChartCard): solid
@@ -804,6 +834,9 @@ div[data-slot="sidebar"]:not([data-side], [data-mobile]) {
 }
 
 @scope ([data-surface="open"]) to ([data-surface="ruled"], [data-surface="card"]) {
+  [data-slot="table-container"] {
+    --table-fill: var(--background);
+  }
   [data-slot="card"] {
     background: none;
     --tw-ring-color: transparent;