@sproutsocial/seeds-theme 0.1.0

package/src/extension.d.ts

@@ -0,0 +1,18 @@
+import type { DtcgTokenTree, ThemeMode } from "./index.js";
+
+/** Validate sparse light/dark token files and write only product CSS overrides. */
+export function buildThemeExtension(
+  definition: {
+    name: string;
+    extends: "seeds";
+    common?: DtcgTokenTree;
+    modes: Record<ThemeMode, DtcgTokenTree>;
+  },
+  options: { outputFile: string }
+): Promise<string>;
+
+export function composeSeedsTheme(definition: {
+  name: string;
+  common?: DtcgTokenTree;
+  modes?: Record<ThemeMode, DtcgTokenTree>;
+}): Promise<{ name: string; modes: Record<ThemeMode, DtcgTokenTree> }>;

package/src/extension.js

@@ -0,0 +1,81 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import StyleDictionary from "style-dictionary";
+import {
+  composeTheme,
+  defineTheme,
+  defineThemeExtension,
+  selectorsForTheme,
+} from "./contract.js";
+import { compileExtensionCss } from "./compiler.js";
+import { loadSeedsPrimitives } from "./primitives.js";
+
+async function seedsTheme() {
+  const modes = Object.fromEntries(
+    await Promise.all(
+      ["light", "dark"].map(async (mode) => [
+        mode,
+        JSON.parse(
+          await fs.readFile(
+            new URL(
+              `../dist/source/theme-${mode}.tokens.json`,
+              import.meta.url
+            ),
+            "utf8"
+          )
+        ),
+      ])
+    )
+  );
+  return defineTheme({
+    name: "seeds",
+    common: await loadSeedsPrimitives(),
+    modes,
+  });
+}
+
+/** Native Style Dictionary inheritance, validated against the published Seeds tokens. */
+export async function composeSeedsTheme({
+  name,
+  common = {},
+  modes = { light: {}, dark: {} },
+}) {
+  const seeds = await seedsTheme();
+  const extension = defineThemeExtension({
+    name,
+    common,
+    modes,
+    extensionRoots: ["product"],
+  });
+  // Reject misspelled paths, changed types, missing references and cycles before merging.
+  const theme = composeTheme(seeds, extension);
+  const baseline = composeTheme(seeds);
+  for (const mode of ["light", "dark"]) {
+    const dictionary = new StyleDictionary({
+      tokens: baseline.modes[mode],
+      usesDtcg: true,
+      log: { verbosity: "silent" },
+    });
+    const shared = await dictionary.extend({ tokens: common });
+    theme.modes[mode] = (await shared.extend({ tokens: modes[mode] })).tokens;
+  }
+  return theme;
+}
+
+/** Emit only differences; import Seeds' CSS once for all themes and both modes. */
+export async function buildThemeExtension(definition, { outputFile }) {
+  if (definition.extends !== "seeds")
+    throw new Error('Theme extensions must declare extends: "seeds".');
+  if (definition.name === "seeds")
+    throw new Error("An extension must have its own theme name.");
+  const baseline = composeTheme(await seedsTheme());
+  const product = await composeSeedsTheme(definition);
+  const css = await compileExtensionCss(
+    product,
+    baseline,
+    selectorsForTheme(definition.name)
+  );
+  await fs.mkdir(path.dirname(outputFile), { recursive: true });
+  await fs.writeFile(outputFile, css);
+  return outputFile;
+}

package/src/index.d.ts

@@ -0,0 +1,90 @@
+export type DtcgToken = {
+  $value: unknown;
+  $type?: string;
+  $description?: string;
+  [metadata: `$${string}`]: unknown;
+};
+
+export type DtcgTokenTree = {
+  [name: string]: DtcgTokenTree | DtcgToken | unknown;
+};
+
+export type ThemeMode = "light" | "dark";
+
+export type ThemeDefinition = {
+  kind: "theme";
+  name: string;
+  common: DtcgTokenTree;
+  modes: Record<ThemeMode, DtcgTokenTree>;
+};
+
+export type ThemeExtension = {
+  kind: "extension";
+  name: string;
+  common: DtcgTokenTree;
+  modes: Record<ThemeMode, DtcgTokenTree>;
+  extensionRoots: string[];
+};
+
+export type ComposedTheme = {
+  name: string;
+  modes: Record<ThemeMode, DtcgTokenTree>;
+};
+
+export function defineTheme(input: {
+  name: string;
+  common?: DtcgTokenTree;
+  modes: Record<ThemeMode, DtcgTokenTree>;
+}): ThemeDefinition;
+
+export function defineThemeExtension(input: {
+  name: string;
+  common?: DtcgTokenTree;
+  modes: Record<ThemeMode, DtcgTokenTree>;
+  extensionRoots?: string[];
+}): ThemeExtension;
+
+export function composeTheme(
+  baseTheme: ThemeDefinition,
+  ...extensions: ThemeExtension[]
+): ComposedTheme;
+
+/**
+ * The CSS selectors a theme's generated stylesheets are emitted under.
+ *
+ * `base` applies in every color mode and carries the complete token set;
+ * `dark` is layered over it and carries only the declarations that differ.
+ * `darkVariant` is the Tailwind `@custom-variant dark` condition and is
+ * deliberately theme-agnostic.
+ */
+export type ThemeSelectors = {
+  base: string;
+  dark: string;
+  darkVariant: string;
+  /** Wrap dark token declarations in this media query for CSS-only hosts. */
+  darkMedia?: string;
+};
+
+export function assertThemeSelectors(
+  selectors: unknown
+): asserts selectors is ThemeSelectors;
+
+export function selectorsForTheme(
+  name: string,
+  options?: {
+    /** Theme whose defaults apply to every brand; its selectors have lower specificity than product overrides. */
+    defaultTheme?: string;
+    mode?: "class" | "attribute" | "media";
+    darkVariant?: string;
+  }
+): ThemeSelectors;
+
+export const themeModes: readonly ThemeMode[];
+
+export {
+  buildProductTheme,
+  defineProductTheme,
+  type ProductThemeConfig,
+  type ProductThemeInput,
+  type ProductThemeTokenSource,
+} from "./config.js";

package/src/index.js

@@ -0,0 +1,9 @@
+export {
+  assertThemeSelectors,
+  composeTheme,
+  defineTheme,
+  defineThemeExtension,
+  selectorsForTheme,
+  themeModes,
+} from "./contract.js";
+export { buildProductTheme, defineProductTheme } from "./config.js";

package/src/primitives.js

@@ -0,0 +1,98 @@
+// Adapt the existing packages' public exports for Style Dictionary. No primitive
+// values are authored or shipped again by seeds-theme. CSS names are matched
+// against each package's actual stylesheet, including historical double hyphens.
+import fs from "node:fs/promises";
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+
+const packages = [
+  "color",
+  "space",
+  "border",
+  "typography",
+  "depth",
+  "motion",
+  "networkcolor",
+];
+export const primitiveRoots = new Set([
+  "color",
+  "space",
+  "border",
+  "typography",
+  "elevation",
+  "motion",
+  "networkColor",
+]);
+
+function camel(parts) {
+  return parts
+    .map((part, index) =>
+      index
+        ? part[0].toUpperCase() + part.slice(1).toLowerCase()
+        : part.toLowerCase()
+    )
+    .join("");
+}
+
+function tokenPath(name) {
+  const parts = name.toLowerCase().split("_");
+  if (name.startsWith("COLOR_"))
+    return ["color", camel(parts.slice(1, -1)), parts.at(-1)];
+  if (name.startsWith("NETWORK_COLOR_"))
+    return ["networkColor", parts.slice(2).join("-")];
+  if (name.startsWith("TYPOGRAPHY_FAMILY"))
+    return ["typography", "family", parts.slice(2).join("-") || "family"];
+  if (name.startsWith("TYPOGRAPHY_FONT_SIZE_"))
+    return ["typography", "fontSize", parts.at(-1)];
+  if (name.startsWith("TYPOGRAPHY_LINE_HEIGHT_"))
+    return ["typography", "lineHeight", parts.at(-1)];
+  if (name.startsWith("TYPOGRAPHY_WEIGHT_"))
+    return ["typography", "weight", parts.slice(2).join(" ")];
+  return parts;
+}
+
+function tokenType(root, group) {
+  if (root === "color" || root === "networkColor") return "color";
+  if (root === "motion") return group === "duration" ? "duration" : "string";
+  if (root === "elevation") return "string";
+  if (root === "typography" && group === "family") return "fontFamily";
+  if (root === "typography" && group === "weight") return "fontWeight";
+  return "dimension";
+}
+
+export async function loadSeedsPrimitives() {
+  const tree = {};
+  for (const suffix of packages) {
+    const name = `@sproutsocial/seeds-${suffix}`;
+    const module = await import(name);
+    const values = module.default ?? module;
+    const css = await fs.readFile(
+      require.resolve(`${name}/dist/seeds-${suffix}.css`),
+      "utf8"
+    );
+    const normalize = (name) => name.replace(/[-_]/g, "").toLowerCase();
+    const cssNames = new Map(
+      [...css.matchAll(/(--[a-zA-Z0-9-]+)\s*:/g)].map(([, name]) => [
+        normalize(name),
+        name,
+      ])
+    );
+    for (const [key, value] of Object.entries(values)) {
+      // Composite typography sizes are resolved via their scalar fontSize and
+      // lineHeight tokens. They are not a second theme typography scale.
+      if (typeof value !== "string" && typeof value !== "number") continue;
+      const keys = tokenPath(key);
+      let node = tree;
+      for (const segment of keys.slice(0, -1)) node = node[segment] ??= {};
+      const cssName = cssNames.get(normalize(key));
+      if (!cssName)
+        throw new Error(`${name}: missing published CSS name for ${key}`);
+      node[keys.at(-1)] = {
+        $type: tokenType(keys[0], keys[1]),
+        $value: value,
+        $extensions: { "com.sproutsocial.theme": { cssName } },
+      };
+    }
+  }
+  return tree;
+}