@recursica/mui-adapter 0.19.0 → 0.21.0

package/src/components/Panel/USAGE.md

@@ -43,61 +43,4 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 
 ## 4. Key Integration Features & Constraints
 
-## 1. Mapping to MUI Drawer
-
-**Decision:** Panel maps to MUI's `Drawer` component, not `Paper` or `Card`.
-
-**Implementation:** Per the Recursica design system specification, "Panels slide in or expand from the edge of the screen to reveal additional content or functionality." This is the exact behavior of MUI's `Drawer` component, which provides:
-
-- Slide-in animation from any screen edge (using the `anchor` prop)
-- Backdrop/overlay support
-- Focus trap and overlay portal management
-- Internal scroll lock when open
-
----
-
-## 2. Token Namespace: `panel`
-
-**Decision:** The CSS module exclusively uses variables from the `--recursica_ui-kit_components_panel_*` namespace.
-
-**Implementation:** The Recursica token system defines the `panel` namespace covering:
-
-- Geometry: border-radius, border-size, min-width (200px), max-width (960px)
-- Content padding: content-horizontal-padding (xl), content-vertical-padding (lg)
-- Header/Footer padding: header-footer-horizontal-padding (xl), header-footer-vertical-padding (md)
-- Spacing: header-close-gap (md), footer-button-gap (md)
-- Divider: divider-size (1px), divider-color
-- Elevation: elevation-3
-- Colors (layer-aware): background, border-color, content, divider-color, header-footer-background, title
-- Non-CSS: header-style ("h3")
-
-No tokens from other component namespaces are referenced.
-
----
-
-## 3. Default Placement Override
-
-**Decision:** Use `placement` instead of `position` for configuring slide-out direction, and default it to `"right"`.
-
-**Implementation:** The prop was renamed from `position` to `placement` to prevent collision with the CSS `position` keyword, which is strictly blocked by the styling gatekeeper (`BLOCKED_STYLING_KEYS`). This allows configuring the drawer direction natively while maintaining strict design-system boundaries. The `placement="right"` default is mapped internally to MUI Drawer's `anchor` prop before any other sanitized props are applied. Right-side panels are the most common pattern for supplementary content, settings, and detail views.
-
----
-
-## 4. Custom Panel.Footer
-
-**Decision:** A custom `Panel.Footer` sub-component is provided. MUI's Drawer does not have a native footer.
-
-**Implementation:** `Panel.Footer` is a `<div>` with styling referencing Recursica CSS variables for:
-
-- `header-footer-background` and `header-footer-padding` tokens
-- Top divider using `divider-size` and `divider-color`
-- `footer-button-gap` for action button spacing
-- `margin-top: auto` to push the footer to the bottom
-
----
-
-## 5. Visibility Mapping (`opened` -> `open`)
-
-**Decision:** Accept `opened` prop to match the standard Recursica component API.
-
-**Implementation:** MUI Drawer natively expects the `open` boolean prop. The wrapper maps the incoming framework-agnostic `opened` prop to MUI's `open={Boolean(opened)}`, allowing consistent usage across both adapter implementations.
+`Panel` accepts a `placement` prop (`"left"`, `"right"`, `"top"`, or `"bottom"`) that controls which edge of the screen the panel slides in from, and defaults to `"right"`. This prop was renamed from `position` to `placement`.

package/src/components/Stepper/USAGE.md

@@ -39,10 +39,3 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 > - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
 > - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
 > - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
-
----
-
-## 4. Key Integration Features & Constraints
-
-- **Compositional API Dropped:** Mantine manages stepper state and content via `<Stepper.Step>` and `<Stepper.Completed>`. MUI delegates content rendering to the developer and focuses purely on the stepper visual layout using `<Step>`, `<StepLabel>`, etc.
-- **Monolithic API Adopted:** Following architectural review, we have abandoned the fabricated context wrappers for `mui-adapter`. We now natively export `Stepper`, `Step`, `StepLabel`, `StepButton`, and `StepConnector` wrapping their `@mui/material` counterparts. Developers are expected to manage the active step logic and content rendering outside the `Stepper` component, consistent with MUI patterns. Storybook tests have been updated to reflect this divergence while retaining core visual compatibility.

package/src/components/Tabs/USAGE.md

@@ -43,10 +43,3 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 > - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
 > - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
 > - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
-
----
-
-## 4. Key Integration Features & Constraints
-
-- **Compositional API Dropped:** Mantine uses `<Tabs.List>`, `<Tabs.Tab>`, and `<Tabs.Panel>` natively with implicit context from `<Tabs>`. MUI relies on `@mui/lab/TabContext` and separates `Tabs` and `TabPanel`.
-- **Monolithic API Adopted:** Following architectural review, we have opted to drop the broken dot-notation wrappers for `mui-adapter`. We now natively export `Tabs` (MUI List), `Tab` (MUI Item), and `TabPanel` (from `@mui/lab`). Developers must use `TabContext` (from `@mui/lab`) to manage state, just like native MUI. Storybook and visual regression tests have been updated to reflect this divergence while retaining core property mapping compatibility.

package/src/components/TimePicker/TIMEPICKER_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,68 @@
+# TimePicker Implementation Notes
+
+## Architecture Overview
+
+`TimePicker` is a composite of two independently-styled controls sitting side by side in a flex row:
+
+1. **The time field** — `@mui/x-date-pickers`'s `TimePicker`, always rendered with `format="hh:mm"` (or `"hh:mm:ss"` with `withSeconds`) — 12-hour digits, no native meridiem section.
+2. **The AM/PM selector** — `BareDropdown`, a headless variant of this adapter's own `Dropdown` component (see below), not a plain `Select`.
+
+This shape is deliberate and **not configurable** — there is no prop to get a plain 24-hour field or to hide the AM/PM control. Every consumer gets the same 12-hour + Dropdown-styled-AM/PM composite. (Matt Massey, 2026-08-07 — an earlier revision of this component had a `hideAmPm` prop; it was removed once the design was confirmed fixed, and the shared `RecursicaTimePickerProps` contract in `adapter-common` no longer includes it.)
+
+This was a deliberate choice over a native `<input type="time">`, in exchange for a real clock/list-based time selection UI, at the cost of a new dependency (`@mui/x-date-pickers` + `dayjs`, both added as optional peer deps + a real `dayjs` dependency).
+
+## `BareDropdown`
+
+A new, **internal-only** component in `../Dropdown/BareDropdown.tsx` — not exported from this folder's `index.ts` (which only re-exports `./Dropdown`, not `./BareDropdown`). It's the same `@mui/material` `Select`/`MenuItem` primitives `Dropdown` wraps, styled via the **same** `Dropdown.module.css` classes (`root`/`input`/`icon`/`dropdown`/`option`), but with no `FormControlWrapper`/`WithReadOnlyWrapper` and no label/assistiveText/error/required props. Its `onChange` is normalized to `(value: string | null) => void` (just the selected value), unlike MUI's raw `Select` `onChange`, which hands back a `(event, child)` pair — this keeps its call signature identical to mantine-adapter's `BareDropdown` (whose underlying Mantine `Select` already has a plain-value `onChange`).
+
+**Why not the public `Dropdown` component directly**: `Dropdown` wraps its own `FormControlWrapper`/`FormControlLayout` internally (it's meant to be used standalone). Nesting the full `Dropdown` inside `TimePicker` — which is already `FormControlWrapper`-wrapped — would double up `FormControl`/`FormControlLayout` structure. `BareDropdown` is the headless escape hatch for exactly this situation: reuse `Dropdown`'s visual styling without its structural wrapping. (Matt Massey, 2026-08-07.)
+
+## Internal state, unlike every other component here
+
+Every other input in this adapter is a thin pass-through — the wrapped library component owns all interaction state. `TimePicker` is the exception: the time field and the AM/PM `BareDropdown` both mutate the _same_ conceptual value, so something has to reconcile them. `TimePicker.tsx` keeps a `useState<Dayjs | null>` for the full 24-hour internal value, seeded from `value`/`defaultValue`, synced when `value` changes (controlled usage), and updated by both controls (the field's own `onChange`, and the `BareDropdown`'s `onChange` — which just adds or subtracts 12 from the current hour). The public `value`/`onChange` API is unaffected — still a plain `"HH:mm"`/`"HH:mm:ss"` string; `dayjs` never leaks out.
+
+## `format="hh:mm"` has no meridiem section on purpose
+
+Lowercase `hh` renders 12-hour digits (1–12) with no `a` (meridiem) token, so there's nothing for the user to toggle within the field itself — meridiem is only ever changed via the separate `BareDropdown`. Editing just the hour/minute digits preserves whichever meridiem the current internal value already has, since we always pass a fully-formed `Dayjs` value back into the field (never letting it manage its own uncontrolled state).
+
+## No `variant` prop to force "standard"
+
+`@mui/x-date-pickers` v9's public `TimePicker`/`slotProps.field` API doesn't expose a `variant` prop at all (it's only reachable on an internal `textFieldProps` object this package doesn't surface). The CSS module defensively suppresses **both** the "standard" variant's underline (`::before`/`::after`) and the "outlined" variant's notched-outline, since which one actually renders isn't controllable from here — only one of the two suppressions will ever be doing anything at runtime.
+
+## Design tokens
+
+- No dedicated `min-height` token exists for `time-picker` (unlike `text-field`/`date-picker`) — the field's height is derived from its own padding + line-height instead of a fixed token.
+- `icon-size`/`icon-color`/`icon-text-gap`/`placeholder-opacity` are exempted (`recursica-ignore`) — the time field has no icon slot and MUI X's field renders empty sections via its own internal placeholder styling, not a native `::placeholder` pseudo-element.
+- The AM/PM `BareDropdown` draws its own border/background/padding from `Dropdown`'s own tokens via `Dropdown.module.css` — it does not reuse any `time-picker` tokens.
+
+## Known limitation — the popup clock/list view is unstyled
+
+This pass covers the closed-state field and the AM/PM `BareDropdown` only. The open dropdown (digital clock list, depending on `views`) still renders with MUI's default theme, not Recursica tokens — there's no Figma-exported token set for it (mirrors the same category of gap `DatePicker`'s calendar popover has in `mantine-adapter`). Revisit once there's a design spec for it.
+
+## Read-Only Implementation
+
+`readOnlyType="text"`, matching `DatePicker`'s convention.
+
+## Visual review fix (Matt Massey, 2026-08-07)
+
+**`BareDropdown`'s border color didn't match Mantine's version, despite both reading the same `Dropdown` tokens**: a real bug in `BareDropdown.tsx` — `className={styles.root}` was set explicitly on `<MuiSelect>`, then `{...sanitizedProps}` was spread _after_ it. Any caller passing its own `className` (like `TimePicker.tsx`'s `styles.amPmSelect`) silently overwrote `styles.root` entirely via that later spread, so `Dropdown.module.css`'s border-color/background/`width: 100%` never actually applied — MUI's own default border rendered instead. Fixed by extracting `className` explicitly and merging it (`` `${styles.root} ${className}` ``) before it reaches `<MuiSelect>`, the same pattern mantine-adapter's `BareDropdown` already used. This also explains why the AM/PM box's width had looked accidentally "correct" before: the competing `width: 100%` rule from `.root` was never actually being applied either.
+
+## Visual review round 2 (Matt Massey, 2026-08-08)
+
+- **Time field's default clock icon removed**: `time-picker`'s own token schema has no icon slot (see EXEMPTIONS above) and the popup it opens isn't styled to Recursica tokens anyway (see "Known limitation" below) — showing a button to open an unstyled popup was worse than not showing one. Removed via `slots={{ openPickerButton: () => null }}`; this also shrank the field's own width back down, since the icon's reserved layout space is gone.
+- **AM/PM `BareDropdown` looked shorter than the time field and had a doubled border**: a latent, pre-existing bug in the _shared_ `Dropdown.module.css`, not something new in this composite — confirmed the standalone `Dropdown` component has the exact same issue (measured its own `.input` box at 42.8px instead of the 48px `min-height` token). Root cause: MUI generates a compound class for the select's inner box (e.g. `.css-xxx-...-MuiSelect-select`) that sets its own `min-height: 1.4375em` (~23px) — two classes' worth of specificity, which beats `Dropdown.module.css`'s single-class `.input` rule, so the 48px token silently loses. Separately, MUI's outlined variant renders its own native `fieldset`/`notchedOutline` border _underneath_ `.input`'s own Recursica border — the second border Matt saw. Both fixed **scoped to this composite only** (`.amPmSelect :global(.MuiSelect-select) { min-height: ... !important }` + suppressing `.MuiOutlinedInput-notchedOutline`), matching the same technique already used to suppress the time field's own native decoration — _not_ fixed in the shared `Dropdown.module.css`, since that would change the standalone `Dropdown` component everywhere in the app, outside this component's scope. Flagged to Matt as a separate, real bug worth a dedicated fix.
+
+## Visual review round 3 (Matt Massey, 2026-08-08)
+
+- **AM/PM value wasn't vertically centered**: a side effect of the round-2 min-height fix above — forcing the box to 48px left real slack below the text (`display: block`, top-aligned line box), which reads as "not centered" once the box is taller than its own padding + line-height. Added `display: flex; align-items: center` to the same scoped override so the slack distributes evenly instead.
+- **AM/PM dropdown menu showed MUI's default blue selected-state tint instead of Recursica's**: `Dropdown.module.css`'s `.option[data-selected="true"]` rule (Recursica's neutral hover/selected tint) was never actually wired up — neither `Dropdown.tsx` nor `BareDropdown.tsx` ever set `data-selected` on the currently-selected `MenuItem`, so MUI's own `Mui-selected` class (with its default primary-blue background) rendered uncontested instead. This is a **shared, pre-existing gap** affecting the real `Dropdown` component too, just not visible there by default (`Dropdown`'s own default story has no value pre-selected, so nothing shows the tint) — unlike `TimePicker`'s AM/PM, which always has a value. Fixed in **both** `Dropdown.tsx` and `BareDropdown.tsx` (compare each `MenuItem`'s value against the select's current `value`/`defaultValue`) since this is a low-risk, purely-additive fix completing an already-designed CSS contract, not a new design decision — unlike the min-height/border fix above, which changes visual geometry and was deliberately scoped to this composite only.
+
+## Visual review round 4 (Matt Massey, 2026-08-08) — time field width
+
+The time field itself rendered wider than intended (220px vs. the 130px `time-picker.properties.width` token), despite `.field { width: fit-content }` already being set. Root cause: `@mui/x-date-pickers` computes and inline-sets a literal pixel width on `.MuiPickersInputBase-sectionsContainer` based on the format string (182px for "hh:mm") — sized generously for the widest possible rendered value, independent of `.field`'s own width. Reset via `.field :global(.MuiPickersInputBase-sectionsContainer) { width: auto !important; flex-grow: 0 !important; }` — safe here because these are real text `<span>`s (not native `<input>`s), so `auto` sizes to their actual content correctly, unlike the native-`<input>`-in-`BareDropdown` case elsewhere in this file, where `auto` alone didn't help. Now matches Mantine's `.timeWrapper`'s 130px exactly.
+
+## Visual review round 5 (Matt Massey, 2026-08-08)
+
+- **AM/PM error-state border wasn't changing**: `Dropdown.tsx`'s error/disabled state was set via `inputProps` (`data-error`/`data-disabled`), which only reaches the nested accessibility `<input>` — a different element from `.root` (the actual Select root carrying the border), which is what `Dropdown.module.css`'s `.root[data-error]`/`[data-disabled]` selectors require. The error border never actually applied, in the real `Dropdown` component or `BareDropdown`. Fixed by also setting `data-error`/`data-disabled` directly as top-level props on `<MuiSelect>` (they land on its root element) in both `Dropdown.tsx` and `BareDropdown.tsx` — the latter also needed an `error?: boolean` prop added to its own interface, since it previously had none.
+- **Static/Editable ReadOnly showed "Invalid Date" instead of a value**: a real, separate bug — `toDayjs`'s 2-argument `dayjs(value, format)` call silently does nothing without the `customParseFormat` plugin registered; without it, dayjs falls back to native `Date` parsing, which fails on a bare "HH:mm" string (no date component). This went unnoticed until now because every prior interactive test produced `Dayjs` objects directly from the picker's own `onChange`, never actually exercising `toDayjs` with a real initial `value`/`defaultValue` string. Fixed by adding `dayjs.extend(customParseFormat)`.
+- **Static/Editable ReadOnly showed the raw 24-hour value with no AM/PM** (e.g. "14:30" instead of "2:30 PM"): `readOnlyValue` was passed the raw internal string as-is. Added `formatReadOnlyTime` (uses `toDayjs` + dayjs's own `.format("h:mm A")`) before handing it to `WithReadOnlyWrapper`.

package/src/components/TimePicker/TimePicker.module.css

@@ -1,41 +1,217 @@
 /* EXEMPTIONS:
-   This component is a placeholder stub. Once fully implemented, its specific
-   tokens will be fully wired up to direct styles. */
-
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_border-radius */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_horizontal-padding */
+   - state-specific border-size variables are ignored because a uniform border-size is applied globally
+     to prevent unexpected layout shift or flickering during focus, disabled, or error state transitions.
+   - icon-size/icon-color/icon-text-gap have no equivalent here: the time field has no icon slot,
+     unlike TextField/DatePicker.
+   - placeholder-opacity has no equivalent here: MUI X's field renders empty sections via its own
+     internal placeholder styling, not a native ::placeholder pseudo-element we can target. */
+/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_error_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_border-size */
 /* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_icon-size */
 /* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_icon-text-gap */
+/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_colors_icon-color */
 /* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_placeholder-opacity */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_vertical-padding */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_properties_width */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_layouts_side-by-side_properties_top-bottom-margin */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_layouts_stacked_properties_top-bottom-margin */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_default_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_default_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_default_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_default_properties_colors_icon */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_default_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_colors_icon */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_error_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_icon */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_focus_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_focus_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_focus_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_focus_properties_colors_icon */
-/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_focus_properties_colors_text */
+/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_colors_icon-color */
+/* recursica-ignore: --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_icon-color */
+
+/* LAYOUT SPACING OVERRIDES:
+   - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens. */
+.layoutOverride {
+  --form-control-margin-bottom: var(
+    --recursica_ui-kit_components_time-picker_variants_layouts_stacked_properties_top-bottom-margin
+  );
+}
+
+.layoutOverride[data-form-layout="side-by-side"] {
+  --form-control-margin-bottom: var(
+    --recursica_ui-kit_components_time-picker_variants_layouts_side-by-side_properties_top-bottom-margin
+  );
+}
+
+/* HARDCODED VALUES:
+   - border-style: solid. Native structural rendering rule.
+   - display: flex on .root — the time field and the AM/PM BareDropdown are two visually separate
+     controls sitting side by side, not merged into one shared box (BareDropdown draws its own
+     border/background from Dropdown.module.css). See TIMEPICKER_IMPLEMENTATION_NOTES.md.
+   - MUI X's field variant can't be forced from this component's public API (see
+     TIMEPICKER_IMPLEMENTATION_NOTES.md) — whichever native decoration it renders is suppressed
+     below, and our own border/background are applied to .field instead.
+*/
+
+.root {
+  display: flex;
+  align-items: flex-start;
+  gap: var(
+    --recursica_ui-kit_components_time-picker_properties_horizontal-padding
+  );
+  width: fit-content;
+}
+
+.field {
+  /* min-width, not width: the `width` token was authored for a single plain input (confirmed against
+     text-field's identical token shape); this is now only the time-entry half of the composite. */
+  min-width: var(--recursica_ui-kit_components_time-picker_properties_width);
+  width: fit-content;
+  border-radius: var(
+    --recursica_ui-kit_components_time-picker_properties_border-radius
+  );
+  border-width: var(
+    --recursica_ui-kit_components_time-picker_properties_border-size
+  );
+  border-style: solid;
+  border-color: var(
+    --recursica_ui-kit_components_time-picker_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_time-picker_properties_colors_background-color
+  );
+  color: var(
+    --recursica_ui-kit_components_time-picker_properties_colors_text-color
+  );
+}
+
+/* Suppress whichever native field decoration MUI X renders by default (its public API doesn't
+   expose a variant prop to force "standard" in this version) — .field draws the border instead,
+   regardless of whether the field defaults to "outlined" or "standard". */
+.field :global(.MuiPickersInputBase-root::before),
+.field :global(.MuiPickersInputBase-root::after),
+.field :global(.MuiInput-root::before),
+.field :global(.MuiInput-root::after) {
+  border-bottom: none !important;
+}
+
+.field :global(.MuiPickersOutlinedInput-notchedOutline) {
+  border: none !important;
+}
+
+.field :global(.MuiPickersInputBase-sectionsContainer) {
+  /* MUI X computes and inline-sets a literal pixel width here based on the format string (e.g.
+     182px for "hh:mm"), sized generously to fit the widest possible rendered value — wider than
+     .field's own `width: fit-content` intends. Reset it so the field visually matches Mantine's
+     equally-compact time input; the section <span>s are real text content, so width: auto sizes to
+     them correctly (unlike the native-<input>-in-BareDropdown case elsewhere in this file, where
+     `auto` didn't help — no UA-default-sizing quirk here since these aren't native inputs). */
+  width: auto !important;
+  flex-grow: 0 !important;
+  padding-top: var(
+    --recursica_ui-kit_components_time-picker_properties_vertical-padding
+  );
+  padding-bottom: var(
+    --recursica_ui-kit_components_time-picker_properties_vertical-padding
+  );
+  padding-left: var(
+    --recursica_ui-kit_components_time-picker_properties_horizontal-padding
+  );
+  padding-right: var(
+    --recursica_ui-kit_components_time-picker_properties_horizontal-padding
+  );
+
+  font-family: var(
+    --recursica_ui-kit_components_time-picker_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_time-picker_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_time-picker_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_time-picker_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_time-picker_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_time-picker_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_time-picker_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_time-picker_properties_text_text-transform
+  );
+}
+
+.field :global(.MuiPickersInputBase-input) {
+  color: inherit;
+}
+
+/* The AM/PM BareDropdown reuses Dropdown.module.css's own border/background/padding entirely —
+   this only controls its size/alignment within the flex row. */
+.amPmSelect {
+  flex: 0 0 auto;
+  align-self: flex-start;
+  width: auto;
+  min-width: 5.5rem;
+}
+
+/* MUI's own generated class for the select's inner box (a compound selector, e.g.
+   `.css-xxx-...-MuiSelect-select`) has higher specificity than Dropdown.module.css's single-class
+   `.input` rule, so its own `min-height: 1.4375em` (~23px) silently wins over our 48px token —
+   this is a latent bug in the shared Dropdown.module.css itself (the standalone Dropdown
+   component has the exact same undersized box; flagged separately, not fixed here to avoid an
+   app-wide change outside TimePicker's scope). `!important` here only re-asserts the height
+   Dropdown was always supposed to have, scoped to this composite. MUI's outlined variant also
+   renders its own native `fieldset`/`notchedOutline` border *in addition to* `.input`'s own
+   Recursica border — suppressed the same way the time field already suppresses its own native
+   decoration above. See TIMEPICKER_IMPLEMENTATION_NOTES.md. */
+.amPmSelect :global(.MuiSelect-select) {
+  min-height: var(
+    --recursica_ui-kit_globals_form_field_size_single-line-input-height
+  ) !important;
+  box-sizing: border-box !important;
+  /* Forcing min-height above leaves real slack below the (block-flow, top-aligned) text once the
+     box is taller than its own padding + line-height — the value read as "not centered". Flex +
+     center distributes that slack evenly instead. */
+  display: flex !important;
+  align-items: center !important;
+}
+
+.amPmSelect :global(.MuiOutlinedInput-notchedOutline) {
+  border: none !important;
+}
+
+/* -------------------------------------
+   STATE CASCADE ARCHITECTURE
+-------------------------------------- */
+
+/* Focus State Mapping — applied to the time field only (the BareDropdown has its own via
+   Dropdown's own CSS module). */
+.field:has(:global(.Mui-focused)) {
+  box-shadow:
+    0 0 0 var(--recursica_brand_states_focus_border-size)
+      var(--recursica_brand_states_focus_color),
+    0 0 var(--recursica_brand_states_focus_blur)
+      var(--recursica_brand_states_focus_margin)
+      var(--recursica_brand_states_focus_color);
+}
+
+/* Error State Mapping (data-error is set explicitly by TimePicker.tsx). */
+.root[data-error="true"] .field {
+  border-color: var(
+    --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_border-color
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_background-color
+  ) !important;
+  color: var(
+    --recursica_ui-kit_components_time-picker_variants_states_error_properties_colors_text-color
+  ) !important;
+}
+
+/* Disabled State Mapping */
+.field:has(:global(.Mui-disabled)) {
+  border-color: var(
+    --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_colors_border-color
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_colors_background-color
+  ) !important;
+  color: var(
+    --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_colors_text-color
+  ) !important;
+  opacity: var(
+    --recursica_ui-kit_components_time-picker_variants_states_disabled_properties_opacity
+  ) !important;
+  cursor: not-allowed;
+}

package/src/components/TimePicker/TimePicker.stories.tsx

@@ -1,12 +1,75 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { TimePicker } from "./TimePicker";
-import { ComingSoon } from "@recursica/storybook-template";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
 
 const meta: Meta<typeof TimePicker> = {
-  title: "UI-Kit/🚧 TimePicker",
+  title: "UI-Kit/TimePicker",
   component: TimePicker,
   tags: ["autodocs"],
-  argTypes: {},
+  parameters: {
+    controls: {
+      include: [
+        "value",
+        "defaultValue",
+        "disabled",
+        "error",
+        "required",
+        "label",
+        "assistiveText",
+        "readOnly",
+        "withSeconds",
+        "formLayout",
+      ],
+    },
+    docs: {
+      description: {
+        component: `
+The \`TimePicker\` primitive provides a 12-hour time field (via \`@mui/x-date-pickers\`) paired with a dedicated AM/PM \`Dropdown\`-style selector, integrated directly into the \`FormControlWrapper\` architecture. This composite is the only way this component operates — a Recursica-specific design, not a user-configurable option.
+
+### Examples
+Always structure horizontal architectures via the generic \`formLayout\` parameter.
+\`\`\`tsx
+<TimePicker
+  label="Start Time"
+  assistiveText="Select the deployment kick-off time."
+  formLayout="stacked"
+/>
+\`\`\`
+`,
+      },
+    },
+  },
+  argTypes: {
+    ...formControlArgTypes,
+    disabled: {
+      control: "boolean",
+      description:
+        "Maps the formal disabled variable states structurally to the input core.",
+    },
+    error: {
+      control: "text",
+      description:
+        "Applies the strict error string boundary rendering invalid structures seamlessly.",
+    },
+    required: {
+      control: "boolean",
+    },
+    label: {
+      control: "text",
+    },
+    assistiveText: {
+      control: "text",
+    },
+    readOnly: {
+      control: "boolean",
+      description:
+        "Toggles structural read-only data presentation explicitly blocking standard component bindings.",
+    },
+    withSeconds: {
+      control: "boolean",
+      description: "Shows and allows editing the seconds segment.",
+    },
+  },
 };
 
 export default meta;
@@ -14,5 +77,57 @@ export default meta;
 type Story = StoryObj<typeof TimePicker>;
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="TimePicker" />,
+  args: {
+    disabled: false,
+    label: "Meeting Time",
+    assistiveText: "Choose the start time in your local timezone.",
+  },
+};
+
+export const FormsSideBySide: Story = {
+  args: {
+    label: "Incident Start Time",
+    assistiveText: "When did the incident originally occur?",
+    formLayout: "side-by-side",
+  },
+};
+
+export const WithSeconds: Story = {
+  args: {
+    label: "Precise Execution Time",
+    assistiveText: "Includes a seconds segment for exact scheduling.",
+    withSeconds: true,
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    label: "Disabled Time Slot",
+    disabled: true,
+  },
+};
+
+export const ErrorState: Story = {
+  args: {
+    label: "Deployment Window",
+    error: "The chosen time falls outside the allowed deployment window.",
+    required: true,
+  },
+};
+
+export const StaticReadOnly: Story = {
+  args: {
+    label: "Static ReadOnly Review",
+    value: "14:30",
+    readOnly: true,
+  },
+};
+
+export const EditableReadOnly: Story = {
+  args: {
+    label: "Editable ReadOnly Review",
+    defaultValue: "09:00",
+    readOnly: true,
+    labelWithEditIcon: true,
+  },
 };