@sproutsocial/seeds-theme 0.1.0

package/README.md

@@ -0,0 +1,259 @@
+# @sproutsocial/seeds-theme
+
+Seeds provides the default Sprout appearance in light and dark mode. It also
+provides defaults for shadcn variable names such as `--background`, `--primary`,
+and `--card`. Applications can use these defaults immediately and override only
+what differs in their product theme.
+
+## Choose an entry point
+
+The descriptions below distinguish theme values from the Tailwind configuration
+that makes those values available through utility classes. Import paths shown
+here are relative to `@sproutsocial/seeds-theme`.
+
+| Import               | What to call it                        | What it does                                                                                                                                   |
+| -------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/css/theme`         | **Seeds theme defaults**               | Provides light and dark values for familiar Seeds variables and all shadcn names in the package's mapping. This is the normal CSS entry point. |
+| `/css/tailwind`      | **Tailwind utility mappings**          | Connects utilities such as `bg-primary` and `text-foreground` to the shadcn variables. It contains no light/dark color choices.                |
+| `/css/shadcn`        | **Seeds defaults + Tailwind mappings** | Convenience entry point importing the two files above. It does not define another theme. Choose this or the two explicit imports.              |
+| `/schema`            | **Theme override autocomplete**        | Describes supported token paths, types, and references for editors. It is JSON Schema, not CSS and not a set of theme values.                  |
+| `/extension`         | **Product theme builder**              | Builds one CSS file containing a product's light/dark overrides. Unchanged values inherit Seeds.                                               |
+| `/css/legacy`        | **Historical Seeds CSS names**         | Preserves CSS variable names and behavior needed by existing integrations.                                                                     |
+| `/styled-components` | **Existing React theme objects**       | Supplies the compatibility objects used by `seeds-react-theme`. Existing applications keep their current `seeds-react-theme` imports.          |
+
+For a shadcn application, use `/css/shadcn` after the required primitive
+stylesheets shown below. If the application already has equivalent Tailwind
+mappings, use `/css/theme` and keep that mapping in one place.
+
+## How theme defaults and Tailwind mappings work together
+
+Seeds assigns the light/dark values. The Tailwind mapping connects a utility
+name to a variable, and that connection stays the same in both modes:
+
+```text
+bg-primary
+  → --primary                              shadcn variable
+  → --colors-button-primary-background-base  Seeds theme choice
+  → --color-blue-700                       existing design token (light default)
+```
+
+For example, `tailwind.css` contains:
+
+```css
+@theme inline {
+  --color-primary: var(--primary);
+}
+```
+
+Tailwind uses this to generate `bg-primary` with
+`background-color: var(--primary)`. When the root receives `.dark`, the theme
+changes the underlying value and the same utility follows it. There is no
+separate dark Tailwind mapping file to load. The `@custom-variant dark` rule also
+enables explicit `dark:*` utilities for cases that need a different CSS rule.
+
+Product CSS can remap a shadcn variable directly. The current JSON authoring API
+and autocomplete expose the familiar Seeds paths; changing
+`colors.button.primary.background.base` changes the default `--primary` value.
+Direct shadcn-name overrides in the JSON authoring API are a separate, pending
+improvement. The shadcn light/dark defaults are already provided.
+
+## Read and edit the theme
+
+Start with these three source files:
+
+- [tokens/base.tokens.json](tokens/base.tokens.json): **shared theme choices**,
+  used in both modes and referencing the existing design-token packages.
+- [tokens/light.tokens.json](tokens/light.tokens.json): **light-mode theme choices**.
+- [tokens/dark.tokens.json](tokens/dark.tokens.json): **dark-mode theme choices**.
+
+The paths mirror the existing object API. `theme.colors.container.background.base`
+becomes `colors.container.background.base` in the token file. Button states,
+form colors, navigation, listening, growth, and the other Sprout additions use
+their existing names. The `theme` wrapper is unnecessary inside a theme file.
+
+```json
+{
+  "colors": {
+    "$type": "color",
+    "container": {
+      "background": {
+        "base": { "$value": "{color.neutral.0}" }
+      }
+    }
+  }
+}
+```
+
+Existing design-token packages own palette, spacing, typography, border, depth,
+and motion values. The compiler reads their public exports for reference
+resolution; the theme does not author a second set of those values. `color`
+(singular) references the existing palette; `colors` contains familiar theme roles.
+Declare `$type` once on a group. Leaves inherit it; exceptional values such as
+color gradients declare `$type: "string"`.
+
+Modern CSS, JSON, JavaScript, and token outputs contain theme roles and shadcn
+aliases, without exporting the underlying primitive scales. Historical palette,
+spacing, and typography fields exist only in the compatibility output, with
+[compatibility/scales.tokens.json](compatibility/scales.tokens.json) mapping their
+old paths to the existing packages by reference.
+
+The two historical `colors.gradient.ai-stop-2` colors have no exact palette
+match. They remain documented, theme-owned tokens in light and dark, each
+authored once and referenced by both gradient expressions. Other gradient stops
+and alpha colors reference existing tokens; no nearby colors are substituted.
+Every historical compatibility value is retained, including arrays, numeric
+values, CSS expressions, and alpha spelling. The files use Style Dictionary's DTCG-style `$type` / `$value`
+authoring conventions; historical CSS color and dimension strings are preserved.
+They are not a claim of strict DTCG 2025 composite-value conformance.
+
+## Load the theme defaults
+
+```css
+/* Include each primitive stylesheet once, if the app does not already load it. */
+@import "@sproutsocial/seeds-color/dist/seeds-color.css";
+@import "@sproutsocial/seeds-border/dist/seeds-border.css";
+@import "@sproutsocial/seeds-depth/dist/seeds-depth.css";
+@import "@sproutsocial/seeds-theme/css/theme";
+```
+
+The theme import includes both modes and the Seeds-provided defaults for shadcn's CSS variable names. Add `.dark` to the root
+for dark mode. Seeds remains the baseline when a product theme is selected with
+`data-theme`, so a product can override only the values it needs.
+
+`colors.container.background.base` generates
+`--colors-container-background-base: var(--color-neutral-0)` in light mode.
+The shadcn `--card` variable references that theme role. The primitive declaration
+itself remains in `seeds-color`.
+[tokens/adapters/css.json](tokens/adapters/css.json) is a name-to-token mapping;
+it contains no independently authored color values.
+
+For Tailwind v4, add the utility mappings with
+`@sproutsocial/seeds-theme/css/tailwind`, or replace the theme import with
+`@sproutsocial/seeds-theme/css/shadcn` to load defaults and mappings together. Concrete colors
+owned by the theme use Style Dictionary's OKLCH transform. Existing colors stay
+live references to `seeds-color`; applications can alternatively load its
+`seeds-color-oklch.css` output. Additional references to space, typography, motion,
+or network tokens require the corresponding package's CSS too. Importing a
+package's JavaScript values alone does not load its stylesheet.
+
+## Author product theme overrides
+
+Author `light.tokens.json` and `dark.tokens.json`. Each file contains only its
+mode's overrides, using the same familiar paths:
+
+```json
+{
+  "$schema": "./node_modules/@sproutsocial/seeds-theme/dist/schema.json",
+  "colors": {
+    "$type": "color",
+    "container": {
+      "background": {
+        "base": { "$value": "{color.neutral.100}" }
+      }
+    }
+  }
+}
+```
+
+Adjust `$schema` relative to the file's directory. The published `/schema` is
+generated from the actual Seeds tokens; editors complete the existing nested
+names and expected types. Use `{colors.button.primary.background.base}` references
+instead of CSS `var()` expressions when making tokens depend on one another.
+The schema also completes reference values such as `{color.blue.400}` and
+`{space.size.300}`. Primitive tokens are read-only inputs: reference them rather
+than overriding them. Reserve `product` for genuinely new product-owned tokens;
+do not copy a palette that already exists.
+
+```js
+import fs from "node:fs/promises";
+import { buildThemeExtension } from "@sproutsocial/seeds-theme/extension";
+
+const read = async (file) => JSON.parse(await fs.readFile(file, "utf8"));
+await buildThemeExtension(
+  {
+    name: "sprout-one",
+    extends: "seeds",
+    modes: {
+      light: await read("themes/sprout-one/light.tokens.json"),
+      dark: await read("themes/sprout-one/dark.tokens.json"),
+    },
+  },
+  { outputFile: "src/styles/sprout-one.css" }
+);
+```
+
+Import Seeds CSS once and the generated product CSS after it. Select the product
+with `<html data-theme="sprout-one">`; add `.dark` independently for dark mode.
+The builder validates paths, types, mode coverage, references, and cycles, then
+uses Style Dictionary's native `.extend()`. Its `extends: "seeds"` option chooses
+the Seeds baseline; it is not the DTCG `$extends` group property.
+
+Only changed declarations are emitted. Aliases remain CSS references, and dark
+mode restores an inherited value when a light-only product override would hide it.
+Product selectors outrank both Seeds baseline blocks regardless of import order.
+An optional `common` object is supported, but two mode files are sufficient.
+
+## Existing styled-components consumers
+
+Keep using `@sproutsocial/seeds-react-theme` exactly as today. Its `theme`,
+`darkTheme`, `sproutLightTheme`, and `sproutDarkTheme` exports retain their values,
+shapes, array properties, and shared object identities. The old base `theme`
+export remains its historical subset; it does not acquire the Sprout-only keys.
+
+`@sproutsocial/seeds-theme/styled-components` supplies those compatibility
+objects. `seeds-react-theme` embeds the generated `/styled-components/source`
+at build time, so existing consumers do not acquire a runtime dependency on
+Style Dictionary or its newer Node requirement. [compatibility/seeds-paths.json](compatibility/seeds-paths.json) and
+[compatibility/sprout-paths.json](compatibility/sprout-paths.json) contain only
+historical paths. Their values come from the canonical theme references and compatibility bindings into existing design-token packages.
+Pre-migration snapshots exist only under `test/fixtures/legacy` as independent
+regression fixtures.
+
+Historical `--color-*` names and selectors remain available through `/css/legacy`,
+`/css/legacy-light`, and `/css/legacy-dark`. Those outputs retain their original
+strings and require the historical `seeds-color` primitive CSS. They are checked
+against the full Sprout objects during the package build.
+
+## Additional build outputs
+
+Everything in `dist` is generated. Edit the authored token files above and
+rebuild; do not edit the generated files. Most applications only need the entry
+points in the first table.
+
+- **Separate mode defaults:** `theme-light.css` and `theme-dark.css` contain
+  complete per-mode declarations. Their `shadcn-*` wrappers add Tailwind mappings.
+  Normal applications use the combined theme entry point instead.
+- **Theme token definitions:** `source/*.tokens.json` retain references and
+  metadata for the compiler and extension builder.
+- **Resolved theme values:** `theme-*.json` contain nested values;
+  `theme-*.js` contain flattened constants. Their `.d.ts` files describe those
+  constants. These are concrete snapshots rather than live CSS references, and
+  the JavaScript constants are not the styled-components theme objects.
+- **Compatibility build input:** `styled-components/index.ts` is copied into
+  `seeds-react-theme` during its build. The neighboring `.js`, `.cjs`, and `.d.ts`
+  files provide the existing theme objects in the supported module formats.
+- **Shadcn mapping metadata:** `css-tokens.json` records which Seeds token supplies
+  each shadcn variable. `shadcn.registry.json` is for registry distribution.
+
+`/tokens/light` and `/tokens/dark` expose composed token graphs for tooling.
+`/json/light`, `/json/dark`, `/light`, and `/dark` expose Style Dictionary's
+resolved JSON or JavaScript outputs. `/css-tokens` exposes the shadcn alias map;
+`/shadcn/registry` supplies a shadcn registry theme.
+
+The lower-level `/config` API and CLI can build a complete product package with
+custom selectors and an output manifest. The `/extension` example above is the
+normal consumer API for sparse overrides.
+
+## Verification and scope
+
+Run `yarn workspace @sproutsocial/seeds-theme test` and
+`yarn workspace @sproutsocial/seeds-theme build`. Tests compare all four generated
+compatibility objects with independent historical fixtures, check inheritance and
+CSS references, and verify light/dark output. They also reject copied primitive
+values, duplicate primitive output, missing CSS references, and primitive
+overrides. The build checks legacy CSS parity.
+
+Experience Platform integration is a later phase. Its extra component aliases,
+layout choices, preference migration, and CSS file removal are not part of this
+package's theme model. A combined light/dark authoring format is also deferred;
+see [mode-authoring.md](mode-authoring.md) for the options.

package/dist/css-tokens.json

@@ -0,0 +1,134 @@
+{
+  "background": {
+    "path": "colors.app.background.base",
+    "$description": "Background CSS alias for colors.app.background.base."
+  },
+  "foreground": {
+    "path": "colors.text.body",
+    "$description": "Foreground CSS alias for colors.text.body."
+  },
+  "card": {
+    "path": "colors.container.background.base",
+    "$description": "Card CSS alias for colors.container.background.base."
+  },
+  "card-foreground": {
+    "path": "colors.text.headline",
+    "$description": "Card foreground CSS alias for colors.text.headline."
+  },
+  "popover": {
+    "path": "colors.container.background.base",
+    "$description": "Popover CSS alias for colors.container.background.base."
+  },
+  "popover-foreground": {
+    "path": "colors.text.body",
+    "$description": "Popover foreground CSS alias for colors.text.body."
+  },
+  "primary": {
+    "path": "colors.button.primary.background.base",
+    "$description": "Primary CSS alias for colors.button.primary.background.base."
+  },
+  "primary-foreground": {
+    "path": "colors.button.primary.text.base",
+    "$description": "Primary foreground CSS alias for colors.button.primary.text.base."
+  },
+  "secondary": {
+    "path": "colors.container.border.base",
+    "$description": "Secondary CSS alias for colors.container.border.base."
+  },
+  "secondary-foreground": {
+    "path": "colors.text.body",
+    "$description": "Secondary foreground CSS alias for colors.text.body."
+  },
+  "muted": {
+    "path": "colors.container.background.decorative.neutral",
+    "$description": "Muted CSS alias for colors.container.background.decorative.neutral."
+  },
+  "muted-foreground": {
+    "path": "colors.text.subtext",
+    "$description": "Muted foreground CSS alias for colors.text.subtext."
+  },
+  "accent": {
+    "path": "colors.listItem.background.hover",
+    "$description": "Accent CSS alias for colors.listItem.background.hover."
+  },
+  "accent-foreground": {
+    "path": "colors.text.body",
+    "$description": "Accent foreground CSS alias for colors.text.body."
+  },
+  "destructive": {
+    "path": "colors.button.destructive.background.base",
+    "$description": "Destructive CSS alias for colors.button.destructive.background.base."
+  },
+  "destructive-foreground": {
+    "path": "colors.button.destructive.text.base",
+    "$description": "Destructive foreground CSS alias for colors.button.destructive.text.base."
+  },
+  "border": {
+    "path": "colors.container.border.base",
+    "$description": "Border CSS alias for colors.container.border.base."
+  },
+  "input": {
+    "path": "colors.form.border.base",
+    "$description": "Input CSS alias for colors.form.border.base."
+  },
+  "ring": {
+    "path": "colors.form.border.selected",
+    "$description": "Ring CSS alias for colors.form.border.selected."
+  },
+  "radius": {
+    "path": "radii.inner",
+    "$description": "Radius CSS alias for radii.inner."
+  },
+  "sidebar": {
+    "path": "colors.navigation.main.background.base",
+    "$description": "Sidebar CSS alias for colors.navigation.main.background.base."
+  },
+  "sidebar-foreground": {
+    "path": "colors.navigation.text.base",
+    "$description": "Sidebar foreground CSS alias for colors.navigation.text.base."
+  },
+  "sidebar-primary": {
+    "path": "colors.navigation.listItem.background.selected",
+    "$description": "Sidebar primary CSS alias for colors.navigation.listItem.background.selected."
+  },
+  "sidebar-primary-foreground": {
+    "path": "colors.navigation.text.base",
+    "$description": "Sidebar primary foreground CSS alias for colors.navigation.text.base."
+  },
+  "sidebar-accent": {
+    "path": "colors.navigation.listItem.background.hover",
+    "$description": "Sidebar accent CSS alias for colors.navigation.listItem.background.hover."
+  },
+  "sidebar-accent-foreground": {
+    "path": "colors.navigation.text.hover",
+    "$description": "Sidebar accent foreground CSS alias for colors.navigation.text.hover."
+  },
+  "sidebar-border": {
+    "path": "colors.navigation.main.border.base",
+    "$description": "Sidebar border CSS alias for colors.navigation.main.border.base."
+  },
+  "sidebar-ring": {
+    "path": "colors.form.border.selected",
+    "$description": "Sidebar ring CSS alias for colors.form.border.selected."
+  },
+  "chart-1": {
+    "path": "colors.dataviz.map.1",
+    "$description": "Chart 1 CSS alias for colors.dataviz.map.1."
+  },
+  "chart-2": {
+    "path": "colors.dataviz.map.2",
+    "$description": "Chart 2 CSS alias for colors.dataviz.map.2."
+  },
+  "chart-3": {
+    "path": "colors.dataviz.map.3",
+    "$description": "Chart 3 CSS alias for colors.dataviz.map.3."
+  },
+  "chart-4": {
+    "path": "colors.dataviz.map.4",
+    "$description": "Chart 4 CSS alias for colors.dataviz.map.4."
+  },
+  "chart-5": {
+    "path": "colors.dataviz.map.5",
+    "$description": "Chart 5 CSS alias for colors.dataviz.map.5."
+  }
+}