@apliteni/apliteni-ui 0.38.0 → 0.39.1

package/README.md

@@ -31,8 +31,11 @@ factories below. Yes → the [React components](#react-components-stateful-surfa
 Either layer follows the same UI rules — what one page may hold, which component to reach
 for, the states it owes, how colour and wording work. They live in the **Guidelines** section
 of Storybook, which opens on
-[an overview of every page](https://ui.apli.tech/storybook/?path=/story/guidelines-overview--overview)
-and what the kit does and does not yet meet.
+[links to every guideline page](https://ui.apli.tech/storybook/?path=/story/guidelines-overview--overview).
+The same guidance ships as plain Markdown in
+`node_modules/@apliteni/apliteni-ui/guidelines/`. Start with
+[guidelines/overview.md](guidelines/overview.md); Storybook reads these documents too.
+
 [The page](https://ui.apli.tech/storybook/?path=/story/guidelines-the-page--the-page) is the one
 to read before you design a screen: the limits one page keeps, whatever it is about.
 

package/guidelines/accessibility-floor.md

@@ -0,0 +1,105 @@
+# Accessibility minimums
+
+## Minimum target size
+
+<!-- rule: target-size -->
+
+**Rule:** Give every pointer target at least 24x24 CSS px.
+
+**Why:** Larger targets are easier to activate accurately.
+
+**Do:** Use a centred 24x24 `::before` hit area for a 19x19 checkbox.
+
+**Don't:** Leave a 19x19 target unchanged.
+
+**Except:** WCAG 2.5.8 permits spacing, equivalent controls, inline text, user-agent sizes and essential presentation. Overlays must not reach neighbours.
+
+## Focus ring contrast
+
+<!-- rule: ring-contrast -->
+
+**Rule:** Keep a focus indicator at least 3:1 against every ground it reaches.
+
+**Why:** A solid band remains visible where glow alone may disappear.
+
+**Do:** Use G2’s solid band with a surface-coloured gap around accent-filled controls.
+
+**Don't:** Use the halo alone as the focus indicator.
+
+**Except:** The band must reach 4.22:1 on flat ground and 3:1 against actual gap and halo pixels.
+
+## Disabled control legibility
+
+<!-- rule: disabled-legibility -->
+
+**Rule:** Paint disabled controls with a different ink/surface pair from enabled controls.
+
+**Why:** Opaque colours keep disabled text and surfaces readable.
+
+**Do:** Use opaque `--disabled-ink`, `--disabled-surface` and `--disabled-border`.
+
+**Don't:** Fade the label and box together.
+
+**Except:** Labels must reach 3:1. Boxless ghosts use `--disabled-ink-bare`, floored at 4.89:1. Disabled controls must look weaker by changing the pair and removing accent. Only the label-free switch track may fade.
+
+## Touch field text
+
+<!-- rule: touch-field-size -->
+
+**Rule:** Set coarse-pointer field text to 16px without scaling it down.
+
+**Why:** iOS Safari zooms fields below 16px and does not zoom out.
+
+**Do:** Apply real 16px text to `input`, `select` and `textarea`, including host fields.
+
+**Don't:** Scale 16px down with transforms or smaller computed text.
+
+**Except:** Preserve host fields above 16px with `!important` on a more specific selector. Checkbox, radio, range, colour, file and button types do not zoom. Do not remove pinch-zoom with `user-scalable=no` or `maximum-scale=1`. The host owns the viewport tag.
+
+## Body contrast
+
+<!-- rule: body-contrast -->
+
+**Rule:** Aim for body text contrast close to 7:1, not merely 4.5:1.
+
+**Why:** Stronger contrast supports comfortable reading at every size.
+
+**Do:** Use body ink at every size, then vary size, weight or spacing for hierarchy.
+
+**Don't:** Use pale body ink and rely on larger text for hierarchy.
+
+## Status labels
+
+<!-- rule: status-label -->
+
+**Rule:** Show every status with both a mark and a word.
+
+**Why:** Colour alone is not reliably distinguishable.
+
+**Do:** Pair a status icon with text such as “Paused.”
+
+**Don't:** Show success using green colour alone.
+
+## Measurable pairs
+
+<!-- rule: measurable-pair -->
+
+**Rule:** Prefer opaque grounds behind text so contrast can be measured.
+
+**Why:** Gradients, filters and translucent layers make contrast uncertain.
+
+**Do:** Place text on an opaque surface with a measurable ink pair.
+
+**Don't:** Place text over a gradient, filter or translucent layer.
+
+## Keyboard first
+
+<!-- rule: keyboard-first -->
+
+**Rule:** Implement keyboard behaviour before pointer behaviour and styling.
+
+**Why:** Keyboard access defines the interaction before visual polish.
+
+**Do:** Make focus, order and keyboard actions work before styling controls.
+
+**Don't:** Style pointer interactions before implementing keyboard behaviour.

package/guidelines/colour-and-theming.md

@@ -0,0 +1,56 @@
+# Colour and theming
+
+## Semantic tokens
+
+**Rule:** Add and use a semantic colour token before writing a literal.
+
+**Why:** Literals cannot follow the theme or accent.
+
+**Do:** Use tokens for ground and ink.
+
+**Don't:** Freeze colours at dark-theme values.
+
+**Except:** Token definitions set the colours; `#000` inside a mask controls alpha, not colour.
+
+<!-- rule: tokens -->
+
+## Stable signals
+
+**Rule:** Let the accent change with a sub-theme, but keep `--pink` and `--green` unchanged.
+
+**Why:** If danger followed the accent, revoke and go would look identical.
+
+**Do:** Keep error as `--pink` under every accent.
+
+**Don't:** Point `--pink` at the accent.
+
+**Except:** Across `data-theme`, signals change: light deepens `--pink` from `#e97ca5` to `#b63361` so it reads as ink on white.
+
+<!-- rule: signals -->
+
+## Accent contrast
+
+**Rule:** Use `--accent-strong` for an accent ground and `--accent` for accent ink.
+
+**Why:** `--accent` is text on the canvas; its darker sibling, `--accent-strong`, lets white clear AA.
+
+**Do:** Use `--accent-strong` behind white text.
+
+**Don't:** Use `--accent` as that ground.
+
+**Except:** In Phoenix, Ocean and Emerald, both are one token; the difference matters only in Nebula.
+
+<!-- rule: accent-strong -->
+
+## Theme checks
+
+**Rule:** Check dark and light themes and at least two accents before opening a PR.
+
+**Why:** A pair that clears AA in dark can fail in light over a card’s wash.
+
+**Do:** Test both themes and two accents.
+
+**Don't:** Check only dark mode and one accent.
+
+
+<!-- rule: both-themes -->

package/guidelines/command-palette.md

@@ -0,0 +1,79 @@
+# The command palette
+
+## Named things
+
+<!-- rule: named-things -->
+
+**Rule:** Put something in the palette only if a reader can name it.
+
+**Why:** Named items are easier to find and understand.
+
+**Do:** Include recognisable commands and numbered records that readers can also reach by clicking through the product.
+
+**Don't:** Include “Advanced…”, “More”, a frequency option, or a row that opens the current page.
+
+**Except:** One-step settings are commands, such as “Switch to the light theme”; settings needing a choice open a named page.
+
+## Product-owned groups
+
+<!-- rule: groups -->
+
+**Rule:** Group results by what they are, using the product’s own word for each group.
+
+**Why:** Groups tell readers whether a result opens a record, changes location or runs a command.
+
+**Do:** Use three sentence-case headings at the 13px label rank for actions, destinations and recent items.
+
+**Don't:** Show nine ungrouped rows that hide whether Enter runs a command, opens an invoice or goes to a page.
+
+## Query-based ranking
+
+<!-- rule: ranking -->
+
+**Rule:** Rank results by how the query matches the name, and let the caller break every tie.
+
+**Why:** Caller order keeps preferred commands first, and the kit stores no usage history.
+
+**Do:** For “inv”, rank whole-word matches above fragments and names above notes; put the best row’s group first.
+
+**Don't:** Put INV-4809 first because of its digits while leaving the matching name “New invoice” last.
+
+**Except:** For server results, pass `rank: false` and answer `ui-command-query`; the server ranks the full result, and the kit keeps that order.
+
+## Six keyboard keys
+
+<!-- rule: keyboard -->
+
+**Rule:** Handle Cmd/Ctrl+K, Up, Down, Enter, Escape and Tab, and leave every other key to the text box.
+
+**Why:** These keys open, navigate, run, close and contain the palette without changing text-box behavior.
+
+**Do:** Wrap arrow navigation, run the active row with Enter, close the top overlay with Escape, and keep focus inside with Tab.
+
+**Don't:** Handle Home, End, Ctrl+N/P/J/K or Alt+Arrow; Home and End belong to the caret under ARIA’s combobox pattern.
+
+**Except:** Leave Ctrl+K alone inside another text box, where it means kill-to-end-of-line.
+
+## Focus and announcements
+
+<!-- rule: say-it -->
+
+**Rule:** Focus the text box, announce the result count, and return focus afterward.
+
+**Why:** `aria-activedescendant` identifies the active row while letters and arrows stay in the text box.
+
+**Do:** Announce only the count in a polite live region and restore focus on close, even if the command removed the opener.
+
+**Don't:** Move focus to each row or reread every row after each keystroke.
+
+## Confirm destructive actions
+
+<!-- rule: ask-first -->
+
+**Rule:** Never let the palette run a delete by itself.
+
+**Why:** A destructive row must be confirmed because readers watch the text box on this fast surface.
+
+**Do:** Show an ellipsis and danger ink, and let Enter open a confirm above the palette that answers the first Escape.
+
+**Don't:** Omit confirmation; the row becomes disabled and arrow navigation skips it.

package/guidelines/component-choice.md

@@ -0,0 +1,71 @@
+# Component choice
+
+## Interrupt with a question
+
+<!-- rule: interrupt -->
+
+**Rule:** Stop the page for a question; leave a statement on the page.
+
+**Why:** A confirm keeps keyboard focus until answered; a callout does not interrupt.
+
+**Except:** Use a drawer when the answer needs a form instead of two buttons.
+
+**Do:** The question stops the page.
+
+**Don't:** Show the same question with nothing to answer.
+
+## Show lasting conditions
+
+<!-- rule: transient -->
+
+**Rule:** Use a toast for what happened and a callout for what is still true.
+
+**Why:** A toast dismisses itself, so an active condition disappears too soon.
+
+**Except:** A toast with an action may remain because something happened and can still be answered.
+
+**Do:** Keep a standing warning on the page.
+
+**Don't:** Let the same warning dismiss itself.
+
+## Match controls to panels
+
+<!-- rule: panels -->
+
+**Rule:** Use tabs() when the control owns a panel and segmented() when it owns nothing.
+
+**Why:** A tablist promises a panel and arrow-key support; a strip without either fails the reader.
+
+**Except:** Links between locations are neither; the kit’s nav uses aria-current, not a tablist.
+
+**Do:** Use a filter strip that owns no panel.
+
+**Don't:** Use a tablist that owns no panels.
+
+## Match confirmation scale
+
+<!-- rule: scale -->
+
+**Rule:** Choose the confirmation by how much of the screen it owns.
+
+**Why:** successPanel() is a page block; success() is the page and tells the reader where to go next.
+
+**Except:** A block that needs somewhere to go next still uses success(); successPanel() takes two strings.
+
+**Do:** Use a block confirmation inside the page.
+
+**Don't:** Force a page-sized confirmation into a card.
+
+## Add dropdown search
+
+<!-- rule: dropdown-search -->
+
+**Rule:** Give a dropdown a search field at ten options, or whenever its options come from data.
+
+**Why:** Ten options require scrolling, and data-fed lists need search at any count; matching anywhere in a label also finds later words.
+
+**Except:** Below six options, search adds an unnecessary stop; at six to nine, the author decides, adding search for described rows that scroll from the sixth.
+
+**Do:** For twenty-nine currencies, type “dollar” instead of scrolling.
+
+**Don't:** Show only seven of twenty-nine currencies without search when dollars are scattered through the list.

package/guidelines/dense-tables.md

@@ -0,0 +1,87 @@
+# Dense tables
+
+Keep numbers comparable when the dataset needs many rows and columns.
+
+## Use the right surface
+
+<!-- rule: surface -->
+
+**Why:** Grey or tinted table backgrounds make dense rows harder to separate from the surrounding interface.
+
+**Rule:** Put tables on a white surface in light mode and the base canvas in dark mode.
+
+**Do:** Use a white surface in light mode and the base canvas in dark mode; let the row edge mark hover.
+
+**Don't:** Add a grey zebra or hover fill.
+
+## Choose density without shrinking type
+
+<!-- rule: density -->
+
+**Why:** Compact rows save space without making values harder to read.
+
+**Rule:** Choose compact spacing without changing the type size.
+
+**Do:** Keep readable values at the small text rank and use compact vertical spacing only when needed.
+
+**Don't:** Shrink the type to fit more rows.
+
+## Align numeric values
+
+<!-- rule: numbers -->
+
+**Why:** A shared edge lets readers compare magnitudes quickly.
+
+**Rule:** Right-align numeric headers and values.
+
+**Do:** Right-align numeric headers and values, use tabular numerals, and keep text left-aligned.
+
+**Don't:** Align numbers to their labels or sort formatted strings.
+
+## Name the comparison
+
+<!-- rule: delta -->
+
+**Why:** A sign carries direction without making colour do all the work.
+
+**Rule:** Print the sign and name the comparison.
+
+**Do:** Print the sign, name the comparison, and let the caller choose whether the change is good or bad.
+
+**Don't:** Use colour alone or treat a missing comparison as zero.
+
+## Keep units readable
+
+<!-- rule: units -->
+
+**Why:** Units carry information even when they are secondary to the value.
+
+**Rule:** Keep units smaller and in body ink.
+
+**Do:** Keep units smaller and in body ink, and explain abbreviations in reachable text.
+
+**Don't:** Hide units in muted text or make readers guess what an abbreviation means.
+
+## Scroll instead of squeezing
+
+<!-- rule: overflow -->
+
+**Why:** There is no universal column limit that keeps every dataset readable.
+
+**Rule:** Scroll columns instead of squeezing them.
+
+**Do:** Use a named keyboard-focusable scroll region with a sticky header and pinned identity column.
+
+**Don't:** Squeeze columns until values are unreadable or silently remove data.
+
+## Keep updates stable
+
+<!-- rule: states -->
+
+**Why:** Stable rows and clear states help readers keep their place while results change.
+
+**Rule:** Keep the table stable while results update.
+
+**Do:** Retain rows while refreshing, report busy state, distinguish no data from no matches and errors, and preserve focus when filters change.
+
+**Don't:** Replace the table with a blank state or move focus without telling the reader why.

package/guidelines/destructive-actions.md

@@ -0,0 +1,43 @@
+# Destructive actions
+
+## Quiet destructive controls
+
+<!-- rule: colour -->
+
+**Rule:** Keep destructive controls quiet at rest and turn them `--pink` on hover.
+
+**Why:** `--accent` makes a destructive control look ordinary.
+
+**Except:** `--pink` also marks a seen error, not an impending action.
+
+**Do:** Hover makes the danger row `--pink`.
+
+**Don't:** Hover repaints the row `--accent`.
+
+## Name both actions
+
+<!-- rule: wording -->
+
+**Rule:** Name the action that destroys and the action that does not.
+
+**Why:** “OK” explains nothing; “Revoke access” names the cost.
+
+**Except:** Use “Cancel” when there is nothing to keep yet, such as a new form or upload.
+
+**Do:** Each label makes sense alone.
+
+**Don't:** Use “Are you sure?” without saying what will happen.
+
+## Choose confirmation or undo
+
+<!-- rule: undo -->
+
+**Rule:** Choose confirmation or undo based on reversibility; never use both.
+
+**Why:** Confirmation adds a click to undoable actions, while undo is an empty promise for actions that cannot be restored.
+
+**Except:** Confirm actions affecting many items: one row is undoable with one click, but a whole selection is not.
+
+**Do:** Ask first when nothing can be restored.
+
+**Don't:** Offer undo for an already-gone workspace.

package/guidelines/drawer.md

@@ -0,0 +1,53 @@
+# Drawers
+
+## One-record drawer
+
+<!-- rule: one-record -->
+
+**Rule:** Open a drawer to view or change one record without leaving its list.
+
+**Why:** Closing the drawer returns the user to the opened row.
+
+**Do:** Use a drawer for a short filter, a new key, or a reclassification.
+
+**Don't:** Use it for work needing an address, multiple screens, or steps; use a page instead.
+
+**Except:** Two-answer questions use confirm. Short forms fit; forms needing steps or more than one screen use a page.
+
+## Grouped content
+
+<!-- rule: no-cards -->
+
+**Rule:** Group drawer content under headings and never put a card inside it.
+
+**Why:** The drawer already provides the edge and raised surface, so cards add unnecessary boxes.
+
+**Do:** Use three groups, with a heading over each group’s rows and one line between groups.
+
+**Don't:** Put each group in a card inside the drawer.
+
+## Three divider lines
+
+<!-- rule: three-lines -->
+
+**Rule:** Draw lines under the header, over the footer, and between each group; draw no other lines.
+
+**Why:** These lines mark scrolling boundaries and separate groups, not rows.
+
+**Do:** Separate header, footer and groups.
+
+**Don't:** Add dividers between every row.
+
+## Spaced label rows
+
+<!-- rule: rows -->
+
+**Rule:** Put each value beside its label and separate rows with space.
+
+**Why:** In a drawer up to 560px wide, labels and values stay together at any zoom without row lines.
+
+**Do:** Place a short value beside its label, such as `Status — Active`.
+
+**Don't:** Put the value at the far edge and use row lines to guide the eye back.
+
+**Except:** Put figures readers compare down the panel, such as amounts, in a table using `table()` and right-align them.

package/guidelines/going-back.md

@@ -0,0 +1,77 @@
+# Going back
+
+## Link only for child pages
+
+<!-- rule: below-a-list -->
+
+**Rule:** Add a back link only when the page is under another page.
+
+**Why:** It provides the missing move from a record to its parent list.
+
+**Do:** From an invoice record, link to the invoice list.
+
+**Don't:** Add one to the Invoices sidebar section; it is not a child page.
+
+## Name the destination
+
+<!-- rule: name-it -->
+
+**Rule:** Name the destination instead of using only “Back”.
+
+**Why:** The arrow shows direction, so the words should identify the destination.
+
+**Do:** Say “Back to Invoices”, matching the sidebar spelling; hide the arrow from screen readers.
+
+**Don't:** Use “Back”, which does not identify the destination in a screen reader’s links list.
+
+**Except:** A multi-screen form may use “Back” for the previous step; that is a form button, not this link.
+
+## Link to the parent address
+
+<!-- rule: address-not-history -->
+
+**Rule:** Link to the parent’s address, preserving filters, sort and page; never use history or `javascript:`.
+
+**Why:** Addresses work with new tabs, bookmarks and sharing, while browser Back handles history.
+
+**Do:** Use `backLink()` with the parent list address and its current state.
+
+**Don't:** Use a history link that fails in a new tab or shared address.
+
+**Except:** After search or another record, still link to the parent; browser Back returns to the previous location.
+
+## Choose one navigation method
+
+<!-- rule: one-or-the-other -->
+
+**Rule:** Put one back link or trail above the title, never both.
+
+**Why:** A trail shows several levels; a back link shows one step, and `appShell()` draws only the link when both are provided.
+
+**Do:** Align the single line above the title.
+
+**Don't:** Repeat the hierarchy with both; the current page is then named three times.
+
+## Keep the section active
+
+<!-- rule: section-lit -->
+
+**Rule:** Keep the parent section active with `aria-current="true"`, not `"page"`, and use its name in the link.
+
+**Why:** The record remains in its list’s section without making the list seem like the current page; `appShell()` does this when given a back link.
+
+**Do:** Keep the sidebar row active and say “Back to Invoices”.
+
+**Don't:** Leave the section inactive or give it another name.
+
+## Keep the link quiet
+
+<!-- rule: quiet -->
+
+**Rule:** Style the back link as secondary navigation, using `--text` despite host link colours.
+
+**Why:** It appears on every record page and must not compete with the title or main action.
+
+**Do:** Use body ink, no box until pointer hover, and a size smaller than the title.
+
+**Don't:** Use two filled buttons or make leaving the record more prominent than its main action.

package/guidelines/hover-readouts.md

@@ -0,0 +1,67 @@
+# Hover readouts
+
+## Keep readouts over the page
+
+<!-- rule: overlay -->
+
+**Rule:** Show hover values beside their marks, never inside page layout.
+
+**Why:** A changing readout must not move the page.
+
+**Do:** Float the value beside a chart point, sparkline, heatmap cell, or truncated cell.
+
+**Don't:** Add a value line that grows the card and pushes content down.
+
+## Prefer above the mark
+
+<!-- rule: above-the-mark -->
+
+**Rule:** Open the readout above the mark; place it below only when space above is clipped and below has more room.
+
+**Why:** This keeps the mark and pointer approach clear while keeping the readout on-screen.
+
+**Do:** Open a readout below a tall bar near the top of a clipping region.
+
+**Don't:** Force it above until the month and value are clipped.
+
+## Give one useful comparison
+
+<!-- rule: contents -->
+
+**Rule:** Name the point, show its value, and include no more than one comparison.
+
+**Why:** Short readouts stay readable and do not cover nearby marks.
+
+**Do:** Use three short lines: point, value, one comparison.
+
+**Don't:** Wrap long text or place controls in the readout.
+
+**Except:** Match the page’s currency and precision.
+
+## Tap to open or close
+
+<!-- rule: on-touch -->
+
+**Rule:** On touch screens, tap a mark to open the readout and tap again to move or close it.
+
+**Why:** Hover is not readable under a finger.
+
+**Do:** Tap another mark to move the readout, or tap the same mark or anywhere else to close it.
+
+**Don't:** Require a hover gesture on a touch screen.
+
+**Except:** The opening tap blocks the mark’s click but still reaches page listeners; the tap that closes the readout may also drill down.
+
+## Provide another access method
+
+<!-- rule: not-only-hover -->
+
+**Rule:** Never make hover the only way to reach a value.
+
+**Why:** Pointer, focus, and tap must all support access, and Escape must dismiss the readout.
+
+**Do:** Let focus or tap open the readout, and provide the leading figure plus a table or labelled series summary.
+
+**Don't:** Require pointing at one of 365 daily points to find its value.
+
+**Except:** Touch-screen focus without a tap must support screen-reader arrival; pointer detection must support laptop mouse hover, finger or pen tap, and keyboard focus restoration. Whether chart marks should be tab stops remains undecided; the kit adds none.

package/guidelines/iconography.md

@@ -0,0 +1,57 @@
+# Iconography
+
+## Icon-only controls
+
+<!-- rule: icon-only -->
+
+**Rule:** Remove a control’s label only for an action on the closed list.
+
+**Why:** Without a legend, readers need labels for unfamiliar glyphs.
+
+**Except:** The list grows by decision, not review debate. Today: `x` (close or dismiss), `copy` (copy to clipboard), `moreHorizontal` (overflow menu), `moreVertical` (overflow menu), `chevronDown` (expand or collapse), and `chevronUp` (expand or collapse).
+
+**Do:** Show an overflow menu without words; keep the Settings label.
+
+**Don't:** Use a cog without words, even with a perfect `aria-label`.
+
+## State and action
+
+<!-- rule: meaning -->
+
+**Rule:** A circled glyph represents a state; a bare glyph represents an action.
+
+**Why:** Two meanings force readers to decide from context each time.
+
+**Except:** Most glyphs show a thing, not a state or action, including `globe`, `database`, and `layers`. This split guides component choices, not catalogue organisation.
+
+**Do:** Use `circleX` to report failure and the bare `x` to close a toast.
+
+**Don't:** Use the same `x` for two different meanings.
+
+## Preserve glyph paths
+
+<!-- rule: provenance -->
+
+**Rule:** Use the Lucide path unchanged, and state when a glyph name differs.
+
+**Why:** The shared source keeps the set consistent, while the commit records its origin.
+
+**Except:** A brand mark without a Lucide original is allowed. `github` and `linkedin` are the vendor’s own marks and belong in BRAND.
+
+**Do:** Keep the Lucide path unchanged and document a different name.
+
+**Don't:** Trace or copy a path without recording the difference.
+
+## Status stroke width
+
+<!-- rule: stroke-earns-the-bar -->
+
+**Rule:** Stroke a status glyph at 1.5 CSS px or wider, or require 4.5:1 text contrast instead of 3:1 graphic contrast.
+
+**Why:** Visible width is `stroke-width × box ÷ 24`; below 1.5 CSS px, the stroke reads as a text stem and needs 4.5:1, while above it uses WCAG 1.4.11’s 3:1 graphic bar.
+
+**Except:** Non-status glyphs, such as close buttons and chevrons, have no five-status pair to measure; their control owns their contrast.
+
+**Do:** Use a stroke at least 1.5 CSS px wide before using the 3:1 graphic contrast minimum.
+
+**Don't:** Accept a thinner status stroke at only 3:1 contrast.

package/guidelines/labels-and-titles.md

@@ -0,0 +1,79 @@
+# Labels and titles
+
+## Use body ink
+
+<!-- rule: text-ink -->
+
+**Rule:** Use body ink for all words; use size, weight and spacing for hierarchy.
+
+**Why:** Muted text can look decorative, especially at small sizes, even when contrast passes.
+
+**Do:** Use body ink at xs, sm and base; let size show hierarchy.
+
+**Don't:** Use muted ink at different sizes to show rank.
+
+## Limit muted ink
+
+<!-- rule: text-ink-exceptions -->
+
+**Rule:** Use muted or dim ink only for the three named exception classes.
+
+**Why:** A closed list prevents fading from becoming a hierarchy cue.
+
+**Do:** Use muted ink for a disabled control or empty field placeholder.
+
+**Don't:** Fade timestamps, counts or enabled actions.
+
+**Except:** Only: (1) non-word glyphs, such as arrows, chevrons or dismiss marks; (2) colour reporting off, unset, disabled or archived state; (3) a valueless slot, such as an empty field or cell placeholder. Unselected options, “No earlier figure” sentences, counts, timestamps, keyboard shortcuts, enabled actions and empty-state instructions are information, not exceptions.
+
+## Use sentence case
+
+<!-- rule: sentence-case -->
+
+**Rule:** Write every label in sentence case; never use capitals as style.
+
+**Why:** Capitals are slower to read, take more space and make labels louder than their figures.
+
+**Except:** Keep inherently capitalised words as written, including acronyms, currency codes and key names such as USD, API and Esc.
+
+**Do:** Written and shown in sentence case.
+
+**Don't:** Use all capitals, which pulls attention from the figures.
+
+## Rank card titles
+
+<!-- rule: title-rank -->
+
+**Rule:** Set a card title one rank below the page title and one above the body.
+
+**Why:** A page-sized card title divides the page, while body-sized text does not read as a title.
+
+**Do:** Use --text-2xl for the page title and --text-lg for the card title.
+
+**Don't:** Use a second h1 for the card; it creates two page titles.
+
+## Use heading levels
+
+<!-- rule: title-is-heading -->
+
+**Rule:** Make a card title a heading one level below the page title, and let the class control its appearance.
+
+**Why:** A div title is missing from the page outline.
+
+**Do:** Use the next heading level for each card.
+
+**Don't:** Put the card title in a div and make it look like a heading.
+
+**Except:** A card inside a section with its own h2 uses level 3.
+
+## Name the kind above
+
+<!-- rule: eyebrow-names-the-kind -->
+
+**Rule:** Place an eyebrow above a title to identify what kind of thing it is, never as a replacement for the title.
+
+**Why:** An eyebrow alone cannot describe the card’s content.
+
+**Do:** Use the eyebrow for the period and the title for what is shown.
+
+**Don't:** Use a label-sized eyebrow as the only title.

package/guidelines/layout-and-density.md

@@ -0,0 +1,68 @@
+# Layout and density
+
+## Use the container token
+
+<!-- rule: container -->
+
+**Rule:** Read page width from `--container`; do not write the number.
+
+**Why:** Shared tokens prevent conflicting page widths and topbar overrides.
+
+**Do:** Use one token for both kit and site.
+
+**Don't:** Put four page-width numbers in different files.
+
+
+## Use the measure token
+
+<!-- rule: measure -->
+
+**Rule:** Use `--measure`, never `--container`, for a reading column.
+
+**Why:** `--container` spans the page, while `--measure` limits text beside a sidebar.
+
+**Do:** Use `--measure` for a reading column with a sidebar.
+
+**Don't:** Treat `--container` and `--measure` as competing page widths.
+
+## Use the spacing scale
+
+<!-- rule: density -->
+
+**Rule:** Set density with the spacing scale; there is no kit-wide density mode.
+
+**Why:** The ten-step scale aligns gaps and padding without runtime density switching.
+
+**Do:** Use `--space-3` for rows inside a card.
+
+**Don't:** Set separate values such as `13px`, `9px`, `14px`, `6px`, and `17px`.
+
+**Except:** `.ui-table--dense` is component-local: use `--space-3` across and `--space-2` down inside base `--space-4`. It still uses the scale. Do not add a compact/comfortable mode, `data-density` attribute, or row-height scale.
+
+## Use panel and prose units
+
+<!-- rule: below-the-page -->
+
+**Rule:** Below the reading column, use `--panel-*` in `px` for component boxes and `--prose-*` in `ch` for text lines.
+
+**Why:** Panel tokens match component widths; prose tokens match text types.
+
+**Do:** Use panel `sm/md/lg` for 320/420/560px boxes and prose tokens for caption, lede, body, and dense text.
+
+**Don't:** Use t-shirt sizes for prose or put `ch` on a wrapper with two font sizes.
+
+**Except:** Put `ch` on the element using its font size. The centred `.ui-section-head` uses `--panel-lg` for its 40px heading and 17px copy. Keep `.ui-footer__brand` at 300px because its flex track controls wrapping.
+
+## Use the three breakpoints
+
+<!-- rule: breakpoints -->
+
+**Rule:** Use literal breakpoints of 860px, 720px or 560px.
+
+**Why:** Media queries cannot read custom properties, and adding a compiler would make published CSS less readable.
+
+**Do:** Use `@media (max-width: 860px)`.
+
+**Don't:** Use `@media (max-width: var(--panel-lg))` or add other breakpoint values.
+
+**Except:** `560` also equals `--panel-lg`, and `860` equals `--measure`, but viewport breakpoints and box widths are independent. Do not imply a link between them.

package/guidelines/microcopy.md

@@ -0,0 +1,29 @@
+# Microcopy and tone
+
+## Name the current state
+
+<!-- rule: state-not-destination -->
+
+**Rule:** Name a control for its current state, and rename it when the state changes.
+
+**Why:** A name that is correct only once becomes unhelpful later.
+
+**Do:** Name the checked switch “In-app notifications, on.”
+
+**Don't:** Name the checked switch “Turn off in-app notifications.”
+
+**Except:** An icon-only toggle may add the result: “Theme: Dark. Switch to light.”
+
+## Name every control
+
+<!-- rule: never-nameless -->
+
+**Rule:** Give every control a name, including controls without visible text.
+
+**Why:** The glyph is aria-hidden, so the label is the control’s only accessible name.
+
+**Do:** Name the button “Dismiss.”
+
+**Don't:** Leave the icon button unnamed.
+
+**Except:** An identifier is not a name: the `name` option of `segmented()` seeds a data hook and is never read aloud.

package/guidelines/motion.md

@@ -0,0 +1,53 @@
+# Motion
+
+## Move after load
+
+<!-- rule: after-load -->
+
+**Rule:** Animate anything that appears or leaves after page load.
+
+**Why:** Motion shows where content comes from; content present at load stays still.
+
+**Do:** Slide a panel in from its edge.
+
+**Don't:** Make new content appear in one frame.
+
+**Except:** Update counts, ranges, and status lines immediately.
+
+## Match duration to motion
+
+<!-- rule: durations -->
+
+**Rule:** Use 150ms for controls, 250ms for surfaces, 400ms for entrances, and 80ms (`--dur-instant`) for presses.
+
+**Why:** Use only `--dur-fast`, `--dur-med`, `--dur-slow`, and `--dur-instant` to keep one tempo.
+
+**Do:** Use the matching duration token.
+
+**Don't:** Use an unrelated duration such as 300ms.
+
+## Use the kit curves
+
+<!-- rule: easing -->
+
+**Rule:** Use `--ease` for surfaces that come and go, `--ease-out` for content that arrives and stays, and `linear` for visibility.
+
+**Why:** Visibility keeps its old value during a transition, so easing adds no benefit.
+
+**Do:** Transition visibility with `linear`.
+
+**Don't:** Use CSS `ease` instead of `--ease`.
+
+## Honor reduced motion
+
+<!-- rule: reduced -->
+
+**Rule:** When a reader asks for less motion, change immediately.
+
+**Why:** Published bundles cap animations and transitions at 0.01ms under `prefers-reduced-motion`, so focus reaches a visible control without delay.
+
+**Do:** Open drawers and confirmations without internal transitions.
+
+**Don't:** Keep a transition running after reduced motion is requested.
+
+**Except:** Spinners and skeletons also stop; the surrounding region announces the wait.

package/guidelines/overview.md

@@ -0,0 +1 @@
+# Guidelines

package/guidelines/pagination.md

@@ -0,0 +1,89 @@
+# Pagination
+
+## Use the server count
+
+<!-- rule: counted-total -->
+
+**Rule:** Use the total row count returned by the server when it is available.
+
+**Why:** Readers need accurate ranges and totals, while some APIs can only report whether more rows exist.
+
+**Do:** Show the current row range and the server’s total.
+
+**Don't:** Discard a completed `COUNT(*)` result.
+
+## Choose the main jump
+
+<!-- rule: the-jump -->
+
+**Rule:** Use steps for filtering and sorting, numbers for short lists, or jump for a specific page.
+
+**Why:** Filtering and sorting usually need quick jumps, while short lists can use numbered pages.
+
+**Except:** Use numbered pages for short browsable lists such as changelogs and galleries.
+
+**Do:** Use four fixed controls so a ledger’s first and last pages are one press away.
+
+**Don't:** On page 25 of 49, show only 1, 24, 26, and 49 as direct choices.
+
+## Disable ends in place
+
+<!-- rule: ends-disable -->
+
+**Rule:** Disable controls at each end without removing them.
+
+**Why:** Fixed controls prevent layout shifts and tell screen-reader users when they reached an end.
+
+**Do:** Keep First and Prev in place and mark them unavailable; native `disabled` removes them from Tab order.
+
+**Don't:** Remove Prev on page one and move the other controls left.
+
+## Hide one-page steps
+
+<!-- rule: one-page -->
+
+**Rule:** Do not show pagination steps when a table has one page.
+
+**Why:** One-page controls provide no action.
+
+**Do:** For 12 rows, show only the page-size control, or render nothing if no size choices exist.
+
+**Don't:** Show two permanently useless buttons.
+
+## Keep page turns stable
+
+<!-- rule: page-turn -->
+
+**Rule:** Keep controls, rows, positions, and heights stable while the next page loads.
+
+**Why:** Readers may press the same control twice during loading.
+
+**Do:** Disable the controls, mark the pager busy, and keep the range readable.
+
+**Don't:** Use a placeholder that collapses the pager or moves the next click target.
+
+## Announce only the range
+
+<!-- rule: announce-range -->
+
+**Rule:** Politely announce the complete result range, such as “1–100 of 4,812,” and nothing else.
+
+**Why:** Rows can change without moving focus, so repeating each change creates unnecessary announcements.
+
+**Except:** HTML callers that replace the pager must restore focus themselves; at an end, React restores focus to the remaining step after native `disabled` moves it to the body.
+
+**Do:** Keep focus on the pressed control and announce the new range once.
+
+**Don't:** Announce the same page change through the live region, page-size control, and every button.
+
+## Offer consumer page sizes
+
+<!-- rule: page-size -->
+
+**Rule:** Offer page sizes from 25, 50, and 100, starting at 100, and let consumers choose and persist the selection.
+
+**Why:** Consumers may need different choices and can save them in a URL or profile across reloads.
+
+**Do:** Place rows per page between the count and pagination steps.
+
+**Don't:** Force one size when readers must work through 4,812 rows.

package/guidelines/stat-bands.md

@@ -0,0 +1,39 @@
+# Stat bands
+
+## Use a stat band
+
+<!-- rule: a-band-not-a-card -->
+
+**Rule:** Put key figures in a stat band, not in a card of parts.
+
+**Why:** Each figure stays easy to compare and understand.
+
+**Do:** Use one card per figure by default, with the figure largest, an arrow, a signed change, and one comparison caption above the row.
+
+**Don't:** Use heading-sized figures with a capitalised 10px status chip and no comparison basis.
+
+## Colour by meaning
+
+<!-- rule: tone-not-direction -->
+
+**Rule:** Colour a change by whether it is good news, not by whether it rises or falls.
+
+**Why:** Direction alone does not show whether a change is beneficial.
+
+**Except:** Omitted tone and explicit “neutral” keep the arrow and comparison but use no colour for unscored volume, reader-dependent meaning, or net cashflow already explained by income less cost.
+
+**Do:** Use four verdicts: rising Income and Cost use opposite colours; falling Unclassified is green; undeclared Net cashflow stays grey.
+
+**Don't:** Colour four figures by sign, making three rises green, praising cost growth, and showing the year’s cleanup as red.
+
+## State the comparison basis
+
+<!-- rule: say-the-basis -->
+
+**Rule:** State in reachable text what each change is measured against.
+
+**Why:** Percentages need a basis that readers can find.
+
+**Do:** Put the basis once in a caption referenced by each change, or beside an individual exception; keep the caption before and outside every figure.
+
+**Don't:** Use a title attribute, put the note below the tiles, place it inside the first figure, omit the basis, or nest captions.

package/guidelines/state-set.md

@@ -0,0 +1,57 @@
+# The full state set
+
+## Focus rings
+
+<!-- rule: focus-visible -->
+
+**Rule:** Give every focusable control the same `--ring`, and show it only on `:focus-visible`.
+
+**Why:** One solid band and halo keep focus consistent while the browser decides when to show it.
+
+**Do:** Button and input share one ring.
+
+**Don't:** The input draws its own ring.
+
+**Except:** Text-entry controls may match `:focus-visible` on mouse focus. Surface backgrounds set the gap colour and recompose `--ring`; adjust width and colour at the root.
+
+## Busy controls
+
+<!-- rule: busy -->
+
+**Rule:** Make busy controls disabled: use `aria-busy` and a real disabled state from one flag.
+
+**Why:** A control that still accepts clicks can submit twice.
+
+**Do:** Set `disabled` and `aria-busy` together.
+
+**Don't:** Show “Saving…” while still accepting clicks.
+
+**Except:** Disabled controls are excluded from the WCAG 1.4.3 contrast gate, so busy controls must remain visually legible.
+
+## Marked errors
+
+<!-- rule: error-in-markup -->
+
+**Rule:** Put errors in markup, not only in paint, and connect each message to its field.
+
+**Why:** Red alone communicates the state only to sighted readers.
+
+**Do:** The field reads its reason with it.
+
+**Don't:** Use the same red with no connected reason.
+
+**Except:** Put `required` in the attribute, not the label wording; the asterisk is decoration and hidden from assistive technology.
+
+## Screen loading
+
+<!-- rule: loading -->
+
+**Rule:** Design pending state for the whole screen, not only its button, and announce it.
+
+**Why:** Silent loading gives screen-reader users no event.
+
+**Do:** Announce the coming shape in a status region.
+
+**Don't:** Let only the button know while the page reads as finished.
+
+**Except:** A toast has its own live region, so a screen reporting through the toast stack needs no second one.

package/guidelines/the-page.md

@@ -0,0 +1,123 @@
+# The page
+
+## Keep one shell
+
+<!-- rule: layout -->
+
+**Rule:** Use one shell layout throughout the product: either the rail alone or the rail with a bar above the page containing search and the reader’s menu.
+
+**Why:** Readers learn where search and account controls are once.
+
+**Do:** Use the same shell on every screen.
+
+**Don't:** Move search or the account menu between pages.
+
+## Choose content width
+
+<!-- rule: width -->
+
+**Rule:** Use the wide column for mostly tables and boards, and the centred column for mostly reading and forms.
+
+**Why:** Tables need space, while reading needs a line length readers can follow.
+
+**Do:** Show every table column at once in the wide column.
+
+**Don't:** Put the same table in the centred column when its last column goes off-screen.
+
+## Order page headings
+
+<!-- rule: head -->
+
+**Rule:** Put the way back first, then the page title and a short introduction, with everything else below.
+
+**Why:** Readers should know which page they are on before choosing filters.
+
+**Do:** Back link → title → introduction → filters.
+
+**Don't:** Put filters above the title.
+
+## Use one page title
+
+<!-- rule: one-h1 -->
+
+**Rule:** Give each page exactly one page title.
+
+**Why:** Readers using heading navigation need one clear place to land.
+
+**Do:** Use one h1 for the page.
+
+**Don't:** Use multiple page titles or none.
+
+## Follow heading levels
+
+<!-- rule: outline -->
+
+**Rule:** Use headings in order without skipping levels, and stop at h3: page, section, then group.
+
+**Why:** Skipped levels hide structure, and a fourth level usually means the page should be split.
+
+**Do:** Keep each heading level under the one above it.
+
+**Don't:** Make readers guess which content belongs together.
+
+## Emphasize one action
+
+<!-- rule: one-primary -->
+
+**Rule:** Use one filled button for the main action and give all other actions less emphasis.
+
+**Why:** Equal emphasis makes the main action unclear.
+
+**Do:** Make Create token primary, with Import agents and Export less prominent.
+
+**Don't:** Give all three actions equal emphasis.
+
+## Limit card stacks
+
+<!-- rule: stacking -->
+
+**Rule:** Stack no more than six cards, and never put cards inside other cards.
+
+**Why:** Too many cards make readers scroll past other content to find their target.
+
+**Do:** Show up to six cards.
+
+**Don't:** Show twelve cards or nest cards inside cards.
+
+## Leave pages closed
+
+<!-- rule: at-rest -->
+
+**Rule:** Show the page uncovered until the reader chooses to open something.
+
+**Why:** An overlay on arrival interrupts reading and can move keyboard focus.
+
+**Do:** Let the reader open a menu or dialog.
+
+**Don't:** Open one automatically when the page loads.
+
+## Keep table density consistent
+
+<!-- rule: density -->
+
+**Rule:** Use compact rows in every table on the page, or use compact rows in none of them.
+
+**Why:** Consistent row heights make tables feel like one page.
+
+**Do:** Use compact rows in both tables.
+
+**Don't:** Use compact rows in one table and roomy rows in another.
+
+**Except:** Use the spacing required by the busiest table.
+
+## Write a useful introduction
+
+<!-- rule: lede -->
+
+**Rule:** Keep the introduction to two sentences or fewer and add information the title does not give.
+
+**Why:** Repeating the title wastes the reader’s time.
+
+**Do:** Add useful context below “Payouts.”
+
+**Don't:** Write “This is the payouts page” below “Payouts.”

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.38.0",
+  "version": "0.39.1",
   "workspaces": [
     "react"
   ],
@@ -19,6 +19,7 @@
   },
   "exports": {
     ".": "./src/index.js",
+    "./guidelines/*": "./guidelines/*",
     "./motion": "./src/motion.js",
     "./inline": "./src/inline.js",
     "./css": "./src/index.css",
@@ -36,6 +37,7 @@
     "src",
     "!src/**/*.test.js",
     "react/dist",
+    "guidelines",
     "README.md"
   ],
   "sideEffects": [

package/react/dist/index.css

@@ -99,5 +99,9 @@
 }
 .rx-caret {
   margin-left: 2px;
+  width: 16px;
+  height: 16px;
+  flex-shrink: 0;
+  stroke-width: 2.4;
   color: var(--muted);
 }

package/react/dist/index.js

@@ -899,7 +899,23 @@ function DataTable({
     onSortChange?.(next);
     toFirstPage();
   };
-  const caret = (k) => sort.key === k ? sort.dir === 1 ? " \u25B2" : " \u25BC" : " \u2195";
+  const caret = (k) => /* @__PURE__ */ jsxs8(
+    "svg",
+    {
+      className: "rx-caret",
+      viewBox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": "true",
+      focusable: "false",
+      children: [
+        (sort.key !== k || sort.dir === 1) && /* @__PURE__ */ jsx10("path", { d: sort.key === k ? "m8 14 4-4 4 4" : "m8 9 4-4 4 4" }),
+        (sort.key !== k || sort.dir === -1) && /* @__PURE__ */ jsx10("path", { d: sort.key === k ? "m8 10 4 4 4-4" : "m8 15 4 4 4-4" })
+      ]
+    }
+  );
   const pageAllOn = selectable && slice.length > 0 && slice.every((r) => selected.has(r.name));
   return /* @__PURE__ */ jsxs8(Fragment2, { children: [
     /* @__PURE__ */ jsx10(
@@ -937,7 +953,7 @@ function DataTable({
                       "aria-sort": sort.key === c.key ? sort.dir === 1 ? "ascending" : "descending" : c.sortable && sortIsKnown ? "none" : void 0,
                       children: c.sortable ? /* @__PURE__ */ jsxs8("button", { type: "button", className: "rx-sort", onClick: () => onSort(c.key), children: [
                         c.label,
-                        /* @__PURE__ */ jsx10("span", { className: "rx-caret", "aria-hidden": "true", children: caret(c.key) })
+                        caret(c.key)
                       ] }) : c.label
                     },
                     c.key