@cahyo-dimas/freeday 1.28.0 → 1.29.0

package/CHANGELOG.md

@@ -3,6 +3,62 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
 
+## [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

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.29.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.29.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.29.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.29.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/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

@@ -1051,6 +1051,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 +1293,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 +1320,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);}
 
@@ -1351,7 +1375,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

@@ -681,6 +681,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 +923,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 +950,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);}
 
@@ -981,7 +1005,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/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.29.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.29.0",
   "description": "Freeday — token-driven, framework-agnostic UI KIT (design source-of-truth).",
   "type": "module",
   "license": "MIT",

package/src/components/composition.css

@@ -47,3 +47,19 @@
 .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/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;}