@cahyo-dimas/freeday 1.28.0 → 1.30.0

package/CHANGELOG.md

@@ -3,6 +3,109 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
 
+## [1.30.0] — 2026-08-18
+Note 008 (adopting 1.29.0) plus a direct design report: *"the input border looks too dark next to the
+card and button-group borders."*
+### Fixed
+- **The dark theme's contrast has not actually been tested since v1.21.0.** `contrast.test.mjs` looked
+  for `:root[data-theme="dark"]`; un-rooting the theme selectors in 1.21.0 changed the emitted
+  selector to `[data-theme="dark"]`, so the regex matched nothing, `dark` fell back to the **light**
+  values, and every `WCAG contrast — DARK` assertion re-tested the light theme under a dark label —
+  54 declarations ignored, all green. Fixed, and the scope now has a guard of its own: a dark scope
+  that parses to nothing, or that resolves to the light surface, fails loudly. *No latent dark-theme
+  failures were hiding behind it — the theme passes on its own merits.*
+- **`--color-control-border` retuned** to a new ramp step `--slate-450` (`#798295`). It was
+  `--slate-500`, the same ink as `--color-text-subtle`: a control **boundary** carrying text-level
+  contrast (4.69:1 on surface where WCAG 1.4.11 asks 3:1), which is what makes a form look heavier
+  than the cards around it. Now ≈3.9/3.6/3.4 across the three light surfaces. The same step
+  *strengthens* the dark theme, which was sitting at **3.02:1** on `surface-3` — 0.02 above the
+  floor, and unguarded because of the bug above; it is now 3.66:1.
+- **`.fdy-stat__label` uses `--color-text-muted`.** It spent `--color-text-subtle`, which is gated at
+  3.0 *on purpose* (placeholders, dividers, decorative glyphs) and measures 4.41:1 on `surface-2` —
+  under AA for text, on the only thing naming the number above it. Reported in 006 §6 and still
+  carried by the app at 1.29.0.
+### Added
+- **`.fdy-btn--stretch` now works in a `.fdy-list__row`** (note 008 §1). The pattern existed for
+  "one card, one primary action, one escape hatch" and had no equivalent for the same sentence with
+  *row* in it — an app rendering both grid and list from one component had to hand-roll the row half.
+  The row anchors the overlay itself, opt-in through `:has(.fdy-btn--stretch)` so a plain row is
+  untouched and nothing an app pinned inside one starts resolving against a new containing block.
+  Measured before the fix: **every** row's overlay covered the whole list and the last one in the DOM
+  won, so a click on row one opened row two — under row one's name.
+### Notes on the shape of the fix
+- **Note 008 §2 is not reproducible** and no code shipped for it. With a positive control to prove
+  the measurement works (pointing at the card body *does* put the stretched target in `:hover`),
+  pointing at the escape hatch leaves it at rest: the hover chain is `HTML > BODY > card > footer >
+  hatch`, and the stretched button is a sibling, not an ancestor. The `pointer-events:none` rule the
+  report carries fixes something the kit's own composition does not do.
+- The report's contrast figures (4.41 / 4.69) were re-derived from the 1.29 ramp and are exact.
+### Added — guards
+- `contrast.test.mjs`: the control border is now asserted on **all three** surfaces (`surface-3` was
+  missing, and it is the worst case that pinned the dark theme to the floor) and at **3.25**, not
+  3.0 — a boundary that clears the floor by 0.02 has no headroom, and the margin is what catches a
+  revert to the old ink.
+- `css.test.mjs`: a stat label must spend a *text* ink, and a list row hosting a stretched target
+  must anchor it — both are class↔token pairings that every token-level assertion passes straight
+  through.
+- `browser/card-stretch.mjs`: the list case, asserting **row one** (the point that hides the bug is
+  row two, which passes even when the overlay belongs to another row).
+
+## [1.29.0] — 2026-08-18
+Improvement note 001 from a second consuming app (a 40-screen back office). Eight findings; six
+executed, one already documented, one left as an owner decision.
+### Added
+- **`clearable` on `FdyCfl`** (Vue · React · Blazor). The value type already said `Row | null`, but
+  the emit was `Row` only — a choose-from-list could be **set and never unset**, which breaks every
+  *optional* foreign key (a device with no project, an expense with no workflow, a top-level record
+  with no parent). A user who picked the wrong row had to reload the form. The clear control is a
+  second `.fdy-input-group__btn`, emits `null`, returns focus to the trigger, and never touches the
+  dialog.
+- **`.fdy-label--required`** — the marker is painted through `::after` with **CSS alt text**
+  (`content:"*" / ""`), so the glyph appears and the accessibility tree gets nothing. The control
+  already carries `required`; a `<span>` an app has to remember to mark `aria-hidden` can be
+  forgotten, this cannot.
+- **`.fdy-icon`** — a `1em` square, `flex:none` box for the icons the kit deliberately does not
+  ship. Every icon slot it *does* ship (`.fdy-btn__icon`, `.fdy-nav__icon`, `.fdy-state__icon`)
+  already assumed something sensible inside; a standalone icon had no contract.
+- **`.fdy-text-success` · `.fdy-text-warning` · `.fdy-text-danger`** — the kit had three
+  *de-emphasis* text roles and no *state* role, so a consequential sentence ("Amount changed from X
+  to Y", "No approver assigned") had to fall back to `.fdy-text-caption`, which de-emphasises
+  exactly the line that should stand out. A badge is wrong (prose, not a status) and an alert is
+  wrong (a block, not one line in a row).
+### Fixed
+- **`.fdy-menu__item:focus-visible` gets a real ring.** It marked focus with the same fill as
+  `:hover`, and `freeday-menu.js` moves real DOM focus — so arrowing through a menu was invisible,
+  and hover and focus were identical to everyone else. `.fdy-nav__item`, in the same kit, has always
+  done it correctly. Reported by two different apps before it was fixed.
+- **A grouped `<fieldset>` now has its spacing.** `fieldset.fdy-field` already reset the UA border,
+  but the **rendered legend is laid out outside the flex flow**, so `gap` never reached it —
+  measured 0px between legend and first control. One declaration on the reset the kit already
+  ships, not a new block; `COMPONENTS.md` documents the compose (`.fdy-field` on the fieldset,
+  `.fdy-label` on the legend), which is what was actually missing.
+### Notes on the shape of the fix
+- **§7 (an Indonesian `aria-label`) is not what it looked like.** The report assumed the rest of the
+  kit's output is English; it is not — *every* user-visible string the vanilla enhancers write is
+  Indonesian (`Sebelumnya`, `Berikutnya`, `Berisi teks`, `Reset`, `Tutup`, `Menampilkan …`,
+  `Bulan berikutnya`, `Format tidak valid.`). Translating one would **create** the mixed interface
+  the note objects to. The real choice — an override hook, or switching the defaults and breaking
+  every Indonesian consumer — is recorded in `NEXT-UP.md` #6 with its trigger; `COMPONENTS.md` now
+  states the caveat in full and points English apps at the typed wrappers.
+- **§8 needed no code**, only the line it asked for: the filter button and its dialog share an
+  accessible name on purpose, so a test suite wants `getByRole`, not `getByLabel`.
+- Two traps found by measuring rather than reading: `.fdy-icon` as a bare inline element **ignored
+  `width` entirely** (it does not apply to non-replaced inline boxes) and rendered 936px wide until
+  it got a `display`; and stacking two colour roles (`.fdy-help.fdy-text-warning`) silently loses to
+  whichever rule the bundle happens to emit later — documented, and the docs page no longer does it.
+### Added — guards
+- Adapter specs for `clearable` in both Vue and React (real clicks: emits `null`, empties the field,
+  the control disappears with the value it cleared, focus lands on the trigger, dialog stays shut).
+- CSS gate: menu focus must render as more than the hover fill; the required marker must keep its
+  alt text; `.fdy-icon` must keep a display that accepts a width; the state roles must spend the
+  exact inks the contrast gate proves readable — that last one closes the seam between the two test
+  files, where a class could drift to a weaker token while every token assertion stayed green.
+- `contrast.test.mjs` now also asserts the state inks on **plain** surfaces, not just over their own
+  `-soft` fills.
+
 ## [1.28.0] — 2026-08-18
 Improvement note 007, written while fixing a workspace picker whose cards showed a pointer cursor
 and swallowed every click.

package/COMPONENTS.md

@@ -212,6 +212,8 @@ One role per level of hierarchy — never re-use a card title for a page title.
 | `.fdy-title-card` | `<h3>` | A title inside a card or row (`.fdy-card__title` is equivalent). |
 | `.fdy-text-muted` · `.fdy-text-subtle` | any | Secondary / tertiary text colour. |
 | `.fdy-text-caption` | `<p>` | Small muted text: timestamps, help. |
+| `.fdy-text-success` · `.fdy-text-warning` · `.fdy-text-danger` | any | Inline text that carries **state** — a sentence, not a status. Use when a badge is wrong (it is prose) and an alert is wrong (it is one line inside a row): "Amount changed from X to Y", "No approver assigned". **Do not stack two colour roles** (`.fdy-help.fdy-text-warning`): both are single classes, so the one that happens to come later in the stylesheet wins — put the state class on its own element, and use `.fdy-help--error` for help text. |
+| `.fdy-icon` | `<svg>` or a wrapper | Icon box: `1em` square, `flex:none`, so the glyph tracks the text beside it at every scale. The kit ships no paths — bring your own, use the box. |
 | `.fdy-mono` | any | Tabular/monospace data (codes, amounts, ids). |
 
 ## Utilities
@@ -291,7 +293,23 @@ native control, otherwise a `<div>` + explicitly associated label.
 
 - `.fdy-field` (+ `--full` inside `.fdy-form-grid`; widths `--w-sm` `--w-lg` `--w-xl` `--w-2xl`
   `--w-grow` inside `.fdy-filterbar`)
-- `.fdy-label` · `.fdy-input` (+`--error`) · `.fdy-textarea` · `.fdy-help` (+`--error`)
+- `.fdy-label` (+`--required`) · `.fdy-input` (+`--error`) · `.fdy-textarea` · `.fdy-help` (+`--error`)
+
+**Grouped controls are a `<fieldset>`, not a new block.** Put `.fdy-field` on the fieldset and
+`.fdy-label` on the legend — the kit already resets the UA border/padding and supplies the spacing:
+
+```html
+<fieldset class="fdy-field">
+  <legend class="fdy-label">Working week</legend>
+  <label class="fdy-check"><input type="checkbox"> Monday</label>
+  <label class="fdy-check"><input type="checkbox"> Tuesday</label>
+</fieldset>
+```
+
+**`--required` marks the label, not the accessibility tree.** The control already carries
+`required`; the asterisk is painted through `::after` with CSS alt text, so a screen reader never
+reads "star" after the label — something a `<span>` you have to remember to mark `aria-hidden`
+cannot guarantee.
 - `[readonly]` is styled on input/textarea: full contrast, focusable, copyable.
 
 ```html
@@ -472,6 +490,13 @@ the field. The value is always **chosen, never typed**. Needs `freeday-cfl.js`.
 </dialog>
 ```
 
+**`clearable` makes the value removable.** Without it a choose-from-list can be set but never unset,
+which breaks every *optional* foreign key — the value type already allows null, only the component
+could not produce it. With it, a clear button appears beside the trigger whenever a row is picked
+and the field is editable; it emits `null` (Vue `update:modelValue`/`change`, React `onChange`,
+Blazor `ValueChanged`) and returns focus to the trigger. It is a second `.fdy-input-group__btn`, not
+a new class.
+
 ## Date picker — `data-fdy-datepicker`
 > **Typed wrapper: `<FdyDatepicker>`** — Vue (`v-model`) · React (`value`/`onChange`) · Blazor (`@bind-Value`). In those stacks use the wrapper; the markup below is for stacks without an adapter (and is what the wrapper renders).
 
@@ -660,10 +685,19 @@ pagination. Needs `freeday-table.js`. Wrap the whole thing in `.fdy-datatable` +
 - Footer: `.fdy-table-footer` · `__info` (`data-fdy-table-info`) + `<nav class="fdy-pagination"
   data-fdy-table-pagination>`
 - Sort values: put the raw value in `data-sort-value` when the cell text is formatted.
-- **Language caveat:** the vanilla enhancer writes the footer and bulk-count strings in Indonesian
-  (`Menampilkan 1–5 dari 7`, `N dipilih`) and has no override hook. The Vue/React/Blazor `FdyTable`
-  components are English. For an English static page, render those two nodes yourself from the
-  `fdy-table-change` event instead of using `data-fdy-table-info` / `data-fdy-table-bulk-count`.
+- **Language caveat:** every user-visible string the **vanilla enhancers** write is Indonesian —
+  the table's footer and bulk count (`Menampilkan 1–5 dari 7`, `N dipilih`), its pager and filter
+  UI (`Sebelumnya`, `Berikutnya`, `Filter kolom`, `Berisi teks`, `Reset`, `Tutup`), and the same
+  applies elsewhere (`Bulan berikutnya`, `Format tidak valid.`). There is no override hook. The
+  Vue/React/Blazor components are English throughout, so **an English app should use the typed
+  wrapper**, not the enhancer. For an English static page, render the footer/bulk nodes yourself
+  from the `fdy-table-change` event instead of using `data-fdy-table-info` /
+  `data-fdy-table-bulk-count`; the filter button's `aria-label` has no such escape today.
+
+**Testing note:** a column's filter button and the dialog it opens deliberately share one
+accessible name (`Filter <column>`) — a dialog named after its trigger is the normal pattern. In a
+Playwright/Testing-Library suite that means `getByLabel('Filter Name')` resolves to two elements;
+reach for `getByRole('button', { name: 'Filter Name' })` instead.
 
 ## Pagination — `.fdy-pagination`
 The block class on the `<nav>` is a **structural hook only** — it carries no rule of its own; the
@@ -928,9 +962,13 @@ while it stays a real `<button>`/`<a>` with real keyboard semantics.
 - **Do not add `.fdy-btn--stretch` to more than one control per card** — the last one wins the
   overlap, and which one that is depends on source order.
 - Text under the overlay is no longer selectable; that is the cost of the pattern, not a bug.
-- **Cards only.** The overlay anchors to the nearest *positioned* ancestor, and in the kit that is
-  `.fdy-card`. A `.fdy-list__row` is **not** positioned (`.fdy-list` is), so a stretched target in a
-  list row would cover the **whole list** — for clickable rows use `.fdy-list__row--button`.
+- **Cards and list rows.** The overlay anchors to the nearest *positioned* ancestor, and both hosts
+  supply one: `.fdy-card` always, `.fdy-list__row` when it contains a stretched target. Everything
+  above applies to a row unchanged — same markup, same automatic raise. In any *other* container,
+  make the element `position:relative` yourself, or the overlay resolves against whatever is
+  positioned further up (in a list that used to be `.fdy-list` itself, so every row's target covered
+  the whole list and the last one in the DOM won — a click on row one opened row two).
+  A row whose *whole* surface is one control is still better as `.fdy-list__row--button`.
 - `.fdy-btn` nudges itself on `:hover`/`:active`, and a transformed element becomes the containing
   block for its own absolutely positioned descendants — so a hand-rolled `::after{inset:0}` overlay
   **re-anchors to the button mid-gesture** and the click never lands. `--stretch` neutralises those

package/README.id.md

@@ -5,7 +5,7 @@
 > **Lebih banyak _free day_ buat dev — UI kit-nya sudah siap pakai.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v1.28.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.28.0)
+[![Release](https://img.shields.io/badge/release-v1.30.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.30.0)
 
 UI KIT yang token-driven & framework-agnostic — satu sumber kebenaran untuk warna, tipografi,
 spasi, dan komponen. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.

package/README.md

@@ -5,7 +5,7 @@
 > **More free days for devs — the UI kit is ready to use.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v1.28.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.28.0)
+[![Release](https://img.shields.io/badge/release-v1.30.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.30.0)
 
 A token-driven, framework-agnostic UI kit — one source of truth for color, typography,
 spacing, and components. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.

package/USAGE.md

@@ -27,6 +27,21 @@ the single biggest cause of "flat grey mush". Pick the role, not the size:
 Everything else is body. If you reach for a fourth title size, you probably need a section, not a
 font size.
 
+
+## Borders: two roles, two contrast contracts
+
+`--color-border` (and `-muted` / `-strong`) is **decoration** — a card edge, a table rule, a
+separator. Nothing in WCAG requires it to be visible, and it is deliberately faint (≈1.3:1).
+
+`--color-control-border` is the **boundary of a control** — input, textarea, checkbox, radio,
+switch, dropzone. WCAG 1.4.11 requires 3:1 against every surface it can sit on, so it is
+necessarily darker than a card edge; that difference is the contract, not an inconsistency.
+
+It is tuned to clear that floor with margin (≈3.4–3.9 depending on surface) rather than to be as
+dark as it can be: a boundary that reads as loud as body text makes a form feel heavier than it is.
+Do not "harmonise" a control border down to `--color-border` — that drops a required 3:1 boundary to
+1.3:1.
+
 ## 2. Spacing rhythm — three gaps, always from the scale
 
 Never a loose value; always `var(--space-N)` (a 4px scale). Three rhythms carry most layouts, and the

package/adapters/blazor/FdyCfl.razor

@@ -11,6 +11,15 @@
     <input class="fdy-input" type="text" readonly value="@DisplayValue"
            placeholder="@Placeholder" aria-labelledby="@AriaLabelledby"
            aria-invalid="@(Invalid ? "true" : null)" aria-readonly="@(Readonly ? "true" : null)" />
+    @if (Clearable && Value is not null && !Disabled && !Readonly)
+    {
+        <button class="fdy-input-group__btn" type="button" @onclick="ClearAsync" aria-label="@ClearLabel">
+            <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"
+                 stroke-width="2" stroke-linecap="round" aria-hidden="true">
+                <path d="M6 6l12 12M18 6L6 18"></path>
+            </svg>
+        </button>
+    }
     <button class="fdy-input-group__btn" type="button" @onclick="OpenAsync"
             disabled="@(Disabled || Readonly)" aria-label="@SearchPlaceholder">
         <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"

package/adapters/blazor/FdyCfl.razor.cs

@@ -37,6 +37,11 @@ public partial class FdyCfl<TRow>
     /// <summary>Locked/view mode: shows the value but the search dialog can't be opened.</summary>
     [Parameter] public bool Readonly { get; set; }
     [Parameter] public bool Invalid { get; set; }
+    /// <summary>Render a clear button when a row is picked, so an OPTIONAL foreign key can be unset.
+    /// <c>Value</c> is already <c>TRow?</c>; without this the component can never produce null.</summary>
+    [Parameter] public bool Clearable { get; set; }
+    /// <summary>aria-label for the clear button (when <see cref="Clearable"/>).</summary>
+    [Parameter] public string ClearLabel { get; set; } = "Clear selection";
     [Parameter] public string? AriaLabelledby { get; set; }
 
     /// <summary>Debounce (ms) between a keystroke and the search request.</summary>
@@ -129,6 +134,14 @@ public partial class FdyCfl<TRow>
 
     private Task RetryAsync() => LoadAsync(reset: true);
 
+    /// <summary>Unset the value. Not "choosing nothing": the dialog is not involved, so this neither
+    /// opens nor closes it.</summary>
+    private async Task ClearAsync()
+    {
+        Value = default;
+        await ValueChanged.InvokeAsync(default);
+    }
+
     private async Task ChooseAsync(TRow row)
     {
         Value = row;

package/adapters/react/components/FdyCfl.tsx

@@ -22,7 +22,7 @@ export interface CflPage<Row> {
 
 export interface FdyCflProps<Row extends Record<string, unknown>> {
   value: Row | null;
-  onChange: (value: Row) => void;
+  onChange: (value: Row | null) => void;
   fetchPage: (query: string, page: number) => Promise<CflPage<Row>>;
   columns: ReadonlyArray<CflColumn<Row>>;
   display: (row: Row) => string;
@@ -34,6 +34,11 @@ export interface FdyCflProps<Row extends Record<string, unknown>> {
   /** Locked/view mode: shows the picked value (focusable, copyable), but the search dialog can't be opened. Unlike `disabled`, it keeps tab order and isn't greyed. */
   readonly?: boolean;
   invalid?: boolean;
+  /** Render a clear button when a row is picked, so an OPTIONAL foreign key can be unset. Without it
+   *  `value` accepts `Row | null` but the component can only ever produce a `Row`. */
+  clearable?: boolean;
+  /** aria-label for the clear button (when `clearable`). Default 'Clear selection'. */
+  clearLabel?: string;
   describedby?: string;
   id?: string;
   ariaLabelledby?: string;
@@ -46,6 +51,14 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
   const resultsId: string = `${baseId}-results`;
   const rowId = (index: number): string => `${baseId}-row-${index}`;
 
+  /* Unsetting is not "picking nothing": it must not touch the dialog, and focus must land on a
+     control that still exists — the trigger beside it, since this button disappears with the value. */
+  const clearLabelText: string = props.clearLabel ?? 'Clear selection';
+  const clearValue = (): void => {
+    props.onChange(null);
+    triggerRef.current?.focus();
+  };
+
   const dialogRef = useRef<HTMLDialogElement>(null);
   const triggerRef = useRef<HTMLButtonElement>(null);
   const searchRef = useRef<HTMLInputElement>(null);
@@ -71,6 +84,8 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
 
   const isDisabled: boolean = props.disabled === true;
   const isReadonly: boolean = props.readonly === true;
+  const showClear: boolean =
+    props.clearable === true && props.value !== null && isDisabled === false && isReadonly === false;
   const isInvalid: boolean = props.invalid === true;
   const displayValue: string = props.value !== null ? props.display(props.value) : '';
   // The results <table> (owner of `resultsId`) only renders in the rows branch, so gate the
@@ -253,6 +268,18 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
         aria-describedby={props.describedby}
         disabled={isDisabled}
       />
+      {showClear ? (
+        <button
+          type="button"
+          className="fdy-input-group__btn"
+          aria-label={clearLabelText}
+          onClick={clearValue}
+        >
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" aria-hidden="true">
+            <path d="M6 6l12 12M18 6L6 18" />
+          </svg>
+        </button>
+      ) : null}
       <button
         ref={triggerRef}
         type="button"

package/adapters/vue/components/FdyCfl.vue

@@ -35,14 +35,19 @@ const props = defineProps<{
   /** Locked/view mode: shows the picked value (focusable, copyable), but the search dialog can't be opened. Unlike `disabled`, it keeps tab order and isn't greyed. */
   readonly?: boolean;
   invalid?: boolean;
+  /** Render a clear button when a row is picked, so an OPTIONAL foreign key can be unset. Without it
+   *  `modelValue` accepts `Row | null` but the component can only ever produce a `Row`. */
+  clearable?: boolean;
+  /** aria-label for the clear button (when `clearable`). Default 'Clear selection'. */
+  clearLabel?: string;
   describedby?: string;
   id?: string;
   ariaLabelledby?: string;
 }>();
 
 const emit = defineEmits<{
-  'update:modelValue': [value: Row];
-  change: [value: Row];
+  'update:modelValue': [value: Row | null];
+  change: [value: Row | null];
 }>();
 
 const baseId: string = useId();
@@ -67,6 +72,12 @@ const activeIndex: Ref<number> = ref(-1);
 
 const isDisabled: ComputedRef<boolean> = computed((): boolean => props.disabled === true);
 const isReadonly: ComputedRef<boolean> = computed((): boolean => props.readonly === true);
+
+const showClear: ComputedRef<boolean> = computed(
+  (): boolean =>
+    props.clearable === true && props.modelValue != null && isDisabled.value === false && isReadonly.value === false,
+);
+const clearLabelText: ComputedRef<string> = computed((): string => props.clearLabel ?? 'Clear selection');
 const isInvalid: ComputedRef<boolean> = computed((): boolean => props.invalid === true);
 const displayValue: ComputedRef<string> = computed((): string =>
   props.modelValue !== null ? props.display(props.modelValue) : '',
@@ -154,12 +165,20 @@ function setActive(index: number): void {
   });
 }
 
-function commit(row: Row): void {
+function commit(row: Row | null): void {
   emit('update:modelValue', row);
   emit('change', row);
   closeDialog();
 }
 
+/* Unsetting is not "picking nothing" — it must not open or close the dialog, and it must leave focus
+   on a control that still exists, so focus returns to the trigger beside it. */
+function clearValue(): void {
+  emit('update:modelValue', null);
+  emit('change', null);
+  triggerEl.value?.focus();
+}
+
 function onKeydown(e: KeyboardEvent): void {
   switch (e.key) {
     case 'ArrowDown':
@@ -256,6 +275,17 @@ onBeforeUnmount((): void => {
       :aria-describedby="describedby"
       :disabled="isDisabled"
     />
+    <button
+      v-if="showClear"
+      type="button"
+      class="fdy-input-group__btn"
+      :aria-label="clearLabelText"
+      @click="clearValue"
+    >
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true">
+        <path d="M6 6l12 12M18 6L6 18"></path>
+      </svg>
+    </button>
     <button
       ref="triggerEl"
       type="button"

package/dist/freeday.bundle.css

@@ -18,6 +18,7 @@
   --slate-200: #e0e3ea;
   --slate-300: #cbd0da;
   --slate-400: #99a1b3;
+  --slate-450: #798295;
   --slate-500: #6b7488;
   --slate-600: #4d5568;
   --slate-700: #3a4152;
@@ -138,7 +139,7 @@
   --color-border: var(--slate-200);
   --color-border-strong: var(--slate-300);
   --color-border-muted: var(--slate-100);
-  --color-control-border: var(--slate-500);
+  --color-control-border: var(--slate-450);
   --color-switch-thumb: var(--slate-0);
   --color-shadow-inset: rgba(16,14,30,.06);
   --color-inverse-surface: var(--slate-900);
@@ -209,7 +210,7 @@
   --color-border: var(--slate-800);
   --color-border-strong: var(--slate-700);
   --color-border-muted: #1c2130;
-  --color-control-border: var(--slate-500);
+  --color-control-border: var(--slate-450);
   --color-inverse-surface: var(--slate-100);
   --color-inverse-text: var(--slate-900);
   --color-success: var(--green-500);
@@ -272,7 +273,7 @@
   --color-border: var(--slate-800);
   --color-border-strong: var(--slate-700);
   --color-border-muted: #1c2130;
-  --color-control-border: var(--slate-500);
+  --color-control-border: var(--slate-450);
   --color-inverse-surface: var(--slate-100);
   --color-inverse-text: var(--slate-900);
   --color-success: var(--green-500);
@@ -328,7 +329,7 @@
   --color-border: var(--slate-200);
   --color-border-strong: var(--slate-300);
   --color-border-muted: var(--slate-100);
-  --color-control-border: var(--slate-500);
+  --color-control-border: var(--slate-450);
   --color-inverse-surface: var(--slate-900);
   --color-inverse-text: var(--slate-0);
   --color-success: var(--green-600);
@@ -779,13 +780,13 @@ a { color: var(--color-primary); }
    because forgetting it fails SILENTLY: the secondary control looks and hovers exactly as before and
    simply never receives the click, which is the very symptom the pattern exists to cure. Matched by
    shape (anything focusable) so a control the kit does not ship yet is covered too. */
-.fdy-card:has(.fdy-btn--stretch) :is(a[href],button,input,select,textarea,[tabindex]):not(.fdy-btn--stretch){z-index:1;}
+:is(.fdy-card,.fdy-list__row):has(.fdy-btn--stretch) :is(a[href],button,input,select,textarea,[tabindex]):not(.fdy-btn--stretch){z-index:1;}
 /* The position is a DEFAULT, not an override: z-index needs a positioned box (or a flex/grid item),
    but an app that deliberately pins a control inside the card — a corner dismiss, a favourite star —
    must keep its own `position:absolute`. Wrapped in :where() so this whole selector weighs nothing
    and ANY app rule wins it; measured, because at normal specificity the kit silently dragged an
    absolutely positioned dismiss button back into the flow. Do not merge these two rules. */
-:where(.fdy-card:has(.fdy-btn--stretch) :is(a[href],button,input,select,textarea,[tabindex]):not(.fdy-btn--stretch)){position:relative;}
+:where(:is(.fdy-card,.fdy-list__row):has(.fdy-btn--stretch) :is(a[href],button,input,select,textarea,[tabindex]):not(.fdy-btn--stretch)){position:relative;}
 .fdy-card__body{padding:var(--space-5);}
 .fdy-card__title{font-family:var(--font-display);font-size:var(--text-lg);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);color:var(--color-text);margin:0 0 var(--space-1);}
 .fdy-card__desc{font-size:var(--text-sm);color:var(--color-text-muted);margin:0;line-height:var(--leading-normal);}
@@ -1043,7 +1044,10 @@ a { color: var(--color-primary); }
  * single boxed strip, or use .fdy-stats--boxed for shared surface + dividers. */
 .fdy-stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));gap:var(--space-5);}
 .fdy-stat{display:flex;flex-direction:column;gap:var(--space-1);min-width:0;}
-.fdy-stat__label{font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-wide);text-transform:uppercase;color:var(--color-text-subtle);}
+/* --color-text-muted, not -subtle: this is a LABEL, i.e. text, and -subtle is deliberately gated at
+   3.0 (placeholders, dividers, decorative glyphs). On surface-2 -subtle measures 4.41 — under AA
+   for text, and a stat label is often the only thing naming the number above it. */
+.fdy-stat__label{font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-wide);text-transform:uppercase;color:var(--color-text-muted);}
 .fdy-stat__value{font-family:var(--font-display);font-size:var(--text-3xl);font-weight:var(--weight-bold);letter-spacing:var(--tracking-tighter);line-height:1;color:var(--color-text);font-variant-numeric:tabular-nums;}
 .fdy-stat__value small{font-size:var(--text-lg);font-weight:var(--weight-semibold);color:var(--color-text-muted);}
 .fdy-stat__meta{font-size:var(--text-sm);color:var(--color-text-muted);display:flex;align-items:center;gap:var(--space-2);}
@@ -1051,6 +1055,22 @@ a { color: var(--color-primary); }
 .fdy-stats--boxed .fdy-stat{padding:var(--space-5);border-right:var(--bw) solid var(--color-border-muted);}
 .fdy-stats--boxed .fdy-stat:last-child{border-right:0;}
 
+/* Icon box (#001 §4). The kit ships no icons on purpose, but every icon slot it DOES ship
+   (.fdy-btn__icon, .fdy-nav__icon, .fdy-state__icon) assumes something sensible inside, so a
+   standalone icon had no contract and every app invented one. 1em keeps the glyph matched to the
+   text beside it at every scale — bring your own paths, use our box. Works on the <svg> itself or
+   on a wrapper around it. */
+.fdy-icon{display:inline-block;width:1em;height:1em;flex:none;vertical-align:-0.125em;}
+.fdy-icon>svg{display:block;width:100%;height:100%;}
+
+/* Inline text that carries STATE (#001 §5). The three roles above all de-emphasise; a sentence like
+   "Amount changed from X to Y" or "No approver assigned" needs the opposite, and is neither a badge
+   (those are statuses, not sentences) nor an .fdy-alert (those are blocks, not one line inside a
+   row). Same -strong inks the badges use, gated by contrast.test.mjs on plain surfaces too. */
+.fdy-text-success{color:var(--color-success-strong);}
+.fdy-text-warning{color:var(--color-warning-strong);}
+.fdy-text-danger{color:var(--color-danger-strong);}
+
 /* Freeday — Date picker (input-styled trigger + calendar popover).
  * Built by freeday-datepicker.js from an empty [data-fdy-datepicker] wrapper. */
 .fdy-datepicker{position:relative;display:inline-block;width:100%;max-width:14rem;}
@@ -1277,7 +1297,10 @@ a { color: var(--color-primary); }
    Neutralise the UA groove border / padding / min-inline-size so it lays out identically to the
    <div> form (min-inline-size:min-content would otherwise block the filterbar column widths). */
 fieldset.fdy-field{border:0;margin:0;padding:0;min-inline-size:0;}
-fieldset.fdy-field>legend{padding:0;float:none;}
+/* The rendered legend is laid out outside the fieldset's flex flow, so `gap` never reaches it —
+   measured 0px between legend and first control. This is the spacing contract a grouped field
+   needs; it matches .fdy-field's own gap so the group reads as one rhythm. */
+fieldset.fdy-field>legend{padding:0;float:none;margin-bottom:var(--space-2);}
 .fdy-label{font-size:var(--text-sm);font-weight:var(--weight-medium);color:var(--color-text);}
 .fdy-input,.fdy-textarea{width:100%;height:var(--control-h);padding:0 var(--space-3);font-family:var(--font-body);font-size:var(--text-sm);color:var(--color-text);background:var(--color-surface);border:1.5px solid var(--color-control-border);border-radius:var(--radius-md);box-shadow:inset 0 1px 2px rgba(16,14,30,.06);transition:border-color var(--dur-fast) var(--ease-standard),box-shadow var(--dur-fast) var(--ease-standard);}
 .fdy-input::placeholder,.fdy-textarea::placeholder{color:var(--color-text-subtle);}
@@ -1301,6 +1324,11 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-input[type="number"]::-webkit-outer-spin-button,.fdy-input[type="number"]::-webkit-inner-spin-button{appearance:none;-webkit-appearance:none;margin:0;}
 .fdy-input--error,.fdy-input[aria-invalid="true"],.fdy-textarea[aria-invalid="true"]{border-color:var(--color-danger);}
 .fdy-input--error:focus,.fdy-input[aria-invalid="true"]:focus,.fdy-textarea[aria-invalid="true"]:focus{border-color:var(--color-danger);box-shadow:0 0 0 3px color-mix(in srgb,var(--color-danger) 26%,transparent);}
+/* Required marker. The control already carries `required`, so the asterisk is decoration: the
+   `/ ""` is CSS alt text — the glyph is painted but exposes NOTHING to the accessibility tree, so a
+   screen reader does not read "star" after every label. That is stricter than a <span> an app has to
+   remember to mark aria-hidden, and it cannot be forgotten. */
+.fdy-label--required::after{content:"*" / "";margin-left:var(--space-1);color:var(--color-danger);}
 .fdy-help{font-size:var(--text-xs);color:var(--color-text-muted);}
 .fdy-help--error{color:var(--color-danger);}
 
@@ -1319,6 +1347,13 @@ fieldset.fdy-field>legend{padding:0;float:none;}
  * Works on <ul>/<ol> (list-style is reset here) or on plain <div>s. */
 /* position:relative — containing block for out-of-flow row content (see base.css). */
 .fdy-list{position:relative;list-style:none;margin:0;padding:0;background:var(--color-surface);border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);overflow:hidden;}
+/* A row that hosts a stretched target has to be the anchor itself (#008 §1). Without this the
+   overlay resolves against .fdy-list — which IS positioned — so EVERY row's target covers the whole
+   list and the last one in the DOM wins: measured, a click on row one opens row two, under row one's
+   name, which looks exactly like working software. Opt-in via :has(), so a row that doesn't use the
+   pattern is untouched and nothing an app absolutely positions inside a plain row starts resolving
+   against a new containing block. The escape-hatch raise lives in card.css beside the card's. */
+.fdy-list__row:has(.fdy-btn--stretch){position:relative;}
 .fdy-list__row{display:flex;align-items:center;gap:var(--space-3);padding:var(--space-4) var(--space-5);min-width:0;}
 /* Divider between rows. Two shapes are supported and both are load-bearing: rows as direct children
  * of the list, and rows wrapped in <li> (the semantic shape, where the ADJACENT siblings are the
@@ -1351,7 +1386,10 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-menu--end{left:auto;right:0;}
 .fdy-menu__item{display:flex;align-items:center;gap:var(--space-2);width:100%;padding:var(--space-2) var(--space-3);border:0;background:transparent;border-radius:var(--radius-sm);font-family:var(--font-body);font-size:var(--text-sm);color:var(--color-text);text-align:left;cursor:pointer;white-space:nowrap;}
 .fdy-menu__item:hover,.fdy-menu__item.is-highlighted{background:var(--color-surface-3);}
-.fdy-menu__item:focus-visible{outline:none;background:var(--color-surface-3);}
+/* Focus is not hover. The enhancer moves real DOM focus (freeday-menu.js `.focus()`), so this is
+   the only thing a keyboard user has to go on — with the hover fill alone, arrowing through the
+   menu is invisible. Same ring as .fdy-nav__item, which got this right. Reported twice. */
+.fdy-menu__item:focus-visible{outline:none;background:var(--color-surface-3);box-shadow:0 0 0 2px color-mix(in srgb,var(--color-primary) 45%,transparent);}
 .fdy-menu__item:disabled{opacity:.5;cursor:not-allowed;background:transparent;}
 .fdy-menu__item--danger{color:var(--color-danger-strong);}
 .fdy-menu__item svg{display:block;width:1rem;height:1rem;flex:none;}

package/dist/freeday.css

@@ -409,13 +409,13 @@ a { color: var(--color-primary); }
    because forgetting it fails SILENTLY: the secondary control looks and hovers exactly as before and
    simply never receives the click, which is the very symptom the pattern exists to cure. Matched by
    shape (anything focusable) so a control the kit does not ship yet is covered too. */
-.fdy-card:has(.fdy-btn--stretch) :is(a[href],button,input,select,textarea,[tabindex]):not(.fdy-btn--stretch){z-index:1;}
+:is(.fdy-card,.fdy-list__row):has(.fdy-btn--stretch) :is(a[href],button,input,select,textarea,[tabindex]):not(.fdy-btn--stretch){z-index:1;}
 /* The position is a DEFAULT, not an override: z-index needs a positioned box (or a flex/grid item),
    but an app that deliberately pins a control inside the card — a corner dismiss, a favourite star —
    must keep its own `position:absolute`. Wrapped in :where() so this whole selector weighs nothing
    and ANY app rule wins it; measured, because at normal specificity the kit silently dragged an
    absolutely positioned dismiss button back into the flow. Do not merge these two rules. */
-:where(.fdy-card:has(.fdy-btn--stretch) :is(a[href],button,input,select,textarea,[tabindex]):not(.fdy-btn--stretch)){position:relative;}
+:where(:is(.fdy-card,.fdy-list__row):has(.fdy-btn--stretch) :is(a[href],button,input,select,textarea,[tabindex]):not(.fdy-btn--stretch)){position:relative;}
 .fdy-card__body{padding:var(--space-5);}
 .fdy-card__title{font-family:var(--font-display);font-size:var(--text-lg);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);color:var(--color-text);margin:0 0 var(--space-1);}
 .fdy-card__desc{font-size:var(--text-sm);color:var(--color-text-muted);margin:0;line-height:var(--leading-normal);}
@@ -673,7 +673,10 @@ a { color: var(--color-primary); }
  * single boxed strip, or use .fdy-stats--boxed for shared surface + dividers. */
 .fdy-stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));gap:var(--space-5);}
 .fdy-stat{display:flex;flex-direction:column;gap:var(--space-1);min-width:0;}
-.fdy-stat__label{font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-wide);text-transform:uppercase;color:var(--color-text-subtle);}
+/* --color-text-muted, not -subtle: this is a LABEL, i.e. text, and -subtle is deliberately gated at
+   3.0 (placeholders, dividers, decorative glyphs). On surface-2 -subtle measures 4.41 — under AA
+   for text, and a stat label is often the only thing naming the number above it. */
+.fdy-stat__label{font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-wide);text-transform:uppercase;color:var(--color-text-muted);}
 .fdy-stat__value{font-family:var(--font-display);font-size:var(--text-3xl);font-weight:var(--weight-bold);letter-spacing:var(--tracking-tighter);line-height:1;color:var(--color-text);font-variant-numeric:tabular-nums;}
 .fdy-stat__value small{font-size:var(--text-lg);font-weight:var(--weight-semibold);color:var(--color-text-muted);}
 .fdy-stat__meta{font-size:var(--text-sm);color:var(--color-text-muted);display:flex;align-items:center;gap:var(--space-2);}
@@ -681,6 +684,22 @@ a { color: var(--color-primary); }
 .fdy-stats--boxed .fdy-stat{padding:var(--space-5);border-right:var(--bw) solid var(--color-border-muted);}
 .fdy-stats--boxed .fdy-stat:last-child{border-right:0;}
 
+/* Icon box (#001 §4). The kit ships no icons on purpose, but every icon slot it DOES ship
+   (.fdy-btn__icon, .fdy-nav__icon, .fdy-state__icon) assumes something sensible inside, so a
+   standalone icon had no contract and every app invented one. 1em keeps the glyph matched to the
+   text beside it at every scale — bring your own paths, use our box. Works on the <svg> itself or
+   on a wrapper around it. */
+.fdy-icon{display:inline-block;width:1em;height:1em;flex:none;vertical-align:-0.125em;}
+.fdy-icon>svg{display:block;width:100%;height:100%;}
+
+/* Inline text that carries STATE (#001 §5). The three roles above all de-emphasise; a sentence like
+   "Amount changed from X to Y" or "No approver assigned" needs the opposite, and is neither a badge
+   (those are statuses, not sentences) nor an .fdy-alert (those are blocks, not one line inside a
+   row). Same -strong inks the badges use, gated by contrast.test.mjs on plain surfaces too. */
+.fdy-text-success{color:var(--color-success-strong);}
+.fdy-text-warning{color:var(--color-warning-strong);}
+.fdy-text-danger{color:var(--color-danger-strong);}
+
 /* Freeday — Date picker (input-styled trigger + calendar popover).
  * Built by freeday-datepicker.js from an empty [data-fdy-datepicker] wrapper. */
 .fdy-datepicker{position:relative;display:inline-block;width:100%;max-width:14rem;}
@@ -907,7 +926,10 @@ a { color: var(--color-primary); }
    Neutralise the UA groove border / padding / min-inline-size so it lays out identically to the
    <div> form (min-inline-size:min-content would otherwise block the filterbar column widths). */
 fieldset.fdy-field{border:0;margin:0;padding:0;min-inline-size:0;}
-fieldset.fdy-field>legend{padding:0;float:none;}
+/* The rendered legend is laid out outside the fieldset's flex flow, so `gap` never reaches it —
+   measured 0px between legend and first control. This is the spacing contract a grouped field
+   needs; it matches .fdy-field's own gap so the group reads as one rhythm. */
+fieldset.fdy-field>legend{padding:0;float:none;margin-bottom:var(--space-2);}
 .fdy-label{font-size:var(--text-sm);font-weight:var(--weight-medium);color:var(--color-text);}
 .fdy-input,.fdy-textarea{width:100%;height:var(--control-h);padding:0 var(--space-3);font-family:var(--font-body);font-size:var(--text-sm);color:var(--color-text);background:var(--color-surface);border:1.5px solid var(--color-control-border);border-radius:var(--radius-md);box-shadow:inset 0 1px 2px rgba(16,14,30,.06);transition:border-color var(--dur-fast) var(--ease-standard),box-shadow var(--dur-fast) var(--ease-standard);}
 .fdy-input::placeholder,.fdy-textarea::placeholder{color:var(--color-text-subtle);}
@@ -931,6 +953,11 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-input[type="number"]::-webkit-outer-spin-button,.fdy-input[type="number"]::-webkit-inner-spin-button{appearance:none;-webkit-appearance:none;margin:0;}
 .fdy-input--error,.fdy-input[aria-invalid="true"],.fdy-textarea[aria-invalid="true"]{border-color:var(--color-danger);}
 .fdy-input--error:focus,.fdy-input[aria-invalid="true"]:focus,.fdy-textarea[aria-invalid="true"]:focus{border-color:var(--color-danger);box-shadow:0 0 0 3px color-mix(in srgb,var(--color-danger) 26%,transparent);}
+/* Required marker. The control already carries `required`, so the asterisk is decoration: the
+   `/ ""` is CSS alt text — the glyph is painted but exposes NOTHING to the accessibility tree, so a
+   screen reader does not read "star" after every label. That is stricter than a <span> an app has to
+   remember to mark aria-hidden, and it cannot be forgotten. */
+.fdy-label--required::after{content:"*" / "";margin-left:var(--space-1);color:var(--color-danger);}
 .fdy-help{font-size:var(--text-xs);color:var(--color-text-muted);}
 .fdy-help--error{color:var(--color-danger);}
 
@@ -949,6 +976,13 @@ fieldset.fdy-field>legend{padding:0;float:none;}
  * Works on <ul>/<ol> (list-style is reset here) or on plain <div>s. */
 /* position:relative — containing block for out-of-flow row content (see base.css). */
 .fdy-list{position:relative;list-style:none;margin:0;padding:0;background:var(--color-surface);border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);overflow:hidden;}
+/* A row that hosts a stretched target has to be the anchor itself (#008 §1). Without this the
+   overlay resolves against .fdy-list — which IS positioned — so EVERY row's target covers the whole
+   list and the last one in the DOM wins: measured, a click on row one opens row two, under row one's
+   name, which looks exactly like working software. Opt-in via :has(), so a row that doesn't use the
+   pattern is untouched and nothing an app absolutely positions inside a plain row starts resolving
+   against a new containing block. The escape-hatch raise lives in card.css beside the card's. */
+.fdy-list__row:has(.fdy-btn--stretch){position:relative;}
 .fdy-list__row{display:flex;align-items:center;gap:var(--space-3);padding:var(--space-4) var(--space-5);min-width:0;}
 /* Divider between rows. Two shapes are supported and both are load-bearing: rows as direct children
  * of the list, and rows wrapped in <li> (the semantic shape, where the ADJACENT siblings are the
@@ -981,7 +1015,10 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-menu--end{left:auto;right:0;}
 .fdy-menu__item{display:flex;align-items:center;gap:var(--space-2);width:100%;padding:var(--space-2) var(--space-3);border:0;background:transparent;border-radius:var(--radius-sm);font-family:var(--font-body);font-size:var(--text-sm);color:var(--color-text);text-align:left;cursor:pointer;white-space:nowrap;}
 .fdy-menu__item:hover,.fdy-menu__item.is-highlighted{background:var(--color-surface-3);}
-.fdy-menu__item:focus-visible{outline:none;background:var(--color-surface-3);}
+/* Focus is not hover. The enhancer moves real DOM focus (freeday-menu.js `.focus()`), so this is
+   the only thing a keyboard user has to go on — with the hover fill alone, arrowing through the
+   menu is invisible. Same ring as .fdy-nav__item, which got this right. Reported twice. */
+.fdy-menu__item:focus-visible{outline:none;background:var(--color-surface-3);box-shadow:0 0 0 2px color-mix(in srgb,var(--color-primary) 45%,transparent);}
 .fdy-menu__item:disabled{opacity:.5;cursor:not-allowed;background:transparent;}
 .fdy-menu__item--danger{color:var(--color-danger-strong);}
 .fdy-menu__item svg{display:block;width:1rem;height:1rem;flex:none;}

package/dist/freeday.tokens.css

@@ -17,6 +17,7 @@
   --slate-200: #e0e3ea;
   --slate-300: #cbd0da;
   --slate-400: #99a1b3;
+  --slate-450: #798295;
   --slate-500: #6b7488;
   --slate-600: #4d5568;
   --slate-700: #3a4152;
@@ -137,7 +138,7 @@
   --color-border: var(--slate-200);
   --color-border-strong: var(--slate-300);
   --color-border-muted: var(--slate-100);
-  --color-control-border: var(--slate-500);
+  --color-control-border: var(--slate-450);
   --color-switch-thumb: var(--slate-0);
   --color-shadow-inset: rgba(16,14,30,.06);
   --color-inverse-surface: var(--slate-900);
@@ -208,7 +209,7 @@
   --color-border: var(--slate-800);
   --color-border-strong: var(--slate-700);
   --color-border-muted: #1c2130;
-  --color-control-border: var(--slate-500);
+  --color-control-border: var(--slate-450);
   --color-inverse-surface: var(--slate-100);
   --color-inverse-text: var(--slate-900);
   --color-success: var(--green-500);
@@ -271,7 +272,7 @@
   --color-border: var(--slate-800);
   --color-border-strong: var(--slate-700);
   --color-border-muted: #1c2130;
-  --color-control-border: var(--slate-500);
+  --color-control-border: var(--slate-450);
   --color-inverse-surface: var(--slate-100);
   --color-inverse-text: var(--slate-900);
   --color-success: var(--green-500);
@@ -327,7 +328,7 @@
   --color-border: var(--slate-200);
   --color-border-strong: var(--slate-300);
   --color-border-muted: var(--slate-100);
-  --color-control-border: var(--slate-500);
+  --color-control-border: var(--slate-450);
   --color-inverse-surface: var(--slate-900);
   --color-inverse-text: var(--slate-0);
   --color-success: var(--green-600);

package/docs/getting-started.md

@@ -184,7 +184,7 @@ live docs also have a copy button per component.
 ```bash
 npm i @cahyo-dimas/freeday
 ```
-Lands in `package.json` as `"@cahyo-dimas/freeday": "^1.28.0"` (public npm package). `dist/` is
+Lands in `package.json` as `"@cahyo-dimas/freeday": "^1.30.0"` (public npm package). `dist/` is
 committed and published → no build step; `npm ci` runs without auth.
 
 ### 2. Import the CSS + enhancers **once** in your entry (`src/main.ts`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cahyo-dimas/freeday",
-  "version": "1.28.0",
+  "version": "1.30.0",
   "description": "Freeday — token-driven, framework-agnostic UI KIT (design source-of-truth).",
   "type": "module",
   "license": "MIT",

package/src/components/card.css

@@ -24,13 +24,13 @@
    because forgetting it fails SILENTLY: the secondary control looks and hovers exactly as before and
    simply never receives the click, which is the very symptom the pattern exists to cure. Matched by
    shape (anything focusable) so a control the kit does not ship yet is covered too. */
-.fdy-card:has(.fdy-btn--stretch) :is(a[href],button,input,select,textarea,[tabindex]):not(.fdy-btn--stretch){z-index:1;}
+:is(.fdy-card,.fdy-list__row):has(.fdy-btn--stretch) :is(a[href],button,input,select,textarea,[tabindex]):not(.fdy-btn--stretch){z-index:1;}
 /* The position is a DEFAULT, not an override: z-index needs a positioned box (or a flex/grid item),
    but an app that deliberately pins a control inside the card — a corner dismiss, a favourite star —
    must keep its own `position:absolute`. Wrapped in :where() so this whole selector weighs nothing
    and ANY app rule wins it; measured, because at normal specificity the kit silently dragged an
    absolutely positioned dismiss button back into the flow. Do not merge these two rules. */
-:where(.fdy-card:has(.fdy-btn--stretch) :is(a[href],button,input,select,textarea,[tabindex]):not(.fdy-btn--stretch)){position:relative;}
+:where(:is(.fdy-card,.fdy-list__row):has(.fdy-btn--stretch) :is(a[href],button,input,select,textarea,[tabindex]):not(.fdy-btn--stretch)){position:relative;}
 .fdy-card__body{padding:var(--space-5);}
 .fdy-card__title{font-family:var(--font-display);font-size:var(--text-lg);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);color:var(--color-text);margin:0 0 var(--space-1);}
 .fdy-card__desc{font-size:var(--text-sm);color:var(--color-text-muted);margin:0;line-height:var(--leading-normal);}

package/src/components/composition.css

@@ -40,10 +40,29 @@
  * single boxed strip, or use .fdy-stats--boxed for shared surface + dividers. */
 .fdy-stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));gap:var(--space-5);}
 .fdy-stat{display:flex;flex-direction:column;gap:var(--space-1);min-width:0;}
-.fdy-stat__label{font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-wide);text-transform:uppercase;color:var(--color-text-subtle);}
+/* --color-text-muted, not -subtle: this is a LABEL, i.e. text, and -subtle is deliberately gated at
+   3.0 (placeholders, dividers, decorative glyphs). On surface-2 -subtle measures 4.41 — under AA
+   for text, and a stat label is often the only thing naming the number above it. */
+.fdy-stat__label{font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-wide);text-transform:uppercase;color:var(--color-text-muted);}
 .fdy-stat__value{font-family:var(--font-display);font-size:var(--text-3xl);font-weight:var(--weight-bold);letter-spacing:var(--tracking-tighter);line-height:1;color:var(--color-text);font-variant-numeric:tabular-nums;}
 .fdy-stat__value small{font-size:var(--text-lg);font-weight:var(--weight-semibold);color:var(--color-text-muted);}
 .fdy-stat__meta{font-size:var(--text-sm);color:var(--color-text-muted);display:flex;align-items:center;gap:var(--space-2);}
 .fdy-stats--boxed{background:var(--color-surface);border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);box-shadow:var(--shadow-1);gap:0;}
 .fdy-stats--boxed .fdy-stat{padding:var(--space-5);border-right:var(--bw) solid var(--color-border-muted);}
 .fdy-stats--boxed .fdy-stat:last-child{border-right:0;}
+
+/* Icon box (#001 §4). The kit ships no icons on purpose, but every icon slot it DOES ship
+   (.fdy-btn__icon, .fdy-nav__icon, .fdy-state__icon) assumes something sensible inside, so a
+   standalone icon had no contract and every app invented one. 1em keeps the glyph matched to the
+   text beside it at every scale — bring your own paths, use our box. Works on the <svg> itself or
+   on a wrapper around it. */
+.fdy-icon{display:inline-block;width:1em;height:1em;flex:none;vertical-align:-0.125em;}
+.fdy-icon>svg{display:block;width:100%;height:100%;}
+
+/* Inline text that carries STATE (#001 §5). The three roles above all de-emphasise; a sentence like
+   "Amount changed from X to Y" or "No approver assigned" needs the opposite, and is neither a badge
+   (those are statuses, not sentences) nor an .fdy-alert (those are blocks, not one line inside a
+   row). Same -strong inks the badges use, gated by contrast.test.mjs on plain surfaces too. */
+.fdy-text-success{color:var(--color-success-strong);}
+.fdy-text-warning{color:var(--color-warning-strong);}
+.fdy-text-danger{color:var(--color-danger-strong);}

package/src/components/input.css

@@ -4,7 +4,10 @@
    Neutralise the UA groove border / padding / min-inline-size so it lays out identically to the
    <div> form (min-inline-size:min-content would otherwise block the filterbar column widths). */
 fieldset.fdy-field{border:0;margin:0;padding:0;min-inline-size:0;}
-fieldset.fdy-field>legend{padding:0;float:none;}
+/* The rendered legend is laid out outside the fieldset's flex flow, so `gap` never reaches it —
+   measured 0px between legend and first control. This is the spacing contract a grouped field
+   needs; it matches .fdy-field's own gap so the group reads as one rhythm. */
+fieldset.fdy-field>legend{padding:0;float:none;margin-bottom:var(--space-2);}
 .fdy-label{font-size:var(--text-sm);font-weight:var(--weight-medium);color:var(--color-text);}
 .fdy-input,.fdy-textarea{width:100%;height:var(--control-h);padding:0 var(--space-3);font-family:var(--font-body);font-size:var(--text-sm);color:var(--color-text);background:var(--color-surface);border:1.5px solid var(--color-control-border);border-radius:var(--radius-md);box-shadow:inset 0 1px 2px rgba(16,14,30,.06);transition:border-color var(--dur-fast) var(--ease-standard),box-shadow var(--dur-fast) var(--ease-standard);}
 .fdy-input::placeholder,.fdy-textarea::placeholder{color:var(--color-text-subtle);}
@@ -28,5 +31,10 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-input[type="number"]::-webkit-outer-spin-button,.fdy-input[type="number"]::-webkit-inner-spin-button{appearance:none;-webkit-appearance:none;margin:0;}
 .fdy-input--error,.fdy-input[aria-invalid="true"],.fdy-textarea[aria-invalid="true"]{border-color:var(--color-danger);}
 .fdy-input--error:focus,.fdy-input[aria-invalid="true"]:focus,.fdy-textarea[aria-invalid="true"]:focus{border-color:var(--color-danger);box-shadow:0 0 0 3px color-mix(in srgb,var(--color-danger) 26%,transparent);}
+/* Required marker. The control already carries `required`, so the asterisk is decoration: the
+   `/ ""` is CSS alt text — the glyph is painted but exposes NOTHING to the accessibility tree, so a
+   screen reader does not read "star" after every label. That is stricter than a <span> an app has to
+   remember to mark aria-hidden, and it cannot be forgotten. */
+.fdy-label--required::after{content:"*" / "";margin-left:var(--space-1);color:var(--color-danger);}
 .fdy-help{font-size:var(--text-xs);color:var(--color-text-muted);}
 .fdy-help--error{color:var(--color-danger);}

package/src/components/list.css

@@ -10,6 +10,13 @@
  * Works on <ul>/<ol> (list-style is reset here) or on plain <div>s. */
 /* position:relative — containing block for out-of-flow row content (see base.css). */
 .fdy-list{position:relative;list-style:none;margin:0;padding:0;background:var(--color-surface);border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);overflow:hidden;}
+/* A row that hosts a stretched target has to be the anchor itself (#008 §1). Without this the
+   overlay resolves against .fdy-list — which IS positioned — so EVERY row's target covers the whole
+   list and the last one in the DOM wins: measured, a click on row one opens row two, under row one's
+   name, which looks exactly like working software. Opt-in via :has(), so a row that doesn't use the
+   pattern is untouched and nothing an app absolutely positions inside a plain row starts resolving
+   against a new containing block. The escape-hatch raise lives in card.css beside the card's. */
+.fdy-list__row:has(.fdy-btn--stretch){position:relative;}
 .fdy-list__row{display:flex;align-items:center;gap:var(--space-3);padding:var(--space-4) var(--space-5);min-width:0;}
 /* Divider between rows. Two shapes are supported and both are load-bearing: rows as direct children
  * of the list, and rows wrapped in <li> (the semantic shape, where the ADJACENT siblings are the

package/src/components/menu.css

@@ -5,7 +5,10 @@
 .fdy-menu--end{left:auto;right:0;}
 .fdy-menu__item{display:flex;align-items:center;gap:var(--space-2);width:100%;padding:var(--space-2) var(--space-3);border:0;background:transparent;border-radius:var(--radius-sm);font-family:var(--font-body);font-size:var(--text-sm);color:var(--color-text);text-align:left;cursor:pointer;white-space:nowrap;}
 .fdy-menu__item:hover,.fdy-menu__item.is-highlighted{background:var(--color-surface-3);}
-.fdy-menu__item:focus-visible{outline:none;background:var(--color-surface-3);}
+/* Focus is not hover. The enhancer moves real DOM focus (freeday-menu.js `.focus()`), so this is
+   the only thing a keyboard user has to go on — with the hover fill alone, arrowing through the
+   menu is invisible. Same ring as .fdy-nav__item, which got this right. Reported twice. */
+.fdy-menu__item:focus-visible{outline:none;background:var(--color-surface-3);box-shadow:0 0 0 2px color-mix(in srgb,var(--color-primary) 45%,transparent);}
 .fdy-menu__item:disabled{opacity:.5;cursor:not-allowed;background:transparent;}
 .fdy-menu__item--danger{color:var(--color-danger-strong);}
 .fdy-menu__item svg{display:block;width:1rem;height:1rem;flex:none;}

package/tokens/tokens.json

@@ -10,7 +10,7 @@
   "slate": {
     "0": { "$value": "#ffffff" }, "50": { "$value": "#f7f8fa" },
     "100": { "$value": "#eef0f4" }, "200": { "$value": "#e0e3ea" },
-    "300": { "$value": "#cbd0da" }, "400": { "$value": "#99a1b3" },
+    "300": { "$value": "#cbd0da" }, "400": { "$value": "#99a1b3" }, "450": { "$value": "#798295" },
     "500": { "$value": "#6b7488" }, "600": { "$value": "#4d5568" },
     "700": { "$value": "#3a4152" }, "800": { "$value": "#262b38" },
     "900": { "$value": "#171b26" }, "950": { "$value": "#0e111a" }
@@ -86,7 +86,7 @@
     "border":        { "$value": "{slate.200}", "$dark": "{slate.800}" },
     "border-strong": { "$value": "{slate.300}", "$dark": "{slate.700}" },
     "border-muted":  { "$value": "{slate.100}", "$dark": "#1c2130" },
-    "control-border": { "$value": "{slate.500}", "$dark": "{slate.500}" },
+    "control-border": { "$value": "{slate.450}", "$dark": "{slate.450}" },
     "switch-thumb": { "$value": "{slate.0}" },
     "shadow-inset": { "$value": "rgba(16,14,30,.06)" },