@astryxdesign/core 0.4.1 → 0.4.2-canary.464a445

package/src/hooks/useMenuHover.ts

@@ -4,42 +4,98 @@
 
 /**
  * @file useMenuHover.ts
- * @input Uses React hooks, useListFocus
+ * @input Uses React hooks, useListFocus, useMediaQuery
  * @output Exports useMenuHover hook
- * @position Internal hook; used by nav heading components and TopNavMenu
+ * @position Internal hook; used by nav heading components, TopNavMenu,
+ *           TopNavMegaMenu and DropdownMenuSubMenu
  *
- * Hover as a progressive enhancement on top of standard popover behavior:
+ * Hover as a progressive enhancement over standard popover behavior: click
+ * toggles, Escape and outside-click close, arrows navigate; on top of that,
+ * mouseenter opens after a delay and mouseleave closes one that hover opened.
  *
- * 1. Default popover: click toggles, Escape closes, outside-click closes,
- *    arrow keys navigate menu items.
+ * Three behaviors here are not obvious and are load-bearing:
  *
- * 2. Hover add-on:
- *    - mouseenter activates "hover mode" and opens after delay
- *    - While in hover mode, mouseleave closes after delay
- *    - Any close (click, Escape, outside-click) resets hover mode
- *    - Click-to-close additionally skips the next mouseenter
+ * 1. Hover→click guard (#3121). A hover-opened menu is already open under the
+ *    cursor when the pointer arrives, so the click that naturally follows would
+ *    toggle it shut. Within `clickGuardMs` a click instead confirms it: the menu
+ *    pins and behaves like a click-open from then on.
  *
- * Only uses mouseenter/mouseleave (not mouseover).
+ * 2. Focus moves synchronously. `useLayer.show()` calls `showPopover()` in the
+ *    same tick and the layer's children are always mounted, so items are
+ *    focusable the moment `show()` returns — a `requestAnimationFrame` here
+ *    lands after paint and races anything else moving focus. Hover-opens are the
+ *    exception: the pointer is driving, so focus stays on the trigger. The hook
+ *    always passes `skipAutoFocus` and owns focus itself, because the popover's
+ *    auto-focus targets the first *tabbable* node while a menu wants its first
+ *    item — under roving tabindex those are different elements.
+ *
+ * 3. Native light dismiss. A `popover="auto"` is dismissed by the browser on
+ *    pointer interaction outside the panel, and a trigger outside the panel
+ *    counts — before React's click handler runs. `popoverId` makes the trigger
+ *    the panel's invoker, which exempts it. jsdom implements neither light
+ *    dismiss nor invokers, so that wiring is only verifiable in a browser.
  */
 
 import {useCallback, useEffect, useRef} from 'react';
+import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
 import {useListFocus} from './useListFocus';
 import {useMediaQuery} from './useMediaQuery';
 
-interface UseMenuHoverOptions {
+const DEFAULT_CLICK_GUARD_MS = 500;
+
+/**
+ * How long after a close a mouseenter on the trigger is ignored.
+ *
+ * A panel positioned over its own trigger puts that trigger back under a
+ * stationary pointer when it closes, and the browser fires a fresh mouseenter —
+ * which reopened the menu the user had just dismissed. Time-bounded rather than
+ * a one-shot flag, so a deliberate re-hover seconds later still opens; a real
+ * mouseleave clears it early.
+ */
+const REOPEN_SUPPRESS_MS = 300;
+
+export interface UseMenuHoverOptions {
   show: (options?: {skipAutoFocus?: boolean}) => void;
   hide: () => void;
   isOpen: boolean;
   isEnabled: boolean;
+  /** Delay before a hover opens the menu (ms). @default 150 */
   showDelay?: number;
+  /** Delay before leaving the trigger or menu closes it (ms). @default 200 */
   hideDelay?: number;
+  /**
+   * Window after a hover-open in which a click confirms the menu instead of
+   * closing it. 0 opts out, making every click toggle. @default 500
+   */
+  clickGuardMs?: number;
+  /**
+   * Selector for the menu's focusable items, forwarded to `useListFocus`. A
+   * panel of links (a mega menu) needs an override; `role="menuitem"` rows do
+   * not. @default '[role="menuitem"]'
+   */
+  itemSelector?: string;
+  /**
+   * The popup's DOM id (`usePopover().id`). Supply it when the popup is a
+   * native `popover="auto"` and the trigger sits outside it; omit it for
+   * `popover="manual"` popups and triggers inside the panel.
+   */
+  popoverId?: string;
+  /**
+   * Whether the hook moves focus on a click or keyboard open. False for
+   * consumers that wire the pointer half only and leave focus to the popover's
+   * own trap — a panel that is a dialog rather than a menu (`SideNavItem`'s
+   * collapsed flyout) has no items for the hook to focus. @default true
+   */
+  ownsFocus?: boolean;
 }
 
-interface UseMenuHoverReturn<T extends HTMLElement = HTMLElement> {
+export interface UseMenuHoverReturn<T extends HTMLElement = HTMLElement> {
   triggerProps: {
-    onClick: () => void;
+    onClick: (event?: React.MouseEvent) => void;
     onMouseEnter: () => void;
     onMouseLeave: () => void;
+    /** Present only when `popoverId` is supplied. */
+    popoverTarget?: string;
   };
   contentProps: {
     onMouseEnter: () => void;
@@ -47,7 +103,25 @@ interface UseMenuHoverReturn<T extends HTMLElement = HTMLElement> {
     onKeyDown: (e: React.KeyboardEvent) => void;
   };
   menuRef: React.RefObject<T | null>;
-  focusFirst: () => void;
+  /** Focus the first enabled item. Returns false when there was none. */
+  focusFirst: () => boolean;
+  /**
+   * Focus the first enabled item, falling back to the menu container when the
+   * menu is empty or still loading.
+   */
+  focusMenu: () => void;
+  /**
+   * For consumers with their own click handler: call this in the open branch.
+   * Returns `true` when the click was the one following a hover-open — the menu
+   * is now pinned and the click must NOT be treated as a dismissal.
+   */
+  confirmHoverOpen: () => boolean;
+  /**
+   * Close, restoring focus to the trigger. For dismiss affordances rendered
+   * inside the popup, which are close buttons rather than the trigger and so
+   * must not carry its toggle and keyboard-activation semantics.
+   */
+  close: () => void;
   setTriggerEl: (el: HTMLElement | null) => void;
 }
 
@@ -61,6 +135,10 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
     isEnabled,
     showDelay = 150,
     hideDelay = 200,
+    clickGuardMs = DEFAULT_CLICK_GUARD_MS,
+    itemSelector,
+    popoverId,
+    ownsFocus = true,
   } = options;
 
   const hasHover = useMediaQuery('(hover: hover)');
@@ -68,17 +146,25 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
   const showTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const hideTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const triggerElRef = useRef<HTMLElement | null>(null);
-  // Whether the menu was opened/interacted via hover (enables mouseleave-to-close)
+  /** Menu was hover-opened, so mouseleave may close it. */
   const hoverModeRef = useRef(false);
-  // One-shot: skip the next mouseenter after click-to-close
-  const skipNextEnterRef = useRef(false);
+  const closedAtRef = useRef(0);
+  /** When the current open began as a hover-open; 0 once confirmed or closed. */
+  const hoverOpenedAtRef = useRef(0);
   const prevIsOpenRef = useRef(isOpen);
 
-  // When popover closes (any reason), reset hover mode
-  if (prevIsOpenRef.current && !isOpen) {
-    hoverModeRef.current = false;
-  }
-  prevIsOpenRef.current = isOpen;
+  // Catches every close, whatever caused it. A layout effect, not render: it
+  // must land before the browser hit-tests the vanished panel and fires the
+  // mouseenter REOPEN_SUPPRESS_MS exists to swallow.
+  useIsomorphicLayoutEffect(() => {
+    const wasOpen = prevIsOpenRef.current;
+    prevIsOpenRef.current = isOpen;
+    if (wasOpen && !isOpen) {
+      hoverModeRef.current = false;
+      hoverOpenedAtRef.current = 0;
+      closedAtRef.current = Date.now();
+    }
+  }, [isOpen]);
 
   const clearTimeouts = useCallback(() => {
     if (showTimerRef.current) {
@@ -91,56 +177,160 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
     }
   }, []);
 
+  // useListFocus needs an onEscape that is defined in terms of its own listRef;
+  // the indirection avoids the use-before-declare.
+  const escapeHandlerRef = useRef<() => void>(() => {});
+
   const {
     listRef: menuRef,
     handleKeyDown: handleListKeyDown,
     focusFirst,
   } = useListFocus<T>({
-    onEscape: () => {
-      clearTimeouts();
-      hide();
-    },
+    itemSelector,
+    onEscape: () => escapeHandlerRef.current(),
   });
 
+  const hideAndRestoreFocus = useCallback(() => {
+    // Read before hiding: closing the layer moves focus itself.
+    const menuHadFocus =
+      menuRef.current?.contains(document.activeElement) ?? false;
+    hide();
+    if (menuHadFocus) {
+      triggerElRef.current?.focus();
+    }
+  }, [hide, menuRef]);
+
+  useEffect(() => {
+    escapeHandlerRef.current = () => {
+      clearTimeouts();
+      hideAndRestoreFocus();
+    };
+  }, [clearTimeouts, hideAndRestoreFocus]);
+
   useEffect(() => {
     return () => clearTimeouts();
   }, [clearTimeouts]);
 
-  // Click: always toggle
-  const handleClick = useCallback(() => {
-    clearTimeouts();
-    if (isOpen) {
-      skipNextEnterRef.current = true;
-      hide();
-    } else {
-      skipNextEnterRef.current = false;
+  const focusMenu = useCallback(() => {
+    // An empty or still-loading menu has no focusable item; focus the container
+    // so keyboard ownership still transfers off the trigger's list.
+    if (!focusFirst()) {
+      menuRef.current?.focus();
+    }
+  }, [focusFirst, menuRef]);
+
+  const openAndFocus = useCallback(() => {
+    if (!ownsFocus) {
       show();
-      requestAnimationFrame(() => focusFirst());
+      return;
+    }
+    show({skipAutoFocus: true});
+    focusMenu();
+  }, [ownsFocus, show, focusMenu]);
+
+  const confirmHoverOpen = useCallback((): boolean => {
+    const isConfirming =
+      clickGuardMs > 0 &&
+      hoverOpenedAtRef.current > 0 &&
+      Date.now() - hoverOpenedAtRef.current < clickGuardMs;
+    if (!isConfirming) {
+      return false;
     }
-  }, [isOpen, clearTimeouts, show, hide, focusFirst]);
+    hoverModeRef.current = false;
+    hoverOpenedAtRef.current = 0;
+    return true;
+  }, [clickGuardMs]);
+
+  const handleClick = useCallback(
+    (event?: React.MouseEvent) => {
+      // Cancel the invoker's default toggle so this handler stays the single
+      // source of truth; popoverTarget still exempts the trigger from dismissal.
+      if (popoverId) {
+        event?.preventDefault();
+      }
+      clearTimeouts();
+
+      // Enter/Space arrive as a click with detail 0, and always open. A keyboard
+      // user reaches the trigger of an open menu only because a hover-open left
+      // focus behind; closing there would stranded them outside a visible menu.
+      const isKeyboardActivation = event != null && event.detail === 0;
+      if (isKeyboardActivation) {
+        closedAtRef.current = 0;
+        hoverModeRef.current = false;
+        hoverOpenedAtRef.current = 0;
+        if (isOpen) {
+          if (ownsFocus) {
+            focusMenu();
+          }
+        } else {
+          openAndFocus();
+        }
+        return;
+      }
+
+      if (!isOpen) {
+        closedAtRef.current = 0;
+        hoverModeRef.current = false;
+        hoverOpenedAtRef.current = 0;
+        openAndFocus();
+        return;
+      }
+
+      if (confirmHoverOpen()) {
+        if (ownsFocus) {
+          focusMenu();
+        }
+        return;
+      }
+
+      hideAndRestoreFocus();
+    },
+    [
+      popoverId,
+      clearTimeouts,
+      isOpen,
+      ownsFocus,
+      confirmHoverOpen,
+      openAndFocus,
+      focusMenu,
+      hideAndRestoreFocus,
+    ],
+  );
 
-  // Hover: mouseenter activates hover mode and opens
   const handleMouseEnter = useCallback(() => {
     if (!hasHover) {
       return;
     }
-    if (skipNextEnterRef.current) {
-      skipNextEnterRef.current = false;
+    if (
+      closedAtRef.current > 0 &&
+      Date.now() - closedAtRef.current < REOPEN_SUPPRESS_MS
+    ) {
+      return;
+    }
+    // Re-entering an open menu's trigger must not un-pin it or re-arm the
+    // guard, which would make the next deliberate click another "confirm" and
+    // leave the menu undismissable.
+    if (isOpen) {
+      clearTimeouts();
       return;
     }
     hoverModeRef.current = true;
     clearTimeouts();
+    const openByHover = () => {
+      hoverOpenedAtRef.current = Date.now();
+      show({skipAutoFocus: true});
+    };
     if (showDelay > 0) {
-      showTimerRef.current = setTimeout(() => {
-        show({skipAutoFocus: true});
-      }, showDelay);
+      showTimerRef.current = setTimeout(openByHover, showDelay);
     } else {
-      show({skipAutoFocus: true});
+      openByHover();
     }
-  }, [hasHover, clearTimeouts, show, showDelay]);
+  }, [hasHover, isOpen, clearTimeouts, show, showDelay]);
 
-  // Hover: mouseleave only closes if in hover mode
   const handleMouseLeave = useCallback(() => {
+    // A real leave ends the stationary-pointer case the suppression window
+    // exists for, so the next enter is deliberate whenever it arrives.
+    closedAtRef.current = 0;
     if (!hoverModeRef.current) {
       return;
     }
@@ -150,7 +340,6 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
     }, hideDelay);
   }, [clearTimeouts, hide, hideDelay]);
 
-  // Content: mouseenter cancels pending hide
   const handleContentMouseEnter = useCallback(() => {
     clearTimeouts();
   }, [clearTimeouts]);
@@ -173,6 +362,9 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
       },
       menuRef,
       focusFirst,
+      focusMenu,
+      confirmHoverOpen,
+      close: hideAndRestoreFocus,
       setTriggerEl: noopRef,
     };
   }
@@ -182,6 +374,7 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
       onClick: handleClick,
       onMouseEnter: handleMouseEnter,
       onMouseLeave: handleMouseLeave,
+      ...(popoverId ? {popoverTarget: popoverId} : null),
     },
     contentProps: {
       onMouseEnter: handleContentMouseEnter,
@@ -190,6 +383,9 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
     },
     menuRef,
     focusFirst,
+    focusMenu,
+    confirmHoverOpen,
+    close: hideAndRestoreFocus,
     setTriggerEl: setTriggerRef,
   };
 }

package/src/theme/defineTheme.ts

@@ -28,6 +28,12 @@
  *   <App />
  * </Theme>
  * ```
+ *
+ * SYNC: `DefineThemeInput` is the theme surface. Adding, removing, or renaming
+ * a field means updating:
+ * - /packages/cli/assets/theme.template.ts (documents every field; the
+ *   drift guard is scripts/check-theme-template.test.mjs)
+ * - /packages/cli/assets/docs/theme.doc.mjs (`astryx docs theme`)
  */
 
 import type {IconRegistry} from '../Icon/globalIconRegistry';
@@ -42,6 +48,7 @@ import {
   colorDefaults,
   spacingDefaults,
   sizeDefaults,
+  borderDefaults,
   focusDefaults,
   radiusDefaults,
   shadowDefaults,
@@ -75,6 +82,7 @@ export type CoreTokenName =
   | keyof typeof colorDefaults
   | keyof typeof spacingDefaults
   | keyof typeof sizeDefaults
+  | keyof typeof borderDefaults
   | keyof typeof focusDefaults
   | keyof typeof radiusDefaults
   | keyof typeof shadowDefaults
@@ -379,6 +387,7 @@ export const tokenDefaults: Record<string, string> = {
   ...colorDefaults,
   ...spacingDefaults,
   ...sizeDefaults,
+  ...borderDefaults,
   ...focusDefaults,
   ...radiusDefaults,
   ...shadowDefaults,

package/src/theme/derivedVarRegistry.test.ts

@@ -10,6 +10,21 @@
  * 2. Doc check: verifies each var is documented in the doc file's vars[]
  * 3. Registry check: verifies themeable vars have derived[] entries that
  *    match the registry
+ *
+ * Layers 1 and 3 each used to carry a hole that let real vars through:
+ *
+ * - The source scan skipped every `--_*` name outright, on the theory that a
+ *   private var is "internal, not themeable". It is internal, but it is still
+ *   documented — `theming.vars[]` takes `private: true` for exactly this
+ *   (`--_card-radius`, `--_dropdown-menu-padding`), and the derived-var
+ *   pipeline is what theme authors reach it through. Skipping the prefix meant
+ *   10 private vars across 12 (component, var) sites were declared in source
+ *   and documented nowhere.
+ * - Layer 3 narrowed its verdict to vars matching `/radius|padding/`, so any
+ *   var whose name did not happen to contain those two words was exempt from
+ *   ever needing a derived[] mapping. That is now an explicit allowlist
+ *   (VARS_WITHOUT_DERIVED_MAPPING) instead of a name heuristic: a new var must
+ *   be given a derived[] entry or be added to the list on purpose.
  */
 
 import {describe, it, expect} from 'vitest';
@@ -75,7 +90,13 @@ const STRUCTURAL_VARS = new Set([
 /**
  * Extract component-specific CSS custom property names from a source file.
  * Matches patterns like '--_card-radius': or '--_chat-composer-padding':
- * Excludes structural/runtime vars and standard token vars (--color-*, --spacing-*, etc.).
+ * Excludes structural/runtime vars and standard token vars (--color-*,
+ * --spacing-*, etc.).
+ *
+ * Private (`--_*`) vars are INCLUDED. They are internal in the sense that a
+ * theme author does not set them directly, but they are still part of the
+ * documented theming surface (`theming.vars[]` with `private: true`) and are
+ * how derived[] entries connect a standard CSS property to a component.
  */
 function extractComponentVars(filePath: string): string[] {
   const content = readFileSync(filePath, 'utf-8');
@@ -101,10 +122,6 @@ function extractComponentVars(filePath: string): string[] {
     if (/^--(container-|layout-|edge-|component-)/.test(varName)) {
       continue;
     }
-    // Skip private vars (--_ prefix = internal, not themeable)
-    if (varName.startsWith('--_')) {
-      continue;
-    }
     vars.add(varName);
   }
   return [...vars];
@@ -190,6 +207,7 @@ const DIR_TO_REGISTRY_KEY: Record<string, string> = {
   Button: 'button',
   Card: 'card',
   Chat: 'chat',
+  ContextMenu: 'context-menu',
   Dialog: 'dialog',
   DropdownMenu: 'dropdown-menu',
   Field: 'field',
@@ -213,8 +231,55 @@ const CROSS_COMPONENT_VARS: Record<string, string[]> = {
   Carousel: ['--_button-radius'],
   Thumbnail: ['--_button-radius'],
   Chat: ['--_button-radius'],
+  // AvatarGroupOverflow sets the overlap for the Avatars it lays out; Avatar
+  // owns and documents it (and sets it itself when it is the group root).
+  AvatarGroup: ['--_avatar-group-overlap'],
+  // BreadcrumbItem tunes the DropdownMenu it opens.
+  Breadcrumbs: ['--_dropdown-menu-radius', '--_dropdown-menu-padding'],
+  // SelectableCard draws its selection ring through the Card shadow slot.
+  SelectableCard: ['--_card-ring'],
+  // Toolbar offsets the TabList indicator it hosts.
+  Toolbar: ['--_tab-indicator-bottom'],
+  // The destructive item variant recolors the Item it renders; Item owns,
+  // documents and reads both slots.
+  DropdownMenu: ['--_item-label-color', '--_item-description-color'],
 };
 
+/**
+ * Documented vars that intentionally have NO derived[] entry — a theme author
+ * cannot reach them by writing a standard CSS property, only by targeting the
+ * component's own theming surface.
+ *
+ * This replaces a `/radius|padding/` name test that exempted every var whose
+ * name did not contain those words. Each entry is a deliberate classification,
+ * so a NEW var has to be argued into the list rather than slipping past on its
+ * name. The list should shrink over time, not grow.
+ */
+const VARS_WITHOUT_DERIVED_MAPPING = new Set([
+  // No standard CSS property maps onto these — they are component behaviors.
+  '--button-focus-offset',
+  '--button-icon-only-aspect',
+  '--_avatar-group-overlap',
+  '--_codeblock-gutter-width',
+  '--_tab-indicator-bottom',
+  // Hit-area outset on a ::after overlay — `inset` on a pseudo-element is not
+  // a property a theme author sets on the component.
+  '--_thumbnail-hit-inset',
+  // Indentation and row-spacing metrics: --tree-list-indent is the authorable
+  // step, --_tree-indent the per-row distance TreeListItem computes from it.
+  // --tree-list-row-gap is applied as half a padding-block on each row wrapper,
+  // not as gap on the list, so no standard property on the tree-list target
+  // maps onto it; a theme sets the var directly.
+  '--tree-list-indent',
+  '--_tree-indent',
+  '--tree-list-row-gap',
+  // Composed into a single box-shadow list on the card, so neither maps 1:1
+  // onto boxShadow — setting one through a derived entry would clobber the
+  // other.
+  '--_card-elevation',
+  '--_card-ring',
+]);
+
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
@@ -262,19 +327,20 @@ describe('component CSS vars are documented and themeable', () => {
         return true;
       });
 
-      // Filter to only vars that look like they map to CSS properties
-      // (radius → borderRadius, padding → padding). Vars like
-      // --button-press-scale or --button-disabled-opacity are
-      // component-specific behaviors, not standard CSS property mappings.
-      const themeableVars = missingDerived.filter(v =>
-        /radius|padding/.test(v),
+      // Everything that is not explicitly classified as unmappable must have
+      // a derived[] entry. (This was a `/radius|padding/` name test, which
+      // exempted any var whose name lacked those words.)
+      const themeableVars = missingDerived.filter(
+        v => !VARS_WITHOUT_DERIVED_MAPPING.has(v),
       );
 
       expect(
         themeableVars,
         `${dir} has vars that should be themeable via derived[]: ${themeableVars.join(', ')}. ` +
           `Add derived[] entries in ${dir}.doc.mjs mapping standard CSS ` +
-          `properties (borderRadius, padding) to these internal vars.`,
+          `properties (borderRadius, padding) to these internal vars — or, if ` +
+          `no standard property maps onto them, add them to ` +
+          `VARS_WITHOUT_DERIVED_MAPPING with the reason.`,
       ).toEqual([]);
     });
   }

package/src/theme/derivedVarRegistry.ts

@@ -57,6 +57,10 @@ export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
     {property: 'borderRadius', vars: ['--_dialog-radius']},
     {property: 'padding', expand: 'container'},
   ],
+  'context-menu': [
+    {property: 'borderRadius', vars: ['--_dropdown-menu-radius']},
+    {property: 'padding', vars: ['--_dropdown-menu-padding']},
+  ],
   'dropdown-menu': [
     {property: 'borderRadius', vars: ['--_dropdown-menu-radius']},
     {property: 'padding', vars: ['--_dropdown-menu-padding']},

package/src/theme/expandColorScale.ts

@@ -28,6 +28,7 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/theme/defineTheme.ts
+ * - /packages/cli/assets/theme.template.ts (the annotated field reference)
  */
 
 import {contrastRatio} from './contrast';

package/src/theme/expandMotionScale.ts

@@ -18,6 +18,7 @@
  * SYNC: When modified, update:
  * - /packages/core/src/theme/expandMotionScale.test.ts
  * - /packages/core/src/theme/defineTheme.ts
+ * - /packages/cli/assets/theme.template.ts (the annotated field reference)
  */
 
 // =============================================================================

package/src/theme/expandRadiusScale.ts

@@ -22,6 +22,7 @@
  * SYNC: When modified, update:
  * - /packages/core/src/theme/expandRadiusScale.test.ts
  * - /packages/core/src/theme/defineTheme.ts
+ * - /packages/cli/assets/theme.template.ts (the annotated field reference)
  */
 
 // =============================================================================

package/src/theme/expandTypeScale.ts

@@ -44,6 +44,7 @@
  * SYNC: When modified, update:
  * - /packages/core/src/theme/expandTypeScale.test.ts
  * - /packages/core/src/theme/defineTheme.ts
+ * - /packages/cli/assets/theme.template.ts (the annotated field reference)
  */
 
 // =============================================================================