@sproutsocial/seeds-theme 0.1.0

package/mode-authoring.md

@@ -0,0 +1,54 @@
+# Later exploration: light and dark in one file
+
+Keep separate light/dark files for this phase. First establish the recognizable
+Seeds paths, default Sprout values, compatibility exports, and consumer extension
+API. A later authoring format should compile into the same two token graphs.
+
+Three options are worth comparing:
+
+| Option | What the author sees | Tradeoff |
+| --- | --- | --- |
+| Separate mode files (current) | The same familiar tree in light and dark JSON | Simple native merges; compare files side by side |
+| One file with `light` and `dark` sections | Both complete override trees in one document | Easy preprocessing, but still repeats paths |
+| Per-token mode values | Each token shows its light and dark values together | Best local comparison; requires a documented convention and preprocessing |
+
+For example, a **proposed, unsupported** authoring shorthand could be:
+
+```json
+{
+  "colors": {
+    "container": {
+      "background": {
+        "base": {
+          "$type": "color",
+          "$value": "#fff",
+          "$extensions": {
+            "com.sproutsocial.modes": { "dark": "#222" }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+The custom extension above is not built-in Style Dictionary mode syntax. A
+preprocessor would select each mode before inheritance, reference validation,
+and output generation. Style Dictionary supports this kind of
+[preprocessing](https://styledictionary.com/reference/hooks/preprocessors/).
+We would also need to extend JSON Schema completion and prove that partial dark
+overrides, references, and compatibility output remain identical.
+
+The published [DTCG Resolver 2025.10](https://www.designtokens.org/TR/2025.10/resolver/)
+defines contexts such as light and dark, supports inline token sources, and can
+bundle sources into one document. It is the standards-based option to investigate,
+but it does not prescribe a `dark` value beside every token's `$value`. Resolver
+support in our pinned Style Dictionary version and tooling needs a separate
+implementation spike before adoption.
+
+My recommendation for that later spike: compare the per-token shorthand with a
+resolver document using a small set of real Seeds overrides. Keep the public
+extension build API unchanged if either format wins. Today, the documented
+[native `.extend()` API](https://styledictionary.com/reference/api/#extend)
+handles inheritance of the selected light/dark graphs; file organization is a
+separate authoring choice.

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@sproutsocial/seeds-theme",
+  "version": "0.1.0",
+  "description": "Framework-neutral DTCG replacement for the Seeds theme",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "bin": {
+    "seeds-theme": "./src/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "mode-authoring.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./compiler": {
+      "types": "./src/compiler.d.ts",
+      "import": "./src/compiler.js"
+    },
+    "./config": {
+      "types": "./src/config.d.ts",
+      "import": "./src/config.js"
+    },
+    "./styled-components": {
+      "types": "./dist/styled-components/index.d.ts",
+      "import": "./dist/styled-components/index.js",
+      "require": "./dist/styled-components/index.cjs"
+    },
+    "./light": {
+      "types": "./dist/theme-light.d.ts",
+      "import": "./dist/theme-light.js"
+    },
+    "./dark": {
+      "types": "./dist/theme-dark.d.ts",
+      "import": "./dist/theme-dark.js"
+    },
+    "./css/theme": "./dist/theme.css",
+    "./css/theme-light": "./dist/theme-light.css",
+    "./css/theme-dark": "./dist/theme-dark.css",
+    "./css/legacy": "./dist/legacy.css",
+    "./css/legacy-light": "./dist/legacy-light.css",
+    "./css/legacy-dark": "./dist/legacy-dark.css",
+    "./css/shadcn": "./dist/shadcn.css",
+    "./css/shadcn-light": "./dist/shadcn-light.css",
+    "./css/shadcn-dark": "./dist/shadcn-dark.css",
+    "./css/tailwind": "./dist/tailwind.css",
+    "./shadcn/registry": "./dist/shadcn.registry.json",
+    "./json/light": "./dist/theme-light.json",
+    "./json/dark": "./dist/theme-dark.json",
+    "./tokens/light": "./dist/source/theme-light.tokens.json",
+    "./tokens/dark": "./dist/source/theme-dark.tokens.json",
+    "./tokens/shadcn/light": "./dist/source/shadcn-light.tokens.json",
+    "./tokens/shadcn/dark": "./dist/source/shadcn-dark.tokens.json",
+    "./extension": {
+      "types": "./src/extension.d.ts",
+      "import": "./src/extension.js"
+    },
+    "./schema": "./dist/schema.json",
+    "./css-tokens": "./dist/css-tokens.json",
+    "./styled-components/source": "./dist/styled-components/index.ts"
+  },
+  "scripts": {
+    "build": "node build.js && tsx migration/seeds-react-theme/check-css.ts",
+    "clean": "rm -rf .turbo dist",
+    "clean:modules": "rm -rf node_modules",
+    "test": "node build.js && node --test 'test/**/*.test.js'"
+  },
+  "dependencies": {
+    "@sproutsocial/seeds-color": "^2.3.0",
+    "style-dictionary": "5.5.2",
+    "@sproutsocial/seeds-space": "^0.8.1",
+    "@sproutsocial/seeds-border": "^1.7.1",
+    "@sproutsocial/seeds-typography": "^3.8.0",
+    "@sproutsocial/seeds-depth": "^3.6.0",
+    "@sproutsocial/seeds-motion": "^1.8.2",
+    "@sproutsocial/seeds-networkcolor": "^2.22.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/sproutsocial/seeds-packets.git"
+  },
+  "author": "Sprout Social, Inc.",
+  "license": "MIT"
+}

package/src/cli.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { buildProductTheme } from "./config.js";
+
+const usage = `Usage: seeds-theme build [config]
+
+Build a product-owned Seeds theme. The config defaults to
+seeds-theme.config.mjs in the current directory.`;
+
+async function main() {
+  const [command, configArgument] = process.argv.slice(2);
+  if (command === "--help" || command === "-h") {
+    process.stdout.write(`${usage}\n`);
+    return;
+  }
+  if (command !== "build") {
+    throw new Error(usage);
+  }
+
+  const configPath = path.resolve(
+    process.cwd(),
+    configArgument ?? "seeds-theme.config.mjs"
+  );
+  const configModule = await import(pathToFileURL(configPath).href);
+  if (!configModule.default) {
+    throw new Error(`${configPath} must have a default export.`);
+  }
+
+  const outputDirectory = await buildProductTheme(configModule.default, {
+    configDirectory: path.dirname(configPath),
+  });
+  process.stdout.write(
+    `Built ${configModule.default.name} theme in ${outputDirectory}\n`
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+});

package/src/compiler.d.ts

@@ -0,0 +1,9 @@
+import type { ComposedTheme, ThemeSelectors } from "./index.js";
+
+export function buildThemeArtifacts(
+  theme: ComposedTheme,
+  options: {
+    outputDirectory: string;
+    selectors?: ThemeSelectors;
+  }
+): Promise<string[]>;