@apliteni/apliteni-ui 0.37.1 → 0.39.0

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.