@godxjp/ui 28.6.0 → 28.8.0

package/docs/data-display/service-launcher-card.tsx

@@ -1,10 +1,15 @@
 import {
-  BookPlus,
+  BookOpen,
+  Boxes,
+  Calendar,
   Clock3,
   Database,
+  FileText,
   LayoutGrid,
+  Mail,
   PlugZap,
   ReceiptText,
+  Server,
   ShieldCheck,
 } from "lucide-react";
 
@@ -13,132 +18,287 @@ import {
   ServiceLauncherCard,
   ServiceLauncherCardSkeleton,
 } from "@godxjp/ui/data-display";
-import { Button } from "@godxjp/ui/general";
+import { Button, Text } from "@godxjp/ui/general";
 import { Flex, PageContainer, ResponsiveGrid } from "@godxjp/ui/layout";
 
 /**
- * ServiceLauncherCard — organization-scoped launcher states. The consumer supplies every status,
- * entitlement reason and action; the component owns only the shared visual contract.
+ * ServiceLauncherCard — one tile for one application in an organization's launcher.
+ *
+ * WHY THIS PAGE IS GENERIC. It used to render this product's own service catalogue —
+ * `attendance.godx.jp`, plans `Standard/Enterprise/Free`, a 「カタログを見る」 link — which made a
+ * reader ask whether the component belonged in a UI framework at all. A fair question: a page that
+ * demonstrates a product cannot demonstrate a component. The data here is therefore ANY
+ * organization's internal tools, on RFC 2606 reserved domains, with no plan names of ours.
+ *
+ * WHAT IS NOT NEGOTIABLE is the state set — available / restricted / suspended / archived /
+ * loading / catalog entry. Those ARE the component's API surface, because the component infers
+ * nothing: `statusLabel`, `statusTone`, `disabledReason` and `action` all come from the consumer's
+ * own entitlement contract. There is no `href`, no `available`, no `entitlement` prop to find.
+ *
+ * ResponsiveGrid owns the 3 → 2 → 1 ladder. The page writes no grid tracks and no page-local CSS.
  */
+
+/** A section heading. Headings are headings, not Cards — a Card here would nest borders. */
+function Section({
+  title,
+  why,
+  children,
+}: {
+  title: string;
+  why: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <Flex direction="col" gap="sm">
+      <Text as="div" weight="medium">
+        {title}
+      </Text>
+      <Text as="div" size="sm" tone="muted">
+        {why}
+      </Text>
+      {children}
+    </Flex>
+  );
+}
+
 export default function Demo() {
   return (
     <PageContainer
       title="ServiceLauncherCard"
-      subtitle="利用可能・制限中・読み込み中・カタログ導線"
+      subtitle="社内アプリケーション一覧のタイル — 利用可能・制限・停止・アーカイブ・読み込み中・カタログ導線"
     >
       <Flex direction="col" gap="lg">
-        <ResponsiveGrid columns={{ sm: 1, md: 2, lg: 3 }}>
-          <ServiceLauncherCard
-            icon={Clock3}
-            title="勤怠管理"
-            statusLabel="LIVE"
-            statusTone="success"
-            description="打刻、シフト、休暇申請を一つのワークスペースで管理します。"
-            metadata="attendance.godx.jp · Standard"
-            action={<Button>サービスを開く</Button>}
-          />
-          <ServiceLauncherCard
-            icon={ReceiptText}
-            title="請求管理"
-            statusLabel="要契約"
-            statusTone="warning"
-            description="請求書、支払い方法、利用明細を管理します。"
-            metadata="billing.godx.jp"
-            disabledReason="この組織には有効な請求管理プランがありません。"
-            action={<Button disabled>サービスを開く</Button>}
-          />
-          <ServiceLauncherCard
-            icon={ShieldCheck}
-            title="高度なセキュリティ管理と監査ログ"
-            statusLabel="管理者限定"
-            statusTone="info"
-            description="権限、二要素認証ポリシー、監査イベントを確認します。"
-            metadata="security.godx.jp · Enterprise"
-            action={<Button variant="outline">権限を確認</Button>}
-          />
-          <ServiceLauncherCardSkeleton label="サービスを読み込み中" />
-          <ServiceCatalogCta
-            title="サービスカタログから追加"
-            action={<Button variant="outline">カタログを見る</Button>}
-          />
-        </ResponsiveGrid>
+        <Section
+          title="1 · 基本 · 利用できるサービス"
+          why="アイコン・名称・ステータス・説明・識別子・操作。ステータスの文言は常に利用側のコピーで、コンポーネントが決めるのは tone に対応する Badge の意味づけだけです。"
+        >
+          <ResponsiveGrid columns={{ sm: 1, md: 2, lg: 3 }}>
+            <ServiceLauncherCard
+              icon={Clock3}
+              title="勤怠管理"
+              statusLabel="利用可能"
+              statusTone="success"
+              description="打刻、シフト、休暇申請を一つのワークスペースで管理します。"
+              metadata="attend.corp.example.jp · v4.2"
+              action={<Button>サービスを開く</Button>}
+            />
+            <ServiceLauncherCard
+              icon={ReceiptText}
+              title="経費精算"
+              statusLabel="利用可能"
+              statusTone="success"
+              description="領収書の提出から承認、仕訳連携までを扱います。"
+              metadata="keihi.corp.example.jp · v2.8"
+              action={<Button>サービスを開く</Button>}
+            />
+            <ServiceLauncherCard
+              icon={Calendar}
+              title="会議室予約"
+              statusLabel="利用可能"
+              statusTone="success"
+              description="拠点ごとの会議室と備品を予約します。"
+              metadata="rooms.corp.example.jp · v1.9"
+              action={<Button>サービスを開く</Button>}
+            />
+          </ResponsiveGrid>
+        </Section>
+
+        <Section
+          title="2 · statusTone の 6 値すべて"
+          why="success / warning / destructive / info / neutral / muted。tone は Badge の意味づけだけを決め、文言・判定・操作の可否はすべて利用側が渡します。"
+        >
+          <ResponsiveGrid columns={{ sm: 1, md: 2, lg: 3 }}>
+            <ServiceLauncherCard
+              icon={Mail}
+              titleLevel={3}
+              title="社内メール"
+              statusLabel="稼働中"
+              statusTone="success"
+              description="メールボックス、配布リスト、共有署名を管理します。"
+              metadata="mail.corp.example.jp"
+              action={<Button>サービスを開く</Button>}
+            />
+            <ServiceLauncherCard
+              icon={Server}
+              titleLevel={3}
+              title="ファイル共有"
+              statusLabel="メンテナンス中"
+              statusTone="warning"
+              description="部門フォルダと外部共有リンクを扱います。"
+              metadata="files.corp.example.jp"
+              action={<Button variant="outline">状況を見る</Button>}
+            />
+            <ServiceLauncherCard
+              icon={Database}
+              titleLevel={3}
+              title="データ連携基盤"
+              statusLabel="停止中"
+              statusTone="destructive"
+              description="外部システムとのデータ同期ジョブを管理します。"
+              metadata="sync.corp.example.jp"
+              action={<Button variant="outline">履歴を見る</Button>}
+            />
+            <ServiceLauncherCard
+              icon={ShieldCheck}
+              titleLevel={3}
+              title="権限管理"
+              statusLabel="管理者限定"
+              statusTone="info"
+              description="ロール、二要素認証ポリシー、監査イベントを確認します。"
+              metadata="iam.corp.example.jp"
+              action={<Button variant="outline">権限を確認</Button>}
+            />
+            <ServiceLauncherCard
+              icon={PlugZap}
+              titleLevel={3}
+              title="連携アプリ"
+              statusLabel="準備中"
+              statusTone="neutral"
+              description="サードパーティ連携の接続とスコープを設定します。"
+              metadata="connect.corp.example.jp"
+              action={<Button variant="outline">設定を開く</Button>}
+            />
+            <ServiceLauncherCard
+              icon={BookOpen}
+              titleLevel={3}
+              title="旧ナレッジベース"
+              statusLabel="アーカイブ"
+              statusTone="muted"
+              description="2024 年度までの運用手順を読み取り専用で保管しています。"
+              metadata="kb-archive.corp.example.jp"
+              action={<Button variant="outline">アーカイブを見る</Button>}
+            />
+          </ResponsiveGrid>
+        </Section>
+
+        <Section
+          title="3 · disabledReason · 操作が効かない理由は操作より先に置かれる"
+          why="無効化されたボタンは「なぜ」を一切伝えません。だから理由は DOM 順で操作より先に置かれ（WCAG 2.2 · 1.3.2）、タイルは data-unavailable を帯びてメダリオンが沈みます。disabledReason はボタンを無効化しません — それは利用側の Button prop のままです。"
+        >
+          <ResponsiveGrid columns={{ sm: 1, md: 2, lg: 3 }}>
+            <ServiceLauncherCard
+              icon={Boxes}
+              titleLevel={3}
+              title="在庫管理"
+              statusLabel="未申請"
+              statusTone="warning"
+              description="拠点別の在庫、入出庫、棚卸を管理します。"
+              metadata="zaiko.corp.example.jp"
+              disabledReason="この部門ではまだ利用申請が承認されていません。"
+              action={<Button disabled>サービスを開く</Button>}
+            />
+            <ServiceLauncherCard
+              icon={FileText}
+              titleLevel={3}
+              title="契約書管理"
+              statusLabel="権限なし"
+              statusTone="info"
+              description="契約書の保管、期限通知、電子署名の依頼を扱います。"
+              metadata="keiyaku.corp.example.jp"
+              disabledReason="閲覧には法務部門のロールが必要です。IT ヘルプデスクへ申請してください。"
+              action={<Button disabled>サービスを開く</Button>}
+            />
+            <ServiceLauncherCard
+              icon={Database}
+              titleLevel={3}
+              title="分析基盤"
+              statusLabel="停止中"
+              statusTone="destructive"
+              description="全社ダッシュボードとデータマートを提供します。"
+              metadata="bi.corp.example.jp"
+              disabledReason="このサービスは組織の管理者によって停止されています。"
+              action={<Button disabled>サービスを開く</Button>}
+            />
+          </ResponsiveGrid>
+        </Section>
+
+        <Section
+          title="4 · 読み込み中とカタログ導線"
+          why="ServiceLauncherCardSkeleton は同じ骨格の初期プレースホルダーで、label が必須・aria-busy を持ち、ライブリージョンは意図的に開きません。ServiceCatalogCta は実在する追加導線がある場合にだけ並べる相棒タイルで、既定の Plus 以外のグリフも受け取ります。"
+        >
+          <ResponsiveGrid columns={{ sm: 1, md: 2, lg: 3 }}>
+            <ServiceLauncherCardSkeleton label="サービスを読み込み中" />
+            <ServiceCatalogCta
+              title="アプリを追加"
+              action={<Button variant="outline">申請フォームを開く</Button>}
+            />
+            <ServiceCatalogCta
+              icon={LayoutGrid}
+              title="すべての社内アプリを見る"
+              action={<Button variant="ghost">一覧を開く</Button>}
+            />
+          </ResponsiveGrid>
+        </Section>
 
-        {/* Remaining status tones — the label text is always the consumer's own copy; the
-         * component maps only the tone to a semantic Badge. */}
-        <ResponsiveGrid columns={{ sm: 1, md: 2, lg: 3 }}>
-          <ServiceLauncherCard
-            icon={Database}
-            titleLevel={3}
-            title="データ連携基盤"
-            statusLabel="停止中"
-            statusTone="destructive"
-            description="外部システムとのデータ同期ジョブを管理します。"
-            metadata="sync.godx.jp · Enterprise"
-            disabledReason="このサービスは組織の管理者によって停止されています。"
-            action={<Button disabled>サービスを開く</Button>}
-          />
-          <ServiceLauncherCard
-            icon={PlugZap}
-            titleLevel={3}
-            title="連携アプリ"
-            statusLabel="準備中"
-            statusTone="neutral"
-            description="サードパーティ連携の接続とスコープを設定します。"
-            action={<Button variant="outline">設定を開く</Button>}
-          />
-          <ServiceLauncherCard
-            icon={BookPlus}
-            titleLevel={3}
-            title="ナレッジベース"
-            statusLabel="アーカイブ"
-            statusTone="muted"
-            description="社内ドキュメントと運用手順を保管します。"
-            metadata="kb.godx.jp · Free"
-            action={<Button variant="outline">アーカイブを見る</Button>}
-          />
-          {/* The companion CTA takes an explicit glyph when the default `Plus` is too generic. */}
-          <ServiceCatalogCta
-            icon={LayoutGrid}
-            title="すべてのサービスを見る"
-            action={<Button variant="ghost">カタログ一覧</Button>}
-          />
-        </ResponsiveGrid>
+        <Section
+          title="5 · 端に触れる · 3 行の名称、説明なし、切れない長いホスト名"
+          why="整った例はタイルが崩れる場所を何も見せません。ここは崩れる側です：3 行になる名称と 2 語の名称が同じ行に並び、説明のないタイルが説明のあるタイルの隣に置かれ、空白のないホスト名が列幅を広げようとします。見苦しく見えるなら、このセクションは仕事をしています — 耐えるのはサンプルデータではなくコンポーネントの側です。"
+        >
+          <ResponsiveGrid columns={{ sm: 1, md: 2, lg: 3 }}>
+            <ServiceLauncherCard
+              icon={ShieldCheck}
+              titleLevel={3}
+              title="グローバル人事情報基盤・従業員セルフサービスポータル（アジア太平洋地域）"
+              statusLabel="利用可能"
+              statusTone="success"
+              description="人事マスタ、勤怠、給与、評価を一元管理する統合ワークスペースです。"
+              metadata="workforce-identity-administration.ap-northeast-1.corp.example.jp · v11.0"
+              action={<Button>サービスを開く</Button>}
+            />
+            <ServiceLauncherCard
+              icon={Clock3}
+              titleLevel={3}
+              title="日報"
+              statusLabel="利用可能"
+              statusTone="success"
+              metadata="nippo.corp.example.jp"
+              action={<Button>サービスを開く</Button>}
+            />
+            <ServiceLauncherCard
+              icon={Server}
+              titleLevel={3}
+              title="Global Workforce Identity & Entitlement Administration Console"
+              statusLabel="Attention required"
+              statusTone="warning"
+              description="Review pending entitlement requests before the next access certification."
+              metadata="workforce-identity-administration.ap-southeast-1.corp.example.com"
+              disabledReason="Your organization has no approved request for this service yet."
+              action={<Button disabled>Open service</Button>}
+            />
+          </ResponsiveGrid>
+        </Section>
 
-        {/* Long JA / EN / VI names + an unbreakable hostname: the tile must wrap, never widen its
-         * grid column. Same 3 → 2 → 1 grid, no page-local CSS anywhere. */}
-        <ResponsiveGrid columns={{ sm: 1, md: 2, lg: 3 }}>
-          <ServiceLauncherCard
-            icon={ShieldCheck}
-            titleLevel={3}
-            title="グローバル人事情報基盤・従業員セルフサービスポータル（アジア太平洋地域）"
-            statusLabel="LIVE"
-            statusTone="success"
-            description="人事マスタ、勤怠、給与、評価を一元管理する統合ワークスペースです。"
-            metadata="workforce-identity-administration.ap-northeast-1.godx.jp · Enterprise"
-            action={<Button>サービスを開く</Button>}
-          />
-          <ServiceLauncherCard
-            icon={ShieldCheck}
-            titleLevel={3}
-            title="Acme Global Workforce Identity & Entitlement Administration Console"
-            statusLabel="Attention required"
-            statusTone="warning"
-            description="Review pending entitlement requests before the next access certification."
-            metadata="workforce-identity-administration.ap-northeast-1.godx.jp · Enterprise"
-            disabledReason="Your organization has no active subscription for this service yet."
-            action={<Button disabled>Open service</Button>}
-          />
-          <ServiceLauncherCard
-            icon={ShieldCheck}
-            titleLevel={3}
-            title="Cổng quản trị định danh và phân quyền nhân sự toàn cầu của doanh nghiệp"
-            statusLabel="Chỉ quản trị viên"
-            statusTone="info"
-            description="Xem lại quyền truy cập, chính sách xác thực hai yếu tố và nhật ký kiểm toán."
-            metadata="workforce-identity-administration.ap-southeast-1.godx.jp · Enterprise"
-            action={<Button variant="outline">Xem quyền truy cập</Button>}
-          />
-        </ResponsiveGrid>
+        <Section
+          title="6 · 最小のタイル"
+          why="必須は icon・title・action の 3 つだけです。statusLabel を省けば Badge の行ごと消え、description と metadata を省いても骨格は保たれます — 隣の満載のタイルと高さを比べてください。"
+        >
+          <ResponsiveGrid columns={{ sm: 1, md: 2, lg: 3 }}>
+            <ServiceLauncherCard
+              icon={BookOpen}
+              titleLevel={3}
+              title="社内 Wiki"
+              action={<Button variant="outline">開く</Button>}
+            />
+            <ServiceLauncherCard
+              icon={Mail}
+              titleLevel={3}
+              title="問い合わせ窓口"
+              description="社内のシステム相談はこちらで受け付けています。"
+              action={<Button variant="outline">開く</Button>}
+            />
+            <ServiceLauncherCard
+              icon={Calendar}
+              titleLevel={3}
+              title="全社カレンダー"
+              statusLabel="利用可能"
+              statusTone="success"
+              description="全社行事、休業日、拠点別の予定を共有します。"
+              metadata="calendar.corp.example.jp · v3.1"
+              disabledReason="読み取り専用で公開されています。"
+              action={<Button variant="outline">開く</Button>}
+            />
+          </ResponsiveGrid>
+        </Section>
       </Flex>
     </PageContainer>
   );

package/docs/foundation/_theme-editor-scope.ts

@@ -0,0 +1,222 @@
+/**
+ * What the Theme Editor page needs that is NOT React: the repo's own brand derivation, the two
+ * stylesheet facts it takes as arguments, and the ONE style object that makes a previewed seed
+ * actually reach the components under it.
+ *
+ * `deriveBrand` is `scripts/gen-brand.mjs`'s body (src/tokens/__tests__/brand-derivation.ts).
+ * Importing it — rather than porting it — is why the page's export and `pnpm gen:brand` emit the
+ * same bytes for the same hex. `wcag-contrast.ts`'s own opening line says why there is one copy of
+ * the luminance formula; this is the same argument one level up.
+ */
+import type { CSSProperties } from "react";
+
+import {
+  asTriplet,
+  deriveBrand,
+  triplet,
+  type BrandChannels,
+  type BrandTheme,
+  type Hsl,
+} from "../../src/tokens/__tests__/brand-derivation";
+
+export {
+  AA_TEXT,
+  NON_TEXT,
+  asTriplet,
+  contrast,
+  deriveBrand,
+  hslToRgb,
+  parseHex,
+  toHex,
+  toHsl,
+  round,
+} from "../../src/tokens/__tests__/brand-derivation";
+export type {
+  Brand,
+  BrandChannels,
+  BrandTheme,
+  ContrastRow,
+  Hsl,
+} from "../../src/tokens/__tests__/brand-derivation";
+
+/* ── what the stylesheet says, asked of the browser rather than copied here ─────────────────── */
+
+/**
+ * `gen:brand` reads `--background` and the three `-channels` expressions out of `foundation.css`
+ * and `derived.css` with `node:fs`. A page has no filesystem, and a literal copied into this file
+ * would be a third place the canvas colour lives — stale the first time someone retunes the spine.
+ * So the page asks the DOCUMENT, which is the same declarations after the same cascade.
+ *
+ * The CANVASES come from the CSSOM rather than `getComputedStyle`, because the page needs BOTH at
+ * once and an element can only be in one theme at a time: read live, a page rendered under
+ * `data-theme="dark"` would report the dark canvas as the light one and the whole dark-seed search
+ * would target the wrong number, silently. The CSSOM carries both declarations side by side no
+ * matter which theme is on screen.
+ *
+ * The CHANNELS are the opposite case: `--primary-hover-darken-channels` and its three siblings are
+ * declared once at `:root` and never re-scoped (`.dark` only repoints `--primary-hover-channels`
+ * AT one of them), so a computed read is correct under any theme and is one line instead of a walk.
+ */
+export type ThemeSpine = { lightCanvas: Hsl; darkCanvas: Hsl; channels: BrandChannels };
+
+/** Every style rule in the document, walking into `@layer` / `@media` / `@supports` and nesting. */
+function* styleRules(rules: CSSRuleList): Generator<CSSStyleRule> {
+  for (const rule of Array.from(rules)) {
+    if ("selectorText" in rule) yield rule as CSSStyleRule;
+    const nested = (rule as CSSGroupingRule).cssRules;
+    if (nested) yield* styleRules(nested);
+  }
+}
+
+/** The LAST `--background` declared by a rule this selector test accepts — cascade order. */
+function canvasFrom(accepts: (selector: string) => boolean): Hsl | null {
+  let found: Hsl | null = null;
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules: CSSRuleList;
+    try {
+      rules = sheet.cssRules;
+    } catch {
+      /* A cross-origin sheet refuses `cssRules`. Ours are same-origin; skip anything else. */
+      continue;
+    }
+    for (const rule of styleRules(rules)) {
+      if (!accepts(rule.selectorText)) continue;
+      const value = rule.style.getPropertyValue("--background").trim();
+      if (!value) continue;
+      try {
+        found = triplet(value);
+      } catch {
+        /* Not a plain `H S% L%` triple — not a canvas this derivation can use. */
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * The probe fallback, for the one case the CSSOM cannot answer: a sheet the document can paint from
+ * but not read. It costs a layout, so it only runs when the walk came back empty.
+ */
+function canvasByProbe(dark: boolean): Hsl | null {
+  const probe = document.createElement("div");
+  if (dark) probe.className = "dark";
+  document.body.append(probe);
+  try {
+    const value = getComputedStyle(probe).getPropertyValue("--background").trim();
+    return value ? triplet(value) : null;
+  } catch {
+    return null;
+  } finally {
+    probe.remove();
+  }
+}
+
+const channel = (name: string) =>
+  getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+
+/** The spine this document is actually painting, or `null` when it cannot be read at all. */
+export function readThemeSpine(): ThemeSpine | null {
+  const lightCanvas = canvasFrom((s) => s.trim() === ":root") ?? canvasByProbe(false);
+  const darkCanvas = canvasFrom((s) => /\[data-theme=["']?dark/.test(s)) ?? canvasByProbe(true);
+  const channels: BrandChannels = {
+    hoverDarken: channel("--primary-hover-darken-channels"),
+    activeDarken: channel("--primary-active-darken-channels"),
+    hoverLighten: channel("--primary-hover-lighten-channels"),
+  };
+  if (!lightCanvas || !darkCanvas) return null;
+  if (!channels.hoverDarken || !channels.activeDarken || !channels.hoverLighten) return null;
+  return { lightCanvas, darkCanvas, channels };
+}
+
+/* ── the scope a preview pane declares ──────────────────────────────────────────────────────── */
+
+/**
+ * THE THREE TOKENS `gen:brand` EMITS ARE THE THREE A SCOPE MUST DECLARE, and that is not a
+ * coincidence — it is the freeze rule (docs/TOKENS.md) read from the other end.
+ *
+ * `--primary` and `--primary-foreground` are ordinary roles: declare them on the pane and every
+ * descendant paints from them, including `--primary-hover` and `--text-link`, which are `initial`
+ * knobs whose defaults re-resolve at the element that paints (gh#678, gh#664). Writing THOSE here
+ * is the drift `gen:brand` refuses to emit, so this does not write them either.
+ *
+ * `--ring` is the one that bites. `derived.css` declares `--ring: var(--primary)` — and a `var()`
+ * substitutes where it is DECLARED, so at `:root` it computed against the package's own seed and
+ * inherits that frozen answer into every subtree. The dark pane escapes by accident (it carries
+ * `.dark`, and `derived.css` re-declares `--ring: var(--primary)` in that block too, which
+ * re-substitutes on the pane); the LIGHT pane does not, and a focus ring in the old brand colour
+ * on a re-themed button is exactly the defect. `derived.css` says so in as many words: "a
+ * `--primary` scoped BELOW `<html>` does not reach `--ring` … a nested scope sets `--ring`
+ * itself". So both panes set it, which is also what a consumer's `:root` gets from `gen:brand`.
+ *
+ * The `-channels` PAIR is written only when the seed's label runs against the theme's default,
+ * because that is the one thing CSS cannot infer: the label decides which way a state steps, and
+ * only the author knows the label. It is a role-mirror, so it is written as `var(--…-channels)`
+ * and never as a resolved literal.
+ */
+export function previewScope(theme: BrandTheme): CSSProperties {
+  const scope: Record<string, string> = {
+    "--primary": asTriplet(theme.seed),
+    "--primary-foreground": asTriplet(theme.label),
+    "--ring": asTriplet(theme.seed),
+  };
+  if (theme.repointsChannels) {
+    scope["--primary-hover-channels"] = `var(--primary-hover-${theme.polarity}-channels)`;
+    scope["--primary-active-channels"] = `var(--primary-active-${theme.polarity}-channels)`;
+  }
+  return scope as CSSProperties;
+}
+
+/* ── the seeds a demo must not avoid ────────────────────────────────────────────────────────── */
+
+/**
+ * AN EDITOR THAT ONLY DEMOS A NICE BLUE PROVES NOTHING. Each of these is here because it produces
+ * an answer the happy path hides; `hex` is the only input, everything else is measured.
+ */
+export type SeedPreset = {
+  id: "godx" | "blue" | "very-light" | "very-dark" | "sunflower";
+  hex: string;
+};
+
+export const SEED_PRESETS: SeedPreset[] = [
+  /* The package's own `--primary`: the export must reproduce foundation.css's light block. */
+  { id: "godx", hex: "#7A00FF" },
+  /* An ordinary, well-behaved brand — every row clears, so a passing readout is visible too. */
+  { id: "blue", hex: "#2563EB" },
+  /* Near-white: the label flips to black and the fill cannot clear 3:1 on a near-white canvas. */
+  { id: "very-light", hex: "#FFF9C4" },
+  /* Near-black: the dark-seed search runs all the way to pure white to hold parity. */
+  { id: "very-dark", hex: "#0B0B14" },
+  /* A dark label in light and a light label in dark — the seed that repoints the `-channels`
+   * pair in BOTH theme blocks, which nothing else here exercises. */
+  { id: "sunflower", hex: "#F5D60A" },
+];
+
+/** One place that knows how a hex becomes a brand, so the page never calls `deriveBrand` twice. */
+export function brandFor(
+  spine: ThemeSpine,
+  hex: string,
+  name: string,
+  foreground: string | null,
+  darkLightness: number | null,
+) {
+  return deriveBrand({ hex, name, foreground, darkLightness, ...spine });
+}
+
+/**
+ * THE COMMAND THAT REPRODUCES THIS EXPORT, or `null` when nothing does.
+ *
+ * The seed and the forced label are both `gen:brand` flags, so those exports are byte-identical to
+ * what the CLI writes and the page can say which command to run. An AUTHORED dark lightness is
+ * not: the generator searches for parity and has no flag to override it, so the page has to stop
+ * claiming agreement rather than print a command that emits something else.
+ */
+export function genBrandCommand(
+  hex: string,
+  name: string,
+  foreground: string | null,
+  darkLightnessOverridden: boolean,
+): string | null {
+  if (darkLightnessOverridden) return null;
+  const flags = foreground ? ` --foreground '${foreground}'` : "";
+  return `pnpm gen:brand '${hex}' --name ${name}${flags}`;
+}