@godxjp/ui 28.10.0 → 28.12.0

package/agent/START-HERE.md

@@ -3,7 +3,7 @@
 You are about to write code against a design system you did not author. This file is the whole
 contract. Read it before you write JSX.
 
-**This catalog describes `@godxjp/ui` 28.10.0.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 28.12.0.** If the project you are editing has a different
 version in its `package.json`, read the pinned catalog for THAT version instead
 (`…/v<their-version>/agent/…`). A catalog newer than the installed package describes props that do
 not exist yet; older, and it hides props that do. Neither failure announces itself.
@@ -56,7 +56,7 @@ Then ask it: `search_components`, `get_component`, `get_tokens`, `get_rule`, `li
    its `importPath`, and its examples. Fetch only the handful you picked in step 1.
 3. `rules.json` — 47 cardinal rules. The ones about raw HTML and hardcoded colour are not
    style advice.
-4. `tokens.json` — 1684 design tokens. Only when you need a specific knob's name.
+4. `tokens.json` — 1685 design tokens. Only when you need a specific knob's name.
 5. `anti-ai-tells.json` — 26 shapes that make generated UI look generated, each with the
    fix. Read before you reach for a gradient hero or a wall of coloured chips.
 

package/agent/components/Attachments.json

@@ -67,7 +67,8 @@
   "usage": [
     "DO keep antd field names on each item (`thumbUrl`, `originFileObj`, `uid`) — an Ant X call site should compile unchanged.",
     "DO use `ref.select({ accept, multiple })` to open the picker programmatically (Ant X 2.0).",
-    "DON'T expect `styles`/`classNames` from Ant X — retune through `--attachments-*` tokens."
+    "DON'T expect `styles`/`classNames` from Ant X — retune through `--attachments-*` tokens.",
+    "The card is a FIXED box — 268x68 (Ant X's own), from `--attachments-card-size` (inline) and `--attachments-card-block-size`. The block size is also the `+` tile's square and the `overflow=\"scrollY\"` one-row viewport, so retune it once and all three follow. The file input is `sr-only`: never style it visible."
   ],
   "useCases": [
     "The attachment tray above a ChatComposer in an assistant surface.",

package/agent/components/ServiceLauncherCard.json

@@ -1,15 +1,20 @@
 {
-  "example": "import { Clock } from \"lucide-react\";\nimport {\n  ServiceCatalogCta,\n  ServiceLauncherCard,\n  ServiceLauncherCardSkeleton,\n} from \"@godxjp/ui/data-display\";\nimport { Button } from \"@godxjp/ui/general\";\nimport { ResponsiveGrid } from \"@godxjp/ui/layout\";\n\n// ResponsiveGrid owns the canonical 3 → 2 → 1 ladder; the page writes no tracks.\n<ResponsiveGrid columns={{ sm: 1, md: 2, lg: 3 }}>\n  {loading\n    ? services.map((s) => <ServiceLauncherCardSkeleton key={s.id} label={t(\"loadingService\")} />)\n    : services.map((s) => (\n        <ServiceLauncherCard\n          key={s.id}\n          icon={Clock}\n          title={s.name}\n          statusLabel={s.accessLabel}\n          statusTone={s.accessTone}\n          description={s.description}\n          metadata={s.hostnameAndPlan}\n          disabledReason={s.blockedReason}\n          action={\n            <Button asChild={s.canLaunch} disabled={!s.canLaunch}>\n              {s.canLaunch ? <a href={s.launchUrl}>{t(\"launch\")}</a> : t(\"launch\")}\n            </Button>\n          }\n        />\n      ))}\n  <ServiceCatalogCta\n    title={t(\"addFromCatalog\")}\n    action={<Button variant=\"outline\">{t(\"viewCatalog\")}</Button>}\n  />\n</ResponsiveGrid>",
+  "example": "import { Clock } from \"lucide-react\";\nimport {\n  ServiceCatalogCta,\n  ServiceLauncherCard,\n  ServiceLauncherCardSkeleton,\n} from \"@godxjp/ui/data-display\";\nimport { Button } from \"@godxjp/ui/general\";\nimport { ResponsiveGrid } from \"@godxjp/ui/layout\";\n\n// ResponsiveGrid owns the canonical 3 → 2 → 1 ladder; the page writes no tracks.\n<ResponsiveGrid columns={{ sm: 1, md: 2, lg: 3 }}>\n  {loading\n    ? services.map((s) => <ServiceLauncherCardSkeleton key={s.id} label={t(\"loadingService\")} />)\n    : services.map((s) => (\n        <ServiceLauncherCard\n          key={s.id}\n          icon={Clock}\n          // The uploaded mark when there is one; the tile falls back to `icon` when there is not,\n          // and again if the file behind the URL has gone away.\n          logo={s.logoUrl ?? undefined}\n          title={s.name}\n          statusLabel={s.accessLabel}\n          statusTone={s.accessTone}\n          description={s.description}\n          metadata={s.hostnameAndPlan}\n          disabledReason={s.blockedReason}\n          action={\n            <Button asChild={s.canLaunch} disabled={!s.canLaunch}>\n              {s.canLaunch ? <a href={s.launchUrl}>{t(\"launch\")}</a> : t(\"launch\")}\n            </Button>\n          }\n        />\n      ))}\n  <ServiceCatalogCta\n    title={t(\"addFromCatalog\")}\n    action={<Button variant=\"outline\">{t(\"viewCatalog\")}</Button>}\n  />\n</ResponsiveGrid>",
   "group": "data-display",
   "importPath": "@godxjp/ui/data-display",
   "name": "ServiceLauncherCard",
   "props": [
     {
-      "description": "Decorative service glyph rendered in the canonical semantic icon surface.",
+      "description": "Decorative glyph for the KIND of service, rendered in the canonical semantic icon surface. Stays required because it is also what `logo` falls back to when an upload is missing or broken.",
       "name": "icon",
       "required": true,
       "type": "LucideIcon"
     },
+    {
+      "description": "URL of the service's OWN uploaded mark (the PNG/WebP an administrator uploaded). When it loads it replaces `icon` in the medallion, in the glyph's exact box (--card-service-launcher-icon-glyph-size, object-fit: contain). It is a fallback chain, not a switch: the tile renders `icon` while the URL is in flight and KEEPS rendering `icon` if the URL 404s or is empty — a broken logo never reaches the DOM as an <img>. Decorative (alt=\"\", medallion aria-hidden), so there is no logoAlt prop: the service name is already beside it.",
+      "name": "logo",
+      "type": "string"
+    },
     {
       "description": "Real downstream service display name.",
       "name": "title",
@@ -68,13 +73,15 @@
   "subParts": [
     "ServiceLauncherCardSkeleton"
   ],
-  "tagline": "Token-owned downstream-service launcher tile with semantic icon, status, metadata, action, disabled reason, matching skeleton, and companion catalog CTA.",
+  "tagline": "Token-owned downstream-service launcher tile with an uploaded service logo (falling back to a semantic icon), status, metadata, action, disabled reason, matching skeleton, and companion catalog CTA.",
   "usage": [
     "DO provide status, hostname, plan, access state and action from the product's real API contract. ServiceLauncherCard deliberately performs no entitlement or URL inference — it has no href/entitlement/available prop at all.",
     "DO own the layout with ResponsiveGrid columns={{ sm: 1, md: 2, lg: 3 }} — the canonical 3→2→1 launcher grid. ResponsiveGrid queries its OWN container (40/48/64rem), so never hand-write grid-template-columns or a media query in the page. The shorthand columns={3} also works but widens to 2 columns earlier (40rem).",
     "DO render ServiceLauncherCard directly as a grid child; it already owns its Card shell, its 36px medallion (--control-height-lg tier) and the canonical internal rhythm.",
     "DO replace it with ServiceLauncherCardSkeleton while loading (it carries a required `label` and aria-busy, and deliberately opens no live region). Use ServiceCatalogCta as the peer tile only when a real catalog/add route exists.",
     "DO keep `metadata` to machine identifiers (hostname · plan) — it is the only mono line. Sentences belong in `description` / `disabledReason`.",
+    "DO pass BOTH `logo` and `icon` when a service may have an uploaded mark: `logo={s.logoUrl ?? undefined}` with `icon` as the kind glyph. `icon` is not optional and must not be treated as redundant — it is the tile a freshly created service, and a service whose logo file has been deleted, actually shows.",
+    "DON'T wrap an <img> in a component to squeeze it through `icon`, and DON'T style the medallion to fit a picture. `logo` sizes the image to the glyph's own token, so a grid mixing logo tiles and glyph tiles keeps one optical weight.",
     "DON'T recreate launcher geometry with page-local CSS, utility padding, grid tracks, or a hand-built Card hierarchy. Retune it with the --card-service-launcher-* tokens instead.",
     "DON'T show LIVE, a hostname, subscribed plan, or launch action merely because a service is active in the global catalog."
   ],

package/agent/components-index.json

@@ -224,7 +224,7 @@
   {
     "group": "data-display",
     "name": "ServiceLauncherCard",
-    "tagline": "Token-owned downstream-service launcher tile with semantic icon, status, metadata, action, disabled reason, matching skeleton, and companion catalog CTA."
+    "tagline": "Token-owned downstream-service launcher tile with an uploaded service logo (falling back to a semantic icon), status, metadata, action, disabled reason, matching skeleton, and companion catalog CTA."
   },
   {
     "group": "data-display",

package/agent/components.json

@@ -3796,17 +3796,22 @@
     ]
   },
   {
-    "example": "import { Clock } from \"lucide-react\";\nimport {\n  ServiceCatalogCta,\n  ServiceLauncherCard,\n  ServiceLauncherCardSkeleton,\n} from \"@godxjp/ui/data-display\";\nimport { Button } from \"@godxjp/ui/general\";\nimport { ResponsiveGrid } from \"@godxjp/ui/layout\";\n\n// ResponsiveGrid owns the canonical 3 → 2 → 1 ladder; the page writes no tracks.\n<ResponsiveGrid columns={{ sm: 1, md: 2, lg: 3 }}>\n  {loading\n    ? services.map((s) => <ServiceLauncherCardSkeleton key={s.id} label={t(\"loadingService\")} />)\n    : services.map((s) => (\n        <ServiceLauncherCard\n          key={s.id}\n          icon={Clock}\n          title={s.name}\n          statusLabel={s.accessLabel}\n          statusTone={s.accessTone}\n          description={s.description}\n          metadata={s.hostnameAndPlan}\n          disabledReason={s.blockedReason}\n          action={\n            <Button asChild={s.canLaunch} disabled={!s.canLaunch}>\n              {s.canLaunch ? <a href={s.launchUrl}>{t(\"launch\")}</a> : t(\"launch\")}\n            </Button>\n          }\n        />\n      ))}\n  <ServiceCatalogCta\n    title={t(\"addFromCatalog\")}\n    action={<Button variant=\"outline\">{t(\"viewCatalog\")}</Button>}\n  />\n</ResponsiveGrid>",
+    "example": "import { Clock } from \"lucide-react\";\nimport {\n  ServiceCatalogCta,\n  ServiceLauncherCard,\n  ServiceLauncherCardSkeleton,\n} from \"@godxjp/ui/data-display\";\nimport { Button } from \"@godxjp/ui/general\";\nimport { ResponsiveGrid } from \"@godxjp/ui/layout\";\n\n// ResponsiveGrid owns the canonical 3 → 2 → 1 ladder; the page writes no tracks.\n<ResponsiveGrid columns={{ sm: 1, md: 2, lg: 3 }}>\n  {loading\n    ? services.map((s) => <ServiceLauncherCardSkeleton key={s.id} label={t(\"loadingService\")} />)\n    : services.map((s) => (\n        <ServiceLauncherCard\n          key={s.id}\n          icon={Clock}\n          // The uploaded mark when there is one; the tile falls back to `icon` when there is not,\n          // and again if the file behind the URL has gone away.\n          logo={s.logoUrl ?? undefined}\n          title={s.name}\n          statusLabel={s.accessLabel}\n          statusTone={s.accessTone}\n          description={s.description}\n          metadata={s.hostnameAndPlan}\n          disabledReason={s.blockedReason}\n          action={\n            <Button asChild={s.canLaunch} disabled={!s.canLaunch}>\n              {s.canLaunch ? <a href={s.launchUrl}>{t(\"launch\")}</a> : t(\"launch\")}\n            </Button>\n          }\n        />\n      ))}\n  <ServiceCatalogCta\n    title={t(\"addFromCatalog\")}\n    action={<Button variant=\"outline\">{t(\"viewCatalog\")}</Button>}\n  />\n</ResponsiveGrid>",
     "group": "data-display",
     "importPath": "@godxjp/ui/data-display",
     "name": "ServiceLauncherCard",
     "props": [
       {
-        "description": "Decorative service glyph rendered in the canonical semantic icon surface.",
+        "description": "Decorative glyph for the KIND of service, rendered in the canonical semantic icon surface. Stays required because it is also what `logo` falls back to when an upload is missing or broken.",
         "name": "icon",
         "required": true,
         "type": "LucideIcon"
       },
+      {
+        "description": "URL of the service's OWN uploaded mark (the PNG/WebP an administrator uploaded). When it loads it replaces `icon` in the medallion, in the glyph's exact box (--card-service-launcher-icon-glyph-size, object-fit: contain). It is a fallback chain, not a switch: the tile renders `icon` while the URL is in flight and KEEPS rendering `icon` if the URL 404s or is empty — a broken logo never reaches the DOM as an <img>. Decorative (alt=\"\", medallion aria-hidden), so there is no logoAlt prop: the service name is already beside it.",
+        "name": "logo",
+        "type": "string"
+      },
       {
         "description": "Real downstream service display name.",
         "name": "title",
@@ -3865,13 +3870,15 @@
     "subParts": [
       "ServiceLauncherCardSkeleton"
     ],
-    "tagline": "Token-owned downstream-service launcher tile with semantic icon, status, metadata, action, disabled reason, matching skeleton, and companion catalog CTA.",
+    "tagline": "Token-owned downstream-service launcher tile with an uploaded service logo (falling back to a semantic icon), status, metadata, action, disabled reason, matching skeleton, and companion catalog CTA.",
     "usage": [
       "DO provide status, hostname, plan, access state and action from the product's real API contract. ServiceLauncherCard deliberately performs no entitlement or URL inference — it has no href/entitlement/available prop at all.",
       "DO own the layout with ResponsiveGrid columns={{ sm: 1, md: 2, lg: 3 }} — the canonical 3→2→1 launcher grid. ResponsiveGrid queries its OWN container (40/48/64rem), so never hand-write grid-template-columns or a media query in the page. The shorthand columns={3} also works but widens to 2 columns earlier (40rem).",
       "DO render ServiceLauncherCard directly as a grid child; it already owns its Card shell, its 36px medallion (--control-height-lg tier) and the canonical internal rhythm.",
       "DO replace it with ServiceLauncherCardSkeleton while loading (it carries a required `label` and aria-busy, and deliberately opens no live region). Use ServiceCatalogCta as the peer tile only when a real catalog/add route exists.",
       "DO keep `metadata` to machine identifiers (hostname · plan) — it is the only mono line. Sentences belong in `description` / `disabledReason`.",
+      "DO pass BOTH `logo` and `icon` when a service may have an uploaded mark: `logo={s.logoUrl ?? undefined}` with `icon` as the kind glyph. `icon` is not optional and must not be treated as redundant — it is the tile a freshly created service, and a service whose logo file has been deleted, actually shows.",
+      "DON'T wrap an <img> in a component to squeeze it through `icon`, and DON'T style the medallion to fit a picture. `logo` sizes the image to the glyph's own token, so a grid mixing logo tiles and glyph tiles keeps one optical weight.",
       "DON'T recreate launcher geometry with page-local CSS, utility padding, grid tracks, or a hand-built Card hierarchy. Retune it with the --card-service-launcher-* tokens instead.",
       "DON'T show LIVE, a hostname, subscribed plan, or launch action merely because a service is active in the global catalog."
     ],
@@ -15127,7 +15134,8 @@
     "usage": [
       "DO keep antd field names on each item (`thumbUrl`, `originFileObj`, `uid`) — an Ant X call site should compile unchanged.",
       "DO use `ref.select({ accept, multiple })` to open the picker programmatically (Ant X 2.0).",
-      "DON'T expect `styles`/`classNames` from Ant X — retune through `--attachments-*` tokens."
+      "DON'T expect `styles`/`classNames` from Ant X — retune through `--attachments-*` tokens.",
+      "The card is a FIXED box — 268x68 (Ant X's own), from `--attachments-card-size` (inline) and `--attachments-card-block-size`. The block size is also the `+` tile's square and the `overflow=\"scrollY\"` one-row viewport, so retune it once and all three follow. The file input is `sr-only`: never style it visible."
     ],
     "useCases": [
       "The attachment tray above a ChatComposer in an assistant surface.",

package/agent/index.json

@@ -4,7 +4,7 @@
     "components": 170,
     "patterns": 19,
     "rules": 47,
-    "tokens": 1684,
+    "tokens": 1685,
     "vocabulary": 14
   },
   "files": [
@@ -48,9 +48,9 @@
   "note": "Pin to the tag that matches the @godxjp/ui version you installed. A catalog newer than your package describes props you do not have; older, and it hides props you do.",
   "read": {
     "live": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/index.json",
-    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v28.10.0/agent/index.json"
+    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v28.12.0/agent/index.json"
   },
   "source": "mcp/src/data — the same data @godxjp/ui-mcp serves",
   "start": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/START-HERE.md",
-  "version": "28.10.0"
+  "version": "28.12.0"
 }

package/agent/llms.txt

@@ -1,10 +1,10 @@
 # @godxjp/ui
 
-> A Japanese-enterprise React design system: 170 components, 1684 design tokens,
-> 47 cardinal rules. This file is the entry point for AI agents. Catalog version 28.10.0.
+> A Japanese-enterprise React design system: 170 components, 1685 design tokens,
+> 47 cardinal rules. This file is the entry point for AI agents. Catalog version 28.12.0.
 
 If your client can run a process, do not read these files — run the MCP server instead
-(`npx @godxjp/ui-mcp@28.10.0`). It is searchable and version-locked. These files exist for agents
+(`npx @godxjp/ui-mcp@28.12.0`). It is searchable and version-locked. These files exist for agents
 that can only fetch URLs.
 
 ## Start
@@ -26,7 +26,7 @@ that can only fetch URLs.
 ## Pinning
 
 Every URL above tracks `main`. To pin to the release a project actually installed, swap `main` for
-the tag: `.../godx-jp/godxjp-ui/v28.10.0/agent/...`. A catalog that does not match the installed
+the tag: `.../godx-jp/godxjp-ui/v28.12.0/agent/...`. A catalog that does not match the installed
 package describes props that are absent, or hides props that are present, and says nothing either way.
 
 Pinned catalogs only exist for releases whose tag actually contains `agent/`. If `…/v<version>/agent/index.json` returns 404, that release predates this catalog: read `…/main/…` instead and compare `index.json` → `version` against the package you have, so you at least know which way it drifted.

package/agent/tokens.json

@@ -155,62 +155,67 @@
     "value": "var(--space-inline-lg)"
   },
   {
-    "description": "Attachments — Ant Design X chat-surface file collection. * * Ant X retunes this through `styles={{ list, placeholder, upload, … }}`. Here every length and * tint is a named knob (rules #44/#45) so a service sets the rail once in theme.css.",
+    "description": "Gap between cards in the list. Ant X: `marginXS` = 8px.",
     "name": "--attachments-gap",
     "value": "var(--space-2)"
   },
   {
-    "description": "Attachments — Ant Design X chat-surface file collection. * * Ant X retunes this through `styles={{ list, placeholder, upload, … }}`. Here every length and * tint is a named knob (rules #44/#45) so a service sets the rail once in theme.css.",
+    "description": "THE CARD BOX. Ant X's file card is a fixed 268x68 chip: wide enough for a name plus one line * of description, short enough that a row of them reads as a tray and not as a list. Both axes * are fixed there and fixed here — the block size is what the `+` tile and the `scrollY` * one-row viewport are measured against, so it has three readers, not one. Ant X `width: 268`",
     "name": "--attachments-card-size",
-    "value": "var(--upload-tile-size)"
+    "value": "16.75rem"
   },
   {
-    "description": "Attachments — Ant Design X chat-surface file collection. * * Ant X retunes this through `styles={{ list, placeholder, upload, … }}`. Here every length and * tint is a named knob (rules #44/#45) so a service sets the rail once in theme.css.",
+    "description": "Ant X `cardHeight` = 14 * 1.5714 * 2 + 12 + 12 = 68",
+    "name": "--attachments-card-block-size",
+    "value": "4.25rem"
+  },
+  {
+    "description": "Ant X `token.borderRadius` = 6 ≡ --radius",
     "name": "--attachments-card-radius",
-    "value": "var(--upload-tile-radius)"
+    "value": "var(--radius-lg)"
   },
   {
-    "description": "Attachments — Ant Design X chat-surface file collection. * * Ant X retunes this through `styles={{ list, placeholder, upload, … }}`. Here every length and * tint is a named knob (rules #44/#45) so a service sets the rail once in theme.css.",
+    "description": "Ant X `marginSM` — glyph to name",
     "name": "--attachments-card-gap",
-    "value": "var(--upload-tile-space-gap)"
+    "value": "var(--space-3)"
   },
   {
-    "description": "Attachments — Ant Design X chat-surface file collection. * * Ant X retunes this through `styles={{ list, placeholder, upload, … }}`. Here every length and * tint is a named knob (rules #44/#45) so a service sets the rail once in theme.css.",
+    "description": "THE PLACEHOLDER — the whole control while the list is empty, and the drop target. Ant X `token.padding` = 16",
     "name": "--attachments-placeholder-space-inset",
-    "value": "var(--upload-dropzone-space-inset)"
+    "value": "var(--space-4)"
   },
   {
-    "description": "Attachments — Ant Design X chat-surface file collection. * * Ant X retunes this through `styles={{ list, placeholder, upload, … }}`. Here every length and * tint is a named knob (rules #44/#45) so a service sets the rail once in theme.css.",
+    "description": "Ant X `token.borderRadius` = 6 ≡ --radius",
     "name": "--attachments-placeholder-radius",
-    "value": "var(--upload-dropzone-radius)"
+    "value": "var( --radius-lg )"
   },
   {
-    "description": "Attachments — Ant Design X chat-surface file collection. * * Ant X retunes this through `styles={{ list, placeholder, upload, … }}`. Here every length and * tint is a named knob (rules #44/#45) so a service sets the rail once in theme.css.",
+    "description": "Ant X's placeholder mark is `fontSizeHeading2` = 30px, which is not a step of this repo's * nine-value icon scale (gh#326) and whose neighbours are 24 and 36. It stays on the step the * frozen table in `src/tokens/__tests__/icon-size-scale.test.ts` already records for it — the * same mark Upload's dropzone draws, which is the surface a reader meets this one beside.",
     "name": "--attachments-placeholder-icon-size",
-    "value": "var(--upload-dropzone-icon-size)"
+    "value": "var(--icon-size-3xl)"
   },
   {
-    "description": "Attachments — Ant Design X chat-surface file collection. * * Ant X retunes this through `styles={{ list, placeholder, upload, … }}`. Here every length and * tint is a named knob (rules #44/#45) so a service sets the rail once in theme.css.",
+    "description": "Attachments — Ant Design X chat-surface file collection. * * Ant X retunes this through `styles={{ list, placeholder, upload, … }}`. Here every length and * tint is a named knob (rules #44/#45) so a service sets the rail once in theme.css. * * EVERY KNOB BELOW IS READ BY A RULE IN `src/styles/data-entry-layout.css` (gh#855). It was not * always so: all twelve of these resolved, were generated into the MCP catalog, were described to * every consumer — and nothing anywhere read one of them, because the component had no stylesheet * at all. The defaults are Ant X's own numbers, taken from `@ant-design/x@2.9.0` * (`es/attachments/style/index.js` + `es/file-card/style/index.js`) rather than invented, and * mapped onto this repo's scales; `docs/DESIGN-AUTHORITY.md` carries the divergences.",
     "name": "--attachments-placeholder-title-font-size",
-    "value": "var(--font-size-sm, var(--font-size-base))"
+    "value": "var(--font-size-base)"
   },
   {
-    "description": "Attachments — Ant Design X chat-surface file collection. * * Ant X retunes this through `styles={{ list, placeholder, upload, … }}`. Here every length and * tint is a named knob (rules #44/#45) so a service sets the rail once in theme.css.",
+    "description": "Attachments — Ant Design X chat-surface file collection. * * Ant X retunes this through `styles={{ list, placeholder, upload, … }}`. Here every length and * tint is a named knob (rules #44/#45) so a service sets the rail once in theme.css. * * EVERY KNOB BELOW IS READ BY A RULE IN `src/styles/data-entry-layout.css` (gh#855). It was not * always so: all twelve of these resolved, were generated into the MCP catalog, were described to * every consumer — and nothing anywhere read one of them, because the component had no stylesheet * at all. The defaults are Ant X's own numbers, taken from `@ant-design/x@2.9.0` * (`es/attachments/style/index.js` + `es/file-card/style/index.js`) rather than invented, and * mapped onto this repo's scales; `docs/DESIGN-AUTHORITY.md` carries the divergences.",
     "name": "--attachments-placeholder-description-font-size",
-    "value": "var(--upload-dropzone-meta-font-size)"
+    "value": "var(--font-size-sm, var(--font-size-base))"
   },
   {
-    "description": "Attachments — Ant Design X chat-surface file collection. * * Ant X retunes this through `styles={{ list, placeholder, upload, … }}`. Here every length and * tint is a named knob (rules #44/#45) so a service sets the rail once in theme.css.",
+    "description": "Attachments — Ant Design X chat-surface file collection. * * Ant X retunes this through `styles={{ list, placeholder, upload, … }}`. Here every length and * tint is a named knob (rules #44/#45) so a service sets the rail once in theme.css. * * EVERY KNOB BELOW IS READ BY A RULE IN `src/styles/data-entry-layout.css` (gh#855). It was not * always so: all twelve of these resolved, were generated into the MCP catalog, were described to * every consumer — and nothing anywhere read one of them, because the component had no stylesheet * at all. The defaults are Ant X's own numbers, taken from `@ant-design/x@2.9.0` * (`es/attachments/style/index.js` + `es/file-card/style/index.js`) rather than invented, and * mapped onto this repo's scales; `docs/DESIGN-AUTHORITY.md` carries the divergences.",
     "name": "--attachments-placeholder-gap",
-    "value": "var(--space-2)"
+    "value": "var(--space-1)"
   },
   {
-    "description": "Attachments — Ant Design X chat-surface file collection. * * Ant X retunes this through `styles={{ list, placeholder, upload, … }}`. Here every length and * tint is a named knob (rules #44/#45) so a service sets the rail once in theme.css.",
+    "description": "The scrim the drop layer paints over the whole control while a file is dragged across it. * Role-mirror knob, so `initial` and the role resolved at the CALL SITE (docs/TOKENS.md) — * a `[data-tenant]`/`.dark` scope that re-seeds `--background` must reach this. Documented * default = `color-mix(in srgb, hsl(var(--background)) 85%, transparent)`, which is Ant X's * `colorBgPlaceholderHover` (`colorBgContainer` at alpha .85).",
     "name": "--attachments-drop-overlay-background",
     "value": "initial"
   },
   {
-    "description": "Attachments — Ant Design X chat-surface file collection. * * Ant X retunes this through `styles={{ list, placeholder, upload, … }}`. Here every length and * tint is a named knob (rules #44/#45) so a service sets the rail once in theme.css.",
+    "description": "The ✕ at the end of a card's row. Ant X draws it at `fontSizeLG` = 16; it stays at the 14px * step the frozen icon table records, which is also `--upload-remove-icon-size`. Two remove * affordances in one group drawing two different sizes is the defect, not the saving.",
     "name": "--attachments-remove-icon-size",
     "value": "var(--upload-remove-icon-size)"
   },
@@ -5885,9 +5890,9 @@
     "value": "calc(var(--space-1) / 2)"
   },
   {
-    "description": "track background — the recessed ground a control group sits in.",
+    "description": "track background — the recessed ground a control group sits in. default = var(--muted), resolved at the call site",
     "name": "--segmented-track-background",
-    "value": "var(--muted)"
+    "value": "initial"
   },
   {
     "description": "track radius = the base radius; item radius = one step DOWN the radius scale, not * `radius − trackPadding` (the two coincide only because the source scale happens to step by 2). * This scale is φ-spaced, so \"one step down\" from --radius is --radius-md (6px → 3.71px, against * the source's 6 → 4); --radius-sm is two steps and reads visibly squarer. The same pair is * already what TabsList (`rounded-lg`) and TabsTrigger (`rounded-md`) use — this library's other * track-and-slab control.",
@@ -5945,9 +5950,9 @@
     "value": "var(--secondary)"
   },
   {
-    "description": "selected fill = the elevated surface + a soft shadow — the selected slab reads as lifted * off the recessed track, which is the whole affordance.",
+    "description": "selected fill = the elevated surface + a soft shadow — the selected slab reads as lifted * off the recessed track, which is the whole affordance. default = var(--background), resolved at the call site",
     "name": "--segmented-item-selected-background",
-    "value": "var(--background)"
+    "value": "initial"
   },
   {
     "description": "Segmented (one-of-N control) component tokens. * * EVERY VALUE BELOW IS A PORT OF AN ESTABLISHED SEGMENTED SPEC, NOT A CHOICE. The geometry and the * role assignments come from the widely-implemented enterprise Segmented control, transcribed as * ratios rather than as pixels: * * track padding: the bold line width → 2px * track background: the page's recessed neutral * item colour: the label ink · hover / selected colour: the body ink * item hover fill: the lighter neutral · item active fill: the heavier neutral * item selected fill: the elevated surface * label height = control height − track padding × 2 → 32 − 4 = 28 * label padding-inline = control padding-x − border width → 12 − 1 = 11 * icon gap = the small margin step / 2 → 6 * * THE ROLE PORTS ARE THE ONES `Tabs` ALREADY MADE. TabsList is `bg-muted` and an active * TabsTrigger is `bg-background` + `shadow-sm` — the same track-and-slab pair, so a Segmented and a * default Tabs strip read as one control family in both themes rather than two near-misses. That * matters more than reproducing the source dark ramp literally: that ramp's dark track is BLACK * with a lighter slab on it, while this palette's dark `--muted` sits above `--background`, so a * literal port would invert the pairing relative to every Tabs strip on the same page. * * NOT ONE OF THEM READS THE BRAND SEED. The spec's own derivation produces identical Segmented * values for its default seed and for this system's `#0071bd` — the control is neutral by * construction, and the only brand ink it can carry is the focus mark, which styles/focus-ring.css * owns. So the ports below are ROLE references (the same neutrals this system already names), * never copied hex. * * The disabled state is the ONE place this departs. The source recolours to a disabled ink and * changes nothing else; this system disables every control with the one `--disabled-opacity` knob, * and a single library-wide answer outranks a per-component one. * * The other thing NOT ported is the sliding thumb: it exists to animate between items, and the * implementations that have one remove the `-item-selected` class while it runs, which means the * selected state lives in two places at once. A static selected slab reads identically at rest and * cannot desynchronise.",

package/dist/components/data-display/service-launcher-card.d.ts

@@ -28,7 +28,26 @@ import type { LucideIcon } from "lucide-react";
 import type { HeadingLevelProp, ToneProp } from "../../props/vocabulary/index.js";
 export type ServiceLauncherStatusTone = Extract<ToneProp, "success" | "warning" | "destructive" | "info" | "neutral" | "muted">;
 export interface ServiceLauncherCardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    /**
+     * The generic glyph for this KIND of service. Stays REQUIRED and stays a `LucideIcon`: every
+     * service has one, including a service created ten seconds ago that has no logo yet, and it is
+     * the thing `logo` falls back to. See the `logo` note for why this was not widened to a union.
+     */
     icon: LucideIcon;
+    /**
+     * URL of the service's OWN uploaded mark — the PNG/WebP an administrator uploaded (gh#850).
+     * When it loads, it replaces `icon` in the medallion, in the glyph's exact box.
+     *
+     * It is a fallback chain, not a switch: the tile shows `icon` while the URL is in flight, and
+     * KEEPS showing `icon` if the URL 404s, is empty, or decodes to nothing. A launcher never
+     * degrades to an empty medallion or a torn-page glyph because a logo went missing — which is the
+     * only state that reaches production, since a logo path outlives the file it points at.
+     *
+     * Decorative, and deliberately has no `logoAlt` companion: the medallion is `aria-hidden` and the
+     * service NAME sits beside it. A screen reader must not hear "Attendance" twice (WCAG 2.2 · 1.1.1
+     * — an image adjacent to text conveying the same thing is decorative).
+     */
+    logo?: string;
     title: React.ReactNode;
     titleLevel?: HeadingLevelProp;
     statusLabel?: React.ReactNode;

package/dist/components/data-display/service-launcher-card.js

@@ -2,6 +2,7 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { Plus } from "lucide-react";
+import { useImageLoadingStatus } from "../../lib/image-loading-status.js";
 import { cn } from "../../lib/utils.js";
 import { Badge } from "./badge.js";
 import { Card, CardContent } from "./card.js";
@@ -9,6 +10,7 @@ const ServiceLauncherCard = React.forwardRef(
   ({
     className,
     icon: Icon,
+    logo,
     title,
     titleLevel = 2,
     statusLabel,
@@ -20,6 +22,11 @@ const ServiceLauncherCard = React.forwardRef(
     ...props
   }, ref) => {
     const Heading = `h${titleLevel}`;
+    const [logoStatus, setLogoStatus] = React.useState("idle");
+    const logoLoadingStatus = useImageLoadingStatus(logo || void 0, {
+      loadingStatus: logoStatus,
+      setLoadingStatus: setLogoStatus
+    });
     return /* @__PURE__ */ jsx(
       Card,
       {
@@ -32,7 +39,13 @@ const ServiceLauncherCard = React.forwardRef(
         children: /* @__PURE__ */ jsxs(CardContent, { solo: true, children: [
           /* @__PURE__ */ jsxs("div", { "data-slot": "service-launcher-heading", children: [
             /* @__PURE__ */ jsxs("div", { "data-slot": "service-launcher-identity", children: [
-              /* @__PURE__ */ jsx("span", { "data-slot": "service-launcher-icon", "aria-hidden": "true", children: /* @__PURE__ */ jsx(Icon, {}) }),
+              /* @__PURE__ */ jsx("span", { "data-slot": "service-launcher-icon", "aria-hidden": "true", children: logoLoadingStatus === "loaded" ? (
+                /* No `loading="lazy"`: the probe above has ALREADY fetched this URL by the time
+                 * this element exists, so a lazy hint would describe a request that is over.
+                 * `decoding="async"` is the hint that still means something here — it keeps the
+                 * decode of a grid of logos off the main thread. */
+                /* @__PURE__ */ jsx("img", { "data-slot": "service-launcher-logo", src: logo, alt: "", decoding: "async" })
+              ) : /* @__PURE__ */ jsx(Icon, {}) }),
               /* @__PURE__ */ jsx(Heading, { "data-slot": "service-launcher-title", children: title })
             ] }),
             statusLabel != null ? /* @__PURE__ */ jsx(Badge, { tone: statusTone, "data-slot": "service-launcher-status", children: statusLabel }) : null

package/dist/components/data-entry/attachments.js

@@ -6,7 +6,6 @@ import { useTranslation } from "../../i18n/use-translation.js";
 import { formatBytes } from "../../lib/format.js";
 import { cn } from "../../lib/utils.js";
 import { Button } from "../general/button.js";
-import { Text } from "../general/typography.js";
 import { Progress } from "../data-display/progress.js";
 import { createUploadItem } from "./upload-types.js";
 import { readDroppedFiles } from "./upload-files.js";
@@ -30,6 +29,10 @@ function resolvePlaceholder(placeholder, type) {
   if (!placeholder) return {};
   return typeof placeholder === "function" ? placeholder(type) : placeholder;
 }
+function splitFileName(name) {
+  const match = /^(.*)\.[^.]+$/.exec(name ?? "");
+  return match ? [match[1], (name ?? "").slice(match[1].length)] : [name ?? "", ""];
+}
 function fileMatchesAccept(file, accept) {
   if (!accept) return true;
   return accept.split(",").some((rule) => {
@@ -60,6 +63,7 @@ function PlaceholderUploader({
       className: cn("ui-attachments-placeholder", className),
       style,
       "data-drag-active": dragActive ? "true" : void 0,
+      "data-disabled": disabled ? "true" : void 0,
       "aria-hidden": disabled ? true : void 0,
       onDragEnter: (event) => {
         event.preventDefault();
@@ -71,6 +75,7 @@ function PlaceholderUploader({
       },
       onDrop: async (event) => {
         event.preventDefault();
+        event.stopPropagation();
         setDragActive(false);
         if (disabled) return;
         const files = await readDroppedFiles(event.dataTransfer, false);
@@ -107,27 +112,55 @@ function AttachmentCard({
   const { t } = useTranslation();
   const { disabled } = React.useContext(AttachmentContext);
   const preview = item.thumbUrl ?? item.url;
+  const [namePrefix, nameSuffix] = splitFileName(item.name);
   const desc = description ?? item.description ?? (item.status === "uploading" ? `${item.percent ?? 0}%` : item.status === "error" ? typeof item.response === "string" ? item.response : t("dataEntry.attachments.error") : item.size ? formatBytes(item.size) : "");
-  return /* @__PURE__ */ jsxs("li", { className: cn("ui-attachments-card", classNames?.card, classNames?.file), children: [
-    preview ? /* @__PURE__ */ jsx("img", { src: preview, alt: "", className: "ui-attachments-card-preview", "aria-hidden": "true" }) : /* @__PURE__ */ jsx("span", { className: "ui-attachments-card-placeholder", "aria-hidden": "true", children: /* @__PURE__ */ jsx(FileIcon, {}) }),
-    (item.status === "uploading" || item.status === "error") && /* @__PURE__ */ jsx("div", { className: "ui-attachments-card-overlay", children: item.status === "uploading" && item.percent != null ? /* @__PURE__ */ jsx(Progress, { value: item.percent, "aria-label": t("dataEntry.attachments.uploading") }) : /* @__PURE__ */ jsx(Text, { size: "xs", children: String(desc) }) }),
-    desc && item.status !== "uploading" && item.status !== "error" ? /* @__PURE__ */ jsx("div", { className: "ui-attachments-card-meta", children: desc }) : null,
-    !disabled && onRemove ? /* @__PURE__ */ jsx(
-      Button,
-      {
-        type: "button",
-        variant: "ghost",
-        size: "icon-xs",
-        className: "ui-attachments-card-remove",
-        "aria-label": t("dataEntry.attachments.remove", { name: item.name }),
-        onClick: (event) => {
-          event.stopPropagation();
-          onRemove();
-        },
-        children: /* @__PURE__ */ jsx(X, { "aria-hidden": "true" })
-      }
-    ) : null
-  ] });
+  return /* @__PURE__ */ jsxs(
+    "li",
+    {
+      className: cn("ui-attachments-card", classNames?.card, classNames?.file),
+      "data-status": item.status,
+      children: [
+        preview ? /* @__PURE__ */ jsx("img", { src: preview, alt: "", className: "ui-attachments-card-preview", "aria-hidden": "true" }) : /* @__PURE__ */ jsx("span", { className: "ui-attachments-card-placeholder", "aria-hidden": "true", children: /* @__PURE__ */ jsx(FileIcon, {}) }),
+        /* @__PURE__ */ jsxs("span", { className: "ui-attachments-card-content", children: [
+          /* @__PURE__ */ jsxs("span", { className: "ui-attachments-card-name", title: item.name, children: [
+            /* @__PURE__ */ jsx("span", { className: "ui-attachments-card-name-prefix", children: namePrefix }),
+            /* @__PURE__ */ jsx("span", { className: "ui-attachments-card-name-suffix", children: nameSuffix })
+          ] }),
+          desc ? /* @__PURE__ */ jsx(
+            "span",
+            {
+              className: "ui-attachments-card-meta",
+              title: typeof desc === "string" ? desc : void 0,
+              children: desc
+            }
+          ) : null
+        ] }),
+        item.status === "uploading" && item.percent != null ? /* @__PURE__ */ jsx("span", { className: "ui-attachments-card-progress", children: /* @__PURE__ */ jsx(
+          Progress,
+          {
+            size: "sm",
+            value: item.percent,
+            "aria-label": t("dataEntry.attachments.uploading")
+          }
+        ) }) : null,
+        !disabled && onRemove ? /* @__PURE__ */ jsx(
+          Button,
+          {
+            type: "button",
+            variant: "ghost",
+            size: "icon-xs",
+            className: "ui-attachments-card-remove",
+            "aria-label": t("dataEntry.attachments.remove", { name: item.name }),
+            onClick: (event) => {
+              event.stopPropagation();
+              onRemove();
+            },
+            children: /* @__PURE__ */ jsx(X, { "aria-hidden": "true" })
+          }
+        ) : null
+      ]
+    }
+  );
 }
 const Attachments = React.forwardRef(
   ({
@@ -151,6 +184,7 @@ const Attachments = React.forwardRef(
     const containerRef = React.useRef(null);
     const inputRef = React.useRef(null);
     const [internalItems, setInternalItems] = React.useState([]);
+    const [dropActive, setDropActive] = React.useState(false);
     const items = controlledItems ?? internalItems;
     const setItems = React.useCallback(
       (next, file) => {
@@ -207,7 +241,7 @@ const Attachments = React.forwardRef(
       {
         ref: inputRef,
         type: "file",
-        className: "ui-attachments-input",
+        className: cn("ui-attachments-input", "sr-only"),
         accept,
         multiple: multiple ?? (maxCount == null || maxCount > 1),
         disabled,
@@ -244,7 +278,7 @@ const Attachments = React.forwardRef(
         )
       ] });
     }
-    const dropHost = getDropContainer?.() ?? containerRef.current;
+    const dropScope = getDropContainer?.() ? "viewport" : "control";
     return /* @__PURE__ */ jsx(AttachmentContext.Provider, { value: { disabled }, children: /* @__PURE__ */ jsxs(
       "div",
       {
@@ -252,6 +286,21 @@ const Attachments = React.forwardRef(
         className: cn("ui-attachments", className, rootClassName, classNames.root),
         style: styles.root,
         dir: "auto",
+        onDragEnter: (event) => {
+          event.preventDefault();
+          if (!disabled) setDropActive(true);
+        },
+        onDragOver: (event) => event.preventDefault(),
+        onDragLeave: (event) => {
+          if (!event.currentTarget.contains(event.relatedTarget)) setDropActive(false);
+        },
+        onDrop: async (event) => {
+          event.preventDefault();
+          setDropActive(false);
+          if (disabled) return;
+          const files = await readDroppedFiles(event.dataTransfer, false);
+          if (files.length) dispatchFiles(files);
+        },
         children: [
           fileInput,
           hasFiles ? /* @__PURE__ */ jsxs(
@@ -297,20 +346,15 @@ const Attachments = React.forwardRef(
               hidden: hasFiles
             }
           ),
-          dropHost ? /* @__PURE__ */ jsx(
+          /* @__PURE__ */ jsx(
             "div",
             {
               className: "ui-attachments-drop-layer",
-              "data-active": void 0,
-              "aria-hidden": "true",
-              onDragOver: (event) => event.preventDefault(),
-              onDrop: async (event) => {
-                event.preventDefault();
-                const files = await readDroppedFiles(event.dataTransfer, false);
-                dispatchFiles(files);
-              }
+              "data-scope": dropScope,
+              "data-active": dropActive ? "true" : void 0,
+              "aria-hidden": "true"
             }
-          ) : null
+          )
         ]
       }
     ) });

package/dist/components/ui/avatar.d.ts

@@ -1,22 +1,6 @@
 import * as React from "react";
+import { type ImageLoadingStatus } from "../../lib/image-loading-status.js";
 import type { AvatarProp } from "../../props/components/data-display.prop.js";
-/**
- * Trạng thái tải của ảnh trong avatar — chia sẻ giữa `AvatarImage` và
- * `AvatarFallback` qua context, đúng như Radix làm.
- *
- * React Aria KHÔNG có avatar, nên đây là việc TỰ DỰNG. Nhưng phần cần dựng lại
- * không phải cái vỏ `<span>` — mà là logic thật mà `@radix-ui/react-avatar` cầm:
- * ảnh chỉ được vẽ khi đã tải XONG, fallback chỉ được vẽ khi ảnh CHƯA xong hoặc
- * HỎNG, và `delayMs` giữ fallback im lặng đủ lâu để mạng nhanh không kịp nháy
- * một khung initials trước khi ảnh về.
- *
- * Phép dò là một `new Image()` RỜI, không phải `onLoad`/`onError` trên chính
- * thẻ được vẽ: thẻ chỉ tồn tại khi đã `loaded`, nên handler trên nó không bao
- * giờ có cơ hội báo "đang tải" hay "hỏng". Đây cũng là lý do một `<img>` hỏng
- * không bao giờ nằm trong DOM để trình duyệt vẽ biểu tượng ảnh vỡ lên trên
- * fallback.
- */
-type ImageLoadingStatus = "idle" | "loading" | "loaded" | "error";
 export declare const Avatar: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & {
     asChild?: boolean;
 } & Pick<AvatarProp, "appearance" | "presence" | "presenceLabel" | "shape" | "size"> & React.RefAttributes<HTMLSpanElement>>;
@@ -28,4 +12,3 @@ export declare const AvatarFallback: React.ForwardRefExoticComponent<Omit<React.
     asChild?: boolean;
     delayMs?: number;
 } & React.RefAttributes<HTMLSpanElement>>;
-export {};