@apliteni/apliteni-ui 0.37.1 → 0.39.0

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.37.1",
+  "version": "0.39.0",
   "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": [