@godxjp/ui 19.1.0 → 19.2.0

package/docs/foundation/_email-specimen.ts

@@ -0,0 +1,274 @@
+/**
+ * A complete transactional-email document, built ONLY from `@godxjp/ui/email`.
+ *
+ * This is the reference implementation the `foundation/email-tokens` page renders in an iframe and
+ * that a Blade / Twig / MJML author copies: table layout, literal inline styles, an embedded brand
+ * mark, a bulletproof CTA and a legal footer — with every colour, size and radius read from the
+ * token export instead of typed by hand. The copy is deliberate placeholder text; product wording,
+ * recipients, links and locale belong to the sending application.
+ */
+import {
+  EMAIL_BRAND_MARK,
+  EMAIL_COLORS,
+  EMAIL_COLORS_DARK,
+  EMAIL_CTA,
+  EMAIL_FOCUS,
+  EMAIL_FOOTER,
+  EMAIL_MOBILE,
+  EMAIL_SHELL,
+  EMAIL_TYPOGRAPHY,
+  emailBrandMarkSvg,
+  emailInlineStyle,
+} from "@godxjp/ui/email";
+
+const c = EMAIL_COLORS;
+
+/** A vertical spacer row — the only rhythm device every client honours. */
+const spacer = (height: number) =>
+  `<div style="${emailInlineStyle({ height: `${height}px`, lineHeight: `${height}px`, fontSize: 0 })}">&#8203;</div>`;
+
+/**
+ * The `<style>` block: progressive enhancement ONLY. Every rule here has a literal inline
+ * equivalent, so a client that strips `<style>` (Gmail on mobile web, most desktop clients) still
+ * renders the desktop layout correctly — it simply does not reflow.
+ */
+const progressiveStyles = `
+  @media (max-width: ${EMAIL_MOBILE.maxWidth}) {
+    .email-page { padding: ${EMAIL_MOBILE.pagePadding} !important; }
+    .email-card { width: ${EMAIL_MOBILE.width} !important; }
+    .email-body { padding: ${EMAIL_MOBILE.padding} !important; }
+    .email-heading { font-size: ${EMAIL_MOBILE.headingFontSize} !important; }
+    .email-cta, .email-cta-link { width: ${EMAIL_MOBILE.ctaWidth} !important; }
+  }
+  @media (prefers-color-scheme: dark) {
+    .email-page { background-color: ${EMAIL_COLORS_DARK.background} !important; }
+    .email-card { background-color: ${EMAIL_COLORS_DARK.surface} !important;
+                  border-color: ${EMAIL_COLORS_DARK.border} !important; }
+    .email-body, .email-heading { color: ${EMAIL_COLORS_DARK.foreground} !important; }
+    .email-footer, .email-footer a { color: ${EMAIL_COLORS_DARK.mutedForeground} !important; }
+  }
+  a:focus-visible {
+    outline: ${EMAIL_FOCUS.borderWidth} solid ${c.focus};
+    outline-offset: 2px;
+  }
+`;
+
+export interface EmailSpecimenCopy {
+  wordmark: string;
+  heading: string;
+  lede: string;
+  /** Reference strings — ids, masked numbers, ISO dates. Set in the mono face. */
+  reference: string[];
+  cta: string;
+  legal: string;
+  links: string[];
+}
+
+export const EMAIL_SPECIMEN_COPY: EmailSpecimenCopy = {
+  wordmark: "GoDX",
+  heading: "Heading placeholder",
+  lede: `One or two calm sentences of placeholder body copy, long enough to wrap and show the ${EMAIL_TYPOGRAPHY.bodyLineHeight} line height inside the 416px content column.`,
+  cta: "Primary action",
+  reference: ["Reference: ref_0000", "Date: 2026-01-01"],
+  legal: "Placeholder legal line. This address is not monitored.",
+  links: ["Help", "Privacy", "Unsubscribe"],
+};
+
+/** Build the full email document. */
+export function buildEmailSpecimenHtml(copy: EmailSpecimenCopy = EMAIL_SPECIMEN_COPY): string {
+  // In a header the mark is DECORATIVE: the wordmark beside it carries the accessible name, so the
+  // brand is announced once rather than twice.
+  const mark = emailBrandMarkSvg({ label: "" });
+
+  // The canonical header is a LOCKUP, not a bare mark. Email clients have no flexbox, so the row is
+  // a presentational table and the mark-to-wordmark gap is a spacer cell.
+  // ui-audit-disable-next-line no-raw-table
+  const lockup = `<table role="presentation" border="0" cellpadding="0" cellspacing="0" style="${emailInlineStyle(
+    { borderCollapse: "collapse" },
+  )}"><tr>
+              <td valign="middle" style="${emailInlineStyle({
+                fontSize: 0,
+                lineHeight: 0,
+                // The next line closes a JS template-literal interpolation, not a hand-formatted
+                // price, so the currency rule is a false positive here.
+                // ui-audit-disable-next-line hardcoded-currency
+              })}">${mark}</td>
+              <td style="${emailInlineStyle({ width: EMAIL_BRAND_MARK.gap, fontSize: 0, lineHeight: 0 })}">&#8203;</td>
+              <td valign="middle" style="${emailInlineStyle({
+                fontFamily: EMAIL_TYPOGRAPHY.fontFamily,
+                fontSize: EMAIL_BRAND_MARK.wordmarkFontSize,
+                fontWeight: EMAIL_BRAND_MARK.wordmarkFontWeight,
+                lineHeight: 1,
+                color: c.foreground,
+                // The next line closes a JS template-literal interpolation, not a hand-formatted
+                // price, so the currency rule is a false positive here.
+                // ui-audit-disable-next-line hardcoded-currency
+              })}">${copy.wordmark}</td>
+            </tr></table>`;
+
+  const reference = copy.reference.join("<br>");
+
+  const footerLinks = copy.links
+    .map(
+      (label, index) =>
+        (index === 0
+          ? ""
+          : `<span style="${emailInlineStyle({ display: "inline-block", width: EMAIL_FOOTER.linkGap })}">&#8203;</span>`) +
+        `<a href="#" style="${emailInlineStyle({
+          color: c.mutedForeground,
+          textDecoration: "underline",
+          // The next line closes a JS template-literal interpolation, it is not a hand-formatted
+          // price, so the currency rule is a false positive here.
+          // ui-audit-disable-next-line hardcoded-currency
+        })}">${label}</a>`,
+    )
+    .join("");
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light dark">
+<title>Transactional email specimen</title>
+<style>
+${progressiveStyles}
+</style>
+</head>
+<body style="${emailInlineStyle({ margin: 0, padding: 0, backgroundColor: c.background })}">
+<!-- Page canvas. Email clients support neither flex nor grid, so every band of the document is a
+     presentational table. ui-audit-disable-next-line no-raw-table -->
+<table role="presentation" border="0" cellpadding="0" cellspacing="0" width="100%" style="${emailInlineStyle(
+    { borderCollapse: "collapse", backgroundColor: c.background },
+  )}">
+  <tr>
+    <td class="email-page" align="center" style="${emailInlineStyle({
+      padding: EMAIL_SHELL.pagePadding,
+      backgroundColor: c.background,
+    })}">
+      <!-- Card shell. A fixed-width presentational table is the only container that centres
+           reliably in Outlook. ui-audit-disable-next-line no-raw-table -->
+      <table role="presentation" border="0" cellpadding="0" cellspacing="0" width="${EMAIL_SHELL.widthPx}" class="email-card" style="${emailInlineStyle(
+        {
+          width: EMAIL_SHELL.width,
+          maxWidth: "100%",
+          borderCollapse: "separate",
+          backgroundColor: c.surface,
+          border: `${EMAIL_SHELL.borderWidth} solid ${c.border}`,
+          borderRadius: EMAIL_SHELL.radius,
+        },
+      )}">
+        <tr>
+          <td class="email-body" style="${emailInlineStyle({
+            padding: EMAIL_SHELL.padding,
+            fontFamily: EMAIL_TYPOGRAPHY.fontFamily,
+            fontSize: EMAIL_TYPOGRAPHY.bodyFontSize,
+            lineHeight: EMAIL_TYPOGRAPHY.bodyLineHeight,
+            fontWeight: EMAIL_TYPOGRAPHY.bodyFontWeight,
+            color: c.foreground,
+          })}">
+            ${lockup}
+            ${spacer(EMAIL_SHELL.gapPx)}
+            <h1 class="email-heading" style="${emailInlineStyle({
+              margin: 0,
+              fontFamily: EMAIL_TYPOGRAPHY.fontFamily,
+              fontSize: EMAIL_TYPOGRAPHY.headingFontSize,
+              lineHeight: EMAIL_TYPOGRAPHY.headingLineHeight,
+              fontWeight: EMAIL_TYPOGRAPHY.headingFontWeight,
+              color: c.foreground,
+              // The next line closes a JS template-literal interpolation, not a hand-formatted
+              // price, so the currency rule is a false positive here.
+              // ui-audit-disable-next-line hardcoded-currency
+            })}">${copy.heading}</h1>
+            ${spacer(EMAIL_SHELL.gapSmPx)}
+            <p style="${emailInlineStyle({
+              margin: 0,
+              fontSize: EMAIL_TYPOGRAPHY.bodyFontSize,
+              lineHeight: EMAIL_TYPOGRAPHY.bodyLineHeight,
+              color: c.foreground,
+              // The next line closes a JS template-literal interpolation, not a hand-formatted
+              // price, so the currency rule is a false positive here.
+              // ui-audit-disable-next-line hardcoded-currency
+            })}">${copy.lede}</p>
+            ${spacer(EMAIL_SHELL.gapSmPx)}
+            <!-- Reference block. Ids, masked numbers and ISO dates are set in the mono face so the
+                 figures align and cannot be misread. -->
+            <p style="${emailInlineStyle({
+              margin: 0,
+              fontFamily: EMAIL_TYPOGRAPHY.monoFontFamily,
+              fontSize: EMAIL_FOOTER.fontSize,
+              lineHeight: EMAIL_TYPOGRAPHY.bodyLineHeight,
+              color: c.mutedForeground,
+              // The next line closes a JS template-literal interpolation, not a hand-formatted
+              // price, so the currency rule is a false positive here.
+              // ui-audit-disable-next-line hardcoded-currency
+            })}">${reference}</p>
+            ${spacer(EMAIL_SHELL.gapPx)}
+            <!-- Bulletproof CTA. The button is a padded table cell so Outlook paints the fill and
+                 the radius. ui-audit-disable-next-line no-raw-table -->
+            <table role="presentation" border="0" cellpadding="0" cellspacing="0" style="${emailInlineStyle(
+              { borderCollapse: "separate" },
+            )}">
+              <tr>
+                <td class="email-cta" align="center" valign="middle" height="${EMAIL_CTA.heightPx}" style="${emailInlineStyle(
+                  {
+                    height: EMAIL_CTA.height,
+                    borderRadius: EMAIL_CTA.radius,
+                    backgroundColor: c.primary,
+                  },
+                )}">
+                  <a class="email-cta-link" href="#" style="${emailInlineStyle({
+                    display: "inline-block",
+                    padding: `0 ${EMAIL_CTA.paddingX}`,
+                    height: EMAIL_CTA.height,
+                    lineHeight: EMAIL_CTA.lineHeight,
+                    fontFamily: EMAIL_TYPOGRAPHY.fontFamily,
+                    fontSize: EMAIL_CTA.fontSize,
+                    fontWeight: EMAIL_CTA.fontWeight,
+                    color: c.primaryForeground,
+                    textDecoration: "none",
+                    // The next line closes a JS template-literal interpolation, not a
+                    // hand-formatted price, so the currency rule is a false positive here.
+                    // ui-audit-disable-next-line hardcoded-currency
+                  })}">${copy.cta}</a>
+                </td>
+              </tr>
+            </table>
+            ${spacer(EMAIL_SHELL.gapPx)}
+            <!-- Legal footer rail. A full-width presentational table keeps the hairline and the
+                 inset stable in clients that drop CSS borders. ui-audit-disable-next-line no-raw-table -->
+            <table role="presentation" border="0" cellpadding="0" cellspacing="0" width="100%">
+              <tr>
+                <td class="email-footer" style="${emailInlineStyle({
+                  borderTop: `${EMAIL_FOOTER.borderWidth} solid ${c.border}`,
+                  paddingTop: EMAIL_FOOTER.paddingTop,
+                  fontFamily: EMAIL_TYPOGRAPHY.fontFamily,
+                  fontSize: EMAIL_FOOTER.fontSize,
+                  lineHeight: EMAIL_FOOTER.lineHeight,
+                  color: c.mutedForeground,
+                })}">
+                  <p style="${emailInlineStyle({
+                    margin: 0,
+                    // The next line closes a JS template-literal interpolation, not a
+                    // hand-formatted price, so the currency rule is a false positive here.
+                    // ui-audit-disable-next-line hardcoded-currency
+                  })}">${copy.legal}</p>
+                  ${spacer(EMAIL_SHELL.gapSmPx)}
+                  <p style="${emailInlineStyle({
+                    margin: 0,
+                    // The next line closes a JS template-literal interpolation, not a
+                    // hand-formatted price, so the currency rule is a false positive here.
+                    // ui-audit-disable-next-line hardcoded-currency
+                  })}">${footerLinks}</p>
+                </td>
+              </tr>
+            </table>
+          </td>
+        </tr>
+      </table>
+    </td>
+  </tr>
+</table>
+</body>
+</html>`;
+}

package/docs/foundation/colors.tsx

@@ -0,0 +1,202 @@
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
+import { Text } from "@godxjp/ui/general";
+import { Flex, PageContainer, ResponsiveGrid } from "@godxjp/ui/layout";
+
+/**
+ * Colors · design-token foundation. Every swatch is a real semantic Tailwind
+ * utility wired to the reference-design token (@theme in src/styles/index.css); no raw
+ * hex, no raw palette. Composed only from real @godxjp/ui components.
+ */
+const surfaces = [
+  { cls: "bg-background text-foreground", token: "--background", role: "page" },
+  { cls: "bg-card text-card-foreground", token: "--card", role: "raised surface" },
+  { cls: "bg-popover text-popover-foreground", token: "--popover", role: "overlay surface" },
+  { cls: "bg-secondary text-secondary-foreground", token: "--secondary", role: "muted fill" },
+  { cls: "bg-muted text-muted-foreground", token: "--muted", role: "muted" },
+  { cls: "bg-accent text-accent-foreground", token: "--accent", role: "hover" },
+];
+
+// Structural neutrals · hairlines, field borders, focus ring. Shown as fills so
+// the named token is visible (in practice they paint borders/outlines, not areas).
+const structural = [
+  { cls: "bg-border", token: "--border", role: "hairline / divider" },
+  { cls: "bg-input", token: "--input", role: "field border" },
+  { cls: "bg-ring", token: "--ring", role: "focus ring" },
+];
+
+const status = [
+  { cls: "bg-primary text-primary-foreground", token: "--primary", role: "brand action" },
+  { cls: "bg-success text-success-foreground", token: "--success", role: "若竹 success" },
+  { cls: "bg-warning text-warning-foreground", token: "--warning", role: "山吹 warning" },
+  { cls: "bg-info text-info-foreground", token: "--info", role: "群青 info" },
+  { cls: "bg-attention text-attention-foreground", token: "--attention", role: "朱 attention" },
+  { cls: "bg-destructive text-destructive-foreground", token: "--destructive", role: "茜 danger" },
+];
+
+const waIro = [
+  { cls: "bg-wa-ai", token: "--wa-ai", role: "藍 indigo" },
+  { cls: "bg-wa-gunjo", token: "--wa-gunjo", role: "群青 ultramarine" },
+  { cls: "bg-wa-ruri", token: "--wa-ruri", role: "瑠璃 lapis" },
+  { cls: "bg-wa-kon", token: "--wa-kon", role: "紺 navy" },
+  { cls: "bg-wa-wakatake", token: "--wa-wakatake", role: "若竹 young bamboo" },
+  { cls: "bg-wa-moegi", token: "--wa-moegi", role: "萌葱 spring green" },
+  { cls: "bg-wa-yamabuki", token: "--wa-yamabuki", role: "山吹 mountain yellow" },
+  { cls: "bg-wa-shu", token: "--wa-shu", role: "朱 vermilion" },
+  { cls: "bg-wa-akane", token: "--wa-akane", role: "茜 madder" },
+  { cls: "bg-wa-enji", token: "--wa-enji", role: "臙脂 cochineal" },
+  { cls: "bg-wa-sakura", token: "--wa-sakura", role: "桜 cherry (soft bg)" },
+  { cls: "bg-wa-sumi", token: "--wa-sumi", role: "墨 ink" },
+  { cls: "bg-wa-nezu", token: "--wa-nezu", role: "鼠 mouse grey" },
+];
+
+// Chart accents · neutral decorative primitives for series colour, NOT business
+// semantics. Wired to --color-chart-1…6 (bg-chart-N utilities).
+const charts = [
+  { cls: "bg-chart-1", token: "--chart-1", role: "series 1" },
+  { cls: "bg-chart-2", token: "--chart-2", role: "series 2" },
+  { cls: "bg-chart-3", token: "--chart-3", role: "series 3" },
+  { cls: "bg-chart-4", token: "--chart-4", role: "series 4" },
+  { cls: "bg-chart-5", token: "--chart-5", role: "series 5" },
+  { cls: "bg-chart-6", token: "--chart-6", role: "series 6" },
+];
+
+type Swatch = { cls: string; token: string; role: string };
+
+/** One swatch tile: a token-coloured box (with foreground text when paired) + its token name + role. */
+function SwatchTile({ swatch, text }: { swatch: Swatch; text?: boolean }) {
+  return (
+    <Flex direction="col" gap="xs">
+      <div className={`border-border flex h-14 items-end rounded-md border p-2 ${swatch.cls}`}>
+        {text ? (
+          <Text size="xs" mono className="leading-none">
+            Aa 亜
+          </Text>
+        ) : null}
+      </div>
+      <div>
+        <Text as="div" size="xs" mono>
+          {swatch.token}
+        </Text>
+        <Text as="div" size="xs" tone="muted">
+          {swatch.role}
+        </Text>
+      </div>
+    </Flex>
+  );
+}
+
+/**
+ * A token group rendered TWICE · light theme then a `.dark`-scoped copy · so a
+ * single static screenshot proves both renditions defined in foundation.css.
+ * Themed groups (`dark`) re-paint under the `.dark` wrapper; decorative groups
+ * (wa-iro, chart) are theme-invariant and render once.
+ */
+function SwatchGroup({ items, text, dark }: { items: Swatch[]; text?: boolean; dark?: boolean }) {
+  const grid = (
+    <ResponsiveGrid columns={{ sm: 2, md: 3, lg: 4 }}>
+      {items.map((s) => (
+        <SwatchTile key={s.token} swatch={s} text={text} />
+      ))}
+    </ResponsiveGrid>
+  );
+  if (!dark) return grid;
+  return (
+    <Flex direction="col" gap="md">
+      <div>
+        <Text as="div" size="xs" tone="muted" weight="medium" className="mb-2">
+          Light
+        </Text>
+        {grid}
+      </div>
+      <div className="bg-background text-foreground dark rounded-md p-3">
+        <Text as="div" size="xs" tone="muted" weight="medium" className="mb-2">
+          Dark (.dark)
+        </Text>
+        <ResponsiveGrid columns={{ sm: 2, md: 3, lg: 4 }}>
+          {items.map((s) => (
+            <SwatchTile key={s.token} swatch={s} text={text} />
+          ))}
+        </ResponsiveGrid>
+      </div>
+    </Flex>
+  );
+}
+
+export default function Demo() {
+  return (
+    <PageContainer
+      title="Colors"
+      subtitle="Semantic roles + 和色 (wa-iro) · OKLCH, 渋み (chroma ≤ 0.18)"
+    >
+      <Flex direction="col" gap="lg">
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Semantic surfaces</CardTitle>
+            <CardDescription>
+              Page / raised / overlay / muted neutrals. Use these; never invent a new grey. Each box
+              shows its own foreground text token. Every role is redefined under .dark.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <SwatchGroup items={surfaces} text dark />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Structural neutrals</CardTitle>
+            <CardDescription>
+              Hairlines, field borders, focus ring. In practice these paint borders and outlines,
+              not areas. They are shown as fills here so the named token is visible. Also themed
+              under .dark.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <SwatchGroup items={structural} dark />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Brand & status</CardTitle>
+            <CardDescription>
+              Fixed semantic mapping: never substitute. primary = the single most important action;
+              status is success / warning / info / attention / danger. Lifted for contrast under
+              .dark.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <SwatchGroup items={status} text dark />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>和色 wa-iro · decorative only</CardTitle>
+            <CardDescription>
+              Traditional Japanese accents for charts / tags / tenant theming. NEVER map a wa-iro
+              hue to a semantic role beyond the five canonical ones above. Fixed hex ·
+              theme-invariant.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <SwatchGroup items={waIro} />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Chart accents</CardTitle>
+            <CardDescription>
+              Series colours for data visualisation: neutral decorative primitives, NOT business
+              semantics. Use bg-chart-1…6 in order; theme-invariant like wa-iro.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <SwatchGroup items={charts} />
+          </CardContent>
+        </Card>
+      </Flex>
+    </PageContainer>
+  );
+}