@godxjp/ui 28.3.1 → 28.5.0

package/dist/styles/data-entry-layout.css

@@ -92,15 +92,15 @@
   }
 
   .ui-password-strength-segment[data-tone="destructive"] {
-    background: hsl(var(--mark-destructive));
+    background: hsl(var(--mark-destructive, var(--text-error)));
   }
 
   .ui-password-strength-segment[data-tone="warning"] {
-    background: hsl(var(--mark-warning));
+    background: hsl(var(--mark-warning, var(--text-warning)));
   }
 
   .ui-password-strength-segment[data-tone="success"] {
-    background: hsl(var(--mark-success));
+    background: hsl(var(--mark-success, var(--text-success)));
   }
 
   .ui-password-strength-meta {

package/dist/styles/table-layout.css

@@ -16,27 +16,30 @@
   }
 
   .ui-table-row[data-tone="primary"] {
-    --table-row-tone-color: var(--mark-primary);
+    --table-row-tone-color: var(
+      --mark-primary,
+      var(--text-primary, from hsl(var(--primary)) var(--text-primary-channels))
+    );
   }
 
   .ui-table-row[data-tone="success"] {
-    --table-row-tone-color: var(--mark-success);
+    --table-row-tone-color: var(--mark-success, var(--text-success));
   }
 
   .ui-table-row[data-tone="warning"] {
-    --table-row-tone-color: var(--mark-warning);
+    --table-row-tone-color: var(--mark-warning, var(--text-warning));
   }
 
   .ui-table-row[data-tone="info"] {
-    --table-row-tone-color: var(--mark-info);
+    --table-row-tone-color: var(--mark-info, var(--text-info));
   }
 
   .ui-table-row[data-tone="attention"] {
-    --table-row-tone-color: var(--mark-attention);
+    --table-row-tone-color: var(--mark-attention, var(--attention));
   }
 
   .ui-table-row[data-tone="destructive"] {
-    --table-row-tone-color: var(--mark-destructive);
+    --table-row-tone-color: var(--mark-destructive, var(--text-error));
   }
 
   .ui-table-row[data-tone] {

package/dist/styles/text-layout.css

@@ -134,7 +134,7 @@
   }
 
   [data-slot="text"][data-link][data-tone="primary"]:not([data-disabled]) {
-    color: hsl(var(--text-link));
+    color: hsl(var(--text-link, from hsl(var(--primary)) var(--text-link-channels)));
   }
   [data-slot="text"][data-link]:hover,
   [data-slot="text"][data-link]:focus-visible {

package/dist/theme/famgia.service.css

@@ -7,8 +7,7 @@
 
   --primary: 221 83% 53%;
   --primary-foreground: 0 0% 100%;
-  --primary-hover: 224 71% 48%;
-  --primary-active: 226 71% 40%;
+
   --ring: 221 83% 53%;
 
   --text-link: 224 76% 45%;
@@ -25,8 +24,7 @@
 .dark {
   --primary: 221 90% 66%;
   --primary-foreground: 222 47% 11%;
-  --primary-hover: 221 90% 72%;
-  --primary-active: 221 90% 60%;
+
   --ring: 221 90% 66%;
   --text-link: 221 90% 72%;
   --text-brand: 221 90% 70%;

package/dist/tokens/components/control.css

@@ -39,7 +39,8 @@
 
   --control-count-font-size: var(--font-size-sm);
   --control-count-color: var(--muted-foreground);
-  --control-count-exceeded-color: var(--text-error);
+
+  --control-count-exceeded-color: initial;
   --control-count-space-inline: var(--space-1);
   --textarea-count-inset-block-end: var(--space-1);
   --textarea-count-inset-inline-end: var(--space-2);
@@ -388,9 +389,9 @@
   --control-borderless-shadow: none;
 
   --control-status-error-border-color: hsl(var(--destructive));
-  --control-status-warning-border-color: hsl(var(--text-warning));
+  --control-status-warning-border-color: initial;
 
-  --control-status-warning-outline-color: var(--text-warning);
+  --control-status-warning-outline-color: initial;
 }
 
 @media (pointer: coarse) {

package/dist/tokens/components/scroll-area.css

@@ -8,5 +8,8 @@
 
   --scroll-area-scrollbar-space: auto;
 
+  --scroll-area-always-bar-size: 0.625rem;
+  --scroll-area-always-thumb-radius: var(--radius-pill);
+
   --scroll-area-anchor-offset: 3rem;
 }

package/dist/tokens/derived.css

@@ -20,6 +20,15 @@
   --control-outline-channels: h s calc(l - 5.3);
   --control-outline-alpha: 0.11;
 
+  --text-link: initial;
+  --text-brand: initial;
+  --text-primary: initial;
+
+  --text-link-channels: var(--primary-hover-channels);
+  --text-brand-channels: var(--primary-hover-channels);
+
+  --text-primary-channels: var(--primary-active-channels);
+
   --destructive-hover: 359 50.6% 53.1%;
   --destructive-active: 355 70.6% 33.3%;
 
@@ -39,6 +48,11 @@
   --control-outline-channels: h calc(s * 0.99) calc(l - 25.1);
   --control-outline-alpha: 0.29;
 
+  --text-link-channels: h s l;
+  --text-brand-channels: h s l;
+
+  --text-primary-channels: var(--primary-hover-channels);
+
   --destructive-hover: 358.8 42.3% 53.1%;
   --destructive-active: 357.3 50.6% 34.1%;
 
@@ -54,6 +68,9 @@
     --primary-active: 268.7 100% 34.5%;
     --primary-border: 268.7 68% 66%;
     --control-outline: 268.7 100% 44.7%;
+    --text-link: 268.7 100% 41.6%;
+    --text-brand: 268.7 100% 41.6%;
+    --text-primary: 268.7 100% 34.5%;
   }
 
   .dark,
@@ -62,5 +79,8 @@
     --primary-active: 268.7 100% 81.1%;
     --primary-border: 268.7 46.7% 23.5%;
     --control-outline: 268.7 99% 61.8%;
+    --text-link: 268.7 100% 86.9%;
+    --text-brand: 268.7 100% 86.9%;
+    --text-primary: 268.7 100% 92.7%;
   }
 }

package/dist/tokens/foundation.css

@@ -40,21 +40,17 @@
   --text-tertiary: 44 5% 55%;
   --text-disabled: 40 6% 68%;
 
-  --text-link: 268.3 100% 41.6%;
-  --text-brand: 268.3 100% 41.6%;
-
-  --text-primary: 268 100% 34.5%;
   --text-success: 152 84% 22%;
   --text-warning: 36 100% 28%;
   --text-info: 221 70% 38%;
   --text-error: 357 75% 38%;
 
-  --mark-primary: var(--text-primary);
-  --mark-success: var(--text-success);
-  --mark-warning: var(--text-warning);
-  --mark-info: var(--text-info);
-  --mark-destructive: var(--text-error);
-  --mark-attention: var(--attention);
+  --mark-primary: initial;
+  --mark-success: initial;
+  --mark-warning: initial;
+  --mark-info: initial;
+  --mark-destructive: initial;
+  --mark-attention: initial;
 
   --secondary-hover: 45 15% 91%;
   --secondary-active: 45 15% 88%;
@@ -349,10 +345,7 @@
 
   --text-tertiary: 44 6% 56%;
   --text-disabled: 45 6% 40%;
-  --text-link: 268.7 100% 86.9%;
-  --text-brand: 268.7 100% 86.9%;
 
-  --text-primary: 262.7 100% 92.7%;
   --text-success: 146 55% 64%;
   --text-warning: 44 95% 62%;
   --text-info: 221 70% 72%;

package/docs/CUSTOMER-THEMING.md

@@ -6,6 +6,82 @@ The design system ships a complete, **zero-config default theme**. Two audiences
 
 ---
 
+## The order to reach for things — read this before anything below
+
+This document lists a lot of ways to change how the system looks. They are not alternatives; they
+are a **priority order**, and the whole point of the order is that you stop at the first level that
+does the job. Ant Design states the same rule for the same reason — _"In most cases, using Seed
+Tokens is sufficient for custom themes"_ — and the cost of skipping down a level is real, not
+stylistic.
+
+| level            | what it is                                                                                                                                          | when                                            | what you give up by going lower                                           |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------- |
+| **1 · seed**     | `--primary`, `--radius`, `--font-size-base`, `--shadow-color` — the handful everything derives from. `pnpm gen:brand '#RRGGBB'` writes them for you | **almost always**                               | nothing — this is the main road                                           |
+| **2 · role**     | a named semantic token: `--text-link`, `--accent`, `--card-radius`                                                                                  | when the seed is right but ONE role must differ | that role stops following the seed; a later brand change will not move it |
+| **3 · scope**    | the same token under `[data-tenant]` / `.dark` / any subtree                                                                                        | multi-tenant, or one region that differs        | nothing extra, provided you set the token and not a literal               |
+| **4 · instance** | a documented prop, or `style={{ "--x": … }}` on one element                                                                                         | this one element, this one time                 | it is invisible to every audit and every future theme                     |
+
+**Why the order matters more than the count of knobs.** Every level below the first is a value that
+has stopped being derived. A literal at level 4 is not "more control" — it is a pixel that has left
+the system, and nothing will tell you when the brand moves past it. That is why the generator
+writes three tokens and not thirty: the ones it leaves out are not missing, they are _downstream_.
+
+**If you find yourself at level 4 twice for the same reason, the token is missing.** File it —
+`docs/COMPOSITION-VS-COMPONENT.md` has the test for whether it is a token or a composition. Adding
+the knob is how the system absorbs the change; repeating the literal is how it drifts.
+
+---
+
+## Start from one hex — `pnpm gen:brand`
+
+Everything below this section is the manual route, and it is worth reading because it says what each
+role means. But the colour half of a brand file is mechanical, and two of its decisions are ones CSS
+cannot make at all, so there is a generator:
+
+```sh
+pnpm gen:brand '#2563EB' --name acme --out src/theme
+```
+
+It writes `acme.service.css` and `acme.email.ts`, and prints what it measured:
+
+```
+  light seed #2563eb  ·  dark seed #5586ef (lifted 10.4%)
+
+  ✓ primary label on fill (light)    5.17:1  (needs 4.5:1)
+  ✓ primary label on fill (dark)     6.03:1  (needs 4.5:1)
+  ✓ primary fill on canvas (light)   5.09:1  (needs 3:1)
+  ✓ primary fill on canvas (dark)    5.10:1  (needs 3:1)
+  ✓ link ink on canvas (light)       6.73:1  (needs 4.5:1)
+  ✓ link ink on canvas (dark)        6.36:1  (needs 4.5:1)
+```
+
+It exits non-zero when a ratio misses, so a brand that cannot meet AA says so at the point you
+choose the colour rather than at the point a user cannot read a link.
+
+**The two things it does that hand-authoring keeps getting wrong:**
+
+- **A dark seed.** Nothing in CSS lifts a light seed onto the dark spine, so a brand file that sets
+  `--primary` only in `:root` keeps the GoDX violet in dark mode and nothing says so. The generator
+  holds your hue and saturation and moves lightness until the dark seed reads against the dark
+  canvas the way the light seed reads against the light one.
+- **Email.** `src/email/tokens.generated.ts` bakes literal hex at build time, because Gmail strips
+  `<style>` and Outlook ignores custom properties. Those literals are _this package's_ seed, so a
+  re-themed product still sends GoDX-violet mail — the one surface no amount of CSS reaches. The
+  emitted `acme.email.ts` is the override that corrects it.
+
+**What it deliberately leaves out**, because writing them would be a regression:
+
+- `--primary-hover`, `--primary-active`, `--primary-border`, `--control-outline` — these DERIVE from
+  the `--primary` in scope at the element that paints them (gh#678). A literal pins them to one seed
+  and stops them following the next change.
+- `--brand` / `--brand-foreground` — the identity role is independent of the action colour on
+  purpose (gh#250), so the logo does not retint when a tenant changes its button colour.
+
+The output is a starting point, not a ceiling: every role in the tables below can still be set by
+hand in the generated file, and an explicit value always beats a derived default.
+
+---
+
 ## Internal apps — zero config
 
 ```ts
@@ -165,17 +241,20 @@ Import the styles, then set anchor tokens in your app's `theme.css` (loaded afte
 
 ### Focus ring — THE SWITCH FIRST, then three levels of override
 
-**The indicator ships OFF.** `--focus-outline` is `0`, and every painted focus length multiplies by it, so by default nothing paints a focus mark. That is a product decision with a stated cost — it forfeits WCAG 2.2 SC 2.4.7 (AA) and a JIS X 8341-3 AA claim — recorded in `docs/DESIGN-AUTHORITY.md`. Turning it on is ONE attribute on the root element, no CSS:
+**The indicator ships ON.** `--focus-outline` is `1` (`src/tokens/foundation.css`), and every painted focus length multiplies by it, so a focus mark paints by default and the package meets WCAG 2.2 SC 2.4.7. It did ship `0` once, and that earlier default — with its stated cost, a forfeited SC 2.4.7 and JIS X 8341-3 AA claim — is recorded in `docs/DESIGN-AUTHORITY.md`; gh#544 flipped it. Nothing has to be opted into.
+
+Switching the paint is ONE attribute on the root element, no CSS:
 
 ```html
 <html data-focus-outline="on"></html>
+<html data-focus-outline="off"></html>
 ```
 
 (`AppProvider` has the equivalent.) Every `:focus-visible` selector is present either way; only the paint is switched.
 
 Every ring is then drawn by a single rule (`src/styles/focus-ring.css`) reading the tokens above. Nothing else paints one; a test fails the build if a stylesheet tries.
 
-**Thickness is `--focus-ring-weight`, never `--focus-ring-width`.** The width is DERIVED — `calc(var(--focus-ring-weight) * var(--focus-outline))` — so assigning it directly paints a ring even while the indicator is switched off, and that is exactly what the build-failing test forbids a stylesheet to do.
+**Thickness is `--focus-ring-weight`, never `--focus-ring-width`.** The width is DERIVED — `calc(var(--focus-ring-weight) * var(--focus-outline))` — so assigning it directly paints a ring even where the indicator is switched off, and that is exactly what the build-failing test forbids a stylesheet to do.
 
 ```css
 :root {
@@ -203,7 +282,7 @@ Every ring is then drawn by a single rule (`src/styles/focus-ring.css`) reading
 <div style={{ "--focus-ring-color": "0 84% 60%" } as React.CSSProperties}>…</div>
 ```
 
-**Turning it back off** — drop the `data-focus-outline` attribute (or set `--focus-outline: 0`), which is the shipped state. Do NOT reach for `--focus-ring-width`: it is derived from the weight and the switch, and pinning it to any value is the same mistake in the other direction. Note the cost either way — with no visible focus indicator the package does not meet WCAG 2.2 SC 2.4.7.
+**Turning it off** — set `--focus-outline: 0` (or `data-focus-outline="off"`). Do NOT reach for `--focus-ring-width`: it is derived from the weight and the switch, and pinning it to any value is the same mistake in the other direction. Note the cost: with no visible focus indicator the package no longer meets WCAG 2.2 SC 2.4.7, so this is a claim you are giving up, not a style preference.
 
 **Adding your own component to the system**: put `ui-focus-ring` (or `ui-focus-ring-outline` when the mark needs a gap) on the focusable element.
 

package/docs/FRAME-COVERAGE-REPORT.md

@@ -135,7 +135,7 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | TreeSelect | ✓ | ✓ | · | · | · | · | · | · | · | · |
 | Transfer | ✓ | N/A | · | · | · | · | · | · | · | · |
 | Upload | ✓ | ✓ | · | · | · | · | · | · | · | · |
-| UploadCropDialog | ✓ | · | · | · | · | · | · | · | · | · |
+| UploadCropDialog | ✓ | N/A | N/A | · | · | · | · | · | · | · |
 | ColorPicker | ✓ | N/A | · | · | · | · | · | · | · | · |
 | Slider | ✓ | N/A | · | · | · | · | · | · | · | · |
 | Calendar | ✓ | N/A | · | N/A | · | · | · | · | · | · |

package/docs/data-display/scroll-area.tsx

@@ -16,8 +16,12 @@ import { Flex, PageContainer, ResponsiveGrid } from "@godxjp/ui/layout";
 /**
  * ScrollArea — a native scrolling box. ALWAYS give it an explicit height/max-height
  * (vertical) or width (horizontal), or nothing ever overflows and no scrollbar appears.
- * `orientation` decides which axes may scroll; the browser draws the bar, styled from
- * the --scroll-area-* tokens. Composed only from real @godxjp/ui components.
+ * `orientation` decides which axes may scroll. By default the PLATFORM draws the bar,
+ * styled from the --scroll-area-* tokens — and on macOS/iPadOS with the system default
+ * "Show scroll bars: when scrolling" that bar is an OVERLAY: it exists only while the
+ * reader is already scrolling, so a wide area does not look scrollable at rest (gh#798).
+ * `scrollbar="always"` forces a classic bar that occupies layout, from the same tokens.
+ * Composed only from real @godxjp/ui components.
  */
 const entries = Array.from(
   { length: 18 },

package/docs/data-entry/upload-crop-dialog.tsx

@@ -0,0 +1,110 @@
+import { useRef, useState } from "react";
+
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@godxjp/ui/data-display";
+import { Upload, UploadCropDialog } from "@godxjp/ui/data-entry";
+import { Button, Text } from "@godxjp/ui/general";
+import { Flex, PageContainer } from "@godxjp/ui/layout";
+
+/**
+ * UploadCropDialog — the square-crop step of an avatar flow, on its own.
+ *
+ * MOST SCREENS SHOULD NOT REACH FOR THIS. `<Upload variant="avatar-crop">` already embeds this
+ * dialog and owns the picker, the object URL and the commit; mounting both double-mounts the
+ * dialog. The standalone component exists for the case where the FILE ARRIVES FROM SOMEWHERE ELSE
+ * — a drag-drop zone you already own, a paste handler, a file already on the server — and only the
+ * crop step is wanted. That is the case this frame shows, beside the composed one for contrast.
+ *
+ * It is fully controlled: `open`, `file` and `onConfirm` are all required, and the dialog never
+ * opens itself. It creates and revokes its own object URL, so a caller passes the raw `File` and
+ * does NOT pre-create one. The result is always a 256×256 image/jpeg.
+ */
+export default function Demo() {
+  const [cropFile, setCropFile] = useState<File | null>(null);
+  const [avatar, setAvatar] = useState<string | null>(null);
+  const [lastResult, setLastResult] = useState<string | null>(null);
+  const pickerRef = useRef<HTMLInputElement>(null);
+
+  return (
+    <PageContainer title="UploadCropDialog" subtitle="切り抜きだけを単体で使う場合">
+      <Flex direction="col" gap="lg">
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>単体で使う</CardTitle>
+            <CardDescription>
+              ファイルの取得は呼び出し側の責任です。ここではブラウザのピッカーから受け取り、
+              切り抜き結果だけをこのダイアログから受け取ります。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Flex direction="row" gap="md" align="center" wrap>
+                <Avatar size="lg">
+                  {avatar ? <AvatarImage src={avatar} alt="切り抜いたプロフィール写真" /> : null}
+                  <AvatarFallback>田</AvatarFallback>
+                </Avatar>
+                <Button onClick={() => pickerRef.current?.click()}>写真を選ぶ</Button>
+              </Flex>
+
+              {/* The picker is the CONSUMER's, not the dialog's — that is the whole point of using
+                  this component standalone. It is hidden because the Button above is the affordance;
+                  a visible raw control beside a godx Button would be two controls for one job. */}
+              <input
+                ref={pickerRef}
+                type="file"
+                accept="image/*"
+                className="sr-only"
+                aria-hidden
+                tabIndex={-1}
+                onChange={(event) => {
+                  const file = event.target.files?.[0] ?? null;
+                  setCropFile(file);
+                  // Clear the input so re-picking the SAME file fires change again.
+                  event.target.value = "";
+                }}
+              />
+
+              <Text size="sm" tone="muted" aria-live="polite">
+                {lastResult ?? "まだ切り抜いていません。"}
+              </Text>
+
+              <UploadCropDialog
+                open={cropFile !== null}
+                // Always clear the held File on close, or the next open shows a stale image.
+                onOpenChange={(open) => !open && setCropFile(null)}
+                file={cropFile}
+                onConfirm={(cropped) => {
+                  setAvatar(URL.createObjectURL(cropped));
+                  setLastResult(
+                    `${cropped.name} · ${cropped.type} · ${Math.round(cropped.size / 1024)} KB`,
+                  );
+                }}
+              />
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>通常はこちら</CardTitle>
+            <CardDescription>
+              `Upload variant="avatar-crop"` は同じダイアログを内部に持ち、ピッカーも
+              オブジェクトURLも引き受けます。両方を同時に置いてはいけません。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Upload variant="avatar-crop" accept="image/*" />
+          </CardContent>
+        </Card>
+      </Flex>
+    </PageContainer>
+  );
+}