@celestia-island/hikari 0.31.1 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/components/HkAdminHeader.tsx

@@ -168,7 +168,7 @@ export const HkAdminHeader = defineComponent({
                 class="s-popup-menu-item"
                 onClick={() => props.onForceSignOut?.()}
               >
-                <LogOut size={14} />
+                <span class="hk-menu-item-icon"><LogOut size={14} /></span>
                 {props.forceSignOutLabel ?? t("hikari::adminHeader.forceSignOut", "Sign out")}
               </button>
             </div>
@@ -202,7 +202,7 @@ export const HkAdminHeader = defineComponent({
                   avatarModalOpen.value = true;
                 }}
               >
-                <Camera size={14} />
+                <span class="hk-menu-item-icon"><Camera size={14} /></span>
                 {props.avatarMenuLabel ?? t("hikari::adminHeader.avatar", "Avatar")}
               </button>
               {/* The language trigger owns the locale anchor: the ref sits
@@ -216,7 +216,7 @@ export const HkAdminHeader = defineComponent({
                 class="s-popup-menu-item"
                 onClick={() => (localeMenuOpen.value = !localeMenuOpen.value)}
               >
-                <Languages size={14} />
+                <span class="hk-menu-item-icon"><Languages size={14} /></span>
                 {props.localeMenuLabel ?? t("hikari::adminHeader.language", "Language")}
               </button>
               {slots["locale-picker"]?.({
@@ -240,7 +240,7 @@ export const HkAdminHeader = defineComponent({
                     emit("goToFrontend");
                   }}
                 >
-                  <ExternalLink size={14} />
+                  <span class="hk-menu-item-icon"><ExternalLink size={14} /></span>
                   {props.goToFrontendLabel}
                 </button>
               ) : null}
@@ -251,7 +251,7 @@ export const HkAdminHeader = defineComponent({
                   emit("logout");
                 }}
               >
-                <LogOut size={14} />
+                <span class="hk-menu-item-icon"><LogOut size={14} /></span>
                 {props.logoutLabel ?? t("hikari::adminHeader.logout", "Logout")}
               </button>
             </div>

package/src/components/HkAuthMethodList.tsx

@@ -54,15 +54,20 @@ export default defineComponent({
     const listRef = ref<HTMLDivElement | null>(null);
 
     /** Measure the widest label text and publish it as the label-column
-     *  width custom property. `scrollWidth` reports the text width even
-     *  while the fixed column clips it, so this is correct both before
-     *  the variable is first set and after any label change. */
+     *  width custom property. Each span is momentarily set to
+     *  `max-content` while reading: a plain `scrollWidth` on the fixed
+     *  column would report `max(textWidth, columnWidth)` and the column
+     *  could never shrink below its fallback. All reads happen inside one
+     *  synchronous task, so no intermediate paint is observable. */
     function measure() {
       const root = listRef.value;
       if (!root) return;
       let widest = 0;
       for (const label of root.querySelectorAll<HTMLElement>(".s-auth-methods-label")) {
+        const previous = label.style.width;
+        label.style.width = "max-content";
         widest = Math.max(widest, label.scrollWidth);
+        label.style.width = previous;
       }
       if (widest > 0) root.style.setProperty("--auth-methods-label-width", `${widest}px`);
     }

package/src/components/HkBreadcrumb.scss

@@ -1,3 +1,4 @@
+@use "./menu-item" as mi;
 // Use theme variables with namespace to avoid conflicts
 @use "./hikari-vars" as vars;
 
@@ -295,44 +296,28 @@
       pointer-events: auto;
     }
 
-    // Menu items
-    .hk-breadcrumb-dropdown-item {
-      // Layout
-      display: flex;
-      align-items: center;
-      gap: 0.5rem;
-
-      // Spacing
-      padding: 0.5rem 0.75rem;
-      margin: 0.125rem 0;
-
-      // Typography
-      font-size: vars.$hikari-font-size-sm;
-      color: var(--hi-color-text-primary);
-      text-decoration: none;
-      white-space: nowrap;
-
-      // Appearance
-      border-radius: vars.$hikari-radius-fui-sm;
-
-      // Cursor
-      cursor: pointer;
+    // NOTE: the dropdown ITEM rule lives at TOP LEVEL below, not nested
+    // here — @mixin item declares its desktop tokens on the row element,
+    // and a deeply nested selector would out-rank the sheet-context token
+    // re-declaration in _menu-item.scss (see the comment there).
+  }
+}
 
-      // Transitions
-      // DISABLED - migrated to JS animation
+// Menu items — unified menu-item spec (./_menu-item.scss): same
+// metrics/states as every other row family. The old hover (full
+// primary fill + double glow) was the library's only remaining
+// bespoke row hover and is retired with the unification. Kept at
+// (0,1,0) so the sheet binding can win inside sheet contexts.
+.hk-breadcrumb-dropdown-item {
+  @include mi.item;
 
-      // transition: all vars.$hikari-duration-fast vars.$hikari-ease-smooth;
+  // Spacing
+  margin: 0.125rem 0;
 
-      // Hover state
-      &:hover {
-        background: var(--hi-primary);
-        color: var(--hi-color-text-primary);
-        box-shadow:
-          0 0 12px var(--hi-primary),
-          inset 0 0 8px var(--hi-primary);
-      }
-    }
-  }
+  // Typography
+  color: var(--hi-color-text-primary);
+  text-decoration: none;
+  white-space: nowrap;
 }
 
 // ------

package/src/components/HkMenu.scss

@@ -3,49 +3,17 @@
  * surface): desktop anchored popouts, mobile bottom sheets with
  * scrim/grabber/title, popup-manager z-stacking, back-guard history.
  * The panel/sheet geometry lives in HkSelect.scss — this file only
- * owns what HkMenu itself brings to that surface: the row grammar,
- * the leading check column, and the sidebar variant's inline nav. */
+ * owns what HkMenu itself brings to that surface: the row grammar
+ * (the unified menu-item spec — see ./_menu-item.scss), the leading
+ * check column, and the sidebar variant's inline nav. */
 
-/* rows are shared by popout levels and mobile sheet layers */
-.hk-menu-row {
-  display: flex;
-  align-items: center;
-  justify-content: flex-start;
-  gap: 8px;
-  width: 100%;
-  padding: 7px 10px;
-  border: 0;
-  border-radius: var(--radius-sm, 4px);
-  background: transparent;
-  color: rgb(var(--color-text));
-  font-size: var(--text-sm);
-  line-height: 1.35;
-  text-align: left;
-  cursor: pointer;
-  appearance: none;
-  transition: background 0.12s ease;
-}
-
-.hk-menu-row:hover {
-  background: rgb(var(--color-primary) / 10%);
-}
-
-.hk-menu-row[data-active] {
-  background: rgb(var(--color-primary) / 14%);
-  font-weight: 600;
-}
+@use "./menu-item" as mi;
 
-.hk-menu-row[data-disabled] {
-  opacity: 0.45;
-  cursor: not-allowed;
-}
-
-.hk-menu-row[data-danger] {
-  color: rgb(var(--color-danger, 240 70 80));
-}
-
-.hk-menu-row[data-danger]:hover {
-  background: rgb(var(--color-danger, 240 70 80) / 12%);
+/* rows are shared by popout levels and mobile sheet layers; metrics
+ * and states come from the unified spec — inside a sheet the shared
+ * panel context swaps the tokens to the 44px touch geometry. */
+.hk-menu-row {
+  @include mi.item;
 }
 
 .hk-menu-flag {
@@ -55,22 +23,25 @@
 }
 
 .hk-menu-label {
-  flex: 1;
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
+  @include mi.label;
+}
+
+/* Leading icon cell — every row icon renders inside the spec's fixed
+ * square, so mixed lucide sizes read as one column and the icon box
+ * (not the raw svg) centers against the label. */
+.hk-menu-item-icon {
+  @include mi.icon;
 }
 
 /* Leading check column (selectMode). The cell is reserved on EVERY row
  * of a level while the column is on, so labels stay aligned; only
- * checked === true shows the mark. */
+ * checked === true shows the mark — an SVG check inside the same fixed
+ * cell grammar as leading icons (the old text "✓" carried its own
+ * baseline rhythm and sat off-center against svg icons). */
 .hk-menu-check {
-  flex-shrink: 0;
-  width: 16px;
+  @include mi.icon;
+
   color: rgb(var(--color-primary));
-  font-weight: 700;
-  text-align: center;
 }
 
 .hk-menu-more {
@@ -88,14 +59,6 @@
   min-width: 0;
 }
 
-/* Touch-sized rows inside the shared mobile sheet surface (the same
- * grammar HkSelect applies to its own sheet options). */
-.hk-select-sheet-panel .hk-menu-level .hk-menu-row {
-  min-height: 44px;
-  padding: 12px 10px;
-  font-size: var(--text-base);
-}
-
 @media (prefers-reduced-motion: reduce) {
   .hk-menu-row {
     transition: none;
@@ -104,10 +67,10 @@
 
 /* ── sidebar variant ────────────────────────────────────────────── */
 /* Inline vertical nav list — always rendered, no popover machinery.
- * Rows share the popup row's interaction grammar (hover wash, active
- * tint + weight, disabled/danger) but with nav-appropriate rhythm:
- * a consistent 4px gap between rows so rounded hover pills never touch,
- * deeper levels indenting under their group. */
+ * Rows share the unified menu-item spec's grammar (metrics + states),
+ * with nav-appropriate rhythm: a consistent 4px gap between rows so
+ * rounded hover pills never touch, deeper levels indenting under
+ * their group. */
 
 .hk-menu-sidebar {
   display: flex;
@@ -117,21 +80,7 @@
 }
 
 .hk-menu-sidebar-row {
-  display: flex;
-  align-items: center;
-  gap: var(--space-8, 8px);
-  width: 100%;
-  padding: var(--space-8, 8px) var(--space-12, 12px);
-  border: 0;
-  border-radius: var(--radius-sm, 4px);
-  background: transparent;
-  color: rgb(var(--color-text) / 82%);
-  font-size: var(--text-sm);
-  line-height: 1.4;
-  text-align: left;
-  cursor: pointer;
-  appearance: none;
-  transition: background 0.12s ease, color 0.12s ease;
+  @include mi.item;
 
   .hk-menu-label {
     flex: 1;
@@ -142,24 +91,8 @@
   }
 }
 
-.hk-menu-sidebar-row:hover:not([data-disabled]):not([data-active]) {
-  background: rgb(var(--color-primary) / 10%);
-  color: rgb(var(--color-text));
-}
-
-.hk-menu-sidebar-row[data-active] {
-  background: rgb(var(--color-primary) / 14%);
-  color: rgb(var(--color-primary));
-  font-weight: 600;
-}
-
-.hk-menu-sidebar-row[data-disabled] {
-  opacity: 0.45;
-  cursor: not-allowed;
-}
-
-.hk-menu-sidebar-row[data-danger] {
-  color: rgb(var(--color-danger, 240 70 80));
+.hk-menu-sidebar-row .hk-menu-item-icon {
+  @include mi.icon;
 }
 
 .hk-menu-sidebar-group {

package/src/components/HkMenu.test.ts

@@ -352,9 +352,11 @@ describe("HkMenu check column (selectMode)", () => {
     mountMenu(ref(true), checkedItems);
     const cells = checkCells();
     expect(cells).toHaveLength(3);
-    expect(cells[0].textContent).toBe("✓");
-    expect(cells[1].textContent).toBe("");
-    expect(cells[2].textContent).toBe("");
+    // The mark is an SVG check inside the fixed icon cell (same grammar
+    // as leading row icons) — not a text glyph.
+    expect(cells[0].querySelector("svg")).not.toBeNull();
+    expect(cells[1].querySelector("svg")).toBeNull();
+    expect(cells[2].querySelector("svg")).toBeNull();
   });
 
   it("auto shows no column for plain action menus", () => {

package/src/components/HkMenu.tsx

@@ -10,7 +10,7 @@ import {
   type VNode,
 } from "vue";
 
-import { ChevronRight } from "lucide-vue-next";
+import { Check, ChevronRight } from "lucide-vue-next";
 
 import { useBreakpoint } from "../runtime/useBreakpoint";
 import HkSelectPanel, { type SelectPanelPlacement } from "./HkSelectPanel";
@@ -504,11 +504,13 @@ export default defineComponent({
         >
           {reserved && (
             <span class="hk-menu-check" data-on={item.checked || undefined} aria-hidden="true">
-              {item.checked ? "✓" : ""}
+              {item.checked ? <Check size={12} /> : null}
             </span>
           )}
           {item.flag && <span class="hk-menu-flag">{item.flag}</span>}
-          {item.icon && h(item.icon, { size: 15 })}
+          {item.icon && (
+            <span class="hk-menu-item-icon">{h(item.icon, { size: 16 })}</span>
+          )}
           <span class="hk-menu-label">{item.label}</span>
           {hasKids && <ChevronRight size={14} class="hk-menu-more" />}
         </button>
@@ -708,7 +710,9 @@ export default defineComponent({
             emit("select", item.key, item);
           }}
         >
-          {item.icon && h(item.icon, { size: 16 })}
+          {item.icon && (
+            <span class="hk-menu-item-icon">{h(item.icon, { size: 16 })}</span>
+          )}
           {item.flag && <span class="hk-menu-flag">{item.flag}</span>}
           <span class="hk-menu-label">{item.label}</span>
           {item.badge && <span class="hk-menu-sidebar-badge">{item.badge}</span>}
@@ -734,7 +738,9 @@ export default defineComponent({
               toggleGroup(item.key);
             }}
           >
-            {item.icon && h(item.icon, { size: 16 })}
+            {item.icon && (
+              <span class="hk-menu-item-icon">{h(item.icon, { size: 16 })}</span>
+            )}
             <span class="hk-menu-label">{item.label}</span>
             {item.badge && <span class="hk-menu-sidebar-badge">{item.badge}</span>}
             <ChevronRight size={14} class="hk-menu-more" />

package/src/components/HkMenuActionItem.scss

@@ -1,58 +1,20 @@
 /* ── Standard menu action row (HkMenuActionItem) ────────────────
- * Shares the nav row grammar (`.hk-menu-sidebar-row`): same padding,
- * gap, typography and hover wash, so a menu panel of these rows reads
- * as one list with the navigation above it. */
+ * Speaks the unified menu-item spec (see ./_menu-item.scss) — same
+ * metrics, icon cell, states and focus ring as every other row, so a
+ * menu panel of these rows reads as one list with HkMenu rows and
+ * select options around it. Danger rides the spec's [data-danger]
+ * state (the tsx keeps the legacy `--danger` class for compat). */
 
-.hk-menu-action-item {
-  display: flex;
-  align-items: center;
-  gap: var(--space-8, 8px);
-  width: 100%;
-  padding: var(--space-8, 8px) var(--space-12, 12px);
-  border: 0;
-  border-radius: var(--radius-sm, 4px);
-  background: transparent;
-  color: rgb(var(--color-text) / 82%);
-  font-size: var(--text-sm);
-  font-weight: 500;
-  font-family: inherit;
-  line-height: 1.4;
-  text-align: left;
-  cursor: pointer;
-  appearance: none;
-  transition: background 0.12s ease, color 0.12s ease;
-
-  &:hover:not(:disabled) {
-    background: var(--c-primary-subtle, rgb(var(--color-primary) / 8%));
-    color: rgb(var(--color-text));
-  }
+@use "./menu-item" as mi;
 
-  &:disabled {
-    opacity: 0.5;
-    cursor: not-allowed;
-  }
+.hk-menu-action-item {
+  @include mi.item;
 }
 
 .hk-menu-action-item__icon {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  flex-shrink: 0;
+  @include mi.icon;
 }
 
 .hk-menu-action-item__label {
-  flex: 1;
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.hk-menu-action-item--danger {
-  color: rgb(var(--color-error, 200 50 50) / 90%);
-
-  &:hover:not(:disabled) {
-    background: rgb(var(--color-error, 200 50 50) / 10%);
-    color: rgb(var(--color-error, 200 50 50));
-  }
+  @include mi.label;
 }

package/src/components/HkMenuActionItem.tsx

@@ -2,18 +2,20 @@ import { defineComponent } from "vue";
 import "./HkMenuActionItem.scss";
 
 /**
- * Standard menu row: icon + label button sharing the nav row's exact
- * padding/typography constraints (see HkMenuPanel). Pluggable — renders
- * as a bare button, so it works inside HkMenuPanel, a popover, or any
- * other menu host; attrs (including a template `ref`) fall through to
- * the button element.
+ * Standard menu row: icon + label button speaking the unified menu-item
+ * spec (metrics/icon cell/states — see _menu-item.scss). Pluggable —
+ * renders as a bare button, so it works inside HkMenuPanel, a popover,
+ * or any other menu host; attrs (including a template `ref`) fall
+ * through to the button element.
  */
 export default defineComponent({
   name: "HkMenuActionItem",
   props: {
-    /** Leading icon node (e.g. `<Camera size={14} />`). Typed loosely
-     *  (plain Object) so consumers building on a different vue copy than
-     *  hikari's own node_modules never hit VNode type identity errors. */
+    /** Leading icon node (e.g. `<Camera size={14} />`). Rendered inside
+     * the spec's fixed icon cell, so any size centers uniformly. Typed
+     * loosely (plain Object) so consumers building on a different vue
+     * copy than hikari's own node_modules never hit VNode type identity
+     * errors. */
     icon: { type: Object, default: undefined },
     label: { type: String, required: true },
     /** Destructive styling (logout, delete…). */
@@ -28,6 +30,7 @@ export default defineComponent({
       <button
         type="button"
         class={["hk-menu-action-item", props.danger ? "hk-menu-action-item--danger" : ""]}
+        data-danger={props.danger || undefined}
         disabled={props.disabled}
         role="menuitem"
         onClick={(e: MouseEvent) => emit("click", e)}

package/src/components/HkNavItem.scss

@@ -1,16 +1,28 @@
+/* HkNavItem — nav row. Speaks the unified menu-item spec's METRICS
+ * (min-height / padding / gap / font / radius / icon cell — see
+ * ./_menu-item.scss) so nav rows, menu rows, select options and theme
+ * pills share one box geometry. Colors stay on the --hi-* token family:
+ * nav rows are consumed by hosts that re-theme via --hi-*, so the
+ * interaction palette deliberately does not switch to --c-*. */
+
+@use "./menu-item" as mi;
+
 .hk-nav-item {
+  @include mi.item-tokens;
+
   display: flex;
   align-items: center;
-  gap: 0.5rem;
-  padding: 0.5rem 0.75rem;
-  border-radius: var(--hi-radius-md, 6px);
+  gap: var(--hk-menu-item-gap);
+  min-height: var(--hk-menu-item-min-h);
+  padding: var(--hk-menu-item-pad-y) var(--hk-menu-item-pad-x);
+  border-radius: var(--hk-menu-item-radius);
   color: var(--hi-color-muted);
-  font-size: 0.875rem;
+  font-size: var(--hk-menu-item-font);
   font-family: inherit;
-  line-height: 1.4;
+  line-height: var(--hk-menu-item-lh);
   text-decoration: none;
   background: none;
-  border: none;
+  border: 1px solid transparent;
   width: 100%;
   text-align: left;
   cursor: pointer;
@@ -64,12 +76,7 @@
 }
 
 .hk-nav-item-icon {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  flex-shrink: 0;
-  width: 1rem;
-  height: 1rem;
+  @include mi.icon;
 }
 
 .hk-nav-item-label {

package/src/components/HkPopover.scss

@@ -1,3 +1,5 @@
+@use "./menu-item" as mi;
+
 .hk-popover-backdrop {
   position: fixed;
   inset: 0;
@@ -54,35 +56,13 @@
   padding: var(--space-4, 12px);
 }
 
-/* Locale picker menu items */
+/* Locale picker menu items — unified menu-item spec (./_menu-item.scss). */
 .hk-popup-menu-item {
-  display: flex;
-  align-items: center;
-  gap: var(--space-8);
-  padding: var(--space-8) var(--space-14);
-  font-size: var(--text-sm);
-  font-weight: 500;
-  font-family: inherit;
-  color: rgb(var(--color-text));
-  cursor: pointer;
-  transition: background var(--duration-normal) ease;
-  border: none;
-  background: none;
-  width: 100%;
-  text-align: left;
-  outline: none;
-  border-radius: var(--radius-sm);
-}
-
-/* Hover = background wash only, never on the active item (active >
-   hover precedence — see HkNavItem.scss for the spec). */
-.hk-popup-menu-item:hover:not([data-active]) {
-  background: var(--c-primary-subtle);
+  @include mi.item;
 }
 
-.hk-popup-menu-item[data-active] {
-  color: rgb(var(--color-primary));
-  font-weight: 600;
+.hk-popup-menu-item[data-active]:hover {
+  background: var(--c-primary-dim, rgb(var(--color-primary) / 10%));
 }
 
 .hk-locale-submenu {
@@ -173,7 +153,7 @@
   // slightly letterspaced, inset to the content edge. Hosts tune the
   // leading inset via --hk-sheet-title-inset.
   padding: 0 var(--space-16, 1rem) var(--space-8, 0.5rem)
-    var(--hk-sheet-title-inset, var(--space-16, 1rem));
+    var(--hk-sheet-title-inset, calc(var(--space-16, 1rem) * 2));
   font-size: var(--text-xs, 0.75rem);
   font-weight: 600;
   letter-spacing: 0.02em;

package/src/components/HkPopupSelect.scss

@@ -1,4 +1,5 @@
 @use "../tokens";
+@use "./menu-item" as mi;
 
 /* HkPopupSelect */
 
@@ -108,32 +109,18 @@
   padding: var(--space-2);
 }
 
+/* Unified menu-item spec (see ./_menu-item.scss); sheet geometry flows
+ * from the shared `.hk-popover-panel.hk-is-sheet` token context. */
 .hk-popup-select-item {
-  display: flex;
-  align-items: center;
-  gap: var(--space-8);
-  padding: var(--space-10) var(--space-16);
-  font-size: var(--text-base);
-  color: rgb(var(--color-text));
-  border: 1px solid transparent;
-  border-radius: var(--radius-md);
-  cursor: pointer;
-  outline: none;
-  transition: background-color, border-color, color, box-shadow, opacity, transform, filter var(--duration-normal) ease;
-  text-align: left;
+  @include mi.item;
 }
 
-.hk-popup-select-item:hover,
-.hk-popup-select-item[data-highlighted] {
-  background: var(--c-primary-subtle);
-  border-color: var(--c-primary-medium);
-}
-
-.hk-popup-select-item[data-checked] {
-  background: var(--c-primary-dim);
-  border-color: var(--c-primary-strong);
-  color: rgb(var(--color-primary));
-  font-weight: 600;
+/* Highlight face yields to checked/active (see HkSelect.scss). */
+.hk-popup-select-item:hover:not([data-checked]):not([data-active]),
+.hk-popup-select-item[data-highlighted]:not([data-checked]):not([data-active]) {
+  background: var(--c-primary-subtle, rgb(var(--color-primary) / 8%));
+  border-color: var(--c-primary-medium, rgb(var(--color-primary) / 25%));
+  color: rgb(var(--color-text));
 }
 
 .hk-popup-select-error {
@@ -143,14 +130,9 @@
 }
 
 // Mobile sheet form (HPopover sheetOnMobile): full-width option list with
-// touch-sized rows.
+// touch-sized rows (row geometry flows from the shared sheet tokens).
 .hk-popover-panel.hk-is-sheet.hk-popup-select-content {
   .hk-popup-select-viewport {
     max-height: min(56vh, 24rem);
   }
-
-  .hk-popup-select-item {
-    padding: var(--space-14) var(--space-16);
-    font-size: var(--text-base);
-  }
 }

package/src/components/HkSelect.scss

@@ -1,4 +1,5 @@
 @use "../tokens";
+@use "./menu-item" as mi;
 
 /* HkSelect — popup select component */
 
@@ -198,37 +199,26 @@
   }
 }
 
+/* Unified menu-item spec (see ./_menu-item.scss) — options, menu rows
+ * and theme pills share one grammar; sheet geometry flows from the
+ * shared sheet token context, so the old per-component sheet bump is
+ * gone. [data-highlighted] (keyboard/pointer highlight) maps to the
+ * spec's hover face. */
 .hk-select-option {
-  display: flex;
-  align-items: center;
-  gap: var(--space-8);
-  padding: var(--space-10) var(--space-16);
-  font-size: var(--text-base);
-  color: rgb(var(--color-text));
-  border: 1px solid transparent;
-  border-radius: var(--radius-md);
-  cursor: pointer;
-  outline: none;
-  transition: background-color, border-color, color, box-shadow, opacity, transform, filter var(--duration-normal) ease;
-  text-align: left;
+  @include mi.item;
 }
 
-.hk-select-option:hover,
-.hk-select-option[data-highlighted] {
-  background: var(--c-primary-subtle);
-  border-color: var(--c-primary-medium);
+/* The highlight face never overrides the checked/active face — a
+ * keyboard-highlighted selected option keeps its dim wash + primary
+ * text (active > hover precedence, same as the spec mixin). */
+.hk-select-option:hover:not([data-checked]):not([data-active]),
+.hk-select-option[data-highlighted]:not([data-checked]):not([data-active]) {
+  background: var(--c-primary-subtle, rgb(var(--color-primary) / 8%));
+  border-color: var(--c-primary-medium, rgb(var(--color-primary) / 25%));
 }
 
-.hk-select-option[data-checked] {
-  background: var(--c-primary-dim);
-  border-color: var(--c-primary-strong);
-  color: rgb(var(--color-primary));
-  font-weight: 600;
-}
-
-.hk-select-option[data-disabled] {
-  opacity: 0.4;
-  cursor: not-allowed;
+.hk-select-option[data-highlighted]:not(:hover):not([data-checked]):not([data-active]) {
+  color: rgb(var(--color-text));
 }
 
 .hk-select-error {
@@ -353,11 +343,6 @@
   &::-webkit-scrollbar {
     display: none;
   }
-
-  .hk-select-option {
-    padding: var(--space-14) var(--space-16);
-    font-size: var(--text-base);
-  }
 }
 
 /* Leading in-content heading hidden by the sheet duplicate-title

package/src/components/HkThemeToggle.scss

@@ -1,3 +1,5 @@
+@use "./menu-item" as mi;
+
 .s-theme-toggle {
   display: inline-flex;
   align-items: center;
@@ -121,6 +123,12 @@
  * invisible slot left a permanent dead strip right of every row in the
  * mobile bottom sheet — and every pill and highlight still shares the
  * exact same width.
+ *
+ * Metrics/states come from the unified menu-item spec (./_menu-item.scss)
+ * — the same grammar as menu rows and select options; inside the mobile
+ * sheet the shared `.hk-popover-panel.hk-is-sheet` token context applies
+ * the 44px touch geometry, so the old component-local media bump is gone
+ * (only the overlaid delete button keeps its own touch sizing below).
  */
 
 .s-theme-item-row {
@@ -136,30 +144,20 @@
  * bespoke 6×8 tight rows (small text, borderless 12% wash) are what
  * made the theme sheet read as "not from the standard dropdown". */
 .s-theme-item-btn {
-  display: flex;
-  align-items: center;
-  gap: var(--space-8, 0.5rem);
+  @include mi.item;
+
   min-width: 0;
   flex: 1;
-  padding: var(--space-10, 0.625rem) var(--space-16, 1rem);
-  border: 1px solid transparent;
-  border-radius: var(--radius-md, 8px);
-  background: transparent;
-  color: rgb(var(--color-text));
-  font-size: var(--text-base, 0.875rem);
-  line-height: 1.35;
-  text-align: left;
-  cursor: pointer;
-  appearance: none;
-  transition: background-color 0.12s ease, border-color 0.12s ease;
+  width: auto;
 }
 
 .s-theme-item-name {
-  flex: 1;
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
+  @include mi.label;
+}
+
+/* Leading check / customize glyphs share the spec's fixed icon cell. */
+.s-theme-item-btn .hk-menu-item-icon {
+  @include mi.icon;
 }
 
 /* Custom rows keep the name clear of the overlaid delete button. */
@@ -173,14 +171,14 @@
 }
 
 .s-theme-item-btn:hover:not([data-active]) {
-  background: var(--c-primary-subtle);
-  border-color: var(--c-primary-medium);
+  background: var(--c-primary-subtle, rgb(var(--color-primary) / 8%));
+  border-color: var(--c-primary-medium, rgb(var(--color-primary) / 25%));
   color: rgb(var(--color-text));
 }
 
 .s-theme-item-btn[data-active] {
-  background: var(--c-primary-dim);
-  border-color: var(--c-primary-strong);
+  background: var(--c-primary-dim, rgb(var(--color-primary) / 10%));
+  border-color: var(--c-primary-strong, rgb(var(--color-primary) / 40%));
   color: rgb(var(--color-primary));
   font-weight: 600;
 }
@@ -210,17 +208,11 @@
   color: rgb(var(--color-error));
 }
 
-/* Touch-sized rows on phone widths — the same sheet bump the shared
- * surfaces apply (.hk-select-sheet-list .hk-select-option → 14px
- * vertical, .hk-select-sheet-panel .hk-menu-row → 44px min-height).
- * The overlaid delete button grows with them and the name clearance
- * follows so the two never collide on long custom scheme names. */
+/* Touch-sized delete target on phone widths, scaled for the 44px sheet
+ * rows that the shared spec applies inside sheet contexts (see
+ * ./_menu-item.scss). The name clearance follows so the button and the
+ * label never collide on long custom scheme names. */
 @media (max-width: 767px) {
-  .s-theme-item-btn {
-    min-height: 44px;
-    padding: var(--space-14, 0.875rem) var(--space-16, 1rem);
-  }
-
   .s-theme-item-delete {
     width: 2.25rem;
     height: 2.25rem;

package/src/components/HkThemeToggle.tsx

@@ -241,7 +241,9 @@ export const HkThemeToggle = defineComponent({
                   data-active={currentTheme.value === th.id || undefined}
                   onClick={() => onSelectTheme(th.id)}
                 >
-                  {currentTheme.value === th.id && <Check size={14} class="s-theme-item-check" />}
+                  {currentTheme.value === th.id && (
+                    <span class="hk-menu-item-icon s-theme-item-check"><Check size={14} /></span>
+                  )}
                   <span class="s-theme-item-name">{th.name}</span>
                 </button>
                 {th.isCustom && (
@@ -269,7 +271,7 @@ export const HkThemeToggle = defineComponent({
                 }
               }}
             >
-              <Palette size={14} />
+              <span class="hk-menu-item-icon"><Palette size={14} /></span>
               <span class="s-theme-item-name">{t("hikari::theme.customize")}</span>
             </button>
           </div>

package/src/components/HkToolBlock.scss

@@ -273,8 +273,10 @@
 }
 
 .s-jt-row {
+  /* Baseline alignment keeps the small type hints (boolean/number/string)
+     on the value's text baseline instead of floating above it. */
   display: flex;
-  align-items: flex-start;
+  align-items: baseline;
   min-height: 1.55em;
   padding: 0 var(--space-6, 0.375rem);
   border-radius: var(--radius-xs, 2px);
@@ -297,6 +299,10 @@
   height: var(--jt-toggle);
   flex-shrink: 0;
   margin-right: 2px;
+  /* The toggle box has no text baseline of its own — pin it to the line
+     top instead of letting it join the row's baseline group with a
+     synthesized border-box baseline. */
+  align-self: flex-start;
 }
 
 .s-jt-toggle[data-parent] {
@@ -368,9 +374,8 @@
   color: rgb(var(--color-muted) / 0.6);
   font-size: var(--text-3xs, 0.5rem);
   font-style: italic;
-  margin-left: 0.5em;
+  margin-left: 0.75em;
   font-weight: 400;
-  align-self: center;
 }
 
 .s-jt-badge {

package/src/components/_menu-item.scss

@@ -0,0 +1,180 @@
+/* ── Unified menu-item grammar (the ONE row spec) ────────────────────
+ *
+ * Every selectable list row the library renders — cascade menu rows,
+ * action rows, select options, popup-select items, theme pills, admin
+ * header rows, nav rows, breadcrumb dropdown items — shares this exact
+ * grammar. Desktop (anchored popouts) and mobile (bottom sheets) are
+ * the same spec at two token sets; a sheet context merely swaps the
+ * tokens, so every row inside ANY sheet gets the touch geometry
+ * without per-component media queries.
+ *
+ * Metric contract (desktop / sheet):
+ *   min-height  34px / 44px        icon cell  16px / 20px
+ *   padding     6×12px / 10×16px   font       13px / 14px
+ *   gap 8px · radius --radius-md · weight 500 · line-height 1.3
+ *
+ * Interaction contract:
+ *   - hover: subtle primary wash + medium border (guarded — never
+ *     fights the active/checked state, never changes layout: the 1px
+ *     border is always reserved).
+ *   - active/checked: dim primary wash + strong border + primary text
+ *     + 600 (active > hover precedence).
+ *   - checked mark: an SVG check inside the reserved cell, normalized
+ *     to the cell like every other icon (16px / 20px in sheets).
+ *   - danger rows tint red; disabled rows dim to 45%.
+ *   - focus-visible: 2px inset primary ring (keyboard parity for every
+ *     row family — previously only HkNavItem had one).
+ *   - label carries the optical shift: small CJK rasterization biases
+ *     glyph ink high against box-centered icons; a half-pixel down
+ *     nudge re-centers the perceived mass (tunable per host).
+ *
+ * Adoption: `@use "./menu-item" as mi;` then
+ *   .your-row { @include mi.item; }
+ *   .your-row .your-icon { @include mi.icon; }   // wrap TSX side!
+ *   .your-row .your-label { @include mi.label; }
+ * Keep the component's own class names — this file owns metrics and
+ * states only, never selectors of the adopting rows.
+ */
+
+/* ── Tokens ─────────────────────────────────────────────────────────── */
+
+@mixin item-tokens {
+  --hk-menu-item-min-h: 34px;
+  --hk-menu-item-pad-x: 12px;
+  --hk-menu-item-pad-y: 6px;
+  --hk-menu-item-gap: 8px;
+  --hk-menu-item-font: var(--text-sm, 0.8125rem);
+  --hk-menu-item-weight: 500;
+  --hk-menu-item-lh: 1.3;
+  --hk-menu-item-radius: var(--radius-md, 8px);
+  --hk-menu-item-icon-box: 16px;
+  /* Label optical shift — see header comment. */
+  --hk-menu-item-optical: 0.5px;
+}
+
+/* Mobile bottom-sheet geometry. */
+@mixin item-sheet-tokens {
+  --hk-menu-item-min-h: 44px;
+  --hk-menu-item-pad-x: 16px;
+  --hk-menu-item-pad-y: 10px;
+  --hk-menu-item-font: var(--text-base, 0.875rem);
+  --hk-menu-item-icon-box: 20px;
+}
+
+/* Sheet context. The tokens are re-declared ON each adopting row, not
+ * merely on the panel: a custom property declared on an element always
+ * beats an inherited value, and @mixin item declares the desktop set at
+ * row level — an ancestor-only binding would never win. The (0,2,0)
+ * descendant selector here beats the row's own (0,1,0) declaration.
+ * Therefore every adopter MUST @include mi.item at a TOP-LEVEL (0,1,0)
+ * rule — a nested include (e.g. inside its parent menu selector)
+ * compiles to a higher specificity and silently defeats this binding
+ * (HkBreadcrumb was caught exactly this way). New row families must
+ * also register their class in this list. */
+.hk-select-sheet-panel,
+.hk-popover-panel.hk-is-sheet,
+.hk-drawer-panel {
+  .hk-menu-row,
+  .hk-menu-sidebar-row,
+  .hk-menu-action-item,
+  .hk-select-option,
+  .hk-popup-select-item,
+  .s-theme-item-btn,
+  .s-popup-menu-item,
+  .hk-popup-menu-item,
+  .hk-breadcrumb-dropdown-item {
+    @include item-sheet-tokens;
+  }
+}
+
+/* ── Row grammar ────────────────────────────────────────────────────── */
+
+@mixin item {
+  @include item-tokens;
+  display: flex;
+  align-items: center;
+  justify-content: flex-start;
+  gap: var(--hk-menu-item-gap);
+  width: 100%;
+  min-height: var(--hk-menu-item-min-h);
+  padding: var(--hk-menu-item-pad-y) var(--hk-menu-item-pad-x);
+  border: 1px solid transparent;
+  border-radius: var(--hk-menu-item-radius);
+  background: transparent;
+  color: rgb(var(--color-text) / 88%);
+  font-size: var(--hk-menu-item-font);
+  font-weight: var(--hk-menu-item-weight);
+  font-family: inherit;
+  line-height: var(--hk-menu-item-lh);
+  text-align: left;
+  cursor: pointer;
+  appearance: none;
+  user-select: none;
+  -webkit-user-select: none;
+  -webkit-tap-highlight-color: transparent;
+  transition: background-color 0.12s ease, border-color 0.12s ease, color 0.12s ease;
+
+  &:hover:not(:disabled):not([data-disabled]):not([data-active]):not([data-checked]) {
+    background: var(--c-primary-subtle, rgb(var(--color-primary) / 8%));
+    border-color: var(--c-primary-medium, rgb(var(--color-primary) / 25%));
+    color: rgb(var(--color-text));
+  }
+
+  &:focus-visible {
+    outline: 2px solid rgb(var(--color-primary) / 70%);
+    outline-offset: -2px;
+  }
+
+  &[data-active],
+  &[data-checked] {
+    background: var(--c-primary-dim, rgb(var(--color-primary) / 10%));
+    border-color: var(--c-primary-strong, rgb(var(--color-primary) / 40%));
+    color: rgb(var(--color-primary));
+    font-weight: 600;
+  }
+
+  &[data-disabled],
+  &:disabled {
+    opacity: 0.45;
+    cursor: not-allowed;
+  }
+
+  &[data-danger] {
+    color: rgb(var(--color-danger, 240 70 80) / 90%);
+
+    &:hover:not(:disabled):not([data-disabled]):not([data-active]) {
+      background: rgb(var(--color-danger, 240 70 80) / 10%);
+      border-color: rgb(var(--color-danger, 240 70 80) / 25%);
+      color: rgb(var(--color-danger, 240 70 80));
+    }
+  }
+}
+
+/* ── Leading icon cell ────────────────────────────────────────────────
+ * Fixed square; any icon size the consumer passes is centered and
+ * normalized to the cell, so lucide 13/14/15/16px imports all read as
+ * one column. Icon inherits the row color (danger rows tint red). */
+@mixin icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: var(--hk-menu-item-icon-box);
+  height: var(--hk-menu-item-icon-box);
+
+  > svg {
+    width: 100%;
+    height: 100%;
+  }
+}
+
+/* ── Label ──────────────────────────────────────────────────────────── */
+@mixin label {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  position: relative;
+  top: var(--hk-menu-item-optical);
+}

package/src/styles/admin-tokens.scss

@@ -3,6 +3,8 @@
    Defines layout variables needed by plana-ui + hikari components.
    Color tokens are provided by hikari's initTheme(). */
 
+@use "../components/menu-item" as mi;
+
 :root {
   /* ── Layout tokens ─ */
   --s-footer-height: 3rem;
@@ -357,41 +359,23 @@
 }
 
 /* ── Popup menu items ─ */
+/* Unified menu-item spec (packages/vue/src/components/_menu-item.scss):
+ * one row grammar across menus, selects, theme pills, admin header
+ * rows and nav. The tsx wraps leading icons in .hk-menu-item-icon so
+ * the column centers against the label. */
 .s-popup-menu-item {
-  display: flex;
-  align-items: center;
-  gap: var(--space-8);
-  padding: var(--space-8) var(--space-14);
-  font-size: var(--text-sm);
-  font-weight: 500;
-  font-family: inherit;
-  color: rgb(var(--color-text));
-  cursor: pointer;
-  transition: background var(--duration-normal) ease;
-  border: none;
-  background: none;
-  width: 100%;
-  text-align: left;
-  /* Rows are flex containers (icon + label + optional trailing caret).
-     Without an explicit justification, Chrome's button UA default
-     (justify-content: center) applies — invisible on shrink-to-fit
-     popovers, glaring in full-width mobile sheets where icon+label
-     float to the middle. Pin to flex-start; trailing carets keep
-     parking at the far edge via their own margin-left: auto. */
-  justify-content: flex-start;
-  outline: none;
-  border-radius: var(--radius-sm);
+  @include mi.item;
+
+  /* Trailing carets keep parking at the far edge via their own
+     margin-left: auto. */
 }
 
-/* Hover = background wash only, never on the active item (active >
-   hover precedence — hue and font-weight never change on hover). */
-.s-popup-menu-item:hover:not([data-active]) {
-  background: var(--c-primary-subtle);
+.s-popup-menu-item .hk-menu-item-icon {
+  @include mi.icon;
 }
 
-.s-popup-menu-item[data-active] {
-  color: rgb(var(--color-primary));
-  font-weight: 600;
+.s-popup-menu-item[data-active]:hover {
+  background: var(--c-primary-dim, rgb(var(--color-primary) / 10%));
 }
 
 /* ── User identity header (shared) ─ */