al-design-system 1.3.0 → 1.4.0

package/README.md

@@ -10,7 +10,7 @@ An open-source design system, from Figma to code. Plain CSS, a little vanilla Ja
 
 ## What it is
 
-- **Foundation + 26 components**, designed in Figma and coded from the same tokens.
+- **Foundation + 27 components**, designed in Figma and coded from the same tokens.
 - **Light and dark themes** built in. It follows the operating system by default, and you can force one.
 - **Accessibility is checked by the build.** Every rendered combination (variant × state × theme) is measured for contrast against the background it actually sits on, and each component's markup contract is verified. If something fails, the build stops.
 - **Nothing is typed by hand.** Tokens, CSS variables, `tokens.json` and the documentation tables are all generated from one source.
@@ -32,6 +32,7 @@ An open-source design system, from Figma to code. Plain CSS, a little vanilla Ja
 | | Input | | [guidelines](src/components/input/guidelines.md) |
 | | Textarea | | [guidelines](src/components/textarea/guidelines.md) |
 | | Password | ✓ | [guidelines](src/components/password/guidelines.md) |
+| | Number field | ✓ | [guidelines](src/components/number-field/guidelines.md) |
 | Structure and overlays | Divider | | [guidelines](src/components/divider/guidelines.md) |
 | | Card | | [guidelines](src/components/card/guidelines.md) |
 | | Tab | ✓ | [guidelines](src/components/tab/guidelines.md) |
@@ -57,7 +58,7 @@ npm install al-design-system
 Or straight from a CDN, pinned to a version:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/al-design-system@1.3.0/dist/al.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/al-design-system@1.4.0/dist/al.css">
 ```
 
 Each [GitHub Release](https://github.com/guilhermedworakowski/al-design-system/releases) also carries the `dist/` folder as a zip.
@@ -66,10 +67,10 @@ Each [GitHub Release](https://github.com/guilhermedworakowski/al-design-system/r
 
 | File | What it is |
 |---|---|
-| `al.css` | Foundation + all 26 components, in one file |
+| `al.css` | Foundation + all 27 components, in one file |
 | `foundation.css` | Only the Foundation: color, typography, spacing, radius, icon size, elevation, focus ring and motion |
 | `components/<name>.css` | One component (its tokens + its CSS) |
-| `components/<name>.js` | The behavior, for the 9 components that have a script |
+| `components/<name>.js` | The behavior, for the 10 components that have a script |
 | `icons/*.svg`, `icons/icons.json` | The 70 icons |
 | `tokens.json` | The Foundation tokens, to read from code |
 
@@ -100,7 +101,7 @@ The exact markup of each component (which element, which attributes) is describe
 
 ### Scripts
 
-Password, Tab, Modal, Drawer, Sidebar, Breadcrumb, Tooltip, Toast and Alert need their script, loaded once per page. Each one wires up the components already on the page by itself:
+Password, Number field, Tab, Modal, Drawer, Sidebar, Breadcrumb, Tooltip, Toast and Alert need their script, loaded once per page. Each one wires up the components already on the page by itself:
 
 ```html
 <script src="node_modules/al-design-system/dist/components/modal.js" defer></script>

package/README.pt-BR.md

@@ -10,7 +10,7 @@ Design system open source, do Figma ao código. CSS puro, um pouco de JavaScript
 
 ## O que é
 
-- **Foundation + 26 componentes**, desenhados no Figma e codados a partir dos mesmos tokens.
+- **Foundation + 27 componentes**, desenhados no Figma e codados a partir dos mesmos tokens.
 - **Temas claro e escuro** já incluídos. Por padrão segue o sistema operacional, e dá para forçar um.
 - **A acessibilidade é conferida no build.** Cada combinação renderizada (variante × estado × tema) tem o contraste medido contra o fundo onde ela realmente aparece, e o contrato de marcação de cada componente é verificado. Se algo reprova, o build para.
 - **Nada é digitado à mão.** Tokens, variáveis CSS, `tokens.json` e as tabelas da documentação saem todos de uma fonte só.
@@ -32,6 +32,7 @@ Design system open source, do Figma ao código. CSS puro, um pouco de JavaScript
 | | Input | | [diretrizes](src/components/input/guidelines.md) |
 | | Textarea | | [diretrizes](src/components/textarea/guidelines.md) |
 | | Password | ✓ | [diretrizes](src/components/password/guidelines.md) |
+| | Number field | ✓ | [diretrizes](src/components/number-field/guidelines.md) |
 | Estrutura e sobreposição | Divider | | [diretrizes](src/components/divider/guidelines.md) |
 | | Card | | [diretrizes](src/components/card/guidelines.md) |
 | | Tab | ✓ | [diretrizes](src/components/tab/guidelines.md) |
@@ -57,7 +58,7 @@ npm install al-design-system
 Ou direto de uma CDN, fixado numa versão:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/al-design-system@1.3.0/dist/al.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/al-design-system@1.4.0/dist/al.css">
 ```
 
 Cada [Release no GitHub](https://github.com/guilhermedworakowski/al-design-system/releases) também traz a pasta `dist/` num zip.
@@ -66,10 +67,10 @@ Cada [Release no GitHub](https://github.com/guilhermedworakowski/al-design-syste
 
 | Arquivo | O que é |
 |---|---|
-| `al.css` | Foundation + os 26 componentes, num arquivo só |
+| `al.css` | Foundation + os 27 componentes, num arquivo só |
 | `foundation.css` | Só a Foundation: cor, tipografia, espaçamento, radius, tamanho de ícone, elevação, anel de foco e motion |
 | `components/<nome>.css` | Um componente (os tokens + o CSS dele) |
-| `components/<nome>.js` | O comportamento, para os 9 componentes que têm script |
+| `components/<nome>.js` | O comportamento, para os 10 componentes que têm script |
 | `icons/*.svg`, `icons/icons.json` | Os 70 ícones |
 | `tokens.json` | Os tokens da Foundation, para ler por código |
 
@@ -100,7 +101,7 @@ A marcação exata de cada componente (qual elemento, quais atributos) está des
 
 ### Scripts
 
-Password, Tab, Modal, Drawer, Sidebar, Breadcrumb, Tooltip, Toast e Alert precisam do script, carregado uma vez por página. Cada um liga sozinho os componentes que já estão na página:
+Password, Number field, Tab, Modal, Drawer, Sidebar, Breadcrumb, Tooltip, Toast e Alert precisam do script, carregado uma vez por página. Cada um liga sozinho os componentes que já estão na página:
 
 ```html
 <script src="node_modules/al-design-system/dist/components/modal.js" defer></script>

package/dist/al.css

@@ -1,8 +1,8 @@
-/* AL Design System 1.3.0 - Foundation + 26 components.
+/* AL Design System 1.4.0 - Foundation + 27 components.
  * MIT. https://github.com/guilhermedworakowski/al-design-system
  */
 /* AL Design System - Foundation
- * v1.3.0 - MIT
+ * v1.4.0 - MIT
  * GENERATED by src/foundation/css.py. Do not edit by hand: run the script.
  */
 
@@ -7243,3 +7243,367 @@
     outline-offset: var(--al-border-focus-offset);
   }
 }
+
+/* AL Design System - Number field tokens
+ * GENERATED by src/components/number-field/tokens.py. Do not edit by hand.
+ *
+ * There is no theme block here: each token points to a semantic, and the
+ * theme switches on :root - the same element where these aliases are declared.
+ *
+ * Field height: 48px, derived, no token.
+ * Stepper target: 24px = icon-size, no token of its own.
+ */
+
+:root {
+
+  /* background - only disabled and readonly change it */
+  --al-number-field-bg: var(--al-bg-surface-raised);
+  --al-number-field-bg-disabled: var(--al-bg-disabled);
+  --al-number-field-bg-readonly: var(--al-bg-subtle);
+
+  /* border - the axis that carries the state */
+  --al-number-field-border: var(--al-border-default);
+  --al-number-field-border-hover: var(--al-border-strong);
+  --al-number-field-border-focus: var(--al-border-brand);
+  --al-number-field-border-error: var(--al-border-danger);
+  --al-number-field-border-disabled: var(--al-border-default);
+  --al-number-field-border-readonly: var(--al-border-subtle);
+
+  /* value - no placeholder, the field always has a value */
+  --al-number-field-text-value: var(--al-text-primary);
+  --al-number-field-text-disabled: var(--al-text-disabled);
+
+  /* steppers - out of the Tab order, no hover or ring of their own */
+  --al-number-field-stepper-icon: var(--al-text-primary);
+  --al-number-field-stepper-icon-disabled: var(--al-text-disabled);
+
+  /* label, mark and help - they live outside the field, on the canvas */
+  --al-number-field-label: var(--al-text-primary);
+  --al-number-field-label-error: var(--al-text-danger);
+  --al-number-field-label-disabled: var(--al-text-disabled);
+  --al-number-field-optional: var(--al-text-secondary);
+  --al-number-field-help: var(--al-text-secondary);
+  --al-number-field-help-error: var(--al-text-danger);
+
+  /* focus ring - points to the composite shadow, not the raw color */
+  --al-number-field-ring: var(--al-focus-ring-default);
+  --al-number-field-ring-error: var(--al-focus-ring-error);
+
+  /* geometry */
+  --al-number-field-padding-x: var(--al-space-12);
+  --al-number-field-padding-y: var(--al-space-12);
+  --al-number-field-gap: var(--al-space-8);
+  --al-number-field-stepper-gap: var(--al-space-24);
+  --al-number-field-radius: var(--al-radius-lg);
+  --al-number-field-border-width: var(--al-border-width-1);
+  --al-number-field-icon-size: var(--al-icon-size-24);
+
+  /* width of the box - declared literal, the Foundation has no width scale */
+  --al-number-field-width: 140px;
+
+  /* typography - one style becomes four vars */
+  --al-number-field-font-size: var(--al-font-size-md);
+  --al-number-field-line-height: var(--al-line-height-md);
+  --al-number-field-font-weight: 400;
+  --al-number-field-tracking: 0em;
+  --al-number-field-label-font-size: var(--al-font-size-md);
+  --al-number-field-label-line-height: var(--al-line-height-md);
+  --al-number-field-label-font-weight: 400;
+  --al-number-field-label-tracking: 0em;
+  --al-number-field-optional-font-size: var(--al-font-size-sm);
+  --al-number-field-optional-line-height: var(--al-line-height-sm);
+  --al-number-field-optional-font-weight: 400;
+  --al-number-field-optional-tracking: 0em;
+  --al-number-field-help-font-size: var(--al-font-size-xs);
+  --al-number-field-help-line-height: var(--al-line-height-xs);
+  --al-number-field-help-font-weight: 400;
+  --al-number-field-help-tracking: 0.01em;
+}
+
+/* AL Design System - Number field
+ *
+ * Depends on: foundation/al-foundation.css
+ *           + components/number-field/al-number-field-tokens.css
+ *           + components/icon/icon.css
+ *           + components/number-field/number-field.js (the steppers)
+ *
+ * A QUANTITY THE PERSON ADJUSTS A LITTLE AT A TIME
+ *   A native <input type="number"> between a - and a + button. Numbers that
+ *   are not quantities (zip code, phone, card) are the Input with
+ *   inputmode="numeric" - rule 2.
+ *
+ * ANATOMY
+ *   <div class="al-number-field">
+ *     <div class="al-number-field__labelrow">
+ *       <label class="al-number-field__label" for="qty">Quantity</label>
+ *       <span class="al-number-field__optional">(Optional)</span>
+ *     </div>
+ *     <div class="al-number-field__control">
+ *       <button class="al-number-field__step" type="button" tabindex="-1"
+ *               data-step="down" aria-controls="qty"
+ *               aria-label="Decrease quantity" hidden>
+ *         <svg class="al-icon" aria-hidden="true" focusable="false">minus</svg>
+ *       </button>
+ *       <input class="al-number-field__field" id="qty" type="number"
+ *              min="1" max="10" step="1" value="1"
+ *              aria-describedby="qty-help">
+ *       <button class="al-number-field__step" type="button" tabindex="-1"
+ *               data-step="up" aria-controls="qty"
+ *               aria-label="Increase quantity" hidden>
+ *         <svg class="al-icon" aria-hidden="true" focusable="false">plus</svg>
+ *       </button>
+ *     </div>
+ *     <p class="al-number-field__help" id="qty-help">From 1 to 10</p>
+ *   </div>
+ *
+ * THE STEPPERS ARE OUT OF THE TAB ORDER
+ *   One tab stop: the arrow keys and typing change the value (Carbon, rule
+ *   13). So the buttons carry tabindex="-1", have no ring and no hover of
+ *   their own (rule 14) - the field's border and ring say where pointer and
+ *   focus are. They are born `hidden`: without JavaScript the arrow keys
+ *   still work and a button that does nothing never shows (the same as the
+ *   Password's eye).
+ *
+ * THE STEPPER AT THE LIMIT IS A DISABLED <button>
+ *   At the minimum the - is `disabled`, at the maximum the + (rule 10). The
+ *   JS sets the attribute; the CSS only reads `:disabled`. There is no Figma
+ *   variant for it.
+ *
+ * THE BOX IS `__control`, NOT THE <input>
+ *   The same as the Input: border, background, radius and ring live on
+ *   `__control` and the state is read through `:has()`. Without `:has()` the
+ *   native outline stays (it is only removed inside @supports).
+ *
+ * THE STATE IS DRIVEN BY THE MARKUP
+ *   Error reads `aria-invalid="true"`; disabled `:disabled`; read-only
+ *   `[readonly]` - never `:read-only`, which also matches disabled. The same
+ *   precedence by variable as the Input: error, read-only, disabled in file
+ *   order, disabled wins over all.
+ *
+ * READ-ONLY HAS NO STEPPERS (rule 17)
+ *   Nothing can change, so they are hidden and the value stays centered.
+ *
+ * THE BROWSER'S OWN SPINNERS ARE HIDDEN
+ *   WebKit draws arrows inside type=number and Firefox draws its own. With
+ *   AL's buttons there would be two pairs.
+ *
+ * HEIGHT AND WIDTH
+ *   48 = padding-y x2 + line height, border subtracted from the padding.
+ *   The box is fixed at `--al-number-field-width` (140), decided on
+ *   2026-10-21. Label and help text are not limited by it - they may be
+ *   wider than the box.
+ *
+ * HANDWRITTEN. The tokens it consumes are generated by tokens.py.
+ */
+
+/* ---------------------------------------------------------------- root */
+.al-number-field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--al-number-field-gap);
+}
+
+/* ------------------------------------------------------------ label */
+.al-number-field__labelrow {
+  display: flex;
+  align-items: baseline;
+  gap: var(--al-number-field-gap);
+}
+
+.al-number-field__label {
+  color: var(--al-number-field-label);
+  font-family: var(--al-font-sans);
+  font-size: var(--al-number-field-label-font-size);
+  line-height: var(--al-number-field-label-line-height);
+  font-weight: var(--al-number-field-label-font-weight);
+  letter-spacing: var(--al-number-field-label-tracking);
+}
+
+.al-number-field__optional {
+  color: var(--al-number-field-optional);
+  font-family: var(--al-font-sans);
+  font-size: var(--al-number-field-optional-font-size);
+  line-height: var(--al-number-field-optional-line-height);
+  font-weight: var(--al-number-field-optional-font-weight);
+  letter-spacing: var(--al-number-field-optional-tracking);
+}
+
+/* --------------------------------------------------------------- box */
+.al-number-field__control {
+  --_border-state: var(--al-number-field-border);
+
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  gap: var(--al-number-field-stepper-gap);
+  width: var(--al-number-field-width);
+
+  padding: calc(var(--al-number-field-padding-y) - var(--al-number-field-border-width))
+           calc(var(--al-number-field-padding-x) - var(--al-number-field-border-width));
+
+  border: var(--al-number-field-border-width) solid
+          var(--_border-force, var(--_border-state));
+  border-radius: var(--al-number-field-radius);
+  background-color: var(--_bg-force, var(--al-number-field-bg));
+  cursor: text;
+
+  transition:
+    border-color var(--al-motion-duration-feedback) var(--al-motion-easing-exit),
+    box-shadow var(--al-motion-duration-feedback) var(--al-motion-easing-exit);
+}
+
+/* ------------------------------------------------------------- field */
+.al-number-field__field {
+  --_text-state: var(--al-number-field-text-value);
+
+  flex: 1 1 0;
+  min-width: 0;
+  width: 100%;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--_text-force, var(--_text-state));
+  text-align: center;
+
+  font-family: var(--al-font-sans);
+  font-size: var(--al-number-field-font-size);
+  line-height: var(--al-number-field-line-height);
+  font-weight: var(--al-number-field-font-weight);
+  letter-spacing: var(--al-number-field-tracking);
+  font-variant-numeric: tabular-nums;
+
+  -moz-appearance: textfield;
+  appearance: textfield;
+}
+
+/* the browser's own spinners - see the header */
+.al-number-field__field::-webkit-inner-spin-button,
+.al-number-field__field::-webkit-outer-spin-button {
+  -webkit-appearance: none;
+  margin: 0;
+}
+
+@supports selector(:has(*)) {
+  .al-number-field__field:focus {
+    outline: none;
+  }
+}
+
+/* --------------------------------------------------------- the steppers */
+.al-number-field__step {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+
+  box-sizing: border-box;
+  width: var(--al-number-field-icon-size);
+  height: var(--al-number-field-icon-size);
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: none;
+  /* the svg inherits from here through currentColor - the Icon contract */
+  color: var(--al-number-field-stepper-icon);
+
+  cursor: pointer;
+  -webkit-appearance: none;
+  appearance: none;
+  -webkit-tap-highlight-color: transparent;
+}
+
+/* `display` above would beat the attribute - without JS the buttons don't show */
+.al-number-field__step[hidden] {
+  display: none;
+}
+
+.al-number-field__step > svg {
+  display: block;
+  flex: none;
+  width: var(--al-number-field-icon-size);
+  height: var(--al-number-field-icon-size);
+}
+
+/* at the limit, and in a disabled field - rule 10 */
+.al-number-field__step:disabled {
+  color: var(--al-number-field-stepper-icon-disabled);
+  cursor: not-allowed;
+}
+
+/* ------------------------------------------------------------ help text */
+.al-number-field__help {
+  color: var(--al-number-field-help);
+  font-family: var(--al-font-sans);
+  font-size: var(--al-number-field-help-font-size);
+  line-height: var(--al-number-field-help-line-height);
+  font-weight: var(--al-number-field-help-font-weight);
+  letter-spacing: var(--al-number-field-help-tracking);
+  margin: 0;
+}
+
+/* -------------------------------------------------------------- states */
+.al-number-field__control:hover:not(:has(.al-number-field__field:disabled, .al-number-field__field[readonly])) {
+  --_border-state: var(--al-number-field-border-hover);
+}
+
+.al-number-field__control:has(.al-number-field__field:focus-visible) {
+  --_border-state: var(--al-number-field-border-focus);
+  box-shadow: var(--_ring-force, var(--al-number-field-ring));
+}
+
+/* error - beats hover and focus by writing to another property */
+.al-number-field__control:has(.al-number-field__field[aria-invalid="true"]) {
+  --_border-force: var(--al-number-field-border-error);
+  --_ring-force: var(--al-number-field-ring-error);
+}
+
+.al-number-field:has(.al-number-field__field[aria-invalid="true"]) .al-number-field__label {
+  color: var(--al-number-field-label-error);
+}
+
+.al-number-field:has(.al-number-field__field[aria-invalid="true"]) .al-number-field__help {
+  color: var(--al-number-field-help-error);
+}
+
+/* read-only - `[readonly]`, never `:read-only`. No steppers - rule 17. */
+.al-number-field__control:has(.al-number-field__field[readonly]) {
+  --_border-force: var(--al-number-field-border-readonly);
+  --_bg-force: var(--al-number-field-bg-readonly);
+  cursor: default;
+}
+
+.al-number-field__control:has(.al-number-field__field[readonly]) .al-number-field__step {
+  display: none;
+}
+
+/* disabled - last, because it wins over all */
+.al-number-field__control:has(.al-number-field__field:disabled) {
+  --_border-force: var(--al-number-field-border-disabled);
+  --_bg-force: var(--al-number-field-bg-disabled);
+  cursor: not-allowed;
+}
+
+.al-number-field__field:disabled {
+  --_text-force: var(--al-number-field-text-disabled);
+  cursor: not-allowed;
+}
+
+.al-number-field:has(.al-number-field__field:disabled) .al-number-field__label,
+.al-number-field:has(.al-number-field__field:disabled) .al-number-field__optional {
+  color: var(--al-number-field-label-disabled);
+}
+
+/* ENTER - CSS uses the curve of the state the transition goes to. */
+.al-number-field__control:hover,
+.al-number-field__control:has(.al-number-field__field:focus-visible),
+.al-number-field__control:has(.al-number-field__field[aria-invalid="true"]) {
+  transition-timing-function: var(--al-motion-easing-enter);
+}
+
+/* --------------------------------------------------------- environment */
+@media (prefers-reduced-motion: reduce) {
+  .al-number-field__control {
+    transition: none;
+  }
+}

package/dist/components/number-field.css

@@ -0,0 +1,363 @@
+/* AL Design System - Number field tokens
+ * GENERATED by src/components/number-field/tokens.py. Do not edit by hand.
+ *
+ * There is no theme block here: each token points to a semantic, and the
+ * theme switches on :root - the same element where these aliases are declared.
+ *
+ * Field height: 48px, derived, no token.
+ * Stepper target: 24px = icon-size, no token of its own.
+ */
+
+:root {
+
+  /* background - only disabled and readonly change it */
+  --al-number-field-bg: var(--al-bg-surface-raised);
+  --al-number-field-bg-disabled: var(--al-bg-disabled);
+  --al-number-field-bg-readonly: var(--al-bg-subtle);
+
+  /* border - the axis that carries the state */
+  --al-number-field-border: var(--al-border-default);
+  --al-number-field-border-hover: var(--al-border-strong);
+  --al-number-field-border-focus: var(--al-border-brand);
+  --al-number-field-border-error: var(--al-border-danger);
+  --al-number-field-border-disabled: var(--al-border-default);
+  --al-number-field-border-readonly: var(--al-border-subtle);
+
+  /* value - no placeholder, the field always has a value */
+  --al-number-field-text-value: var(--al-text-primary);
+  --al-number-field-text-disabled: var(--al-text-disabled);
+
+  /* steppers - out of the Tab order, no hover or ring of their own */
+  --al-number-field-stepper-icon: var(--al-text-primary);
+  --al-number-field-stepper-icon-disabled: var(--al-text-disabled);
+
+  /* label, mark and help - they live outside the field, on the canvas */
+  --al-number-field-label: var(--al-text-primary);
+  --al-number-field-label-error: var(--al-text-danger);
+  --al-number-field-label-disabled: var(--al-text-disabled);
+  --al-number-field-optional: var(--al-text-secondary);
+  --al-number-field-help: var(--al-text-secondary);
+  --al-number-field-help-error: var(--al-text-danger);
+
+  /* focus ring - points to the composite shadow, not the raw color */
+  --al-number-field-ring: var(--al-focus-ring-default);
+  --al-number-field-ring-error: var(--al-focus-ring-error);
+
+  /* geometry */
+  --al-number-field-padding-x: var(--al-space-12);
+  --al-number-field-padding-y: var(--al-space-12);
+  --al-number-field-gap: var(--al-space-8);
+  --al-number-field-stepper-gap: var(--al-space-24);
+  --al-number-field-radius: var(--al-radius-lg);
+  --al-number-field-border-width: var(--al-border-width-1);
+  --al-number-field-icon-size: var(--al-icon-size-24);
+
+  /* width of the box - declared literal, the Foundation has no width scale */
+  --al-number-field-width: 140px;
+
+  /* typography - one style becomes four vars */
+  --al-number-field-font-size: var(--al-font-size-md);
+  --al-number-field-line-height: var(--al-line-height-md);
+  --al-number-field-font-weight: 400;
+  --al-number-field-tracking: 0em;
+  --al-number-field-label-font-size: var(--al-font-size-md);
+  --al-number-field-label-line-height: var(--al-line-height-md);
+  --al-number-field-label-font-weight: 400;
+  --al-number-field-label-tracking: 0em;
+  --al-number-field-optional-font-size: var(--al-font-size-sm);
+  --al-number-field-optional-line-height: var(--al-line-height-sm);
+  --al-number-field-optional-font-weight: 400;
+  --al-number-field-optional-tracking: 0em;
+  --al-number-field-help-font-size: var(--al-font-size-xs);
+  --al-number-field-help-line-height: var(--al-line-height-xs);
+  --al-number-field-help-font-weight: 400;
+  --al-number-field-help-tracking: 0.01em;
+}
+
+/* AL Design System - Number field
+ *
+ * Depends on: foundation/al-foundation.css
+ *           + components/number-field/al-number-field-tokens.css
+ *           + components/icon/icon.css
+ *           + components/number-field/number-field.js (the steppers)
+ *
+ * A QUANTITY THE PERSON ADJUSTS A LITTLE AT A TIME
+ *   A native <input type="number"> between a - and a + button. Numbers that
+ *   are not quantities (zip code, phone, card) are the Input with
+ *   inputmode="numeric" - rule 2.
+ *
+ * ANATOMY
+ *   <div class="al-number-field">
+ *     <div class="al-number-field__labelrow">
+ *       <label class="al-number-field__label" for="qty">Quantity</label>
+ *       <span class="al-number-field__optional">(Optional)</span>
+ *     </div>
+ *     <div class="al-number-field__control">
+ *       <button class="al-number-field__step" type="button" tabindex="-1"
+ *               data-step="down" aria-controls="qty"
+ *               aria-label="Decrease quantity" hidden>
+ *         <svg class="al-icon" aria-hidden="true" focusable="false">minus</svg>
+ *       </button>
+ *       <input class="al-number-field__field" id="qty" type="number"
+ *              min="1" max="10" step="1" value="1"
+ *              aria-describedby="qty-help">
+ *       <button class="al-number-field__step" type="button" tabindex="-1"
+ *               data-step="up" aria-controls="qty"
+ *               aria-label="Increase quantity" hidden>
+ *         <svg class="al-icon" aria-hidden="true" focusable="false">plus</svg>
+ *       </button>
+ *     </div>
+ *     <p class="al-number-field__help" id="qty-help">From 1 to 10</p>
+ *   </div>
+ *
+ * THE STEPPERS ARE OUT OF THE TAB ORDER
+ *   One tab stop: the arrow keys and typing change the value (Carbon, rule
+ *   13). So the buttons carry tabindex="-1", have no ring and no hover of
+ *   their own (rule 14) - the field's border and ring say where pointer and
+ *   focus are. They are born `hidden`: without JavaScript the arrow keys
+ *   still work and a button that does nothing never shows (the same as the
+ *   Password's eye).
+ *
+ * THE STEPPER AT THE LIMIT IS A DISABLED <button>
+ *   At the minimum the - is `disabled`, at the maximum the + (rule 10). The
+ *   JS sets the attribute; the CSS only reads `:disabled`. There is no Figma
+ *   variant for it.
+ *
+ * THE BOX IS `__control`, NOT THE <input>
+ *   The same as the Input: border, background, radius and ring live on
+ *   `__control` and the state is read through `:has()`. Without `:has()` the
+ *   native outline stays (it is only removed inside @supports).
+ *
+ * THE STATE IS DRIVEN BY THE MARKUP
+ *   Error reads `aria-invalid="true"`; disabled `:disabled`; read-only
+ *   `[readonly]` - never `:read-only`, which also matches disabled. The same
+ *   precedence by variable as the Input: error, read-only, disabled in file
+ *   order, disabled wins over all.
+ *
+ * READ-ONLY HAS NO STEPPERS (rule 17)
+ *   Nothing can change, so they are hidden and the value stays centered.
+ *
+ * THE BROWSER'S OWN SPINNERS ARE HIDDEN
+ *   WebKit draws arrows inside type=number and Firefox draws its own. With
+ *   AL's buttons there would be two pairs.
+ *
+ * HEIGHT AND WIDTH
+ *   48 = padding-y x2 + line height, border subtracted from the padding.
+ *   The box is fixed at `--al-number-field-width` (140), decided on
+ *   2026-10-21. Label and help text are not limited by it - they may be
+ *   wider than the box.
+ *
+ * HANDWRITTEN. The tokens it consumes are generated by tokens.py.
+ */
+
+/* ---------------------------------------------------------------- root */
+.al-number-field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--al-number-field-gap);
+}
+
+/* ------------------------------------------------------------ label */
+.al-number-field__labelrow {
+  display: flex;
+  align-items: baseline;
+  gap: var(--al-number-field-gap);
+}
+
+.al-number-field__label {
+  color: var(--al-number-field-label);
+  font-family: var(--al-font-sans);
+  font-size: var(--al-number-field-label-font-size);
+  line-height: var(--al-number-field-label-line-height);
+  font-weight: var(--al-number-field-label-font-weight);
+  letter-spacing: var(--al-number-field-label-tracking);
+}
+
+.al-number-field__optional {
+  color: var(--al-number-field-optional);
+  font-family: var(--al-font-sans);
+  font-size: var(--al-number-field-optional-font-size);
+  line-height: var(--al-number-field-optional-line-height);
+  font-weight: var(--al-number-field-optional-font-weight);
+  letter-spacing: var(--al-number-field-optional-tracking);
+}
+
+/* --------------------------------------------------------------- box */
+.al-number-field__control {
+  --_border-state: var(--al-number-field-border);
+
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  gap: var(--al-number-field-stepper-gap);
+  width: var(--al-number-field-width);
+
+  padding: calc(var(--al-number-field-padding-y) - var(--al-number-field-border-width))
+           calc(var(--al-number-field-padding-x) - var(--al-number-field-border-width));
+
+  border: var(--al-number-field-border-width) solid
+          var(--_border-force, var(--_border-state));
+  border-radius: var(--al-number-field-radius);
+  background-color: var(--_bg-force, var(--al-number-field-bg));
+  cursor: text;
+
+  transition:
+    border-color var(--al-motion-duration-feedback) var(--al-motion-easing-exit),
+    box-shadow var(--al-motion-duration-feedback) var(--al-motion-easing-exit);
+}
+
+/* ------------------------------------------------------------- field */
+.al-number-field__field {
+  --_text-state: var(--al-number-field-text-value);
+
+  flex: 1 1 0;
+  min-width: 0;
+  width: 100%;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--_text-force, var(--_text-state));
+  text-align: center;
+
+  font-family: var(--al-font-sans);
+  font-size: var(--al-number-field-font-size);
+  line-height: var(--al-number-field-line-height);
+  font-weight: var(--al-number-field-font-weight);
+  letter-spacing: var(--al-number-field-tracking);
+  font-variant-numeric: tabular-nums;
+
+  -moz-appearance: textfield;
+  appearance: textfield;
+}
+
+/* the browser's own spinners - see the header */
+.al-number-field__field::-webkit-inner-spin-button,
+.al-number-field__field::-webkit-outer-spin-button {
+  -webkit-appearance: none;
+  margin: 0;
+}
+
+@supports selector(:has(*)) {
+  .al-number-field__field:focus {
+    outline: none;
+  }
+}
+
+/* --------------------------------------------------------- the steppers */
+.al-number-field__step {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+
+  box-sizing: border-box;
+  width: var(--al-number-field-icon-size);
+  height: var(--al-number-field-icon-size);
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: none;
+  /* the svg inherits from here through currentColor - the Icon contract */
+  color: var(--al-number-field-stepper-icon);
+
+  cursor: pointer;
+  -webkit-appearance: none;
+  appearance: none;
+  -webkit-tap-highlight-color: transparent;
+}
+
+/* `display` above would beat the attribute - without JS the buttons don't show */
+.al-number-field__step[hidden] {
+  display: none;
+}
+
+.al-number-field__step > svg {
+  display: block;
+  flex: none;
+  width: var(--al-number-field-icon-size);
+  height: var(--al-number-field-icon-size);
+}
+
+/* at the limit, and in a disabled field - rule 10 */
+.al-number-field__step:disabled {
+  color: var(--al-number-field-stepper-icon-disabled);
+  cursor: not-allowed;
+}
+
+/* ------------------------------------------------------------ help text */
+.al-number-field__help {
+  color: var(--al-number-field-help);
+  font-family: var(--al-font-sans);
+  font-size: var(--al-number-field-help-font-size);
+  line-height: var(--al-number-field-help-line-height);
+  font-weight: var(--al-number-field-help-font-weight);
+  letter-spacing: var(--al-number-field-help-tracking);
+  margin: 0;
+}
+
+/* -------------------------------------------------------------- states */
+.al-number-field__control:hover:not(:has(.al-number-field__field:disabled, .al-number-field__field[readonly])) {
+  --_border-state: var(--al-number-field-border-hover);
+}
+
+.al-number-field__control:has(.al-number-field__field:focus-visible) {
+  --_border-state: var(--al-number-field-border-focus);
+  box-shadow: var(--_ring-force, var(--al-number-field-ring));
+}
+
+/* error - beats hover and focus by writing to another property */
+.al-number-field__control:has(.al-number-field__field[aria-invalid="true"]) {
+  --_border-force: var(--al-number-field-border-error);
+  --_ring-force: var(--al-number-field-ring-error);
+}
+
+.al-number-field:has(.al-number-field__field[aria-invalid="true"]) .al-number-field__label {
+  color: var(--al-number-field-label-error);
+}
+
+.al-number-field:has(.al-number-field__field[aria-invalid="true"]) .al-number-field__help {
+  color: var(--al-number-field-help-error);
+}
+
+/* read-only - `[readonly]`, never `:read-only`. No steppers - rule 17. */
+.al-number-field__control:has(.al-number-field__field[readonly]) {
+  --_border-force: var(--al-number-field-border-readonly);
+  --_bg-force: var(--al-number-field-bg-readonly);
+  cursor: default;
+}
+
+.al-number-field__control:has(.al-number-field__field[readonly]) .al-number-field__step {
+  display: none;
+}
+
+/* disabled - last, because it wins over all */
+.al-number-field__control:has(.al-number-field__field:disabled) {
+  --_border-force: var(--al-number-field-border-disabled);
+  --_bg-force: var(--al-number-field-bg-disabled);
+  cursor: not-allowed;
+}
+
+.al-number-field__field:disabled {
+  --_text-force: var(--al-number-field-text-disabled);
+  cursor: not-allowed;
+}
+
+.al-number-field:has(.al-number-field__field:disabled) .al-number-field__label,
+.al-number-field:has(.al-number-field__field:disabled) .al-number-field__optional {
+  color: var(--al-number-field-label-disabled);
+}
+
+/* ENTER - CSS uses the curve of the state the transition goes to. */
+.al-number-field__control:hover,
+.al-number-field__control:has(.al-number-field__field:focus-visible),
+.al-number-field__control:has(.al-number-field__field[aria-invalid="true"]) {
+  transition-timing-function: var(--al-motion-easing-enter);
+}
+
+/* --------------------------------------------------------- environment */
+@media (prefers-reduced-motion: reduce) {
+  .al-number-field__control {
+    transition: none;
+  }
+}

package/dist/components/number-field.js

@@ -0,0 +1,83 @@
+/* AL Design System - Number field: the steppers' behavior
+ *
+ * The arrow keys and typing are native to <input type="number">. This file
+ * only does what the browser doesn't:
+ *
+ *   1. removes the buttons' `hidden` (without JS they don't exist);
+ *   2. - and + call stepDown()/stepUp() and fire `input` and `change`, so the
+ *      form hears the change like it was typed. One click is one step:
+ *      holding the button does NOT repeat (decision E=a);
+ *   3. keeps focus where it was - clicking a stepper doesn't move focus to
+ *      the field or to the button (rule 15);
+ *   4. disables the stepper at the limit: - at the minimum, + at the maximum
+ *      (rule 10). A disabled field disables both.
+ *
+ * It never clamps what was typed (decision F=a): a value out of range stays
+ * as typed, and the form shows the error by reading `field.validity`
+ * (rangeUnderflow / rangeOverflow) and setting aria-invalid + the message.
+ *
+ * It starts by itself on load. Content inserted later:
+ *   window.alNumberField.init(elementContainingTheFields)
+ */
+(function () {
+  'use strict';
+
+  function setup(root) {
+    var field = root.querySelector('.al-number-field__field');
+    var down = root.querySelector('.al-number-field__step[data-step="down"]');
+    var up = root.querySelector('.al-number-field__step[data-step="up"]');
+    if (!field || !down || !up || root.hasAttribute('data-al-ready')) return;
+    root.setAttribute('data-al-ready', '');
+
+    function bound(attr) {
+      var v = field.getAttribute(attr);
+      return v === null || v === '' ? null : Number(v);
+    }
+
+    function sync() {
+      var value = field.valueAsNumber;
+      var min = bound('min');
+      var max = bound('max');
+      var off = field.disabled || field.readOnly;
+      down.disabled = off || (min !== null && !isNaN(value) && value <= min);
+      up.disabled = off || (max !== null && !isNaN(value) && value >= max);
+    }
+
+    function step(dir) {
+      if (field.disabled || field.readOnly) return;
+      try {
+        if (dir === 'up') field.stepUp(); else field.stepDown();
+      } catch (e) {
+        return;   // an empty or invalid value - stepping has nothing to start from
+      }
+      field.dispatchEvent(new Event('input', { bubbles: true }));
+      field.dispatchEvent(new Event('change', { bubbles: true }));
+      sync();
+    }
+
+    [down, up].forEach(function (button) {
+      // rule 15: the click must not take focus from where it was
+      button.addEventListener('mousedown', function (e) { e.preventDefault(); });
+      button.addEventListener('click', function () {
+        step(button.getAttribute('data-step'));
+      });
+      button.hidden = false;
+    });
+
+    field.addEventListener('input', sync);
+    sync();
+  }
+
+  function init(scope) {
+    var roots = (scope || document).querySelectorAll('.al-number-field');
+    for (var i = 0; i < roots.length; i++) setup(roots[i]);
+  }
+
+  window.alNumberField = { init: init };
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function () { init(); });
+  } else {
+    init();
+  }
+})();

package/dist/foundation.css

@@ -1,5 +1,5 @@
 /* AL Design System - Foundation
- * v1.3.0 - MIT
+ * v1.4.0 - MIT
  * GENERATED by src/foundation/css.py. Do not edit by hand: run the script.
  */
 

package/dist/tokens.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "AL Design System",
-    "version": "1.3.0",
+    "version": "1.4.0",
     "license": "MIT",
     "brandAnchor": "#FC5000",
     "colorSpace": "OKLCH",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "al-design-system",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "AL Design System: Foundation and components in plain CSS, from Figma to code.",
   "license": "MIT",
   "author": "Guilherme Domingues",