@godxjp/ui 27.3.1 → 27.4.1

package/dist/components/general/icon.d.ts

@@ -0,0 +1,31 @@
+import * as React from "react";
+export type { IconGlyphProp, IconGlyphProp as IconProps, } from "../../props/components/general.prop.js";
+/**
+ * Icon — a glyph on the `--icon-size-*` scale, and the only supported way to draw a standalone one.
+ *
+ * WHY THIS EXISTS (gh#712). A lucide component ships `width="24" height="24"`, and exactly four
+ * rules in this library ever override that: `.ui-button svg`, `.ui-dropdown-menu-item > svg`,
+ * `.ui-topbar-item > svg` and `[data-slot="list-row-leading"] > svg`. Anywhere else — in a `Text`,
+ * in a table cell, in an `<a>` — the glyph draws at 24px beside 14px type, 1.71× the text it
+ * annotates. A consumer cannot fix that themselves: `size-4` and `w-[16px]` are what
+ * docs/CONSUMER-RULES.md §3/§8 forbid, and `size={16}` hard-codes a number the theme owns. One
+ * consumer measured 38 such glyphs in a single app.
+ *
+ * RENDERS ONTO THE GLYPH, NOT AROUND IT. `as={Lock}` is invoked with the class, the size and the
+ * a11y wiring, so the element that carries the metric IS the `<svg>`. A wrapper `<span>` would add
+ * a box to every flex row that holds an icon, and would break `Button`'s own `svg` rule by putting
+ * an element between the two.
+ *
+ * DECORATIVE BY DEFAULT. Without `label` the glyph is `aria-hidden` — a glyph beside a visible
+ * label is decoration, and announcing it twice is the usual defect (WCAG 2.2 SC 1.1.1). Pass
+ * `label` only when the glyph is the ONLY thing saying what it says; it then renders as
+ * `role="img"` + that name, which is how a graphic gets a name in WAI-ARIA 1.2. The string is the
+ * consumer's to localize — the library ships no copy for it.
+ */
+export declare const Icon: React.ForwardRefExoticComponent<Omit<React.SVGProps<SVGSVGElement>, "children" | "ref"> & {
+    as: React.ComponentType<React.SVGProps<SVGSVGElement> & React.RefAttributes<SVGSVGElement>>;
+    size?: import("../../props/index.js").IconSizeProp;
+    tone?: import("../../props/index.js").TextToneProp;
+    label?: string;
+    className?: import("../../props/index.js").ClassNameProp;
+} & React.RefAttributes<SVGSVGElement>>;

package/dist/components/general/icon.js

@@ -0,0 +1,23 @@
+import { jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../../lib/utils.js";
+const Icon = React.forwardRef(function Icon2({ as: Glyph, size = "md", tone, label, className, ...props }, ref) {
+  const named = label !== void 0 && label !== "";
+  return /* @__PURE__ */ jsx(
+    Glyph,
+    {
+      ref,
+      "data-slot": "icon",
+      "data-size": size,
+      "data-tone": tone,
+      className: cn("ui-icon", className),
+      role: named ? "img" : void 0,
+      "aria-label": named ? label : void 0,
+      "aria-hidden": named ? void 0 : true,
+      ...props
+    }
+  );
+});
+export {
+  Icon
+};

package/dist/components/general/index.d.ts

@@ -2,6 +2,8 @@ export { Button, buttonVariants } from "./button.js";
 export type { ButtonProps } from "./button.js";
 export { Text, Heading, Typography, Title, Paragraph, Link } from "./typography.js";
 export type { TextProps, HeadingProps, TextProp, HeadingProp, TypographyProp, TypographyProps, TypographyBlockProp, TypographyTitleProp, TitleProps, ParagraphProp, ParagraphProps, LinkProp, LinkProps, } from "./typography.js";
+export { Icon } from "./icon.js";
+export type { IconGlyphProp, IconProps } from "./icon.js";
 export { Logo } from "./logo.js";
 export type { LogoMark, LogoProps, LogoSize, LogoTone } from "./logo.js";
 export { Reveal } from "./reveal.js";

package/dist/components/general/index.js

@@ -1,5 +1,6 @@
 import { Button, buttonVariants } from "./button.js";
 import { Text, Heading, Typography, Title, Paragraph, Link } from "./typography.js";
+import { Icon } from "./icon.js";
 import { Logo } from "./logo.js";
 import { Reveal } from "./reveal.js";
 import { FloatButton } from "./float-button.js";
@@ -15,6 +16,7 @@ export {
   Button,
   FloatButton,
   Heading,
+  Icon,
   Link,
   Logo,
   Paragraph,

package/dist/components/layout/flex.d.ts

@@ -1,3 +1,3 @@
 import type { FlexProp } from "../../props/components/layout.prop.js";
-export type { FlexAlignProp, FlexDirectionProp, FlexJustifyProp, FlexProp, FlexProp as FlexProps, } from "../../props/components/layout.prop.js";
-export declare function Flex({ as: Element, direction, grow, shrink, surface, bleed, reveal, gap, gapRaw, pad, padRaw, align, justify, wrap, hideBelow, hideFrom, hideBelowRaw, hideFromRaw, fill, width, className, style, children, ...props }: FlexProp): import("react").JSX.Element;
+export type { FlexAlignProp, FlexDirectionProp, FlexJustifyProp, FlexMarkerProp, FlexProp, FlexProp as FlexProps, } from "../../props/components/layout.prop.js";
+export declare function Flex({ as: Element, direction, marker, grow, shrink, surface, bleed, reveal, gap, gapRaw, pad, padRaw, align, justify, wrap, hideBelow, hideFrom, hideBelowRaw, hideFromRaw, fill, width, className, style, children, ...props }: FlexProp): import("react").JSX.Element;

package/dist/components/layout/flex.js

@@ -6,9 +6,15 @@ import { flexGapClass, padStyle, padStepToken } from "../../lib/variants.js";
 const toCssLength = (value) => typeof value === "number" ? `${value}px` : value;
 const rawBreakpoint = (value) => typeof value === "number" && Number.isFinite(value) ? value : void 0;
 const rawBreakpointRule = (axis, px) => `@media (width ${axis === "below" ? "<" : ">="} ${px}px){.ui-flex[data-hide-${axis}-raw="${px}"]{display:none}}`;
+const listMarker = (element, marker) => {
+  if (element !== "ul" && element !== "ol") return void 0;
+  const resolved = marker ?? (element === "ul" ? "disc" : "decimal");
+  return resolved === "none" ? void 0 : resolved;
+};
 function Flex({
   as: Element = "div",
   direction = "row",
+  marker,
   grow,
   shrink,
   surface,
@@ -65,7 +71,7 @@ function Flex({
       "data-shrink": shrink === false ? "false" : void 0,
       "data-surface": surface,
       "data-reveal": reveal,
-      "data-list": Element === "ul" ? "disc" : Element === "ol" ? "decimal" : void 0,
+      "data-list": listMarker(Element, marker),
       "data-align": align,
       "data-justify": justify,
       "data-wrap": wrap ? "true" : void 0,

package/dist/components/layout/topbar-item.d.ts

@@ -12,6 +12,7 @@ export type { TopbarItemProp, TopbarItemProp as TopbarItemProps, } from "../../p
  */
 export declare const TopbarItem: React.ForwardRefExoticComponent<Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> & {
     hideBelow?: import("../../props/index.js").BreakpointProp;
+    icon?: React.ReactNode;
     badge?: React.ReactNode;
     badgeTone?: import("../../props/components/layout.prop.js").SidebarBadgeToneProp;
     asChild?: boolean;

package/dist/components/layout/topbar-item.js

@@ -2,9 +2,10 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { Slot } from "../../lib/slot.js";
 import { cn } from "../../lib/utils.js";
-const TopbarItem = React.forwardRef(function TopbarItem2({ asChild = false, className, type, hideBelow, badge, badgeTone, children, ...props }, ref) {
+const TopbarItem = React.forwardRef(function TopbarItem2({ asChild = false, className, type, hideBelow, icon, badge, badgeTone, children, ...props }, ref) {
   const Comp = asChild ? Slot : "button";
   const showBadge = !asChild && badge !== void 0 && badge !== "";
+  const iconNode = !asChild && icon !== void 0 && icon !== null && icon !== false ? /* @__PURE__ */ jsx("span", { "data-slot": "topbar-item-icon", className: "ui-topbar-item-icon", children: icon }) : null;
   const badgeNode = showBadge ? /* @__PURE__ */ jsx(
     "span",
     {
@@ -24,6 +25,7 @@ const TopbarItem = React.forwardRef(function TopbarItem2({ asChild = false, clas
       type: asChild ? void 0 : type ?? "button",
       ...props,
       children: asChild ? children : /* @__PURE__ */ jsxs(Fragment, { children: [
+        iconNode,
         children,
         badgeNode
       ] })

package/dist/contracts/measurement.json

@@ -1,6 +1,6 @@
 {
   "$comment": "AUTO-GENERATED by scripts/gen-measurement-contract.mjs — do not edit. Read this instead of guessing: docs/MEASUREMENT-CONTRACT.md.",
-  "version": "27.3.1",
+  "version": "27.4.1",
   "targetSize": {
     "standard": "WCAG 2.2 SC 2.5.8 Target Size (Minimum), level AA — 24×24 CSS px",
     "min": 24,

package/dist/props/components/general.prop.d.ts

@@ -1,6 +1,6 @@
 /** Foundation component prop types — @see docs/COMPONENTS.md#foundation */
 import type * as React from "react";
-import type { ActivityAnnounceProp, ActivityVariantProp, AsChildProp, ButtonSizeProp, ButtonVariantProp, ChildrenProp, ClassNameProp, DescriptionProp, DisabledProp, FontWeightProp, HeadingLevelProp, IdProp, LabelProp, OnClickProp, OnOpenChangeProp, OpenProp, PendingProp, RevealDelayProp, ShapeProp, SizeProp, TextAlignProp, TextSizeProp, TextToneProp, TextWhitespaceProp, TitleLevelProp, TypographyActionsConfigProp, TypographyCopyConfigProp, TypographyEditConfigProp, TypographyEllipsisConfigProp, TypographyTypeProp } from "../vocabulary/index.js";
+import type { ActivityAnnounceProp, ActivityVariantProp, AsChildProp, ButtonSizeProp, ButtonVariantProp, ChildrenProp, ClassNameProp, DescriptionProp, DisabledProp, FontWeightProp, HeadingLevelProp, IconSizeProp, IdProp, LabelProp, OnClickProp, OnOpenChangeProp, OpenProp, PendingProp, RevealDelayProp, ShapeProp, SizeProp, TextAlignProp, TextSizeProp, TextToneProp, TextWhitespaceProp, TitleLevelProp, TypographyActionsConfigProp, TypographyCopyConfigProp, TypographyEditConfigProp, TypographyEllipsisConfigProp, TypographyTypeProp } from "../vocabulary/index.js";
 /**
  * @see Text — typographic primitive; replaces hand-rolled `<span className="text-[13px] …">`.
  *
@@ -336,6 +336,47 @@ export type ActivityProp = Omit<React.HTMLAttributes<HTMLSpanElement>, "color">
     announce?: ActivityAnnounceProp;
     className?: ClassNameProp;
 };
+/**
+ * @see Icon — the ONE supported way to put a standalone glyph on the `--icon-size-*` scale.
+ *
+ * A lucide component carries `width="24" height="24"` of its own, and only four rules in this
+ * library ever re-size a glyph (`.ui-button svg`, the menu row, the topbar cell, the ListRow
+ * leading slot) — three of them direct-child rules. Outside those four a glyph renders at 24px
+ * beside 14px text, and a consumer has no supported way to fix it: `docs/CONSUMER-RULES.md` §8
+ * forbids `size-4`/`w-[16px]`, and `size={16}` re-derives a scale the theme owns. Measured in a
+ * consumer at 38 such glyphs (gh#712).
+ *
+ * Icon renders ONTO the glyph rather than wrapping it — the sized element IS the `<svg>` — so it
+ * composes anywhere a bare glyph does (inside `Text`, in a `Button`, in a table cell, in an `<a>`)
+ * and adds no box to the layout.
+ */
+export type IconGlyphProp = Omit<React.SVGProps<SVGSVGElement>, "ref" | "children"> & {
+    /**
+     * The glyph COMPONENT — `as={Lock}`, not `<Lock />`. Any component that forwards SVG props and a
+     * ref qualifies (every `lucide-react` icon does); Icon hands it the class, the size attributes
+     * and the a11y wiring.
+     */
+    as: React.ComponentType<React.SVGProps<SVGSVGElement> & React.RefAttributes<SVGSVGElement>>;
+    /**
+     * Step of the nine-step icon scale. Default `md` (16px — "the default icon step" in
+     * docs/TOKENS.md). A glyph beside `Text size="sm"` wants `sm`; an empty-state mark wants `4xl`.
+     */
+    size?: IconSizeProp;
+    /**
+     * Semantic colour intent, the same vocabulary `Text` uses. Omitted by default, and that default
+     * is load-bearing: a glyph inherits `currentColor`, so an Icon inside a Button, a Badge or a
+     * toned `Text` paints in that surface's own ink without being told.
+     */
+    tone?: TextToneProp;
+    /**
+     * Accessible NAME, when the glyph carries meaning nothing else on screen says (a lock in a
+     * status cell with no text beside it). Localized by the consumer — the library ships no copy.
+     * Supplying it switches the glyph from `aria-hidden` to `role="img"` + that name; leave it off
+     * (the default) for a decorative glyph beside a visible label, which is the common case.
+     */
+    label?: string;
+    className?: ClassNameProp;
+};
 /**
  * FloatButton `type` — the two fills Ant Design gives the corner mark.
  *

package/dist/props/components/layout.prop.d.ts

@@ -100,6 +100,11 @@ export type PageContainerProp = {
     className?: ClassNameProp;
 };
 export type FlexDirectionProp = "row" | "col";
+/**
+ * List marker for `as="ul"`/`as="ol"` — the CSS `list-style-type` keywords the layer implements,
+ * plus `none` for a list that is SEMANTIC ONLY (gh#714).
+ */
+export type FlexMarkerProp = "disc" | "decimal" | "none";
 export type FlexAlignProp = "start" | "center" | "end" | "stretch" | "baseline";
 export type FlexJustifyProp = "start" | "center" | "end" | "between" | "around" | "evenly";
 /** @see Flex */
@@ -112,6 +117,26 @@ export type FlexProp = React.HTMLAttributes<HTMLElement> & {
      * `.ui-flex` rules carry `display: flex`, so the box is identical either way.
      */
     as?: "div" | "span" | "ul" | "ol" | "li";
+    /**
+     * Marker for a LIST element (`as="ul"` → `disc`, `as="ol"` → `decimal` by default); ignored by
+     * every other tag.
+     *
+     * `marker="none"` emits no `data-list` at all, so the list keeps its element, its `<li>`
+     * semantics and its `gap`, and loses the bullet AND the `--space-5` indent that come with it.
+     *
+     * ## Why the axis exists
+     *
+     * The bullet was unconditional, and the catalog's own idiom — `<ListRow as="li">` inside a list
+     * — could not live with it: `.ui-flex[data-list] > li { display: list-item }` outranks
+     * `[data-slot="list-row"] { display: flex }`, so every row fell out of flex layout (measured on
+     * this page: row height 94.58px → 41.2px once the attribute is gone). The only move left was a
+     * RAW `<ul>`, which carries no gap token and which the consumer rules forbid in spirit — one
+     * consumer kept three `Flex role="list"` divs for exactly that reason (gh#714).
+     *
+     * `disc`/`decimal` stay available so an `<ol>` can be bulleted (or a `<ul>` numbered) without a
+     * `list-style-type` in a className.
+     */
+    marker?: FlexMarkerProp;
     /** Lightweight surfaces for rows and notices; no Card elevation by default. */
     surface?: "muted" | "popover" | "warning";
     /** Negative inline inset, using the same spacing scale as pad. */
@@ -1314,6 +1339,23 @@ export type TopbarItemProp = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>,
      */
     /** Hide below a shared responsive breakpoint, without changing cell height. */
     hideBelow?: BreakpointProp;
+    /**
+     * The cell's leading glyph, placed in a slot the CELL sizes (`--topbar-icon-size`).
+     *
+     * Passing the glyph as a child works too — but only while it stays a DIRECT child, because
+     * `.ui-topbar-item > svg` is the rule that sizes it. The moment a cell wraps its glyph (a
+     * `<Flex hideBelow>` so the icon drops at narrow widths) the rule can no longer reach it and the
+     * glyph renders at lucide's intrinsic 24px: measured at 390px on an org-switcher cell, 1.5x the
+     * cell's own step (gh#712). This slot survives that, because the wrapper is the one the cell
+     * placed. The alternative — widening the rule to a descendant — was measured to shrink or grow
+     * OTHER components' glyphs inside the cell (a Badge's 12px glyph became 16px), so it is not one.
+     *
+     * Decorative by convention: the cell's accessible name comes from its own `aria-label` or its
+     * visible label, not from the glyph. For a glyph that must carry a name, or one that needs a
+     * step other than the bar's, pass `<Icon as={…} size=… label=… />` — as this prop's value or as
+     * a child — and it keeps its own metric and its own semantics.
+     */
+    icon?: ReactNode;
     /**
      * Unread count OVERLAID on the cell's glyph — the notification-bell affordance the cell's own use
      * cases name (gh#398). Pass the CONTENT ONLY, exactly like `SidebarItemProp.badge`: a number, a

package/dist/props/registry.d.ts

@@ -434,6 +434,11 @@ export declare const VOCABULARY_REGISTRY: {
         readonly category: "interaction";
         readonly description: "Text size — golden-ratio type-scale steps (2xs…2xl), never an arbitrary px";
     };
+    readonly IconSizeProp: {
+        readonly file: "vocabulary/interaction.prop.ts";
+        readonly category: "interaction";
+        readonly description: "Icon size — the nine --icon-size-* scale steps (2xs…4xl), never an arbitrary px or a size- utility";
+    };
     readonly TextToneProp: {
         readonly file: "vocabulary/interaction.prop.ts";
         readonly category: "interaction";
@@ -746,6 +751,11 @@ export declare const COMPONENT_PROP_REGISTRY: {
         readonly file: "components/layout.prop.ts";
         readonly vocabulary: readonly [];
     };
+    readonly FlexMarkerProp: {
+        readonly group: "layout";
+        readonly file: "components/layout.prop.ts";
+        readonly vocabulary: readonly [];
+    };
     readonly FlexAlignProp: {
         readonly group: "layout";
         readonly file: "components/layout.prop.ts";
@@ -767,6 +777,10 @@ export declare const COMPONENT_PROP_REGISTRY: {
             readonly field: "direction";
             readonly local: true;
             readonly reason: "Flex-specific axis control.";
+        }, {
+            readonly field: "marker";
+            readonly local: true;
+            readonly reason: 'List-marker seam for as="ul"/"ol" (disc | decimal | none). marker="none" emits no data-list, so a list keeps its element, its <li> semantics and its gap token while losing the bullet and the --space-5 indent — the home <ListRow as="li"> had none of, which forced a raw <ul> (gh#714).';
         }, "GapProp", {
             readonly field: "align";
             readonly local: true;
@@ -1203,6 +1217,23 @@ export declare const COMPONENT_PROP_REGISTRY: {
             readonly reason: "Ambient live-region opt-in — ActivityAnnounceProp vocabulary; deliberately NOT a boolean so the value names the politeness level.";
         }];
     };
+    readonly IconGlyphProp: {
+        readonly group: "general";
+        readonly file: "components/general.prop.ts";
+        readonly vocabulary: readonly ["IconProp", "IconSizeProp", "TextToneProp", "LabelProp", "ClassNameProp", {
+            readonly field: "label";
+            readonly local: true;
+            readonly reason: "LabelProp narrowed to string: this becomes the glyph's aria-label, and an accessible name is TEXT — a ReactNode cannot be one.";
+        }, {
+            readonly field: "as";
+            readonly local: true;
+            readonly reason: "The glyph COMPONENT to render — the IconProp concept, widened to a component that also forwards SVG props and a ref, because Icon renders ONTO the glyph (the sized element is the <svg> itself) rather than wrapping it.";
+        }, {
+            readonly field: "size";
+            readonly local: true;
+            readonly reason: "IconSizeProp, the nine-step icon scale — deliberately NOT the four-step control SizeProp: a glyph beside 2xs caption text and a 48px empty-state mark are the same primitive.";
+        }];
+    };
     readonly FloatButtonTypeProp: {
         readonly group: "general";
         readonly file: "components/general.prop.ts";

package/dist/props/registry.js

@@ -433,6 +433,11 @@ const VOCABULARY_REGISTRY = {
     category: "interaction",
     description: "Text size \u2014 golden-ratio type-scale steps (2xs\u20262xl), never an arbitrary px"
   },
+  IconSizeProp: {
+    file: "vocabulary/interaction.prop.ts",
+    category: "interaction",
+    description: "Icon size \u2014 the nine --icon-size-* scale steps (2xs\u20264xl), never an arbitrary px or a size- utility"
+  },
   TextToneProp: {
     file: "vocabulary/interaction.prop.ts",
     category: "interaction",
@@ -767,6 +772,7 @@ const COMPONENT_PROP_REGISTRY = {
     ]
   },
   FlexDirectionProp: { group: "layout", file: "components/layout.prop.ts", vocabulary: [] },
+  FlexMarkerProp: { group: "layout", file: "components/layout.prop.ts", vocabulary: [] },
   FlexAlignProp: { group: "layout", file: "components/layout.prop.ts", vocabulary: [] },
   FlexJustifyProp: { group: "layout", file: "components/layout.prop.ts", vocabulary: [] },
   FlexProp: {
@@ -779,6 +785,11 @@ const COMPONENT_PROP_REGISTRY = {
         reason: "Closed tag seam (div | span) so a Flex stays valid HTML inside a phrasing-only parent such as the <button> a TabsTrigger renders \u2014 same shape as ListRow's `as` (gh#354)."
       },
       { field: "direction", local: true, reason: "Flex-specific axis control." },
+      {
+        field: "marker",
+        local: true,
+        reason: 'List-marker seam for as="ul"/"ol" (disc | decimal | none). marker="none" emits no data-list, so a list keeps its element, its <li> semantics and its gap token while losing the bullet and the --space-5 indent \u2014 the home <ListRow as="li"> had none of, which forced a raw <ul> (gh#714).'
+      },
       "GapProp",
       { field: "align", local: true, reason: "Flex-specific align-items keyword subset." },
       { field: "justify", local: true, reason: "Flex-specific justify-content keyword subset." },
@@ -1328,6 +1339,32 @@ const COMPONENT_PROP_REGISTRY = {
       }
     ]
   },
+  IconGlyphProp: {
+    group: "general",
+    file: "components/general.prop.ts",
+    vocabulary: [
+      "IconProp",
+      "IconSizeProp",
+      "TextToneProp",
+      "LabelProp",
+      "ClassNameProp",
+      {
+        field: "label",
+        local: true,
+        reason: "LabelProp narrowed to string: this becomes the glyph's aria-label, and an accessible name is TEXT \u2014 a ReactNode cannot be one."
+      },
+      {
+        field: "as",
+        local: true,
+        reason: "The glyph COMPONENT to render \u2014 the IconProp concept, widened to a component that also forwards SVG props and a ref, because Icon renders ONTO the glyph (the sized element is the <svg> itself) rather than wrapping it."
+      },
+      {
+        field: "size",
+        local: true,
+        reason: "IconSizeProp, the nine-step icon scale \u2014 deliberately NOT the four-step control SizeProp: a glyph beside 2xs caption text and a 48px empty-state mark are the same primitive."
+      }
+    ]
+  },
   FloatButtonTypeProp: {
     group: "general",
     file: "components/general.prop.ts",

package/dist/props/vocabulary/index.d.ts

@@ -2,6 +2,6 @@
 export type { ClassNameProp, ChildrenProp, IdProp, OpenProp, DefaultOpenProp, OnOpenChangeProp, HandlerProp, PendingProp, RequiredProp, DisabledProp, LabelProp, HelperProp, ErrorProp, ErrorBagProp, PlaceholderProp, NameProp, ValueProp, DefaultValueProp, OnValueChangeProp, OnChangeProp, OnClickProp, AsChildProp, FlushProp, WidthProp, ControlWidthProp, AllowClearProp, MaxTagCountProp, MaxTagPlaceholderProp, NotFoundContentProp, PopupMatchWidthProp, } from "./shared.prop.js";
 export type { TitleProp, SubtitleProp, StatusProp, DescriptionProp, ExtraProp, FooterProp, ActionProp, IconProp, ConfirmLabelProp, CancelLabelProp, ActionsProp, EmptyMessageProp, } from "./content.prop.js";
 export type { PageDensityProp, PageContainerVariantProp, CenteredShellWidthProp, CenteredShellAlignProp, CenteredShellPresetProp, ErrorSurfaceModeProp, ErrorSurfaceStatusProp, AuthShellPresetProp, MobileShellHeightProp, MobileShellWidthProp, OrientationProp, TableDensityProp, DensityProp, GapNameProp, PadProp, PadRawProp, PadSides, GapProp, GapStepProp, } from "./layout.prop.js";
-export type { ButtonVariantProp, ButtonSizeProp, BadgeVariantProp, AppSettingPickerAppearanceProp, AppSettingToggleAppearanceProp, ShapeProp, AvatarShapeProp, TextSizeProp, TextToneProp, FontWeightProp, HeadingLevelProp, TextAlignProp, TextWhitespaceProp, TypographyTypeProp, TitleLevelProp, TypographyCopyConfigProp, TypographyEditConfigProp, TypographyEllipsisConfigProp, TypographyActionsConfigProp, SizeProp, ControlStatusProp, ControlVariantProp, FormLayoutProp, DescriptionsLayoutProp, BreakpointProp, ConfirmVariantProp, ToneProp, AlertVariantProp, SortDirectionProp, ColumnAlignProp, SortStateProp, RevealDelayProp, ActivityVariantProp, ActivityAnnounceProp, } from "./interaction.prop.js";
+export type { ButtonVariantProp, ButtonSizeProp, BadgeVariantProp, AppSettingPickerAppearanceProp, AppSettingToggleAppearanceProp, ShapeProp, AvatarShapeProp, TextSizeProp, TextToneProp, FontWeightProp, HeadingLevelProp, TextAlignProp, TextWhitespaceProp, TypographyTypeProp, TitleLevelProp, TypographyCopyConfigProp, TypographyEditConfigProp, TypographyEllipsisConfigProp, TypographyActionsConfigProp, SizeProp, ControlStatusProp, ControlVariantProp, FormLayoutProp, DescriptionsLayoutProp, BreakpointProp, ConfirmVariantProp, ToneProp, AlertVariantProp, SortDirectionProp, ColumnAlignProp, SortStateProp, RevealDelayProp, ActivityVariantProp, ActivityAnnounceProp, IconSizeProp, } from "./interaction.prop.js";
 export type { BreadcrumbItemProp, BreadcrumbProp, BreadcrumbItemMenuProp, BreadcrumbItemMenuEntryProp, BreadcrumbSeparatorProp, BreadcrumbItemRenderProp, } from "./navigation.prop.js";
 export type { GetRowIdProp, GetRowLabelProp, OnRowClickProp, ColumnDefProp, TablePresetProp, TableColumnPriorityProp, TableCellIndentProp, SelectedIdsProp, OnSelectChangeProp, OnTableDensityChangeProp, TableRowToneProp, RowToneProp, OnSortChangeProp, OnSearchChangeProp, OnClearFiltersProp, HasActiveFiltersProp, StickyProp, ColumnFixedProp, ColumnFilterValueProp, ColumnFilterItemProp, ColumnFilterStateProp, OnColumnFilterChangeProp, ColumnCompareProp, ColumnSorterProp, TableSelectionItemProp, TableRowSelectionProp, TableExpandableProp, TableSummaryProp, TableScrollProp, TableStickyProp, OnRowProp, TablePaginationProp, TablePaginationPositionProp, DescriptionsColumnProp, DescriptionsSpanProp, DescriptionsItemsProp, } from "./data.prop.js";

package/dist/props/vocabulary/interaction.prop.d.ts

@@ -31,6 +31,17 @@ export type ShapeProp = "default" | "pill" | "sharp";
 export type AvatarShapeProp = "circle" | "square";
 /** Text size — steps of the golden-ratio type scale (NEVER an arbitrary px). `sm` = base. */
 export type TextSizeProp = "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+/**
+ * Icon size — the NINE steps of the `--icon-size-*` scale (docs/TOKENS.md · gh#326), not the four
+ * of the control `SizeProp`.
+ *
+ * The icon axis already had a vocabulary before it had a name, and it is a FIXED LIST rather than
+ * a ratio: 14/16 = 0.875 but 20/16 = 1.25, because a 1px-stroke glyph cannot sit on half a pixel.
+ * Naming the whole list here — as `TextSizeProp` does for type — is what lets a consumer put a
+ * standalone glyph on the scale (`<Icon as={Lock} size="sm" />`) instead of reaching for a
+ * `className="size-4"` the consumer rules forbid.
+ */
+export type IconSizeProp = "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl";
 /** Text colour intent — maps to semantic foreground tokens (no raw palette). */
 /**
  * `inherit` is the one that is NOT a colour: it takes whatever the surface already set (gh#643).

package/dist/styles/core.css

@@ -23,3 +23,5 @@
 @import "./navigation-layout.css";
 @import "./chart-layout.css";
 @import "./float-button-layout.css";
+
+@import "./icon-layout.css";

package/dist/styles/icon-layout.css

@@ -0,0 +1,37 @@
+
+@layer components {
+  svg.ui-icon[data-slot="icon"] {
+    inline-size: var(--icon-glyph-size);
+    block-size: var(--icon-glyph-size);
+
+    flex: 0 0 auto;
+  }
+
+  .ui-icon[data-size="2xs"] {
+    --icon-glyph-size: var(--icon-size-2xs);
+  }
+  .ui-icon[data-size="xs"] {
+    --icon-glyph-size: var(--icon-size-xs);
+  }
+  .ui-icon[data-size="sm"] {
+    --icon-glyph-size: var(--icon-size-sm);
+  }
+  .ui-icon[data-size="md"] {
+    --icon-glyph-size: var(--icon-size-md);
+  }
+  .ui-icon[data-size="lg"] {
+    --icon-glyph-size: var(--icon-size-lg);
+  }
+  .ui-icon[data-size="xl"] {
+    --icon-glyph-size: var(--icon-size-xl);
+  }
+  .ui-icon[data-size="2xl"] {
+    --icon-glyph-size: var(--icon-size-2xl);
+  }
+  .ui-icon[data-size="3xl"] {
+    --icon-glyph-size: var(--icon-size-3xl);
+  }
+  .ui-icon[data-size="4xl"] {
+    --icon-glyph-size: var(--icon-size-4xl);
+  }
+}

package/dist/styles/index.css

@@ -25,3 +25,5 @@
 @import "./navigation-layout.css";
 @import "./chart-layout.css";
 @import "./float-button-layout.css";
+
+@import "./icon-layout.css";

package/dist/styles/shell-layout.css

@@ -2083,6 +2083,16 @@
     flex: 0 0 auto;
   }
 
+  .ui-topbar-item-icon {
+    display: inline-flex;
+    flex: 0 0 auto;
+    align-items: center;
+  }
+  .ui-topbar-item-icon svg {
+    inline-size: var(--topbar-icon-size);
+    block-size: var(--topbar-icon-size);
+  }
+
   @media (width <= 68.75rem) {
     .ui-topbar-center {
       display: var(--topbar-center-compact-display);

package/dist/styles/text-layout.css

@@ -51,37 +51,45 @@
   }
 
   [data-slot="text"][data-tone="default"],
-  [data-slot="heading"][data-tone="default"] {
+  [data-slot="heading"][data-tone="default"],
+  [data-slot="icon"][data-tone="default"] {
     color: hsl(var(--foreground));
   }
   [data-slot="text"][data-tone="muted"],
-  [data-slot="heading"][data-tone="muted"] {
+  [data-slot="heading"][data-tone="muted"],
+  [data-slot="icon"][data-tone="muted"] {
     color: hsl(var(--muted-foreground));
   }
 
   [data-slot="text"][data-tone="inherit"],
-  [data-slot="heading"][data-tone="inherit"] {
+  [data-slot="heading"][data-tone="inherit"],
+  [data-slot="icon"][data-tone="inherit"] {
     color: inherit;
   }
   [data-slot="text"][data-tone="primary"],
-  [data-slot="heading"][data-tone="primary"] {
+  [data-slot="heading"][data-tone="primary"],
+  [data-slot="icon"][data-tone="primary"] {
     color: hsl(var(--primary));
   }
 
   [data-slot="text"][data-tone="success"],
-  [data-slot="heading"][data-tone="success"] {
+  [data-slot="heading"][data-tone="success"],
+  [data-slot="icon"][data-tone="success"] {
     color: hsl(var(--text-success));
   }
   [data-slot="text"][data-tone="warning"],
-  [data-slot="heading"][data-tone="warning"] {
+  [data-slot="heading"][data-tone="warning"],
+  [data-slot="icon"][data-tone="warning"] {
     color: hsl(var(--text-warning));
   }
   [data-slot="text"][data-tone="destructive"],
-  [data-slot="heading"][data-tone="destructive"] {
+  [data-slot="heading"][data-tone="destructive"],
+  [data-slot="icon"][data-tone="destructive"] {
     color: hsl(var(--text-error));
   }
   [data-slot="text"][data-tone="info"],
-  [data-slot="heading"][data-tone="info"] {
+  [data-slot="heading"][data-tone="info"],
+  [data-slot="icon"][data-tone="info"] {
     color: hsl(var(--text-info));
   }
 

package/docs/CONSUMER-RULES.md

@@ -5,9 +5,9 @@ Read this once; the audit enforces it. Everything else in `docs/` is for contrib
 1. Load styles with `@import "@godxjp/ui/styles"` (fonts bundled, 729 sliced woff2 faces, ~11.7 MB), `@import "@godxjp/ui/styles/core"` (no `@font-face` at all), `@import "@godxjp/ui/styles/core-with-fallbacks"` (`core` + six `local()`-only metric-matched faces, still zero network bytes — for when you supply Noto Sans JP yourself) or `@import "@godxjp/ui/styles/core-with-jis-level1"` (`core-with-fallbacks` + Noto Sans JP merged to JIS X 0208 level 1: **3 requests, ~1.53 MB, once** instead of ~8 font requests on every navigation — for a Japanese app that wants the bundled face). Never cherry-pick `*-layout.css`.
 2. Every page is `<PageContainer title subtitle extra footer>`; its sections are spaced by the page. Group items inside a section with `<Flex direction="col" gap>` or `<ResponsiveGrid>`.
 3. No Tailwind layout on your own elements: no `flex`, `grid`, `gap-*`, `p-*`, `m-*`, `space-*`. Rows are `<Flex>` (default row), stacks are `<Flex direction="col">`, grids are `<ResponsiveGrid>`.
-4. No hand-rolled surfaces: no `rounded-* border bg-*` divs. A box is `Card`, a pill is `Badge`, a person is `Avatar`, a row is `ListRow`, a label/value pair is `Descriptions`, an empty area is `EmptyState`, a read-only sample of a colour the USER chose is `Swatch`.
+4. No hand-rolled surfaces: no `rounded-* border bg-*` divs. A box is `Card`, a pill is `Badge`, a person is `Avatar`, a row is `ListRow`, a label/value pair is `Descriptions`, an empty area is `EmptyState`, a read-only sample of a colour the USER chose is `Swatch`. A LIST of those rows is `<Flex as="ul" marker="none" direction="col" gap="none">` with `<ListRow as="li">` children — `marker="none"` keeps the `<ul>`, the `<li>` semantics and the gap token while dropping the bullet and the indent. Never a raw `<ul>`/`<ol>` (it carries no gap token), never `<div role="list">` + `<div role="listitem">`, and never a wrapper around each row: the divider is `:not(:last-child)` among siblings, so a row alone in its own wrapper is always the last one and EVERY divider disappears silently. A bulleted prose list is the same `<Flex as="ul">` without `marker`.
 5. Real controls only: `Button`, `Input`, `Select`, `Textarea`, `Checkbox`… never raw `<button>`/`<input>`; a labelled control lives in `<FormField label>`. A Select outside a form takes `width="auto"`. **A disabled control's reason is visible text, never a tooltip** — see below.
-6. Text is `<Text>` / `<Heading>` with `tone`, `size`, `weight`, `truncate`, `mono` — not `className="text-muted-foreground font-semibold"`.
+6. Text is `<Text>` / `<Heading>` with `tone`, `size`, `weight`, `truncate`, `mono` — not `className="text-muted-foreground font-semibold"`. A STANDALONE glyph is `<Icon as={Lock} size="sm" tone="muted" />` from `@godxjp/ui/general`: a bare lucide icon carries its own `width="24" height="24"` and only four places re-size it for you (`Button`, a `DropdownMenuItem`, a `TopbarItem`, a `ListRow` leading slot), so everywhere else — in a `Text`, a table cell, an `<a>` — it draws at 24px beside 14px type. `size-4` and `w-[16px]` are closed to you by rules 3 and 8, and `size={16}` hard-codes a number the theme owns; `Icon` puts the glyph on the `--icon-size-*` scale (`2xs…4xl`) instead, and is `aria-hidden` unless you give it a `label` (then it is `role="img"` with that name). The audit rule is `lucide-icon-needs-size`.
 7. Colours are semantic tokens (`tone="destructive"`, `bg-primary`), never palette names, hex, or `bg-black` / `text-white`.
 8. Sizes come from props (`size`, `width`, `columns`), never `w-[240px]` / `max-h-[420px]`.
 9. Logical directions (`ms-`, `me-`, `start-`, `end-`) when a utility is unavoidable; never `ml-` / `left-`.

package/docs/FRAME-COVERAGE-REPORT.md

@@ -3,8 +3,8 @@
 > Generated by `scripts/frame-coverage.mjs` (issue #163). Do not edit by hand — run `pnpm check:frame-coverage`.
 > Standard: [FRAME-COVERAGE-STANDARD.md](./FRAME-COVERAGE-STANDARD.md). A missing dimension is **UNTESTED**, never a pass.
 
-- Public components: **163**
-- With ≥1 frame: **142** · zero-frame: **21**
+- Public components: **164**
+- With ≥1 frame: **143** · zero-frame: **21**
 - Fully covered (every contract axis declared): **0**
 
 ## UNTESTED — no `/frame/**` route
@@ -74,6 +74,7 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | Logo | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
 | Reveal | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | Activity | ✓ | · | N/A | N/A | · | · | · | · | · | · |
+| Icon | ✓ | · | N/A | N/A | · | · | · | · | · | · |
 | DataTable | ✓ | ✓ | · | · | · | · | · | · | · | · |
 | Card | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
 | CardContent | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |

package/docs/general/icon.tsx

@@ -0,0 +1,215 @@
+import {
+  ArrowUpRight,
+  Check,
+  Download,
+  FileWarning,
+  Globe,
+  Lock,
+  ShieldCheck,
+  Smartphone,
+  Unlock,
+} from "lucide-react";
+
+import { Card, CardContent, CardHeader, CardTitle } from "@godxjp/ui/data-display";
+import { Button, Heading, Icon, Text } from "@godxjp/ui/general";
+import { Flex, PageContainer, Separator } from "@godxjp/ui/layout";
+
+/**
+ * Icon · a glyph on the `--icon-size-*` scale, and the only supported way to draw a standalone one.
+ *
+ * A lucide component ships `width="24" height="24"`. Four rules in this library override that
+ * (`.ui-button svg`, the menu row, the topbar cell, the ListRow leading slot) and nothing else
+ * does · so a glyph in a `Text`, a table cell or an `<a>` draws at 24px beside 14px type, 1.7× the
+ * text it annotates. `docs/CONSUMER-RULES.md` §3/§8 forbid the `size-4` / `w-[16px]` escape, which
+ * left a consumer with 38 oversized glyphs and no supported fix (gh#712).
+ *
+ * `Icon` renders ONTO the glyph · the sized element is the `<svg>` itself · so it composes
+ * anywhere a bare glyph does and adds no box to the row. Decorative (`aria-hidden`) by default;
+ * `label` switches it to `role="img"` with that accessible name.
+ *
+ * Composed only from real @godxjp/ui components. All copy is consumer-owned and localized.
+ */
+
+/** The nine steps, with the px each resolves to at a 16px root · docs/TOKENS.md. */
+const SIZES = [
+  { size: "2xs", px: "10px", note: "アバターの在席ドット" },
+  { size: "xs", px: "12px", note: "表の並べ替えカーソル" },
+  { size: "sm", px: "14px", note: 'size="sm" のコントロール' },
+  { size: "md", px: "16px", note: "既定のアイコン段" },
+  { size: "lg", px: "20px", note: "アラート・ランチャー" },
+  { size: "xl", px: "24px", note: "アップロードタイル" },
+  { size: "2xl", px: "36px", note: "StatCard のメダリオン" },
+  { size: "3xl", px: "40px", note: "ドロップゾーン" },
+  { size: "4xl", px: "48px", note: "空状態の枠" },
+] as const;
+
+/** `tone` shares Text's vocabulary · one table for the glyph and the label beside it. */
+const TONES = [
+  { tone: "default", label: "default · 前景色" },
+  { tone: "muted", label: "muted · 補足" },
+  { tone: "primary", label: "primary · 主要導線" },
+  { tone: "success", label: "success · 有効" },
+  { tone: "warning", label: "warning · 要確認" },
+  { tone: "destructive", label: "destructive · 失敗" },
+  { tone: "info", label: "info · 情報" },
+  { tone: "inherit", label: "inherit · 面の色を継承" },
+] as const;
+
+/** The real screen: a security settings list whose status is carried by a glyph beside 14px text. */
+const SESSIONS = [
+  {
+    id: "s1",
+    device: "MacBook Pro · 東京",
+    detail: "2026-09-17 09:12 · 192.0.2.24",
+    secure: true,
+  },
+  {
+    id: "s2",
+    device: "iPhone 15 · 大阪",
+    detail: "2026-09-16 21:40 · 198.51.100.7",
+    secure: true,
+  },
+  {
+    id: "s3",
+    device: "Windows PC · 未確認の拠点",
+    detail: "2026-09-15 02:05 · 203.0.113.19",
+    secure: false,
+  },
+];
+
+export default function Demo() {
+  return (
+    <PageContainer
+      title="Icon"
+      subtitle='--icon-size-* の9段にグリフを載せる唯一の方法 · 既定は装飾（aria-hidden）· label で role="img"'
+    >
+      <Flex direction="col" gap="lg">
+        {/* ── The real screen · the defect this primitive exists for: a status glyph inline with
+             14px body text, where no context rule would ever have sized it. ── */}
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>サインイン中の端末</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              {SESSIONS.map((session) => (
+                <Flex key={session.id} direction="row" gap="sm" align="center" justify="between">
+                  <Flex direction="row" gap="sm" align="center">
+                    <Icon
+                      as={session.secure ? ShieldCheck : FileWarning}
+                      size="lg"
+                      tone={session.secure ? "success" : "warning"}
+                      label={session.secure ? "保護された接続" : "確認が必要な接続"}
+                    />
+                    <Flex direction="col">
+                      <Text weight="medium">{session.device}</Text>
+                      {/* A decorative glyph INSIDE 14px text · `sm` puts it on the type's own step. */}
+                      <Text size="xs" tone="muted">
+                        <Icon as={Globe} size="xs" /> {session.detail}
+                      </Text>
+                    </Flex>
+                  </Flex>
+                  <Button variant="outline" size="sm">
+                    <Icon as={session.secure ? Lock : Unlock} size="sm" />
+                    サインアウト
+                  </Button>
+                </Flex>
+              ))}
+            </Flex>
+          </CardContent>
+        </Card>
+
+        {/* ── Every step of the scale ── */}
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>size · 9段のアイコンスケール</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="sm">
+              {SIZES.map((step) => (
+                <Flex key={step.size} direction="row" gap="md" align="center">
+                  <Flex direction="row" gap="sm" align="center">
+                    <Icon as={Smartphone} size={step.size} />
+                  </Flex>
+                  <Text size="sm" mono>
+                    {step.size}
+                  </Text>
+                  <Text size="sm" tone="muted" mono>
+                    {step.px}
+                  </Text>
+                  <Text size="sm" tone="muted">
+                    {step.note}
+                  </Text>
+                </Flex>
+              ))}
+            </Flex>
+          </CardContent>
+        </Card>
+
+        {/* ── Every tone, beside the Text that shares the vocabulary ── */}
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>tone · Text と同じ意味の語彙</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="sm">
+              {TONES.map((entry) => (
+                <Flex key={entry.tone} direction="row" gap="sm" align="center">
+                  <Icon as={Check} size="md" tone={entry.tone} />
+                  <Text size="sm" tone={entry.tone}>
+                    {entry.label}
+                  </Text>
+                </Flex>
+              ))}
+            </Flex>
+          </CardContent>
+        </Card>
+
+        {/* ── Where it composes · inside Text, inside a Button, standalone in a link ── */}
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>合成 · Text の中・Button の中・単独</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Flex direction="col" gap="xs">
+                <Heading level={3}>Text の中</Heading>
+                <Text size="sm">
+                  請求書は <Icon as={Lock} size="sm" tone="muted" /> 暗号化されて保管されます。
+                </Text>
+              </Flex>
+
+              <Separator />
+
+              <Flex direction="col" gap="xs">
+                <Heading level={3}>Button の中 · 明示した段が Button の既定に勝つ</Heading>
+                <Flex direction="row" gap="sm" align="center">
+                  <Button size="sm">
+                    <Icon as={Download} size="sm" />
+                    書き出す
+                  </Button>
+                  <Button variant="outline">
+                    <Icon as={Download} size="lg" />
+                    大きめのグリフ
+                  </Button>
+                </Flex>
+              </Flex>
+
+              <Separator />
+
+              <Flex direction="col" gap="xs">
+                <Heading level={3}>単独 · 名前を持つグリフ</Heading>
+                <Flex direction="row" gap="sm" align="center">
+                  <Text as="a" href="#icon-standalone" size="sm" tone="primary">
+                    監査ログを開く <Icon as={ArrowUpRight} size="sm" />
+                  </Text>
+                  <Icon as={ShieldCheck} size="md" tone="success" label="二要素認証は有効です" />
+                </Flex>
+              </Flex>
+            </Flex>
+          </CardContent>
+        </Card>
+      </Flex>
+    </PageContainer>
+  );
+}

package/docs/layout/flex.tsx

@@ -5,6 +5,7 @@ import {
   CardDescription,
   CardHeader,
   CardTitle,
+  ListRow,
 } from "@godxjp/ui/data-display";
 import { Button, Text } from "@godxjp/ui/general";
 import { Flex, PageContainer } from "@godxjp/ui/layout";
@@ -309,6 +310,64 @@ export default function Demo() {
             </Flex>
           </CardContent>
         </Card>
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>marker=&quot;none&quot; · 装飾のない意味的リスト</CardTitle>
+            <CardDescription>
+              as=&quot;ul&quot; は既定で中黒と字下げが付きます。設定メニューのような「行の一覧」では
+              marker=&quot;none&quot; を指定すると、ul と li の意味づけと gap トークンは残したまま、
+              中黒も字下げも消えます。行は ListRow as=&quot;li&quot;
+              で、区切り線は行が自分で描きます。
+            </CardDescription>
+          </CardHeader>
+          <CardContent flush>
+            <Flex id="semantic-list" as="ul" marker="none" direction="col" gap="none">
+              <ListRow
+                as="li"
+                title="二要素認証"
+                description="認証アプリ · 有効"
+                trailing={
+                  <Button size="xs" variant="outline">
+                    管理
+                  </Button>
+                }
+              />
+              <ListRow
+                as="li"
+                title="パスキー"
+                description="2 件登録済み"
+                trailing={
+                  <Button size="xs" variant="outline">
+                    管理
+                  </Button>
+                }
+              />
+              <ListRow
+                as="li"
+                title="回復コード"
+                description="未発行"
+                trailing={
+                  <Button size="xs" variant="outline">
+                    発行
+                  </Button>
+                }
+              />
+            </Flex>
+          </CardContent>
+          <CardContent>
+            <Flex id="semantic-list-gap" as="ul" marker="none" gap="sm" wrap>
+              <Flex as="li">
+                <Badge variant="outline">監査ログ</Badge>
+              </Flex>
+              <Flex as="li">
+                <Badge variant="outline">IP 制限</Badge>
+              </Flex>
+              <Flex as="li">
+                <Badge variant="outline">SSO</Badge>
+              </Flex>
+            </Flex>
+          </CardContent>
+        </Card>
         <Card>
           <CardHeader>
             <CardTitle level={2}>軽い強調と行アクション</CardTitle>

package/docs/layout/topbar-item.tsx

@@ -9,7 +9,7 @@ import {
   CardHeader,
   CardTitle,
 } from "@godxjp/ui/data-display";
-import { Button, Text } from "@godxjp/ui/general";
+import { Button, Icon, Text } from "@godxjp/ui/general";
 import { AppShell, Flex, PageContainer, Sidebar, Topbar, TopbarItem } from "@godxjp/ui/layout";
 import type { SidebarSectionProp } from "@godxjp/ui/layout";
 import {
@@ -22,6 +22,7 @@ import {
 } from "@godxjp/ui/navigation";
 import {
   Bell,
+  Building2,
   FileText,
   LayoutDashboard,
   LogOut,
@@ -150,6 +151,33 @@ export default function Demo() {
               />
             </CardContent>
           </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle level={2}>包んだグリフ（icon スロットと Icon）</CardTitle>
+              <CardDescription>
+                `.ui-topbar-item &gt; svg` は直接の子だけを見ます。ブレークポイントで隠すために
+                グリフを包むと、その規則は届かず lucide 既定の 24px で描かれます（390px
+                のセルで実測）。 セル自身が持つ `icon` スロットに渡すか、包むなら `Icon`
+                を使えば、どちらもバーの段 （--topbar-icon-size）に載ります。
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Topbar
+                start={
+                  <>
+                    <TopbarItem icon={<Building2 aria-hidden="true" />}>経理部</TopbarItem>
+                    <TopbarItem aria-label="拠点を切り替える">
+                      <Flex hideBelow="sm">
+                        <Icon as={Building2} size="md" />
+                      </Flex>
+                      東京本社
+                    </TopbarItem>
+                  </>
+                }
+              />
+            </CardContent>
+          </Card>
         </Flex>
       </PageContainer>
     </AppShell>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "27.3.1",
-  "godxUiMcp": "27.3.1",
+  "version": "27.4.1",
+  "godxUiMcp": "27.4.1",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/scripts/consumer-rule.md

@@ -98,23 +98,24 @@ Slack thì đặt lại **một dòng**, không fork `.app-nav-rail`.
 Hỏi MCP `godxjp-ui` (`search_components`, `get_component`). Đo được trong một
 ngày: năm thứ cần đều ĐÃ CÓ và vẫn bị dựng lại bằng thứ khác —
 
-| Cần                                             | Đã có                                                                              |
-| ----------------------------------------------- | ---------------------------------------------------------------------------------- |
-| đường kẻ chạm mép Card                          | `<CardContent flush>`                                                              |
-| header có kẻ khi thân là danh sách flush        | `<CardHeader banded>`                                                              |
-| một hàng LÀ liên kết (thay cho nút rời)         | `<ListRow asChild>`                                                                |
-| kẻ ô từng ngày trong lịch                       | `<Calendar bordered>`                                                              |
-| dải giữa hai vùng, tự kẻ theo VỊ TRÍ            | `<CardBar>` (`border` để ép khi xếp chồng)                                         |
-| chip "điều kiện đang bật" có dấu × để bỏ        | `<Badge onRemove>` — KHÔNG phải `TagInput`                                         |
-| dải tab nằm TRONG đầu Card                      | `<Card tabList activeTabKey onTabChange>`                                          |
-| tiêu đề / đoạn văn / liên kết trong văn bản     | `<Title>` · `<Paragraph>` · `<Link>` (`Text` 33 prop)                              |
-| nút nổi góc màn (quay lên đầu, hành động nhanh) | `<FloatButton>`                                                                    |
-| khung xương của một FORM khi đang tải           | `<SkeletonForm>`                                                                   |
-| ô màu chỉ để xem, màu do NGƯỜI DÙNG chọn        | `<Swatch>`                                                                         |
-| ảnh đại diện của một tệp / bản xem trước        | `<Thumbnail>`                                                                      |
-| danh sách "có gì trong gói này"                 | `<FeatureList>`                                                                    |
-| panel kéo giãn được (chia đôi màn)              | `<DraggablePanel>`                                                                 |
-| màn hội thoại AI                                | `<Welcome>` · `<Conversations>` · `<Attachments>` · `<ThoughtChain>` · `<Actions>` |
+| Cần                                                              | Đã có                                                                              |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| đường kẻ chạm mép Card                                           | `<CardContent flush>`                                                              |
+| header có kẻ khi thân là danh sách flush                         | `<CardHeader banded>`                                                              |
+| một hàng LÀ liên kết (thay cho nút rời)                          | `<ListRow asChild>`                                                                |
+| kẻ ô từng ngày trong lịch                                        | `<Calendar bordered>`                                                              |
+| dải giữa hai vùng, tự kẻ theo VỊ TRÍ                             | `<CardBar>` (`border` để ép khi xếp chồng)                                         |
+| chip "điều kiện đang bật" có dấu × để bỏ                         | `<Badge onRemove>` — KHÔNG phải `TagInput`                                         |
+| dải tab nằm TRONG đầu Card                                       | `<Card tabList activeTabKey onTabChange>`                                          |
+| tiêu đề / đoạn văn / liên kết trong văn bản                      | `<Title>` · `<Paragraph>` · `<Link>` (`Text` 33 prop)                              |
+| nút nổi góc màn (quay lên đầu, hành động nhanh)                  | `<FloatButton>`                                                                    |
+| khung xương của một FORM khi đang tải                            | `<SkeletonForm>`                                                                   |
+| ô màu chỉ để xem, màu do NGƯỜI DÙNG chọn                         | `<Swatch>`                                                                         |
+| ảnh đại diện của một tệp / bản xem trước                         | `<Thumbnail>`                                                                      |
+| danh sách "có gì trong gói này"                                  | `<FeatureList>`                                                                    |
+| panel kéo giãn được (chia đôi màn)                               | `<DraggablePanel>`                                                                 |
+| màn hội thoại AI                                                 | `<Welcome>` · `<Conversations>` · `<Attachments>` · `<ThoughtChain>` · `<Actions>` |
+| một glyph lucide đứng một mình (trong `Text`, ô bảng, thẻ `<a>`) | `<Icon as={Lock} size="sm">` — KHÔNG phải `size-4` hay `size={16}`                 |
 
 Lỗi không phải "đoán sai tên prop" mà là **cho rằng nó không tồn tại nên không
 hỏi**.

package/scripts/ui-audit.mjs

@@ -590,6 +590,68 @@ const RULES = [
     message:
       "No em-dash (—) in product copy. Use a middot `·` for JP/EN label pairs, or restructure into two calm sentences. Keep copy factual and quiet.",
   },
+  {
+    id: "lucide-icon-needs-size",
+    replacement: '<Icon as={Glyph} size="sm" />',
+    // CONSUMER scope, like the other rules about what an app may write: inside this package a bare
+    // glyph is normal — Tree, Pagination, Attachments and a dozen others size their own svg from
+    // their own stylesheet, which is exactly the capability a consumer does not have. Measured:
+    // 90 findings here with the scope off, every one of them a component sizing its own glyph.
+    scope: "consumer",
+    matches: lucideGlyphMatches,
+    spansElement: true,
+    severity: "warn",
+    /*
+     * A lucide element rendered where NOTHING will size it.
+     *
+     * A lucide component ships `width="24" height="24"`, and exactly four rules in this library
+     * override that: `.ui-button svg`, `.ui-dropdown-menu-item > svg`, `.ui-topbar-item svg` and
+     * `[data-slot="list-row-leading"] > svg`. Outside them — in a `Text`, a table cell, an `<a>`,
+     * a `Flex` — the glyph draws at 24px beside 14px type. It is the one defect class that is
+     * INVISIBLE in review: the JSX is correct, the import is correct, and only the screen is
+     * wrong. A consumer swept one app and found 38 (gh#712).
+     *
+     * `warn`, not `error`, and deliberately so: the exemptions below are lexical, so a glyph
+     * inside a consumer's own wrapper component that happens to size it would be reported. The
+     * fix is cheap (`<Icon as={Lock} size="sm" />`) and the finding is worth reading even then.
+     */
+    standard: "WCAG 2.2 SC 1.4.4 · @godxjp/ui icon scale (docs/TOKENS.md, --icon-size-*)",
+    message:
+      'A lucide glyph with nothing to size it renders at its intrinsic 24px — 1.7× a 14px label. Put it on the scale with the primitive: <Icon as={Lock} size="sm" tone="muted" />, which is aria-hidden by default. A size-4 / w-[16px] utility is what docs/CONSUMER-RULES.md §3/§8 forbid, and size={16} hard-codes a number the theme owns.',
+  },
+  {
+    id: "no-hand-rolled-list",
+    replacement: 'Flex as="ul" marker="none" + ListRow as="li"',
+    scope: "consumer",
+    severity: "warn",
+    spansElement: true,
+    /*
+     * A list built by hand instead of by the primitives, in the three shapes a consumer reaches for:
+     *
+     *   1. a raw `<ul>`/`<ol>` — it cannot carry the gap token, so the spacing goes back into
+     *      utilities, and until `marker="none"` (gh#714) it was the only way to get a list without
+     *      a bullet and a --space-5 indent. It no longer is.
+     *   2. `role="list"` / `role="listitem"` on a div — ARIA re-describing markup that HTML already
+     *      has a element for (WAI-ARIA 1.2 §Using ARIA in HTML: prefer the native element).
+     *   3. a `<li>` (or any wrapper) around a library ROW instead of BEING it. This is the one that
+     *      cost real money: `[data-slot="list-row"]:not(:last-child)` draws the divider, so a row
+     *      alone in a wrapper of its own is always `:last-child` and the rule never matches — a
+     *      consumer's settings menu and dashboard lost EVERY divider, silently, and code review saw
+     *      nothing. `ListRow` has `as="li"` (and `as` + `asChild` for a row of links) precisely so
+     *      the rows stay siblings.
+     *
+     * WARN, not error, and the measurement says why: of 15 `role="list"` wrappers one consumer
+     * audited, 3 survived as deliberate exceptions (a drag-and-drop Kanban column of Cards, two
+     * evidence lists inside a TableCell). A rule wrong one time in five is a rule that gets
+     * silenced wholesale at `error`; at `warn` the three exceptions take an
+     * `ui-audit-disable-line` that states the reason and the other twelve still get fixed.
+     */
+    test: /<(?:ul|ol)(?=[\s/>])[^\n]*|\brole=["'](?:list|listitem)["']|<li(?=[\s>])(?:(?!<\/li>)[\s\S]){0,400}?<(?:ListRow|Card)(?=[\s/>])/g,
+    standard:
+      "WAI-ARIA 1.2 (list / listitem) · HTML Living Standard (ul/ol/li) · WCAG 2.2 SC 1.3.1",
+    message:
+      'Hand-rolled list — a raw <ul>/<ol>, an ARIA role="list"/"listitem", or a <li> wrapped around a library row. Build it from <Flex as="ul" marker="none"> (keeps the element, the <li> semantics and the gap token; no bullet, no indent) with <ListRow as="li"> as the rows. A row inside a wrapper of its own is an only child, so its :not(:last-child) divider never matches and every divider disappears silently (docs/CONSUMER-RULES.md §4, gh#714).',
+  },
 ];
 
 /**
@@ -946,6 +1008,72 @@ function insideStringLiteral(source, index) {
   return quote !== "";
 }
 
+/**
+ * The LOCAL names bound to `lucide-react` icons in this file — `import { Lock, Pencil as Edit }`
+ * gives `Lock` and `Edit`. Reading the import rather than matching "any PascalCase tag" is what
+ * keeps the rule from reporting every component in the file.
+ */
+function lucideLocalNames(source) {
+  const names = new Set();
+  for (const imp of source.matchAll(
+    /import\s+(?:type\s+)?\{([^}]*)\}\s*from\s*["']lucide-react["']/g,
+  )) {
+    for (const spec of imp[1].split(",")) {
+      const local =
+        spec
+          .trim()
+          .split(/\s+as\s+/)
+          .pop()
+          ?.trim() ?? "";
+      if (/^[A-Z][A-Za-z0-9]*$/.test(local)) names.add(local);
+    }
+  }
+  return names;
+}
+
+/**
+ * Character ranges in which a glyph is SOMEBODY ELSE'S to size, so a glyph inside one is quiet:
+ *
+ *  1. the body of a component whose CSS sizes its own `svg` — the four rules named on the rule
+ *     below, which are the only four that exist;
+ *  2. the value of a slot PROP (`icon={<Lock />}`, `leading={<Lock />}`). A component handed a
+ *     glyph through a named slot owns the metric for that slot — that is what a slot IS — and
+ *     reporting the call site would push consumers away from the slot and toward a bare glyph.
+ */
+function iconSizingRanges(source) {
+  const ranges = [];
+  for (const m of source.matchAll(
+    /<(Button|DropdownMenuItem|DropdownMenuCheckboxItem|DropdownMenuRadioItem|TopbarItem)\b[\s\S]*?<\/\1>/g,
+  )) {
+    ranges.push([m.index, m.index + m[0].length]);
+  }
+  for (const m of source.matchAll(
+    /\b(?:icon|leading|trailing|mark|indicator|avatar|prefix|suffix|addonBefore|addonAfter)\s*=\s*\{/g,
+  )) {
+    const open = m.index + m[0].length - 1;
+    const close = matchBracket(source, open);
+    ranges.push([open, close < 0 ? source.length : close + 1]);
+  }
+  return ranges;
+}
+
+/** A lucide element that no rule, no slot and no author-supplied size will ever measure. */
+function* lucideGlyphMatches(source) {
+  const names = lucideLocalNames(source);
+  if (names.size === 0) return;
+  const ranges = iconSizingRanges(source);
+  for (const m of source.matchAll(new RegExp(`<(?:${[...names].join("|")})(?=[\\s/>])`, "g"))) {
+    if (insideStringLiteral(source, m.index)) continue;
+    if (ranges.some(([from, to]) => m.index > from && m.index < to)) continue;
+    const end = jsxOpeningEnd(source, m.index);
+    if (end >= source.length) continue;
+    // An explicit size, or ANY className — a class list is the author saying something about this
+    // element's box, and second-guessing which utility sizes it is how a warning becomes noise.
+    if (/\s(?:size|width|height|className|style)\s*=/.test(source.slice(m.index, end))) continue;
+    yield { 0: source.slice(m.index, end + 1), index: m.index };
+  }
+}
+
 /** Match real JSX text after a balanced opening tag, including props with comparisons. */
 function* currencyMatches(source) {
   for (const opening of source.matchAll(/<(?:[A-Za-z][\w.:]*\b|(?=>))/g)) {