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

package/DESIGN.md

@@ -0,0 +1,251 @@
+# Siyahi design guidelines
+
+These rules bind every page built on `@siyahi/ui`: The Book, Dash and any other
+app. Agents must follow them when designing or changing UI; a reviewer treats a
+breach as a defect. The catalogue (https://siyahi.jatinbansal.com) shows each
+component; this file says how to use them.
+
+## Colour
+
+Colour is placed, not spread. A page is neutral greys plus colour that carries
+a meaning:
+
+- **Ink indigo** is the accent: links, the selected sidebar item, the first
+  chart series, a chart's "today" rule and an `accent` `Callout`. Buttons, badges, toggles and focus
+  stay monochrome.
+- **Green and red** mean a gain and a loss. A signed figure is `Delta`: the figure in the text colour with its
+  `+` or `−`, and only a small trend icon in green or red. In plain text (labels, tooltips) write the sign; never
+  colour a run of figures green and red.
+  **Amber** means caution. None of them decorates.
+- **Emphasis tints the whole surface.** A notice is `StatusAlert` in its tone (an
+  error reads like a warning, only red); a state is `StatusBadge`; a point set
+  apart is `Callout` (`neutral`, `accent`, `warning`, `positive`,
+  `negative`); a quotation is `Quote`. Each takes a faint wash of its colour
+  inside a 1px border of the same colour all round. Large marks follow the same
+  rule: every bar is a tint inside a 1px full-colour edge, not a solid slab.
+  A bar is read by its edge, which reaches 3:1 against the card; the tint is a
+  fill carried by that edge.
+- **Never a stripe down one side.** Do not mark a notice, card, row or quote
+  with a left (or any single-side) coloured border; tint the box or add an
+  icon. 1px neutral dividers between columns are separators, not accents, and
+  are fine.
+- **Edges that matter reach 3:1; the rest are hairlines.** A field's edge (input,
+  textarea, select, input group, the command search) is `--input`, at 3:1 on the
+  canvas and the card; dividers, card rings, gridlines and the outlines of
+  buttons, toggles and code blocks are the `--border` hairline (the text colour
+  at 18% in light, white at 20% in dark), firm enough to carry the page's
+  structure. Focus is drawn inside the control, so no neighbour or clipping box
+  covers it: a 2px ring in the text colour (`--ring`) on its edge with a 2px
+  ring of the page colour inside, which reads on a black, white or hovered
+  fill alike. A field shows it as its own edge, 2px in the text colour; a chart
+  mark as a dashed stroke, apart from a picked mark's solid one. A destructive
+  control and an invalid field focus in the destructive red. Menu items show
+  focus as their highlight. A selected
+  toggle or pill tab fills with the foreground. A chart bar that a selection
+  dims keeps its full-colour outline and fades only inside.
+- **Destructive is not loss.** `--destructive` (delete, an invalid field) is a
+  deeper red than `--negative` (a loss figure), so its label reads on its own
+  tint; never use one for the other.
+- Categories (a team, a region, a product line) stay neutral: outline badges,
+  never a hue each. Ordered buckets (largest 5, next 5, rest) use steps of one
+  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.
+  Mark one or two; a page where every row is washed marks nothing.
+
+## Surfaces
+
+`SiyahiProvider`'s `surface` sets how a data block sits on the page. The page
+and card colours are fixed: never tint the canvas.
+
+- **`ruled`** (the default, with or without a provider): ruled on white. The
+  blocks of a `PanelGrid`, the tiles of a `SectionCards` row and the figures
+  of a `MetricStrip` are filled with the card colour and parted by hairlines,
+  with a rule above and below the group and none on its left and right edges.
+  A card standing alone (a `MetricStrip`, a table's card) takes the same rules
+  above and below itself. A short last row ends in a blank cell, ruled off
+  like the rest. A stat tile keeps its footer's top rule and faint band. Set
+  nothing to get it.
+- **`card`**: tight square cards, for a page of separate blocks, such as an
+  index of links. Each block is filled with the card colour inside a hairline
+  ring, with no shadow, 8px from the next in a `PanelGrid` or a row of
+  `SectionCards`. Ask for it with `surface="card"`.
+- **`open`**: no fill, no lines and no padding, so a block sits level with the
+  page's text, for pages read top to bottom.
+
+Every `PanelGrid` numbers its blocks 01, 02 before their card title, in the
+mono face and the link colour, so the text can point to one.
+
+## Shape
+
+- **Square corners everywhere**: panels, cards, buttons, fields, badges,
+  toggles, menus, and bars and tracks (data bars, progress) alike (`--radius`
+  is 0). Only a dot, an avatar, a slider, a spinner or a scrollbar is round;
+  the stock chart tooltip's colour chips keep shadcn's 2px. Never add a
+  `rounded-*` class to a box.
+- **Joined toggles.** The items of a `ToggleGroup` sit flush and share their
+  borders, one control; the pressed item fills with the foreground.
+- **A code block's copy button sits in a header row** (`CodeBlockHeader`),
+  beside its title or alone, never floating over the code, where it would
+  cover the end of a line. An untitled snippet takes the extra row.
+- Badges stay boxed (an outline), the primary button and the pressed toggle
+  black (white in dark), titles in the sans face, at normal spacing.
+
+## Page header
+
+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
+  lines, a `MetricStrip` label, a table's column heads, a sidebar group's
+  label, and a form field's label (muted, above the field). The components and
+  the theme set them; never set a label in this style by hand elsewhere, and
+  never set a figure or a title in it.
+- **A total row reads as a ledger's**: in `TableFooter`, one rule above it and
+  a double rule under it in the text colour, no band.
+
+## Charts
+
+- **Names at the line ends.** A line chart and overlapping areas name each
+  series at its line's end, in the text colour beside a square of its colour,
+  in a gutter after the last point; ends that crowd are spread 14px apart with
+  a short leader. A legend goes below instead on a card under 400px wide (a
+  phone), where the names would take more than 30% of it or not fit the
+  plot's height, and where a line ends short of the plot's right edge (a
+  missing last reading, a single point, an x axis running past the data). Bars and stacks
+  keep a legend.
+- **Five colours, then grey.** Past five series, the page names the few it is
+  about in chart colours and gives the rest `var(--muted-foreground)`: they
+  draw first, in grey. Every line is still named: a grey one's name at its end
+  is muted with no square, and its place says which line it is. Never a count
+  standing in for names. In the legend a grey name is a button that raises its
+  line in the text colour, since a shared grey square cannot tell lines apart;
+  a stack's grey bands read in the legend's order, bottom to top.
+- **No fill under overlapping areas**: from three series on, fills bury each
+  other. A stack fills each band with a flat tint, never a gradient.
+- **Forecast and today.** `forecastFrom` dashes every line from that point,
+  hatches the stretch faintly behind lines on card-coloured halos, labels it
+  FORECAST and hollows the end dots (a stack keeps solid edges and no hatching:
+  its fills cover the stretch);
+  `today` is a 1px rule in the link colour, labelled TODAY.
+- Gridlines are solid hairlines. Lines draw in left to right over 1.3s on
+  first draw, a stack's fills revealed with them; then the names fade in, and
+  each end dot as its line finishes; bars fade in rather than grow. Reduced
+  motion shows them at once.
+- **Stale data is marked by the page**: `stale` on a chart card or a
+  `SectionCards` tile, with since when ("3 Nov"). The block greys and its
+  chart or sparkline draws at about 65% strength, a tile's figure and badge
+  turn muted, and a small "Stale · 3 Nov" note says so. A stale block is meant
+  to be harder to read, so its marks are exempt from the 3:1 mark bar; the
+  note and the figure keep their text contrast. Never infer it from dates.
+
+## Tables
+
+Tables are dense, as a ledger is: compact rows, a 1px rule in the text colour
+under the column heads, the first column (what the row is) in medium weight,
+and figures in the mono face. A figure is a cell marked `data-numeric`, which
+also right-aligns it (the data table marks its number columns; a plain
+`TableCell` or `TableHead` takes the attribute), and any `Delta` in a cell.
+Alignment alone is not a figure. Row hairlines stay; never stripes, never
+column rules.
+
+## Forms
+
+- Every field is a `Field` with a `FieldLabel` above the control, a
+  `FieldDescription` hint or a `FieldError` under it. Never write a bare
+  `<label>` with its own styles.
+- An invalid field (`aria-invalid` on the control, `data-invalid` on its
+  `Field`) keeps its red edge and takes a faint red wash.
+
+## Sidebar
+
+The sidebar is parted from the page by a hairline on its page-side edge, its
+group labels are small monospaced capitals and its rows are compact. Its fill,
+icons and the current page's mark stay as shadcn draws them.

package/README.md

@@ -2,20 +2,31 @@
 
 # Siyahi
 
-Siyahi (Hindi for ink) is a small design system for data-heavy React apps:
-stock [shadcn/ui](https://ui.shadcn.com) on [Base UI](https://base-ui.com) and
-Tailwind CSS v4, shipped as one npm package, `@siyahi/ui`. It adds a theme with
-four meaning colours and a five-hue chart palette that pass WCAG contrast in
-light and dark, a few finance components, locale-aware formatters, a lint that
-keeps pages on the theme, and a catalogue site that is the documentation.
+A design system for data-heavy React apps: [shadcn/ui](https://ui.shadcn.com)
+on [Base UI](https://base-ui.com) and Tailwind CSS v4, with a shared theme,
+charts, tables and locale-aware formatters. Components ship in `@siyahi/ui`;
+checks and build helpers ship in `@siyahi/tools`.
 
-**Catalogue:** https://siyahi.jatinbansal.com
+**[Browse the catalogue](https://siyahi.jatinbansal.com)** for components and live examples.
+
+## For agents
+
+Install the public [Siyahi skill](https://github.com/jatinbansal1998/siyahi/blob/main/skills/siyahi/SKILL.md):
+
+```sh
+npx skills add jatinbansal1998/siyahi --skill siyahi --agent claude-code --agent codex
+```
+
+Read the installed package's `agents/manifest.json` to select components and
+recipes, then only the matching `agents/examples/*.tsx`. Exact prop types are in
+`dist/index.d.ts`. The skill guides reuse and verification; page structure and
+interactions remain yours. No other skill or local Siyahi checkout is required.
 
 ## Install
 
-Siyahi is pre-1.0; releases go out under the `next` tag. It needs React 19 and
-Tailwind CSS v4, compiled by the Tailwind Vite plugin: the package's stylesheet
-is Tailwind source, so a plain CSS import leaves every component unstyled.
+Releases use the `next` tag until 1.0. Siyahi needs React 19 and Tailwind CSS v4.
+Compile its stylesheet with the Tailwind Vite plugin; a plain CSS import leaves
+components unstyled.
 
 ```sh
 npm install @siyahi/ui@next tailwindcss @tailwindcss/vite
@@ -23,7 +34,7 @@ npm install --save-dev @siyahi/tools@next
 ```
 
 ```ts
-// vite.config.ts
+// vite.config.ts: add to your existing plugins
 import tailwindcss from "@tailwindcss/vite";
 import { preloadFonts } from "@siyahi/tools/vite";
 export default defineConfig({ plugins: [react(), tailwindcss(), preloadFonts()] });
@@ -45,198 +56,104 @@ createRoot(root).render(
 );
 ```
 
-`preloadFonts()` adds `<link rel="preload">` tags for Geist and Geist Mono to
-the built `index.html`, so the fonts download with the scripts instead of after
-the first paint. Until they arrive the theme draws Arial (or its Linux twins,
-Liberation Sans and Arimo) scaled to Geist's metrics, so nothing moves when
-Geist swaps in. An app that renders its own HTML adds the tags itself, with
-the hashed URLs of `geist-latin-wght-normal.woff2`,
-`geist-latin-ext-wght-normal.woff2` and `geist-mono-latin-wght-normal.woff2`.
-
-Everything comes from `@siyahi/ui`: the shadcn components, the registry
-add-ons (chart cards, data table, heatmaps, stat tiles, sidebar) and Siyahi's
-own components. Add `lucide-react` only if your
-own code imports icons. A Next.js app compiles the same stylesheet through
-`@tailwindcss/postcss` instead of the Vite plugin.
-
-### Also on GitHub releases
-
-Every merge to `main` also attaches both tarballs to a GitHub release
-(`v<version>`, plus a rolling `next`). They are a fallback if npm is unreachable:
-`npm install --allow-remote=root https://github.com/jatinbansal1998/siyahi/releases/download/v<version>/siyahi-ui-<version>.tgz`.
-
-## What is in it
-
-- **shadcn/ui components** in the `base-luma` style, installed with the shadcn
-  CLI and never edited.
-- **Registry add-ons**, copied once with their origin and licence recorded:
-  bar, area and line chart cards from shadcn's chart blocks, a data table on
-  TanStack Table, calendar, weekday and status heatmaps, a ranked
-  bar list, the `SectionCards` stat tile and the `sidebar-07` app shell.
-- **Siyahi components**: `Delta` (a signed figure with ▲ ▼), `PriceChart`
-  (TradingView Lightweight Charts in theme colours), `Treemap` (holdings heat
-  map; hover or tap a tile for its figures) with `TreemapLegend` (its colour
-  scale), `LocalTime` (a time in the configured zone with the viewer's own clock
-  in a tooltip), `ToneProgress` (Progress in a meaning colour), the page parts
-  `PageSection`, `PageSubheading`, `DataList` and `InlineCode`, the data table
-  parts `DataTableSortHeader` (sorts on one click) and `DataTableRowCount`
-  ("12 of 48"), and `SiyahiProvider`.
-- **Cards and badges as installed**: every `Card`, stat tiles included, keeps
-  luma's `rounded-4xl`, `shadow-md` and faint ring. A category (a sector, a
-  broker, a unit's kind) is an outline `Badge`: categories stay neutral, and
-  colour is left to the four meaning colours and the charts. On a narrow card
-  (header under 24rem, so any phone) a header action such as a toggle drops
-  under the title and description, left-aligned; a stat tile's badge stays
-  top right.
-- **Formatters**: `count`, `money`, `moneyCompact`, `pct` and `time`, or `useFormat()`
-  for the same bound to the provider's locale.
-  `useFormat().time(value, { withDate: true })` (or
-  `time(value, locale, { withDate: true })`) and `<LocalTime withDate>` write
-  the date first: `20 Oct 2026, 14:30 IST`.
-- **`report.css`** for static HTML reports that do not use React: the theme as
-  plain CSS variables plus base body styles, with no network requests.
-
-## Which component
-
-| Need                                                                    | Component                                                           |
-| ----------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| Values over time or another ordered axis (months, hours, price buckets) | `BarChartCard`, `AreaChartCard` or `LineChartCard`                  |
-| Counts or amounts per period, one series or several                     | `BarChartCard`; `stacked` when the series add up to a total         |
-| A running level, such as a portfolio's value against money put in       | `AreaChartCard`                                                     |
-| Series compared point by point, such as a return against an index       | `LineChartCard`                                                     |
-| Samples in time with limits and events marked                           | `LineChartCard` with `xDomain`, `xTicks` and `referenceLines`       |
-| Long category names, such as sectors                                    | `BarChartCard` with `horizontal`                                    |
-| A gain above zero and a loss below it                                   | a series with `color` and `negativeColor`                           |
-| Ranked counts or amounts by category (a name, a bar and a figure)       | `BarList`; give two lists one `max` to share a scale                |
-| Where a budget sits, a split of a whole, or losses against gains        | `DistributionBar`                                                   |
-| Headline figures with their change                                      | `SectionCards`, with a `Delta` in each badge                        |
-| One instrument's price history                                          | `PriceChart`                                                        |
-| Holdings sized by weight and coloured by change                         | `Treemap`                                                           |
-| Activity by day, by weekday and hour, or a status over time             | `CalendarHeatmap`, `WeekdayHeatmap`, `StatusHeatmap`                |
-| Rows to sort and filter                                                 | `DataTable`, inside a `Card`                                        |
-| A column that sorts on one click; a search and an "n of m" count        | `DataTableSortHeader`; `DataTableSearchFilter`, `DataTableRowCount` |
-| Stat tiles that pick a scope for the page                               | `SectionCards` with `selected` and `onSelect`                       |
-| A share or a part of a whole, coloured as a gain or a loss              | `ToneProgress`                                                      |
-| The colour scale under a `Treemap`                                      | `TreemapLegend`, with the map's `range`                             |
-| One part of a long page: rule, eyebrow, heading, lead, action           | `PageSection`, with `PageSubheading` inside                         |
-| Label and value pairs, such as a record's fields                        | `DataList` and `DataListItem`                                       |
-| A command or file to copy, wrapped or scrolling                         | `CodeBlock` with `CodeBlockCopyButton`                              |
-| A labelled copy action, such as "Copy all" for a section                | `CopyButton`                                                        |
-| A command, file or identifier inside prose                              | `InlineCode`                                                        |
-| A signed figure (a gain, a loss, a change)                              | `Delta`                                                             |
-| A time, with the viewer's own clock on hover                            | `LocalTime`                                                         |
-
-The three chart cards take the rows, the field the x axis reads and the series,
-and own everything else: the card and its header action (a range or mode
-toggle), the axes, the dashed horizontal grid, Geist Mono ticks, a tooltip that
-names the hovered point and gives each series' formatted value, and the legend
-below. Props cover the rest: a footer, a placeholder while data loads,
-reference lines, a numeric x axis, a fixed value axis, axis titles, a second
-line under each tick, a picked category, sideways bars and straight segments.
-A page never puts Recharts axes, grids or tooltips together itself.
+`preloadFonts()` loads Geist and Geist Mono with the scripts. Add `lucide-react`
+only when your own code imports icons. Next.js compiles the stylesheet through
+`@tailwindcss/postcss` instead of the Vite plugin. Static HTML reports inline the
+package's `report.css` and follow `agents/report-rules.json`.
 
-```tsx
-<BarChartCard
-  title="Orders by hour"
-  data={[
-    { hour: 9, orders: 42 },
-    { hour: 10, orders: 31 },
-  ]}
-  xKey="hour"
-  xFormatter={(hour) => `${String(hour).padStart(2, "0")}:00`}
-  series={[{ key: "orders", label: "Orders", color: "var(--chart-1)" }]}
-  height={256}
-/>
-```
+If npm is unreachable, both package tarballs are attached to
+[GitHub releases](https://github.com/jatinbansal1998/siyahi/releases).
 
 ## Locale
 
-Numbers, money and times default to Indian English, rupees and IST:
-`₹1,53,110`, `₹2.4L`, `₹40Cr`, `14:30 IST`. In an Indian-region locale,
-`moneyCompact` prints amounts under one lakh in full (`₹99,999`), never as `K`.
-Pass another locale to the provider and every formatter and component under it
-follows:
+`useFormat()` provides `count`, `money`, `moneyCompact`, `pct` and `time`,
+bound to the provider's locale. Defaults are Indian English, rupees and India
+Standard Time: `₹1,53,110`, `₹2.4L`, `14:30 IST`. Use `Delta` for signed changes.
+Override the locale for a whole app or a nested section:
 
 ```tsx
 <SiyahiProvider locale={{ numberLocale: "en-US", currency: "USD", timeZone: "America/New_York" }}>
 ```
 
-The formatters print a minus sign and nothing else. A signed figure (a gain, a
-loss, a change) goes through `<Delta>`, which adds ▲ or ▼ and the meaning
-colour. Time zone names come from the runtime's ICU data; a slim Node or
-browser build may print `GMT+5:30` where a full one prints `IST`.
+## Responsive behavior
+
+Data tables suspend horizontal freezing below 40rem of their own available
+space, including narrow panels on a laptop. Pinning preferences, search, sort,
+selection and expansion stay intact. All columns remain reachable by scrolling;
+the scrolling region also accepts keyboard focus. For page-specific compact
+records, choose essential columns and keep every other field in accessible
+details or an explicit full-table view.
+
+The shipped `data-table-filters` recipe moves secondary filters into a `Sheet`
+using `useDataTable().isCompact`. Configure filtering explicitly when its
+controls render conditionally. Keep search and the active-filter count visible.
+Use container queries for layout and pointer capability for touch targets;
+a touch laptop needs the same reachable controls as a phone.
+
+Ranked lists wrap long labels in narrow panels. Horizontal charts reserve space
+for bars and wrap their category labels; exact axis ticks keep their normal
+text size and scroll when necessary. Heatmap examples expose values on selection
+and support one keyboard entry with arrow navigation. `WeekdayHeatmap` accepts
+`hours` and `weekdays` to show a relevant domain without changing data labels.
+
+## Surfaces
+
+`SiyahiProvider` sets how data blocks sit on the page:
+
+- `surface="ruled"` (default, even outside a provider): ruled on white.
+  `PanelGrid`, `SectionCards` and `MetricStrip` fill their blocks with the card
+  colour and part them with hairlines, with a rule above and below each group
+  and none on the sides; a card standing alone takes the rules above and below
+  itself.
+- `surface="card"`: tight square cards, each filled inside a hairline, 8px
+  apart, no shadow, for a page of separate blocks.
+- `surface="open"`: no fill, boxes or rules; card padding is removed.
+
+`DESIGN.md` has the rest of the look: square corners, mono capital labels,
+ledger totals, the masthead and exception tones.
+
+Nest a provider to change one section. A dialog, sheet or popover renders
+outside the page's provider element: `PanelGrid` and `SectionCards` carry
+their surface into it, but a lone `Card` there is ruled unless the popup's
+content sits in its own provider with an explicit surface, such as
+`<SiyahiProvider surface="card">`; a provider without one draws no element. Stack `PageSection` blocks with
+`flex flex-col gap-6`; use `PanelGrid` for blocks side by side. Categories use
+neutral outline badges, leaving colour for meaning and chart series.
 
 ## Dark mode
 
-The colour scheme follows the device (`prefers-color-scheme`). There is no
-toggle and no class to set. The theme's dark values sit under the same `dark`
-variant as the `dark:` utilities, so an app that wants its own toggle swaps one
-line after the import and sets the `dark` class on `<html>`:
+The theme follows the device through `prefers-color-scheme`. For an app-owned
+toggle, override the variant after the stylesheet import and set the `dark`
+class on `<html>`:
 
 ```css
 @import "@siyahi/ui/styles.css";
 @custom-variant dark (&:where(.dark, .dark *));
 ```
 
-Both the tokens and the utilities then follow the class. Set `color-scheme` on
-`<html>` yourself as well, so scrollbars and form controls match.
-
-## Lint
-
-`@siyahi/tools` ships an [oxlint](https://oxc.rs) plugin. Its rules run only in
-files that import `@siyahi/ui`, so older pages are left alone. They reject
-colour literals (hex, `rgb()`, `oklch()`), Tailwind palette colours, Tailwind
-arbitrary values such as `text-[13px]`, `dark:` and `light:` variants,
-numeric font sizes, and chart configs with a per-scheme `theme` map (shadcn's
-chart applies its dark half under a `.dark` class Siyahi never sets; name a
-chart token with `color: "var(--chart-1)"` instead). Two of the rules are
-[`@shadcn/lint`](https://github.com/shadcn-ui/lint)'s, scoped the same way.
-
-```sh
-npm install --save-dev @siyahi/tools@next oxlint
-```
-
-```json
-{
-  "jsPlugins": ["@siyahi/tools/lint"],
-  "settings": { "shadcn": { "ui": "@siyahi/ui", "themeImports": ["^@siyahi/ui/"] } },
-  "rules": {
-    "siyahi/no-color-literal": "error",
-    "siyahi/no-scheme-variant": "error",
-    "siyahi/no-numeric-font-size": "error",
-    "siyahi/no-chart-theme-map": "error",
-    "siyahi/no-raw-colors": "error",
-    "siyahi/no-arbitrary-values": "error"
-  }
-}
-```
-
-`@siyahi/tools` also has `siyahi-shots` (screenshots of a page at 1920 and 390
-pixels wide in both schemes, with layout checks), `siyahi-cls` (how far a page
-moves after its first paint on a slow network) and `siyahi-contrast` (the
-theme contrast check). See [packages/tools](packages/tools/README.md).
+Set `color-scheme` on `<html>` as well so native controls match.
 
-## This repository
+## Tools
 
-| Path              | What                                                                               |
-| ----------------- | ---------------------------------------------------------------------------------- |
-| `packages/ui`     | `@siyahi/ui`. The theme is `styles/siyahi.css`, the only file with colour values.  |
-| `packages/tools`  | `@siyahi/tools`: lint plugin, font preload, contrast, screenshot and shift checks. |
-| `apps/catalogue`  | The catalogue site, a Vite app deployed as a Cloudflare Worker.                    |
-| `assets/icon.svg` | The mark.                                                                          |
+`@siyahi/tools` provides theme lint rules, font preload, layout screenshots
+(`siyahi-shots`), loading-shift checks (`siyahi-cls`) and contrast checks
+(`siyahi-contrast`). See the
+[tools guide](https://github.com/jatinbansal1998/siyahi/blob/main/packages/tools/README.md)
+for configuration and commands.
 
-Development uses pnpm and [Vite+](https://viteplus.dev):
+## Development
 
 ```sh
 pnpm install
-pnpm --filter @siyahi/tools exec playwright install chromium   # once; the screenshot tests use it
-pnpm check      # format, lint, unused code, generated files, build, typecheck, tests
-pnpm dev        # the catalogue on localhost
+pnpm --filter @siyahi/tools exec playwright install chromium
+pnpm check
+pnpm dev
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) before adding anything.
+Read [CONTRIBUTING.md](https://github.com/jatinbansal1998/siyahi/blob/main/CONTRIBUTING.md)
+before adding components. Source lives in `packages/ui`, `packages/tools` and
+`apps/catalogue`; the catalogue is the visual documentation.
 
 ## Licence
 
-MIT, see [LICENSE](LICENSE). Code copied from other projects keeps its own
-notice; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+MIT. See [LICENSE](LICENSE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -8,17 +8,17 @@ file as copied; `packages/ui/registry.lock.json` lists them all and
 
 ## Copied into `@siyahi/ui`
 
-| What                                                                                  | Where in the package                                     | Origin                                                                                                                                                                                                                                                                                                                                                              | Licence                                                                             |
-| ------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| shadcn/ui core components (installed with `shadcn add`, never edited)                 | `src/components/ui/*`, `src/hooks/use-mobile.ts`         | https://github.com/shadcn-ui/ui                                                                                                                                                                                                                                                                                                                                     | MIT, Copyright (c) 2023 shadcn                                                      |
-| shadcn `tailwind.css` (variants and utilities the components use)                     | `styles/shadcn.css`                                      | https://github.com/shadcn-ui/ui/tree/main/packages/shadcn                                                                                                                                                                                                                                                                                                           | MIT, Copyright (c) 2023 shadcn                                                      |
-| shadcn block `sidebar-07`                                                             | `src/components/registry/sidebar-07/*`                   | https://ui.shadcn.com/r/styles/base-vega/sidebar-07.json                                                                                                                                                                                                                                                                                                            | MIT, Copyright (c) 2023 shadcn                                                      |
-| shadcn block `dashboard-01`, `SectionCards` only                                      | `src/components/registry/dashboard-01/section-cards.tsx` | https://ui.shadcn.com/r/styles/base-vega/dashboard-01.json                                                                                                                                                                                                                                                                                                          | MIT, Copyright (c) 2023 shadcn                                                      |
-| Heatmaps: calendar, weekday by hour, status timeline                                  | `src/components/registry/heatmap/*`                      | https://shadcn-heatmap.pages.dev/r/calendar-heatmap.json, https://shadcn-heatmap.pages.dev/r/weekday-heatmap.json, https://shadcn-heatmap.pages.dev/r/status-heatmap.json (source: https://github.com/rutopio/shadcn-heatmap)                                                                                                                                       | MIT, Copyright (c) 2026 ChingRu                                                     |
-| niko-table data table on TanStack Table                                               | `src/components/registry/niko-table/*`                   | https://niko-table.com/r/data-table.json, https://niko-table.com/r/data-table-core.json, https://niko-table.com/r/data-table-ui.json, https://niko-table.com/r/data-table-faceted-filter.json, https://niko-table.com/r/data-table-column-sort.json, https://niko-table.com/r/data-table-search-filter.json (source: https://github.com/Semkoo/niko-table-registry) | MIT, Copyright (c) 2025 Semir N.; original work Copyright (c) 2025 WebDevSimplified |
-| shadcn chart blocks `chart-bar-multiple`, `chart-area-stacked`, `chart-line-multiple` | `src/components/registry/charts/*`                       | https://ui.shadcn.com/r/styles/new-york-v4/chart-bar-multiple.json, https://ui.shadcn.com/r/styles/new-york-v4/chart-area-stacked.json, https://ui.shadcn.com/r/styles/new-york-v4/chart-line-multiple.json                                                                                                                                                         | MIT, Copyright (c) 2023 shadcn                                                      |
-| dashboardcn ranked list (`BarList`) and stacked bar (`DistributionBar`)               | `src/components/registry/dashboardcn/*`                  | https://dashboardcn.com/r/bar-list.json, https://dashboardcn.com/r/distribution-bar.json (source: https://github.com/NoahGdev/dashboardcn)                                                                                                                                                                                                                          | MIT, Copyright (c) 2026 dashboardcn contributors                                    |
-| MiniDev copy button (`CopyButton`)                                                    | `src/components/registry/minidev/copy-button.tsx`        | https://ui.minidev.pro/r/copy-button.json (source: https://github.com/amankaushik481/minidev-ui)                                                                                                                                                                                                                                                                    | MIT, Copyright (c) 2026 MiniDev                                                     |
+| What                                                                                                | Where in the package                                     | Origin                                                                                                                                                                                                                                                                                                                                                              | Licence                                                                             |
+| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| shadcn/ui core components (installed with `shadcn add`, never edited)                               | `src/components/ui/*`, `src/hooks/use-mobile.ts`         | https://github.com/shadcn-ui/ui                                                                                                                                                                                                                                                                                                                                     | MIT, Copyright (c) 2023 shadcn                                                      |
+| shadcn `tailwind.css` (variants and utilities the components use)                                   | `styles/shadcn.css`                                      | https://github.com/shadcn-ui/ui/tree/main/packages/shadcn                                                                                                                                                                                                                                                                                                           | MIT, Copyright (c) 2023 shadcn                                                      |
+| shadcn block `sidebar-07`                                                                           | `src/components/registry/sidebar-07/*`                   | https://ui.shadcn.com/r/styles/base-vega/sidebar-07.json                                                                                                                                                                                                                                                                                                            | MIT, Copyright (c) 2023 shadcn                                                      |
+| shadcn block `dashboard-01`, `SectionCards` only                                                    | `src/components/registry/dashboard-01/section-cards.tsx` | https://ui.shadcn.com/r/styles/base-vega/dashboard-01.json                                                                                                                                                                                                                                                                                                          | MIT, Copyright (c) 2023 shadcn                                                      |
+| Heatmaps: calendar, weekday by hour, status timeline                                                | `src/components/registry/heatmap/*`                      | https://shadcn-heatmap.pages.dev/r/calendar-heatmap.json, https://shadcn-heatmap.pages.dev/r/weekday-heatmap.json, https://shadcn-heatmap.pages.dev/r/status-heatmap.json (source: https://github.com/rutopio/shadcn-heatmap)                                                                                                                                       | MIT, Copyright (c) 2026 ChingRu                                                     |
+| niko-table data table on TanStack Table                                                             | `src/components/registry/niko-table/*`                   | https://niko-table.com/r/data-table.json, https://niko-table.com/r/data-table-core.json, https://niko-table.com/r/data-table-ui.json, https://niko-table.com/r/data-table-faceted-filter.json, https://niko-table.com/r/data-table-column-sort.json, https://niko-table.com/r/data-table-search-filter.json (source: https://github.com/Semkoo/niko-table-registry) | MIT, Copyright (c) 2025 Semir N.; original work Copyright (c) 2025 WebDevSimplified |
+| shadcn chart blocks `chart-bar-multiple`, `chart-area-stacked`, `chart-line-multiple`               | `src/components/registry/charts/*`                       | https://ui.shadcn.com/r/styles/new-york-v4/chart-bar-multiple.json, https://ui.shadcn.com/r/styles/new-york-v4/chart-area-stacked.json, https://ui.shadcn.com/r/styles/new-york-v4/chart-line-multiple.json                                                                                                                                                         | MIT, Copyright (c) 2023 shadcn                                                      |
+| dashboardcn ranked list (`BarList`), stacked bar (`DistributionBar`), `Sparkline` and `MetricStrip` | `src/components/registry/dashboardcn/*`                  | https://dashboardcn.com/r/bar-list.json, https://dashboardcn.com/r/distribution-bar.json, https://dashboardcn.com/r/sparkline.json, https://dashboardcn.com/r/kpi-row-card.json (source: https://github.com/NoahGdev/dashboardcn)                                                                                                                                   | MIT, Copyright (c) 2026 dashboardcn contributors                                    |
+| MiniDev copy button (`CopyButton`)                                                                  | `src/components/registry/minidev/copy-button.tsx`        | https://ui.minidev.pro/r/copy-button.json (source: https://github.com/amankaushik481/minidev-ui)                                                                                                                                                                                                                                                                    | MIT, Copyright (c) 2026 MiniDev                                                     |
 
 ## Runtime dependencies with attribution terms