> ## Oymyakon DS index > Fetch the full index at: https://super-dollop-pzmo65r.pages.github.io/llms.txt > HTML preview: https://super-dollop-pzmo65r.pages.github.io/numeric-stepper.html > Source: specs/components/numeric-stepper/numeric-stepper.md, specs/components/numeric-stepper/numeric-stepper-a11y.md, specs/components/numeric-stepper/capabilities.json --- # NumericStepper · Oymyakon DS 3 > A value between a "−" and a "+" button — the fare the passenger offers, or a count — changed a > step at a time, or typed in through the button in the middle. **Version:** 3.2.3 · **Status:** Ready · **Figma:** `[NumericStepper] 3.2` (main components file `7vdl5YkZFDWvh9QvSmydsH`, page `18033:1471`, set `18379:2714`, key `26e079e2…`; private StartText set `18379:608`; Specification frame `18465:1511`; update frames `Update 3.1` `33509:3224` and `Update 3.2` `34461:118287`) --- ## 1. Description NumericStepper increases or decreases a value by a fixed step with the "−" and "+" buttons on its sides. The button in the middle shows the value and opens direct entry — a secondary screen or a bottom sheet where the value is typed. Its main use is the fare the passenger offers for a ride ("COL$ 120,000"); the same component also holds a count, such as passengers (owner, 2026-10-21). The value field changes its look with the **Fare State**: **Empty** asks for a value ("Tap to enter"), **Standard** shows it, three **tones** colour the field with a soft glow and an edge — **Green** (Positive), **Orange** (Warning), **Red** (Error) — and **Skeleton** holds the place while the data loads. The tones carry no meaning of their own: the screen decides what a Positive, Warning or Error value is and says it in its own text (owner, 2026-10-21). The step size, the minimum and the maximum belong to the product. At a boundary the host disables the "−" or "+" button; each side button's state is set on its own. ### Platform implementations | Platform | Entry point | Version | Notes | |---|---|---|---| | iOS | `DsNumericStepper` (DS3) | Figma 3.0 axis | `style`: `.recommended` / `.min` / `.max` / `.error` / `.static` / `.empty(placeholder:)`; `canDecrement` / `canIncrement`, `leftSquircleState` / `rightSquircleState`, `subtitle`, `trailingIcon` (the chevron), `minimumTextScaleFactor`, `onDecrement` / `onIncrement` / `onTap`; Skeleton = `.empty(placeholder: "")` + `.isLoading(true)` (manifest bindings, 2026-10-21) | | Android | `DsNumericStepper` (`core.compose.ds.v3.numeric_stepper`) | Figma 3.0 axis | `style`: `Neutral` / `Positive` / `Warning` / `Error`; `minusEnabled` / `plusEnabled`, `isSkeleton`, `onMinusClick` / `onPlusClick` / `onMainClick`; the centre is a content lambda (`PriceText`, `TapToEnter`) (manifest bindings, 2026-10-21) | | Flutter | — | — | Not shipped | | Web | `src/shared/shared.css` (`.numeric-stepper`) | 3.2.0 | Reference implementation, this repo; preview page `src/numeric-stepper.njk` | Both mobile builds still carry the Figma 3.0 Fare State values. The 3.1 update renamed them — Rec → Default (Standard here), Min → Orange, Max → Green, Error → Red — and removed Static; on the platforms the colour is the `style` and the side buttons' availability is separate data, which is the 3.1 model. --- ## 2. Anatomy ``` NumericStepper (.numeric-stepper) fill × hug · s8 padding · s4 gap ├── Decrease (.numeric-stepper__step) Squircle L, Type Icon — "minus" s24 ├── Counter (.numeric-stepper__field) customButton · fill × s56 · radius s20 · no side padding │ ├── Spacer (.numeric-stepper__spacer) s24 × s24 · empty · with the chevron only │ ├── Text (.numeric-stepper__text) fill · centred │ │ ├── Title (.numeric-stepper__title) one line · Heading 3 │ │ │ ├── Currency (.numeric-stepper__currency) optional · before or after the value │ │ │ └── Value (.numeric-stepper__value) │ │ ├── Placeholder (.numeric-stepper__placeholder) Empty only · Heading 4 · "Tap to enter" │ │ └── Subtitle (.text-row.numeric-stepper__subtitle) TextRow, Expanded · optional, off by default │ │ ├── Start slots (.text-row__slot-start-1/2) optional · IconContainer s16 │ │ ├── Text (.text-row__text) Compact Body │ │ └── End slots (.text-row__slot-end-1/2) optional · IconContainer s16 │ └── Chevron (.numeric-stepper__chevron) IconContainer s24 · "chevron-right-small" └── Increase (.numeric-stepper__step) Squircle L, Type Icon — "add" s24 ``` | Part | Required | Description | |---|---|---| | **Container** | Required | A horizontal auto-layout: fills the host's width, hugs its height; padding `s8` on all sides, gap `s4`; no fill of its own | | **Decrease** | Required | A [Squircle](https://super-dollop-pzmo65r.pages.github.io/squircle.md) L (`s56`, radius `s20`), Type Icon, with the "minus" icon (s24). Inherits the Squircle's states — Standard, Disabled, Skeleton. Here the Squircle is a **button** — an interactive host the Squircle spec does not cover (it describes a non-interactive container): ` ``` The Counter's spoken text is the visually hidden span — the label and the value with the currency in words; the visible title is hidden from assistive tech. The side buttons take the value as their description from the `hidden` span, which the product rewrites with the value. The polite live region receives the new value after a step. At a boundary the side button takes `class="… squircle--disabled"` and `aria-disabled="true"` — not `disabled`, which would drop the focus. --- ## Changelog | Version | Date | Change | |---|---|---| | 3.2.3 | 2026-11-12 | Owner rulings, and Status Draft → Ready (owner). **The side buttons are held at 100%** — box, radius and icon on `var(--sp-100-sN)`, as the frame binds them (`SP/100%`), over the Squircle L 130% cap; above 100% the Counter (72.8) stands taller than them. The container's padding and gap and the radii move onto `SP/100%` too, the Counter's vertical padding onto `SP/130%` — the families Figma binds (§ 8 no longer claims the repo lacks a fixed set). The subtitle over the Red glow (≈ 4.1–4.4:1 Day) keeps the Figma colours; the glow's `color-mix` stays until a gradient token exists. | | 3.2.2 | 2026-11-04 | Counter height capped at 130% — `var(--sp-130-s56)`, the Figma `SP/130% ratio` binding — built now that Squircle 3.5 caps the L side buttons at 130%: at SP 150 the buttons hold at 72.8 and a full-scaling Counter would have stood at 84. §8 deviation note narrowed: the side buttons follow Squircle L (130% cap, where this frame binds `SP/100%` — a Figma disagreement between the two components, flagged to the owner); the radii and container padding still scale with the mode. | | 3.2.1 | 2026-10-30 | § 6: the pressed overlay is named as the one press token, the effect style `State/PressedStateOverlay` = `var(--shadow-pressed)` — it pointed at `Surface/PressedOverlay`, which is not used on the web (flagged in color-rules 3.5.2). No change to the build. | | 3.2.0 | 2026-10-21 | Initial spec, from the Figma `[NumericStepper] 3.2` set in the main components file (page `18033:1471`, set `18379:2714`), its Specification frame (`18465:1511`) and the `Update 3.1` / `Update 3.2` frames. Two Squircle L side buttons ("minus" / "add") around a customButton Counter (fill × `s56`, radius `s20`, `Surface/OnWhite`); container padding `s8`, gap `s4`. Fare State Standard (Figma Default) · Empty ("Tap to enter", Heading 4, `TextAndIcon/Secondary`) · Green / Orange / Red (the Positive / Warning / Error tones: a radial glow of `Pastel/Green1` / `Pastel/Orange1` / `Pastel/Red2` at 60% and a 1dp radial edge of `Border/Success` / `Warning` / `Error`, both centred on the bottom edge; Red paints the value `TextAndIcon/Error`) · Skeleton; the Fare State sets the side buttons' default states, the host changes each on its own. Title = currency + value in Heading 3 split by a hair space (`s2`), the currency before or after the value, none for a count; optional Subtitle — a TextRow in Expanded mode (Compact Body, `TextAndIcon/Secondary`, off by default) with up to two `s16` icons on each side in its slots, a colour icon keeping its own colours; optional chevron (on by default) balanced by an empty `s24` spacer at the Counter's start, so the text stays centred. RTL mirrors the row and the chevron, the title keeps its order. Press = `pushHighlight` (the pressed overlay, no scale). A11y spec reworked for the generic value — a fare or a count — with Empty, Skeleton, the tones and the post-step announcement. Owner rulings (2026-10-21): its own sidebar page; the tones are Positive / Warning / Error with no business meaning of their own; the component also holds a count; press feedback `pushHighlight`. Figma flags: the frame calls the first state "Default" (kept — owner, 2026-10-21); its Layout calls the horizontal paddings "vertical"; "Suiqrcle" typo (not urgent — owner); Empty's Heading 4 is bound to the "(Don't use) s17" size token; the Counter binds `SP/130% ratio`, the side buttons `SP/100%`; the glow's paint opacity sits on an alpha token in Night. Both mobile builds ship the Figma 3.0 axis (Rec / Min / Max / Error / Static). Spec-reviewer (0 critical, 1 high, 4 medium) and a11y-reviewer (0 critical, 2 high, 7 medium) passes folded in before release: the value lives on the root only (`data-ds-value`); the nested TextRow carries no `data-ds-*`; Standard first on the page; the Squircle-as-button exception recorded; a limit is said ("…, maximum" / "minimum", repeated on a tap at the limit); the web side buttons take the spoken value as their description from a `hidden` span; direct entry returns the focus to the Counter; iOS hints in Apple's idiom (none on −/+, "Opens [item] entry" on the Counter); TalkBack reads the step from the focused button's state change, the Counter is not a live region (to verify on device); the skeleton's "Loading" is a status node without `aria-busy`. Flagged for the owner: the Subtitle over the Red glow ≈ 4.1–4.4:1 (below 4.5); the Usage example's `TextAndIcon/Success` message ≈ 3.8:1 on `Background/Primary`; the gradient geometry has no DS token. Figma updated by the agent on the owner's ask (2026-10-21, not published): the `[NumericStepper] 3.2` set gets its description; the Specification frame's Accessibility block is rewritten to the a11y spec (generic `[Item]` / `[value]`, the step's hint without "by one", "Dimmed" on iOS, Apple-style iOS hints, a new Edge states point per platform), its two canvases re-pointed from a deleted `NumericStepper/Static/Off` instance to `[NumericStepper] 3.2` Default (Android "+" / iOS "−" disabled), and the frame grown 13273 → 15453 to fit. | --- # NumericStepper — Accessibility NumericStepper has **three tap targets**, each its own focusable button with its own announcement: **Decrease** ("−"), the **Counter** in the middle, and **Increase** ("+"). The Counter is not read-only text — it opens direct entry, a secondary screen or a bottom sheet where the value is typed. "−" and "+" are announced by their meaning — "Decrease" / "Increase" — never as symbols. **One component, two kinds of value** (owner, 2026-10-21). The same stepper holds a fare or a count; the screen supplies the words: - `[Item]` — what the value is, from the screen: *Fare*, *Passengers*, *Seats*. With no domain label the product falls back to "Quantity". - `[value]` — the current value **as it is spoken**: a fare with its currency in words — "120,000 Colombian pesos", never "C O L dollar 120 000" — or a count, "3". The product's formatter supplies the spoken form next to the visible one ("COL$ 120,000"). | Use | Visible | Decrease | Counter | Increase | |---|---|---|---|---| | Fare | COL$ 120,000 | "Decrease fare, 120,000 Colombian pesos" | "Fare, 120,000 Colombian pesos" | "Increase fare, 120,000 Colombian pesos" | | Count | 3 | "Decrease passengers, 3" | "Passengers, 3" | "Increase passengers, 3" | **The step is the product's.** A tap moves the value by the step the product sets — a fare moves by a currency step, a count by one — so the hint names the action, not the amount: "Double-tap to decrease", not "… by one". **The new value is announced right after a step**, while focus stays on "−" or "+": the person never has to move to the Counter to hear what the tap did. **A limit is said, not only shown**: a step that lands on the minimum or the maximum adds the product's limit word — "130,000 Colombian pesos, maximum" — and a tap on a disabled side button repeats that phrase, so a press is never silent. **Direct entry.** The Counter opens a sheet or a screen titled "[Item]"; its input is labelled "[Item]". On dismiss the focus returns to the Counter, and its name — "[Item], [value]" — reads the committed value once; no live announcement on top of it. **Voice control.** The visible text is not in the accessible name word for word ("COL$" is read "Colombian pesos"), but the number is — "Tap 120,000" works. iOS adds `accessibilityInputLabels(["[Item]", visible value])` to the Counter; on the web and Android the spoken name carries the visible number. --- ## Android · TalkBack | Element | Label | Value | Trait | Hint | |---|---|---|---|---| | Decrease | "Decrease [Item]" — `contentDescription` | `[value]` — `stateDescription` | Button — `Role.Button` | "Double-tap to decrease." — `onClick(label = "decrease")` | | Counter | "[Item]" — `contentDescription` | `[value]`, or "Not set" in Empty — `stateDescription` | Button — `Role.Button` | "Double-tap to edit." — `onClick(label = "edit")` | | Increase | "Increase [Item]" — `contentDescription` | `[value]` — `stateDescription` | Button — `Role.Button` | "Double-tap to increase." — `onClick(label = "increase")` | | Icons, spacer, chevron, tone glow and edge | — | — | Decorative — not nodes | — | Voiced previews: - Decrease: "Decrease fare, 120,000 Colombian pesos, Button, Double-tap to decrease." - Counter: "Fare, 120,000 Colombian pesos, Button, Double-tap to edit." - Increase: "Increase passengers, 3, Button, Double-tap to increase." ### Edge states - **After a step:** each step button's `stateDescription` follows the value, and TalkBack speaks a changed state of the focused node — the new value is read while focus stays on the step button. The Counter is **not** a live region: with both, the value would be read twice. (Verify on device; if a build does not voice the state change, the fallback is a polite live region on the Counter with the step buttons' `stateDescription` left unchanged until the next focus.) - **At a limit:** the step that lands on it reads "[value], maximum" (or "minimum") — the product's words; a double-tap on the now disabled button re-reads that phrase. - **Boundary — a disabled side button:** `enabled = false` (`disabled()` semantics). TalkBack appends "Disabled" and drops the hint: "Increase fare, 999,000 Colombian pesos, Button, Disabled." A double-tap does nothing. The Counter stays enabled at a boundary — it still opens direct entry. - **Empty:** the Counter reads "[Item], Not set, Button, Double-tap to edit."; the visible "Tap to enter" is not read — it is a touch instruction. Both side buttons are Disabled by default. - **Subtitle:** its text joins the Counter's `stateDescription` after the value, in words — "Fare, 120,000 Colombian pesos, was 200,000 Colombian pesos". Its slot icons are decorative; an icon that carries meaning the text does not gets a word in that phrase from the screen. - **Tones (Green / Orange / Red):** the colour is never announced and never the only signal. The screen's own message about the value — the text near the stepper — is appended to the value: the Counter's `stateDescription` on Android, its `accessibilityValue` on iOS, `aria-describedby` on the web. A step that changes the tone announces the new message with the new value. - **Skeleton:** not announced, not focusable — `clearAndSetSemantics {}` on the shapes; the loading container announces once, politely. When the value lands, it is read in place, not announced on its own. - **RTL:** the row mirrors ("+" left, "−" right); the semantic order stays Decrease, Counter, Increase, and TalkBack follows the reading direction, so the button on the right — Decrease — is first. The labels are semantic, not positional, and do not change. - **Text scaling:** the Title caps at 130%; the Placeholder and the Subtitle scale to 150%, the DS maximum. --- ## iOS · VoiceOver | Element | Label | Value | Trait | Hint | |---|---|---|---|---| | Decrease | "Decrease [Item]" — `accessibilityLabel` | `[value]` — `accessibilityValue` | `.button` | — the label says it; no hint | | Counter | "[Item]" — `accessibilityLabel` | `[value]`, or "Not set" in Empty — `accessibilityValue` | `.button` | "Opens [item] entry." — `accessibilityHint` | | Increase | "Increase [Item]" — `accessibilityLabel` | `[value]` — `accessibilityValue` | `.button` | — the label says it; no hint | | Icons, spacer, chevron, tone glow and edge | — | — | Decorative — `accessibilityHidden(true)` | — | Voiced previews: - Decrease: "Decrease fare, 120,000 Colombian pesos, Button." - Counter: "Fare, 120,000 Colombian pesos, Button. Opens fare entry." - Increase: "Increase passengers, 3, Button." Apple's hint idiom — a verb phrase that describes the result, never the gesture — so it holds for Switch Control and Voice Control too. TalkBack's "Double-tap to …" is generated by the system from the `onClick` label; iOS reads `accessibilityHint` verbatim. ### Edge states - **After a step:** the new value is posted as an announcement (`UIAccessibility.post(notification: .announcement, argument:)`; SwiftUI `AccessibilityNotification.Announcement`) while focus stays on the step button; every element's `accessibilityValue` follows the value. - **Boundary — a dimmed side button:** `.notEnabled` — VoiceOver appends "Dimmed": "Decrease fare, 110,000 Colombian pesos, Dimmed, Button." It stays in navigation; a double-tap does nothing but re-posts the limit phrase. The Counter stays enabled. - **At a limit:** the announcement after the step that lands on it is "[value], maximum" (or "minimum"). - **Empty:** the Counter reads "[Item], Not set, Button. Opens [item] entry."; the visible "Tap to enter" is not read. Both side buttons are Dimmed by default. - **Subtitle:** as on Android — its text joins the Counter's `accessibilityValue` after the value; the slot icons are decorative unless the screen gives them a word. - **Tones:** as on Android — the screen's message is appended to the Counter's `accessibilityValue`, after the value, and a step that changes the tone announces the new message. - **Skeleton:** `accessibilityHidden(true)` on the shapes (`.isLoading(true)` alone does not hide them); the loading container announces once. - **RTL / Dynamic Type:** as on Android. --- ## Web preview (reference) - **Three `