react-native-terra-ui 0.7.2 → 0.8.1

package/src/theme/tokens/light.ts

@@ -1,105 +1,100 @@
 /**
- * Light-scheme color tokens — flat, dotted-key data (no imports, no types).
- *
- * Convention: [category].[context].[property?].[variant].[state]
- *   - property is omitted when the context implies it (surface → bg, text → fg, border → border-color)
- *   - property is required when a context carries multiple attributes (action, status)
- *
- * Values use {palette.key} reference notation, resolved against primitives at
- * build time via resolveRefs() in theme.ts. {palette.key}/NN resolves the
- * referenced #rrggbb hex with an NN% opacity byte appended (e.g.
- * {palette.amber.500}/15 -> '#fe9a0026'). Raw hex is used only where no
- * palette step matches exactly.
- *
- * GENERATED-STYLE SOURCE: intended to be replaced by the Figma / design-sync export.
+ * Light semantic colors. See docs/design-tokens.md for naming and references.
+ * Generated-style source; naming and contrast updates await the next design-sync export.
  */
 export const light = {
-  // ── color: page background ────────────────────────────────────────────────
-  "color.background": "#fbfbfb",
-
-  // ── color: shadow (used as elevation.*.shadowColor) ───────────────────────
-  "color.shadow": "#1b1b1b",
-
-  // ── color: surfaces  (bg implied — no property segment) ──────────────────
+  // Surfaces
+  "color.surface.canvas": "#fbfbfb",
   "color.surface.default": "{palette.white}",
   "color.surface.raised": "{palette.white}",
   "color.surface.sunken": "#ececee",
-  "color.surface.overlay": "rgba(9, 9, 11, 0.48)",
-  "color.surface.accent": "{palette.emerald.600}",
-  "color.surface.accent.subtle": "{palette.emerald.100}",
-
-  // ── color: text / icons  (fg implied — no property segment) ──────────────
-  "color.text.default": "{palette.neutral.950}",
-  "color.text.muted": "#4b5060",
-  "color.text.subtle": "#6b7280",
+
+  // Text
+  "color.text.primary": "{palette.neutral.950}",
+  "color.text.secondary": "#4b5060",
+  "color.text.tertiary": "#626978",
   "color.text.disabled": "#9ca3af",
   "color.text.inverse": "{palette.white}",
-  "color.text.link": "{palette.blue.600}",
-  "color.text.accent": "{palette.emerald.600}",
-  "color.text.on-accent": "{palette.white}",
-  "color.text.on-accent-subtle": "{palette.emerald.700}",
+  "color.text.link": "{palette.blue.700}",
 
-  // ── color: borders  (border-color implied — no property segment) ──────────
+  // Borders and focus
   "color.border.subtle": "#ebebed",
   "color.border.default": "{palette.neutral.200}",
-  "color.border.strong": "#d1d5db",
-  "color.border.focus": "{palette.blue.500}",
-  "color.border.accent": "{palette.emerald.600}",
-
-  // ── color: interactive actions  (bg + fg → property required) ────────────
-  "color.action.bg.primary": "{palette.emerald.600}",
-  "color.action.bg.primary.hover": "{palette.emerald.700}",
-  "color.action.bg.primary.active": "{palette.emerald.800}",
-  "color.action.bg.primary.disabled": "{palette.slate.200}",
-  "color.action.fg.primary": "{palette.white}",
-
-  "color.action.bg.primary.subtle": "{palette.emerald.100}",
-  "color.action.bg.primary.subtle.hover": "{palette.emerald.200}",
-  "color.action.bg.primary.subtle.active": "{palette.emerald.300}",
-  "color.action.bg.primary.subtle.disabled": "{palette.slate.100}",
-  "color.action.fg.primary.subtle": "{palette.emerald.700}",
-
-  // `secondary`'s resting fill/text — used by Avatar/Chip's `secondary` color
-  // and Button/Toast's neutral-emphasis look; sized for real separation
-  // against `color.background` (#f9f9fb), not just a tint.
-  "color.action.bg.secondary": "{palette.neutral.200}",
-  "color.action.fg.secondary": "{palette.neutral.900}",
-  "color.action.bg.secondary.subtle": "{palette.neutral.400}/15",
-  "color.action.bg.secondary.subtle.hover": "{palette.neutral.400}/25",
-  "color.action.bg.secondary.subtle.active": "{palette.neutral.400}/35",
-  "color.action.bg.secondary.subtle.disabled": "{palette.slate.100}",
-  "color.action.fg.secondary.subtle": "{palette.neutral.700}",
-
-  // ── color: status  (bg + fg + border → property required) ────────────────
-  "color.status.success": "{palette.green.600}",
-  "color.status.success.bg": "{palette.green.600}",
-  "color.status.success.bg.subtle": "{palette.green.600}/20",
-  "color.status.success.border": "{palette.green.300}",
-  "color.status.success.border.subtle": "{palette.green.200}",
-  "color.status.success.fg": "{palette.white}",
-  "color.status.success.fg.subtle": "{palette.green.800}",
-
-  "color.status.warning": "{palette.yellow.500}",
-  "color.status.warning.bg": "{palette.yellow.500}",
-  "color.status.warning.bg.subtle": "{palette.yellow.500}/20",
-  "color.status.warning.border": "{palette.yellow.300}",
-  "color.status.warning.border.subtle": "{palette.yellow.200}",
-  "color.status.warning.fg": "{palette.slate.950}",
-  "color.status.warning.fg.subtle": "{palette.yellow.800}",
-
-  "color.status.danger": "{palette.red.400}",
-  "color.status.danger.bg": "{palette.red.400}",
-  "color.status.danger.bg.subtle": "{palette.red.500}/20",
-  "color.status.danger.border": "{palette.red.500}",
-  "color.status.danger.border.subtle": "{palette.red.200}",
-  "color.status.danger.fg": "{palette.white}",
-  "color.status.danger.fg.subtle": "{palette.red.800}",
-
-  "color.status.info": "{palette.sky.600}",
-  "color.status.info.bg": "{palette.sky.600}",
-  "color.status.info.bg.subtle": "{palette.sky.100}",
-  "color.status.info.border": "{palette.sky.300}",
-  "color.status.info.border.subtle": "{palette.sky.200}",
-  "color.status.info.fg": "{palette.white}",
-  "color.status.info.fg.subtle": "{palette.sky.800}",
+  "color.border.strong": "{palette.neutral.500}",
+  "color.focus.ring": "{palette.blue.500}",
+
+  // Effects
+  "color.backdrop": "rgba(9, 9, 11, 0.48)",
+  "color.shadow": "#1b1b1b",
+
+  // Accent
+  "color.accent.text": "{palette.emerald.800}",
+  "color.accent.border": "{palette.emerald.700}",
+
+  "color.accent.solid.bg": "{palette.emerald.800}",
+  "color.accent.solid.bg.hover": "{palette.emerald.900}",
+  "color.accent.solid.bg.pressed": "{palette.emerald.950}",
+  "color.accent.solid.bg.disabled": "{palette.slate.200}",
+  "color.accent.solid.fg": "{palette.white}",
+
+  "color.accent.soft.bg": "{palette.emerald.100}",
+  "color.accent.soft.bg.hover": "{palette.emerald.200}",
+  "color.accent.soft.bg.pressed": "{palette.emerald.300}",
+  "color.accent.soft.bg.disabled": "{palette.slate.100}",
+  "color.accent.soft.fg": "{palette.emerald.800}",
+
+  // Neutral
+  "color.neutral.solid.bg": "{palette.neutral.200}",
+  "color.neutral.solid.fg": "{palette.neutral.900}",
+
+  // Translucent fills keep soft controls distinct from surrounding surfaces.
+  "color.neutral.soft.bg": "{palette.neutral.400}/15",
+  "color.neutral.soft.bg.hover": "{palette.neutral.400}/25",
+  "color.neutral.soft.bg.pressed": "{palette.neutral.400}/35",
+  "color.neutral.soft.bg.disabled": "{palette.slate.100}",
+  "color.neutral.soft.fg": "{palette.neutral.700}",
+
+  // Success
+  "color.success.text": "{palette.emerald.700}",
+
+  "color.success.solid.bg": "{palette.green.500}",
+  "color.success.solid.fg": "{palette.slate.950}",
+  "color.success.solid.border": "{palette.green.300}",
+
+  "color.success.soft.bg": "{palette.green.100}",
+  "color.success.soft.fg": "{palette.emerald.700}",
+  "color.success.soft.border": "{palette.green.300}",
+
+  // Warning — Atlassian Orange800 text, Orange300 solid, Orange100 soft.
+  "color.warning.text": "#9e4c00",
+
+  "color.warning.solid.bg": "#fbc828",
+  "color.warning.solid.fg": "#292a2e",
+  "color.warning.solid.border": "#e06c00",
+
+  "color.warning.soft.bg": "#fff5db",
+  "color.warning.soft.fg": "#9e4c00",
+  "color.warning.soft.border": "#e06c00",
+
+  // Danger
+  "color.danger.text": "{palette.rose.700}",
+
+  "color.danger.solid.bg": "{palette.red.400}",
+  "color.danger.solid.fg": "{palette.slate.950}",
+  "color.danger.solid.border": "{palette.red.300}",
+
+  "color.danger.soft.bg": "{palette.red.100}",
+  "color.danger.soft.fg": "{palette.rose.700}",
+  "color.danger.soft.border": "{palette.red.300}",
+
+  // Info
+  "color.info.text": "{palette.sky.700}",
+
+  "color.info.solid.bg": "{palette.sky.500}",
+  "color.info.solid.fg": "{palette.slate.950}",
+  "color.info.solid.border": "{palette.sky.300}",
+
+  "color.info.soft.bg": "{palette.sky.100}",
+  "color.info.soft.fg": "{palette.sky.700}",
+  "color.info.soft.border": "{palette.sky.300}",
 };

package/src/theme/tokens/primitives.ts

@@ -1,6 +1,7 @@
 /**
  * Scheme-agnostic primitive tokens — flat, dotted-key data.
  *
+ * Naming migration: screen padding keys updated ahead of the next design-sync export.
  * GENERATED-STYLE SOURCE: this file is plain data (no imports, no types).
  * It is intended to be replaced by the Figma design-system export. Keys use a
  * fully-flat `a.b.c` path; the runtime theme is rebuilt from these via
@@ -451,26 +452,25 @@ export const primitives = {
   "typography.variants.caption.letterSpacing": 0.2,
   "typography.variants.caption.maxFontSizeMultiplier": 1.4,
 
-  // ── state-layer opacities ─────────────────────────────────────────────────
+  // ── component opacity multipliers ─────────────────────────────────────────────────
   "opacity.disabled": 0.45,
   "opacity.pressed": 0.85,
 
   // ── screen-level layout ───────────────────────────────────────────────────
-  // `margin.x`/`margin.y` both scale up with the viewport breakpoint (see
+  // `padding.x`/`padding.y` both scale up with the viewport breakpoint (see
   // `theme/breakpoints.ts`).
-  "layout.screen.margin.x.xs": 16,
-  "layout.screen.margin.x.sm": 16,
-  "layout.screen.margin.x.md": 24,
-  "layout.screen.margin.x.lg": 32,
-  "layout.screen.margin.x.xl": 48,
-  "layout.screen.margin.y.xs": 16,
-  "layout.screen.margin.y.sm": 16,
-  "layout.screen.margin.y.md": 24,
-  "layout.screen.margin.y.lg": 24,
-  "layout.screen.margin.y.xl": 24,
+  "layout.screen.padding.x.xs": 16,
+  "layout.screen.padding.x.sm": 16,
+  "layout.screen.padding.x.md": 24,
+  "layout.screen.padding.x.lg": 32,
+  "layout.screen.padding.x.xl": 48,
+  "layout.screen.padding.y.xs": 16,
+  "layout.screen.padding.y.sm": 16,
+  "layout.screen.padding.y.md": 24,
+  "layout.screen.padding.y.lg": 24,
+  "layout.screen.padding.y.xl": 24,
 
   // ── header layout ─────────────────────────────────────────────────────────
-  // Header bar height (compact nav bar / collapsed large-title bar). 56dp aligns
-  // to the 4dp spacing grid (= spacing.14) and a standard app-bar height.
+  // Header bar height in dp (compact nav bar / collapsed large-title bar).
   "layout.header.height": 54,
 };

package/src/theme/tokens/validate.ts

@@ -0,0 +1,271 @@
+/**
+ * Raw scheme-data validator.
+ *
+ * `light.ts` / `dark.ts` are untyped, Figma-style data that `theme.ts` casts
+ * into `ThemeColor`. This module checks that data against the real schema so
+ * an authoring mistake fails a test with the offending key and value instead
+ * of reaching a component as an unresolved `{palette.x}` string.
+ *
+ * Pure: imports only the token data and the legacy alias list. Safe to run at
+ * build/test time; not part of the runtime theme pipeline.
+ */
+import { legacyColorAliases } from "#theme/legacy-tokens";
+import type { Scheme } from "#theme/types";
+import { CANONICAL_COLOR_KEYS } from "./canonical-color-keys";
+import { dark } from "./dark";
+import { light } from "./light";
+import { primitives } from "./primitives";
+
+/** Where an issue was found: one of the scheme files, or the shared primitives. */
+export type SchemeTokenSource = Scheme | "primitives";
+
+export interface SchemeTokenIssue {
+  source: SchemeTokenSource;
+  /** The authored key (e.g. `color.text.primary`), as written in the file. */
+  key: string;
+  /** The authored value, verbatim. */
+  value: unknown;
+  message: string;
+}
+
+/** The three raw token maps. Defaults to the real data; tests pass fixtures. */
+export interface SchemeTokenData {
+  light: Record<string, unknown>;
+  dark: Record<string, unknown>;
+  primitives: Record<string, unknown>;
+}
+
+export class SchemeTokenValidationError extends Error {
+  readonly issues: readonly SchemeTokenIssue[];
+
+  constructor(issues: readonly SchemeTokenIssue[]) {
+    super(
+      `Invalid scheme token data (${issues.length} issue${issues.length === 1 ? "" : "s"}):\n${issues
+        .map(formatIssue)
+        .join("\n")}`
+    );
+    this.name = "SchemeTokenValidationError";
+    this.issues = issues;
+  }
+}
+
+export function formatIssue(issue: SchemeTokenIssue): string {
+  return `  [${issue.source}] ${issue.key} = ${JSON.stringify(issue.value)} — ${issue.message}`;
+}
+
+const COLOR_PREFIX = "color.";
+const PALETTE_PREFIX = "palette.";
+
+// Mirrors theme.ts: `{palette.key}` and `{palette.key}/NN`.
+const REF_PATTERN = /^\{([\w.]+)\}$/;
+const ALPHA_REF_PATTERN = /^\{([\w.]+)\}\/(\d{1,3})$/;
+// Palette primitives must be plain `#rrggbb` so the alpha suffix can be appended.
+const HEX6_PATTERN = /^#[0-9a-f]{6}$/i;
+// Literal colour values accepted in authored scheme data. Anything else is a
+// typo or an unsupported notation that would pass through `resolveRefs`
+// unchanged and reach a component.
+const LITERAL_PATTERNS = [
+  /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i,
+  /^rgba?\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*(?:,\s*(?:0|1|0?\.\d+)\s*)?\)$/,
+  /^hsla?\(\s*\d{1,3}(?:\.\d+)?\s*,\s*\d{1,3}%\s*,\s*\d{1,3}%\s*(?:,\s*(?:0|1|0?\.\d+)\s*)?\)$/,
+  /^transparent$/,
+];
+
+const legacyAliasNames = new Set(Object.keys(legacyColorAliases));
+
+function checkKeySet(source: Scheme, data: Record<string, unknown>, issues: SchemeTokenIssue[]): void {
+  const authored = new Set(Object.keys(data));
+  for (const canonical of CANONICAL_COLOR_KEYS) {
+    const key = `${COLOR_PREFIX}${canonical}`;
+    if (!authored.has(key)) {
+      issues.push({ source, key, value: undefined, message: "required canonical colour key is missing" });
+    }
+  }
+  for (const key of authored) {
+    if (!key.startsWith(COLOR_PREFIX)) {
+      issues.push({
+        source,
+        key,
+        value: data[key],
+        message: `scheme files may only author \`${COLOR_PREFIX}*\` keys`,
+      });
+      continue;
+    }
+    const name = key.slice(COLOR_PREFIX.length);
+    if (legacyAliasNames.has(name)) {
+      issues.push({
+        source,
+        key,
+        value: data[key],
+        message: `deprecated alias of \`${legacyColorAliases[name as keyof typeof legacyColorAliases]}\`; aliases belong at the public boundary, not in authored data`,
+      });
+    } else if (!(CANONICAL_COLOR_KEYS as readonly string[]).includes(name)) {
+      issues.push({ source, key, value: data[key], message: "not a canonical colour key" });
+    }
+  }
+}
+
+function checkReference(
+  source: Scheme,
+  key: string,
+  value: string,
+  refKey: string,
+  prims: Record<string, unknown>,
+  issues: SchemeTokenIssue[]
+): boolean {
+  if (!refKey.startsWith(PALETTE_PREFIX)) {
+    issues.push({
+      source,
+      key,
+      value,
+      message: `references \`${refKey}\`, which is not a \`palette.*\` primitive`,
+    });
+    return false;
+  }
+  const resolved = prims[refKey];
+  if (resolved === undefined) {
+    issues.push({
+      source,
+      key,
+      value,
+      message: `references \`${refKey}\`, which does not exist in primitives`,
+    });
+    return false;
+  }
+  if (typeof resolved !== "string" || !HEX6_PATTERN.test(resolved)) {
+    issues.push({
+      source,
+      key,
+      value,
+      message: `references \`${refKey}\` = ${JSON.stringify(resolved)}, which is not a \`#rrggbb\` hex`,
+    });
+    return false;
+  }
+  return true;
+}
+
+function checkValues(
+  source: Scheme,
+  data: Record<string, unknown>,
+  prims: Record<string, unknown>,
+  issues: SchemeTokenIssue[]
+): void {
+  for (const [key, value] of Object.entries(data)) {
+    // Non-colour keys are already rejected by the key-set check.
+    if (!key.startsWith(COLOR_PREFIX)) continue;
+    if (typeof value !== "string") {
+      issues.push({ source, key, value, message: `expected a string, got ${typeof value}` });
+      continue;
+    }
+
+    const alphaMatch = value.match(ALPHA_REF_PATTERN);
+    if (alphaMatch) {
+      const refKey = alphaMatch[1] as string;
+      const percent = Number(alphaMatch[2]);
+      if (checkReference(source, key, value, refKey, prims, issues) && (percent < 0 || percent > 100)) {
+        issues.push({ source, key, value, message: `alpha percentage ${percent} is outside 0–100` });
+      }
+      continue;
+    }
+
+    const refMatch = value.match(REF_PATTERN);
+    if (refMatch) {
+      checkReference(source, key, value, refMatch[1] as string, prims, issues);
+      continue;
+    }
+
+    if (value.includes("{") || value.includes("}")) {
+      issues.push({
+        source,
+        key,
+        value,
+        message: "malformed palette reference; expected `{palette.key}` or `{palette.key}/NN`",
+      });
+      continue;
+    }
+
+    if (value.includes("/")) {
+      issues.push({
+        source,
+        key,
+        value,
+        message: "`/NN` alpha suffix is only supported on `{palette.key}` references, not literals",
+      });
+      continue;
+    }
+
+    if (!LITERAL_PATTERNS.some((pattern) => pattern.test(value))) {
+      issues.push({
+        source,
+        key,
+        value,
+        message: "not an accepted colour value (hex, rgb[a](), hsl[a](), transparent, or palette reference)",
+      });
+    }
+  }
+}
+
+function checkKeyOrder(
+  lightData: Record<string, unknown>,
+  darkData: Record<string, unknown>,
+  issues: SchemeTokenIssue[]
+) {
+  const lightKeys = Object.keys(lightData);
+  const darkKeys = Object.keys(darkData);
+  // Only meaningful when both files author the same set; missing/extra keys
+  // are already reported by the key-set check.
+  if (lightKeys.length !== darkKeys.length || !lightKeys.every((key) => key in darkData)) return;
+  for (let index = 0; index < lightKeys.length; index += 1) {
+    if (lightKeys[index] !== darkKeys[index]) {
+      issues.push({
+        source: "dark",
+        key: darkKeys[index] as string,
+        value: lightKeys[index],
+        message: `key order differs from light at position ${index}: light authors \`${lightKeys[index]}\` here`,
+      });
+      return;
+    }
+  }
+}
+
+function checkPalette(prims: Record<string, unknown>, issues: SchemeTokenIssue[]): void {
+  for (const [key, value] of Object.entries(prims)) {
+    if (!key.startsWith(PALETTE_PREFIX)) continue;
+    if (typeof value !== "string" || !HEX6_PATTERN.test(value)) {
+      issues.push({ source: "primitives", key, value, message: "palette primitives must be `#rrggbb` hex" });
+    }
+  }
+}
+
+/**
+ * Collects every problem in the raw scheme data. Returns `[]` for valid data.
+ * Pass a partial {@link SchemeTokenData} to validate fixtures; omitted maps
+ * default to the real token files.
+ */
+export function collectSchemeTokenIssues(data: Partial<SchemeTokenData> = {}): SchemeTokenIssue[] {
+  const lightData = data.light ?? light;
+  const darkData = data.dark ?? dark;
+  const prims = data.primitives ?? primitives;
+  const issues: SchemeTokenIssue[] = [];
+
+  checkPalette(prims, issues);
+  for (const [source, scheme] of [
+    ["light", lightData],
+    ["dark", darkData],
+  ] as const) {
+    checkKeySet(source, scheme, issues);
+    checkValues(source, scheme, prims, issues);
+  }
+  checkKeyOrder(lightData, darkData, issues);
+
+  return issues;
+}
+
+/**
+ * Throws a {@link SchemeTokenValidationError} listing every issue (source,
+ * key, value, message) when the raw scheme data is invalid.
+ */
+export function validateSchemeTokens(data: Partial<SchemeTokenData> = {}): void {
+  const issues = collectSchemeTokenIssues(data);
+  if (issues.length > 0) throw new SchemeTokenValidationError(issues);
+}