@worldcoin/nucleus 0.1.4

package/examples/web/app/components/ColorGroupSection.tsx

@@ -0,0 +1,31 @@
+import { ColorCard } from "./ColorCard";
+import type { ColorGroup, DemoTheme } from "../models";
+
+export function ColorGroupSection({
+  group,
+  theme,
+}: {
+  group: ColorGroup;
+  theme: DemoTheme;
+}) {
+  return (
+    <section className="space-y-3">
+      <h3
+        className="text-sm font-semibold tracking-[0.08em]"
+        style={{ color: theme.muted }}
+      >
+        {group.name}
+      </h3>
+      <div className="grid grid-cols-1 gap-2 md:grid-cols-2 xl:grid-cols-3">
+        {group.colors.map((color) => (
+          <ColorCard
+            key={color.name}
+            name={color.name}
+            value={color.value}
+            theme={theme}
+          />
+        ))}
+      </div>
+    </section>
+  );
+}

package/examples/web/app/components/HeroSection.tsx

@@ -0,0 +1,124 @@
+"use client";
+
+import { useState } from "react";
+import type { AppTheme, DemoSection } from "../models";
+
+function HamburgerIcon({ color }: { color: string }) {
+  return (
+    <span
+      className="inline-flex h-10 w-10 flex-col items-center justify-center gap-1.5 rounded-full border"
+      style={{ borderColor: color }}
+      aria-hidden="true"
+    >
+      {[0, 1, 2].map((bar) => (
+        <span
+          key={bar}
+          className="block h-0.5 w-4 rounded-full"
+          style={{ backgroundColor: color }}
+        />
+      ))}
+    </span>
+  );
+}
+
+export function HeroSection({
+  activeTheme,
+  appThemes,
+  demoSections,
+  selectedSectionId,
+  onSelectTheme,
+  onSelectSection,
+}: {
+  activeTheme: AppTheme;
+  appThemes: AppTheme[];
+  demoSections: DemoSection[];
+  selectedSectionId: string;
+  onSelectTheme: (id: AppTheme["id"]) => void;
+  onSelectSection: (id: string) => void;
+}) {
+  const [isMenuOpen, setIsMenuOpen] = useState(false);
+
+  return (
+    <>
+      {isMenuOpen ? (
+        <button
+          aria-label="Close token set menu"
+          className="fixed inset-0 z-20 bg-black/20"
+          onClick={() => setIsMenuOpen(false)}
+        />
+      ) : null}
+
+      <section className="relative flex flex-wrap items-center justify-between gap-3">
+        <h1 className="text-3xl font-semibold tracking-tight">Nucleus</h1>
+
+        <div className="flex flex-wrap items-center gap-3">
+        <div
+          className="inline-flex rounded-full border p-1"
+          style={{ borderColor: activeTheme.border }}
+        >
+          {appThemes.map((theme) => {
+            const isActive = theme.id === activeTheme.id;
+            return (
+              <button
+                key={theme.id}
+                className="rounded-full px-3 py-1.5 text-sm font-medium transition-colors"
+                onClick={() => onSelectTheme(theme.id)}
+                style={{
+                  backgroundColor: isActive ? activeTheme.text : "transparent",
+                  color: isActive ? activeTheme.background : activeTheme.text,
+                }}
+              >
+                {theme.name}
+              </button>
+            );
+          })}
+        </div>
+
+          <div className="relative">
+            <button
+              aria-label="Open token set menu"
+              onClick={() => setIsMenuOpen((open) => !open)}
+            >
+              <HamburgerIcon color={activeTheme.text} />
+            </button>
+
+            {isMenuOpen ? (
+              <div
+                className="absolute right-0 top-14 z-30 w-56 rounded-3xl border p-2 shadow-xl"
+                style={{
+                  backgroundColor: activeTheme.surface,
+                  borderColor: activeTheme.border,
+                  color: activeTheme.text,
+                }}
+              >
+                {demoSections.map((section) => {
+                  const isActive = section.id === selectedSectionId;
+                  return (
+                    <button
+                      key={section.id}
+                      className="w-full rounded-2xl px-4 py-3 text-left text-sm font-medium transition-colors"
+                      onClick={() => {
+                        onSelectSection(section.id);
+                        setIsMenuOpen(false);
+                      }}
+                      style={{
+                        backgroundColor: isActive
+                          ? activeTheme.text
+                          : activeTheme.surface,
+                        color: isActive
+                          ? activeTheme.background
+                          : activeTheme.text,
+                      }}
+                    >
+                      {section.label}
+                    </button>
+                  );
+                })}
+              </div>
+            ) : null}
+          </div>
+        </div>
+      </section>
+    </>
+  );
+}

package/examples/web/app/components/TokenSectionCard.tsx

@@ -0,0 +1,18 @@
+import { ColorGroupSection } from "./ColorGroupSection";
+import type { DemoSection, DemoTheme } from "../models";
+
+export function TokenSectionCard({
+  section,
+  theme,
+}: {
+  section: DemoSection;
+  theme: DemoTheme;
+}) {
+  return (
+    <div className="space-y-8" style={{ color: theme.text }}>
+      {section.groups.map((group) => (
+        <ColorGroupSection key={group.id} group={group} theme={theme} />
+      ))}
+    </div>
+  );
+}

package/examples/web/app/globals.css

@@ -0,0 +1,35 @@
+@import "tailwindcss";
+
+:root {
+  --background: #F9FAFB;
+  --foreground: #17181A;
+  --muted: #747679;
+  --border: #EAEBED;
+  --surface: #FFFFFF;
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-muted: var(--muted);
+  --color-border: var(--border);
+  --color-surface: var(--surface);
+  --font-sans: "SF Pro Display", "Segoe UI", sans-serif;
+  --font-mono: "SF Mono", "JetBrains Mono", monospace;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html {
+  min-height: 100%;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  background: var(--background);
+  color: var(--foreground);
+  font-family: var(--font-sans);
+}

package/examples/web/app/layout.tsx

@@ -0,0 +1,20 @@
+import type { Metadata } from "next";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "Nucleus",
+  description:
+    "Design tokens for Nucleus — colors across platforms.",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body className="font-sans antialiased">{children}</body>
+    </html>
+  );
+}

package/examples/web/app/models.ts

@@ -0,0 +1,44 @@
+export interface ColorToken {
+  name: string;
+  value: string;
+}
+
+export interface ColorGroup {
+  id: string;
+  name: string;
+  colors: ColorToken[];
+}
+
+export interface DemoTheme {
+  background: string;
+  surface: string;
+  surfaceAlt: string;
+  border: string;
+  text: string;
+  muted: string;
+  accent: string;
+  accentContent: string;
+}
+
+export interface SemanticMode {
+  id: "light" | "dark";
+  name: string;
+  theme: DemoTheme;
+  groups: ColorGroup[];
+}
+
+export interface AppTheme {
+  id: SemanticMode["id"];
+  name: string;
+  background: string;
+  surface: string;
+  border: string;
+  text: string;
+  muted: string;
+}
+
+export interface DemoSection {
+  id: string;
+  label: string;
+  groups: ColorGroup[];
+}

package/examples/web/app/page.tsx

@@ -0,0 +1,54 @@
+"use client";
+
+import { useState } from "react";
+import { HeroSection } from "./components/HeroSection";
+import { TokenSectionCard } from "./components/TokenSectionCard";
+import type { AppTheme, DemoTheme } from "./models";
+import { appThemes, demoSections } from "./tokens";
+
+function fallbackSectionTheme(theme: AppTheme): DemoTheme {
+  return {
+    background: theme.surface,
+    surface: theme.surface,
+    surfaceAlt: theme.surface,
+    border: theme.border,
+    text: theme.text,
+    muted: theme.muted,
+    accent: theme.text,
+    accentContent: theme.background,
+  };
+}
+
+export default function Home() {
+  const [selectedSectionId, setSelectedSectionId] = useState(demoSections[0].id);
+  const [selectedThemeId, setSelectedThemeId] = useState<AppTheme["id"]>("dark");
+
+  const selectedSection =
+    demoSections.find((section) => section.id === selectedSectionId) ?? demoSections[0];
+  const activeTheme =
+    appThemes.find((theme) => theme.id === selectedThemeId) ?? appThemes[0];
+  const chromeTheme = fallbackSectionTheme(activeTheme);
+
+  return (
+    <main
+      className="min-h-screen"
+      style={{
+        backgroundColor: activeTheme.background,
+        color: activeTheme.text,
+      }}
+    >
+      <div className="mx-auto flex max-w-7xl flex-col gap-8 px-6 py-8 md:py-10">
+        <HeroSection
+          activeTheme={activeTheme}
+          appThemes={appThemes}
+          demoSections={demoSections}
+          selectedSectionId={selectedSection.id}
+          onSelectTheme={setSelectedThemeId}
+          onSelectSection={setSelectedSectionId}
+        />
+
+        <TokenSectionCard section={selectedSection} theme={chromeTheme} />
+      </div>
+    </main>
+  );
+}

package/examples/web/app/token-source.local.ts

@@ -0,0 +1,9 @@
+import primitive from "../../../build/web/nucleus-primitive-colors.json";
+import semanticDark from "../../../build/web/nucleus-semantic-colors-dark.json";
+import semanticLight from "../../../build/web/nucleus-semantic-colors-light.json";
+
+export default {
+  primitive,
+  semanticDark,
+  semanticLight,
+};

package/examples/web/app/token-source.package.ts

@@ -0,0 +1,9 @@
+import primitive from "@worldcoin/nucleus/nucleus-primitive-colors.json";
+import semanticDark from "@worldcoin/nucleus/nucleus-semantic-colors-dark.json";
+import semanticLight from "@worldcoin/nucleus/nucleus-semantic-colors-light.json";
+
+export default {
+  primitive,
+  semanticDark,
+  semanticLight,
+};

package/examples/web/app/tokens.ts

@@ -0,0 +1,330 @@
+import localTokenSet from "./token-source.local";
+import packageTokenSet from "./token-source.package";
+import type {
+  AppTheme,
+  ColorGroup,
+  DemoSection,
+  DemoTheme,
+  SemanticMode,
+} from "./models";
+
+const tokenSet =
+  process.env.NEXT_PUBLIC_NUCLEUS_WEB_SOURCE === "package"
+    ? packageTokenSet
+    : localTokenSet;
+
+type TokenMap = Record<string, string>;
+type TokenRoot = "primitive" | "semantic";
+
+interface ResolvedToken {
+  name: string;
+  value: string;
+  family: string;
+  tone: number | null;
+}
+
+const primitiveTokens: TokenMap = tokenSet.primitive;
+const semanticLightTokens: TokenMap = tokenSet.semanticLight;
+const semanticDarkTokens: TokenMap = tokenSet.semanticDark;
+
+function referenceTokenName(value: string): { root: TokenRoot; key: string } | null {
+  const match = value.match(/^\{(primitive|semantic)\.color\.(.+)\}$/);
+  if (!match) {
+    return null;
+  }
+
+  const [, root, path] = match;
+  const key = path
+    .split(".")
+    .map((segment, index) =>
+      index === 0 ? segment : segment.charAt(0).toUpperCase() + segment.slice(1),
+    )
+    .join("");
+
+  return { root: root as TokenRoot, key };
+}
+
+function resolveColorValue(value: string, semanticTokens?: TokenMap): string {
+  const reference = referenceTokenName(value);
+  if (!reference) {
+    return value;
+  }
+
+  const sourceTokens =
+    reference.root === "primitive" ? primitiveTokens : semanticTokens;
+  const resolved = sourceTokens?.[reference.key];
+
+  if (!resolved || resolved === value) {
+    return value;
+  }
+
+  return resolveColorValue(resolved, semanticTokens);
+}
+
+function tokenFamilyKey(name: string): string {
+  if (name === "white" || name === "black") {
+    return "base";
+  }
+
+  const match = name.match(/^[a-z]+/);
+  return match?.[0] ?? name;
+}
+
+function tokenTone(name: string): number | null {
+  const match = name.match(/(\d+)$/);
+  return match ? Number(match[1]) : null;
+}
+
+function familyTitle(key: string): string {
+  return key.charAt(0).toUpperCase() + key.slice(1);
+}
+
+function resolveTokenEntries(tokens: TokenMap, semanticTokens?: TokenMap): ResolvedToken[] {
+  return Object.entries(tokens).map(([name, rawValue]) => ({
+    name,
+    value: resolveColorValue(rawValue, semanticTokens),
+    family: tokenFamilyKey(name),
+    tone: tokenTone(name),
+  }));
+}
+
+function buildGroups(entries: ResolvedToken[]): ColorGroup[] {
+  const groups = new Map<string, ColorGroup>();
+
+  for (const entry of entries) {
+    const key = entry.family;
+    const group = groups.get(key) ?? {
+      id: key,
+      name: familyTitle(key),
+      colors: [],
+    };
+
+    group.colors.push({
+      name: entry.name,
+      value: entry.value,
+    });
+
+    groups.set(key, group);
+  }
+
+  return [...groups.values()];
+}
+
+function groupEntriesByFamily(entries: ResolvedToken[]): Map<string, ResolvedToken[]> {
+  const groups = new Map<string, ResolvedToken[]>();
+
+  for (const entry of entries) {
+    const familyEntries = groups.get(entry.family) ?? [];
+    familyEntries.push(entry);
+    groups.set(entry.family, familyEntries);
+  }
+
+  return groups;
+}
+
+function isOpaque(value: string): boolean {
+  const normalized = value.replace("#", "");
+  return normalized.length !== 8 || normalized.endsWith("FF");
+}
+
+function pickOpaqueFamilyToken(
+  entries: ResolvedToken[] | undefined,
+  index = 0,
+): string | undefined {
+  if (!entries?.length) {
+    return undefined;
+  }
+
+  const opaqueEntries = entries.filter((entry) => isOpaque(entry.value));
+  return opaqueEntries[index]?.value ?? opaqueEntries[0]?.value;
+}
+
+function pickLastDistinctOpaqueToken(
+  entries: ResolvedToken[] | undefined,
+  excluded: string[],
+): string | undefined {
+  if (!entries?.length) {
+    return undefined;
+  }
+
+  const opaqueEntries = entries.filter((entry) => isOpaque(entry.value));
+  return [...opaqueEntries]
+    .reverse()
+    .find((entry) => !excluded.includes(entry.value))
+    ?.value;
+}
+
+function pickTone(entries: ResolvedToken[] | undefined, targets: number[]): string | undefined {
+  const tonedEntries = entries?.filter(
+    (entry): entry is ResolvedToken & { tone: number } => entry.tone !== null,
+  );
+
+  if (!tonedEntries?.length) {
+    return entries?.[0]?.value;
+  }
+
+  for (const target of targets) {
+    const exact = tonedEntries.find((entry) => entry.tone === target);
+    if (exact) {
+      return exact.value;
+    }
+  }
+
+  return tonedEntries.reduce((best, entry) => {
+    return Math.abs(entry.tone - targets[0]) < Math.abs(best.tone - targets[0])
+      ? entry
+      : best;
+  }).value;
+}
+
+function pickNeutralFamily(groups: Map<string, ResolvedToken[]>): ResolvedToken[] {
+  const candidates = ["grey", "gray", "neutral", "stone", "slate"];
+
+  for (const family of candidates) {
+    const entries = groups.get(family);
+    if (entries?.some((entry) => entry.tone !== null)) {
+      return entries;
+    }
+  }
+
+  return [...groups.values()]
+    .filter((entries) => entries.some((entry) => entry.tone !== null))
+    .sort((left, right) => right.length - left.length)[0] ?? [];
+}
+
+function pickAccentFamily(
+  groups: Map<string, ResolvedToken[]>,
+  neutralFamily: string,
+): ResolvedToken[] {
+  const priorities = ["info", "accent", "brand", "blue"];
+
+  for (const family of priorities) {
+    const entries = groups.get(family);
+    if (entries?.length) {
+      return entries;
+    }
+  }
+
+  return [...groups.entries()]
+    .filter(([family]) => family !== "base" && family !== neutralFamily)
+    .map(([, entries]) => entries)[0] ?? [];
+}
+
+function contrastColor(color: string, light = "#FFFFFF", dark = "#17181A"): string {
+  const normalized = color.replace("#", "");
+  const rgb = normalized.slice(0, 6);
+  const red = Number.parseInt(rgb.slice(0, 2), 16);
+  const green = Number.parseInt(rgb.slice(2, 4), 16);
+  const blue = Number.parseInt(rgb.slice(4, 6), 16);
+  const luminance = (0.2126 * red + 0.7152 * green + 0.0722 * blue) / 255;
+
+  return luminance > 0.6 ? dark : light;
+}
+
+function buildNeutralPalette(entries: ResolvedToken[]): DemoTheme {
+  const groups = groupEntriesByFamily(entries);
+  const neutralEntries = pickNeutralFamily(groups);
+  const neutralFamily = neutralEntries[0]?.family ?? "grey";
+  const baseEntries = groups.get("base");
+  const white = baseEntries?.find((entry) => entry.name === "white")?.value ?? "#FFFFFF";
+  const black = baseEntries?.find((entry) => entry.name === "black")?.value ?? "#17181A";
+  const accent = pickTone(pickAccentFamily(groups, neutralFamily), [600, 500, 400]) ?? "#0064EE";
+
+  return {
+    background: pickTone(neutralEntries, [100, 200]) ?? white,
+    surface: white,
+    surfaceAlt: white,
+    border: pickTone(neutralEntries, [300, 400]) ?? "#D7D9DC",
+    text: pickTone(neutralEntries, [950, 900, 800]) ?? black,
+    muted: pickTone(neutralEntries, [700, 600, 500]) ?? black,
+    accent,
+    accentContent: contrastColor(accent, white, black),
+  };
+}
+
+function buildSemanticTheme(entries: ResolvedToken[], fallback: DemoTheme): DemoTheme {
+  const groups = groupEntriesByFamily(entries);
+  const surfaceEntries = groups.get("surface");
+  const textEntries = groups.get("text");
+  const iconEntries = groups.get("icon");
+  const borderEntries = groups.get("border");
+  const accentEntries = groups.get("accent");
+  const actionEntries = groups.get("action");
+  const statusEntries = groups.get("status");
+  const surface = pickOpaqueFamilyToken(surfaceEntries, 0) ?? fallback.surface;
+  const background = pickOpaqueFamilyToken(surfaceEntries, 1) ?? surface;
+  const surfaceAlt =
+    pickLastDistinctOpaqueToken(surfaceEntries, [surface, background]) ??
+    pickOpaqueFamilyToken(surfaceEntries, 0) ??
+    fallback.surfaceAlt;
+  const accent =
+    pickOpaqueFamilyToken(accentEntries, 0) ??
+    pickOpaqueFamilyToken(actionEntries, 0) ??
+    pickOpaqueFamilyToken(statusEntries, 0) ??
+    fallback.accent;
+  const accentContent =
+    pickOpaqueFamilyToken(accentEntries, 1) ??
+    pickOpaqueFamilyToken(actionEntries, 1) ??
+    contrastColor(accent);
+
+  return {
+    background,
+    surface,
+    surfaceAlt,
+    border: pickOpaqueFamilyToken(borderEntries, 1) ?? pickOpaqueFamilyToken(borderEntries, 0) ?? fallback.border,
+    text: pickOpaqueFamilyToken(textEntries, 0) ?? pickOpaqueFamilyToken(iconEntries, 0) ?? fallback.text,
+    muted: pickOpaqueFamilyToken(textEntries, 1) ?? pickOpaqueFamilyToken(iconEntries, 1) ?? fallback.muted,
+    accent,
+    accentContent,
+  };
+}
+
+function buildSemanticMode(
+  id: SemanticMode["id"],
+  name: SemanticMode["name"],
+  tokens: TokenMap,
+  fallback: DemoTheme,
+): SemanticMode {
+  const entries = resolveTokenEntries(tokens, tokens);
+  const groups = buildGroups(entries);
+
+  return {
+    id,
+    name,
+    theme: buildSemanticTheme(entries, fallback),
+    groups,
+  };
+}
+
+const primitiveEntries = resolveTokenEntries(primitiveTokens);
+const neutralPalette = buildNeutralPalette(primitiveEntries);
+
+export const semanticModes: SemanticMode[] = [
+  buildSemanticMode("light", "Light", semanticLightTokens, neutralPalette),
+  buildSemanticMode("dark", "Dark", semanticDarkTokens, neutralPalette),
+];
+
+export const appThemes: AppTheme[] = semanticModes.map((mode) => ({
+  id: mode.id,
+  name: mode.name,
+  background: mode.theme.background,
+  surface: mode.theme.surface,
+  border: mode.theme.border,
+  text: mode.theme.text,
+  muted: mode.theme.muted,
+}));
+
+const primitiveGroups = buildGroups(primitiveEntries);
+
+export const demoSections: DemoSection[] = [
+  {
+    id: "primitive",
+    label: "Primitive",
+    groups: primitiveGroups,
+  },
+  ...semanticModes.map((mode) => ({
+    id: `semantic-${mode.id}`,
+    label: mode.name,
+    groups: mode.groups,
+  })),
+];

package/examples/web/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;