@splenddev/kreativ-core 0.1.0 → 0.1.1

package/README.md

@@ -61,13 +61,13 @@ Kreativ Core   tokens · semantic tokens · typography · sizes · recipes
                themes · validation · CSS variables · component metadata · React runtime
       │
       ▼
-Kreativ UI     components + the default design language
+Kreativ UI     components + the default design language + extend*() helpers
       │
       ▼
 Your app
 ```
 
-Use Kreativ UI to build apps. Reach for Core when you're building your own design system or tooling on the same foundation. Defaults (tokens, sizes, typography, recipes) belong to Kreativ UI, never to Core.
+Use Kreativ UI to build apps. Reach for Core when you're building your own design system or tooling on the same foundation. Defaults (tokens, sizes, typography, recipes) belong to Kreativ UI, never to Core — and because "extending" means merging against _some_ default, the `extendTokens()`, `extendSemanticTokens()`, `extendTypography()`, `extendSizes()`, and `extendRecipes()` helpers live in Kreativ UI too. Core only ships the `defineX` functions that build a layer from scratch. See [Using Core standalone](#using-core-standalone) if you want that extend pattern without Kreativ UI.
 
 ### Providers
 
@@ -195,7 +195,7 @@ const theme = defineTheme({
 
 `defineTheme()` keeps the exact shape you pass in while validating the relationships between layers. Metadata fields are `name`, `description`, `author`, and `source`, all optional.
 
-#### Overriding and extending
+#### Overriding
 
 Customize an existing theme with a `ThemeOverride`:
 
@@ -209,7 +209,7 @@ const override = {
 };
 ```
 
-Or extend one layer at a time with `extendTokens()`, `extendSemanticTokens()`, `extendTypography()`, `extendSizes()`, and `extendRecipes()`.
+Core itself doesn't merge an override against a default theme for you — there's no default theme to merge against here. That's what Kreativ UI's `extendTokens()`, `extendSemanticTokens()`, `extendTypography()`, `extendSizes()`, and `extendRecipes()` do, one layer at a time, against its built-in defaults. If you're not using Kreativ UI, see below.
 
 ### Validation
 
@@ -241,6 +241,13 @@ colors.brand     →  --kui-brand
                     --kui-intensity
 ```
 
+`tokensToCssVars` takes an optional `prefix` argument (default `"kui"`), so you can generate variables under your own namespace instead:
+
+```ts
+tokensToCssVars(resolved, "light", theme.intensity, "myds");
+// --myds-brand, --myds-mode, --myds-intensity, ...
+```
+
 Color values are normalized to RGB channels where appropriate, so the variables work with modern color-manipulation patterns.
 
 ### ThemeProvider
@@ -342,6 +349,31 @@ A component is controlled when `value` is defined. In controlled mode, `setValue
 
 Responsive styles are generated from the active theme's breakpoint tokens, so components never hard-code breakpoints. The generated rules come back together with a data attribute that scopes them to the element.
 
+## Using Core standalone
+
+Core ships the `defineX` functions (`defineTokens`, `defineSemanticToken`, `defineTypography`, `defineSizes`, `defineRecipe`, `defineTheme`) but no built-in defaults, and no `extendX` helpers — those are a Kreativ UI concern, since "extending" means merging an override against _some_ default set, and Core doesn't ship one.
+
+If you're building your own design system on Core, define your own defaults once, then write small `extend` wrappers over them the same way Kreativ UI does internally:
+
+```ts
+import { defineTokens, deepMerge } from "@splenddev/kreativ-core";
+import type {
+  DesignTokens,
+  ThemeOverride,
+} from "@splenddev/kreativ-core/types";
+
+const defaultTokens = defineTokens({
+  colors: { blue: { 500: "#3b82f6", 600: "#2563eb" } },
+  spacing: { sm: "0.5rem", md: "1rem" },
+});
+
+export function extendTokens(override?: ThemeOverride["tokens"]): DesignTokens {
+  return deepMerge(defaultTokens, override);
+}
+```
+
+The same pattern applies to `defineSemanticToken`, `defineTypography`, `defineSizes`, and `defineRecipe` — define the default layer, then merge overrides against it with `deepMerge` (for tokens) or a small per-key merge (for typography, sizes, and recipes, where overrides should merge one level deep rather than replace the whole entry).
+
 ## Design principles
 
 - **Tokens before components.** Components consume the design system; they don't invent their own visual language.
@@ -349,7 +381,7 @@ Responsive styles are generated from the active theme's breakpoint tokens, so co
 - **Strict primitives, flexible semantics.** Primitives stay terminal; semantic tokens do the referencing.
 - **Metadata is part of the contract.** A component's role, relationships, and supported states are described to tooling, not just rendered.
 - **Predictable composition.** Prop merging, theme extension, recipe resolution, and token resolution all follow explicit precedence.
-- **Defaults belong to the implementation.** Core defines the system; Kreativ UI defines the look.
+- **Defaults belong to the implementation.** Core defines the system; Kreativ UI defines the look — and owns the `extendX` helpers that merge against that look.
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@splenddev/kreativ-core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Design-system foundation for Kreativ UI — tokens, theming, recipes, and component primitives.",
   "type": "module",
   "main": "./dist/index.cjs",