# DateField

> Date input with custom calendar popover.

- **Level**: molecule · **Status**: stable · **Role**: input
- **Import**: `import { DateField } from "@rrios-forge/ui/molecules/date-field";`
- **Source**: `packages/ui/src/molecules/date-field`

Apple-style date picker. The trigger reuses Input geometry; the popover renders a custom calendar (Radix Popover gives focus trap + escape-to-close; the calendar grid implements full keyboard navigation per the APG date picker pattern). Locale-aware via `Intl.DateTimeFormat`, theme-native via tokens — no hard-coded colours, no native browser picker.

## Use it for

- Date field / file drop / slider → `DateField` / `FileDropzone` / `Slider`

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `size` | — | `sm` `md` `lg` | `md` | Ergonomic scale, in three families (control, text, container). |
| `tone` | — | `neutral` `muted` | `neutral` | Which semantic colour family the element speaks in. |
| `selected` | — | `true` `false` | `false` | Chosen in a set: the selected wash plus a non-colour cue (weight, check). |
| `today` | — | `true` `false` | `false` | Marks the current day in a calendar. |

## Stories

- [Playground](/?path=/story/components-molecules-datefield--playground) · frame: `/iframe.html?id=components-molecules-datefield--playground&viewMode=story`
- [Required](/?path=/story/components-molecules-datefield--required) · frame: `/iframe.html?id=components-molecules-datefield--required&viewMode=story`
- [Invalid](/?path=/story/components-molecules-datefield--invalid) · frame: `/iframe.html?id=components-molecules-datefield--invalid&viewMode=story`
- [Disabled](/?path=/story/components-molecules-datefield--disabled) · frame: `/iframe.html?id=components-molecules-datefield--disabled&viewMode=story`
- [Empty](/?path=/story/components-molecules-datefield--empty) · frame: `/iframe.html?id=components-molecules-datefield--empty&viewMode=story`
- [With min / max bounds](/?path=/story/components-molecules-datefield--with-bounds) · frame: `/iframe.html?id=components-molecules-datefield--with-bounds&viewMode=story`
- [Open calendar](/?path=/story/components-molecules-datefield--open) · frame: `/iframe.html?id=components-molecules-datefield--open&viewMode=story`
- [Locales](/?path=/story/components-molecules-datefield--locales) · frame: `/iframe.html?id=components-molecules-datefield--locales&viewMode=story`
- [Controlled](/?path=/story/components-molecules-datefield--controlled) · frame: `/iframe.html?id=components-molecules-datefield--controlled&viewMode=story`
- [With range](/?path=/story/components-molecules-datefield--with-range) · frame: `/iframe.html?id=components-molecules-datefield--with-range&viewMode=story`
- [Keyboard flow (interaction test)](/?path=/story/components-molecules-datefield--keyboard-flow) — interaction test · frame: `/iframe.html?id=components-molecules-datefield--keyboard-flow&viewMode=story`
- [Open focus (interaction test)](/?path=/story/components-molecules-datefield--open-focus) — interaction test · frame: `/iframe.html?id=components-molecules-datefield--open-focus&viewMode=story`
- [Month paging (interaction test)](/?path=/story/components-molecules-datefield--month-paging) — interaction test · frame: `/iframe.html?id=components-molecules-datefield--month-paging&viewMode=story`

## Decisions that name it

- ADR-030 — Axis vocabulary: one name, one meaning
- ADR-043 — The default theme is monochrome

## Always

- Tokens only (R04); variants are semantic axes, never appearance (R02).
- Typography and actions are Poesía atoms, never raw HTML with utilities.
- Vibrant panes need a ground and never nest (ADR-027).