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

package/DESIGN.md

@@ -100,6 +100,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

@@ -58,7 +58,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 +68,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

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],
     },
     {

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/package.json

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