refactor(config): make internal properties overridable defaults

Rename INTERNAL_PROPERTIES to DEFAULT_PROPERTIES and merge user-configured
properties on top so they can override defaults. Add #clear and #border
color tokens.

Made-with: Cursor

Author: tenphi

.changeset/smooth-pens-wave.md

@@ -0,0 +1,5 @@
+---
+'@tenphi/tasty': patch
+---
+
+Make internal properties overridable via `configure({ properties })` by merging user properties on top of defaults. Add `#clear` (transparent) and `#border` (rgb(0 0 0)) color tokens.

src/compute-styles.ts

@@ -22,12 +22,10 @@ import {
   getConfig,
   getGlobalConfigTokens,
   getGlobalCounterStyle,
+  getEffectiveProperties,
   getGlobalFontFace,
   getGlobalKeyframes,
-  getGlobalProperties,
   hasGlobalKeyframes,
-  hasGlobalProperties,
-  INTERNAL_PROPERTIES,
 } from './config';
 import {
   counterStyle,
@@ -138,21 +136,11 @@ function collectInternalsRSC(rscCache: RSCStyleCache): string {
 
   const parts: string[] = [];
 
-  for (const [token, definition] of Object.entries(INTERNAL_PROPERTIES)) {
+  for (const [token, definition] of Object.entries(getEffectiveProperties())) {
     const css = formatPropertyCSS(token, definition);
     if (css) parts.push(css);
   }
 
-  if (hasGlobalProperties()) {
-    const globalProps = getGlobalProperties();
-    if (globalProps) {
-      for (const [token, definition] of Object.entries(globalProps)) {
-        const css = formatPropertyCSS(token, definition);
-        if (css) parts.push(css);
-      }
-    }
-  }
-
   const tokenStyles = getGlobalConfigTokens();
   if (tokenStyles && Object.keys(tokenStyles).length > 0) {
     const tokenRules = renderStyles(tokenStyles, ':root') as StyleResult[];

src/config.ts

@@ -146,7 +146,11 @@ export interface TastyConfig {
   /**
    * Global CSS @property definitions for custom properties.
    * Keys use tasty token syntax ($name for properties, #name for colors).
-   * Properties are only injected when the component using them is rendered.
+   *
+   * Tasty ships with `DEFAULT_PROPERTIES` (e.g. `$gap`, `$radius`, `#white`,
+   * `#black`, `#clear`, `#border`, etc.) that are always included.
+   * Properties you specify here are merged on top, so you can override any
+   * default by using the same key.
    *
    * For color tokens (#name), `syntax: '<color>'` is auto-set and
    * `initialValue` defaults to `'transparent'` if not specified.
@@ -158,6 +162,8 @@ export interface TastyConfig {
    *     '$rotation': { syntax: '<angle>', initialValue: '0deg' },
    *     '$scale': { syntax: '<number>', inherits: false, initialValue: 1 },
    *     '#accent': { initialValue: 'purple' }, // syntax: '<color>' auto-set
+   *     // Override a default property:
+   *     '$gap': { syntax: '<length>', inherits: true, initialValue: '8px' },
    *   },
    * });
    *
@@ -363,14 +369,14 @@ let globalRecipes: Record<string, RecipeStyles> | null = null;
 let globalConfigTokens: ConfigTokens | null = null;
 
 /**
- * Internal properties required by tasty core features.
- * These are always injected when styles are first generated.
+ * Default properties shipped with tasty.
+ * These are always included unless explicitly overridden via `configure({ properties })`.
  * Keys use tasty token syntax (#name for colors, $name for other properties).
  *
  * For properties with CSS @property-compatible types (length, time, number, color),
  * an `initialValue` is provided so the property works even without a project-level token.
  */
-export const INTERNAL_PROPERTIES: Record<string, PropertyDefinition> = {
+export const DEFAULT_PROPERTIES: Record<string, PropertyDefinition> = {
   // Used by dual-fill feature to enable CSS transitions on the second fill color
   '#tasty-second-fill': {
     inherits: false,
@@ -390,6 +396,16 @@ export const INTERNAL_PROPERTIES: Record<string, PropertyDefinition> = {
     inherits: true,
     initialValue: 'rgb(0 0 0)',
   },
+  // Shorthand for transparent
+  '#clear': {
+    inherits: true,
+    initialValue: 'transparent',
+  },
+  // Default border color
+  '#border': {
+    inherits: true,
+    initialValue: 'rgb(0 0 0)',
+  },
 
   // ---- Core design tokens used by style handlers ----
   // These provide sensible defaults so tasty works standalone without a design system.
@@ -530,19 +546,11 @@ export function markStylesGenerated(): void {
 
   const injector = getGlobalInjector();
 
-  // Inject internal properties required by tasty core features
-  for (const [token, definition] of Object.entries(INTERNAL_PROPERTIES)) {
+  // Inject all properties (defaults merged with user-configured overrides)
+  for (const [token, definition] of Object.entries(getEffectiveProperties())) {
     injector.property(token, definition);
   }
 
-  // Inject global properties if any were configured
-  // Properties are permanent and only need to be injected once
-  if (globalProperties && Object.keys(globalProperties).length > 0) {
-    for (const [token, definition] of Object.entries(globalProperties)) {
-      injector.property(token, definition);
-    }
-  }
-
   // Inject global @font-face rules (eagerly — fonts should be available before render)
   if (globalFontFace && Object.keys(globalFontFace).length > 0) {
     for (const [family, input] of Object.entries(globalFontFace)) {
@@ -667,6 +675,15 @@ function setGlobalProperties(
   globalProperties = properties;
 }
 
+/**
+ * Get the effective properties: DEFAULT_PROPERTIES merged with user-configured
+ * properties. User properties override defaults with matching keys.
+ */
+export function getEffectiveProperties(): Record<string, PropertyDefinition> {
+  if (!globalProperties) return DEFAULT_PROPERTIES;
+  return { ...DEFAULT_PROPERTIES, ...globalProperties };
+}
+
 // ============================================================================
 // Global Font Face Management
 // ============================================================================

src/ssr/collector.ts

@@ -11,12 +11,10 @@
  */
 
 import {
+  getEffectiveProperties,
   getGlobalCounterStyle,
   getGlobalFontFace,
-  getGlobalProperties,
   getGlobalConfigTokens,
-  hasGlobalProperties,
-  INTERNAL_PROPERTIES,
 } from '../config';
 import { formatCounterStyleRule } from '../counter-style';
 import { fontFaceContentHash, formatFontFaceRule } from '../font-face';
@@ -70,22 +68,12 @@ export class ServerStyleCollector {
     if (this.internalsCollected) return;
     this.internalsCollected = true;
 
-    for (const [token, definition] of Object.entries(INTERNAL_PROPERTIES)) {
+    for (const [token, definition] of Object.entries(
+      getEffectiveProperties(),
+    )) {
       const css = formatPropertyCSS(token, definition);
       if (css) {
-        this.collectProperty(`__internal:${token}`, css);
-      }
-    }
-
-    if (hasGlobalProperties()) {
-      const globalProps = getGlobalProperties();
-      if (globalProps) {
-        for (const [token, definition] of Object.entries(globalProps)) {
-          const css = formatPropertyCSS(token, definition);
-          if (css) {
-            this.collectProperty(`__global:${token}`, css);
-          }
-        }
+        this.collectProperty(`__prop:${token}`, css);
       }
     }
 

src/ssr/ssr.test.ts

@@ -288,7 +288,7 @@ describe('ServerStyleCollector', () => {
     collector.collectInternals();
 
     const css = collector.getCSS();
-    // INTERNAL_PROPERTIES: gap, radius, border-width, font fallbacks, etc.
+    // DEFAULT_PROPERTIES: gap, radius, border-width, font fallbacks, etc.
     expect(css).toContain('@property --gap');
     expect(css).toContain('@property --radius');
     expect(css).toContain('@property --border-width');