feat: extract theme.vars into theme.cssVariables and `theme.cssVa…

…riablePrefix` for improved clarity

packages/react-docs/pages/getting-started/css-variables/default-css-variables.js

@@ -17,7 +17,7 @@ const App = () => {
 
   return (
     <Box fontFamily="mono">
-      {Object.entries(theme?.vars).map(([name, value]) => {
+      {Object.entries(theme?.cssVariables).map(([name, value]) => {
         if (!name.startsWith('--')) {
           return null;
         }

packages/react/src/theme/CSSVariables.js

@@ -1,14 +1,18 @@
 import { Global } from '@emotion/react';
-import { ensureArray } from 'ensure-type';
+import { ensureArray, ensurePlainObject } from 'ensure-type';
 import React, { useCallback } from 'react';
 
 const CSSVariables = ({
   root = [':root', ':host'],
 }) => {
   const styles = useCallback((theme) => {
+    const cssVariables = ensurePlainObject(theme?.cssVariables);
+    if (Object.keys(cssVariables) === 0) {
+      return {};
+    }
     const selector = ensureArray(root).join(',');
     return {
-      [selector]: { ...theme?.vars },
+      [selector]: cssVariables,
     };
   }, [root]);
 

packages/react/src/theme/__tests__/createTheme.test.js

@@ -1,22 +1,26 @@
 import createTheme from '../createTheme';
 
 describe('createTheme', () => {
+  const defaultThemeScales = [
+    'borders',
+    'breakpoints',
+    'colors',
+    'fonts',
+    'fontSizes',
+    'fontWeights',
+    'letterSpacings',
+    'lineHeights',
+    'outlines',
+    'radii',
+    'shadows',
+    'sizes',
+    'space',
+    'zIndices',
+  ];
+
   it('should create a default theme', () => {
     const theme = createTheme();
-    expect(theme).toHaveProperty('borders');
-    expect(theme).toHaveProperty('breakpoints');
-    expect(theme).toHaveProperty('colors');
-    expect(theme).toHaveProperty('fonts');
-    expect(theme).toHaveProperty('fontSizes');
-    expect(theme).toHaveProperty('fontWeights');
-    expect(theme).toHaveProperty('letterSpacings');
-    expect(theme).toHaveProperty('lineHeights');
-    expect(theme).toHaveProperty('outlines');
-    expect(theme).toHaveProperty('radii');
-    expect(theme).toHaveProperty('shadows');
-    expect(theme).toHaveProperty('sizes');
-    expect(theme).toHaveProperty('space');
-    expect(theme).toHaveProperty('zIndices');
+    defaultThemeScales.forEach(scale => expect(theme).toHaveProperty(scale));
   });
 
   it('should merge custom theme options', () => {
@@ -41,20 +45,36 @@ describe('createTheme', () => {
 
   it('should not generate CSS variables with default configuration', () => {
     const theme = createTheme();
-    expect(theme.vars).not.toBeDefined();
+    expect(theme.cssVariables).not.toBeDefined();
   });
 
   it('should generate CSS variables', () => {
     const theme = createTheme({ cssVariables: true });
-    expect(theme.vars).toBeDefined();
-    expect(theme.vars.prefix).toBe('tonic');
-    expect(Object.keys(theme.vars).filter(x => x.startsWith('--'))[0]).toMatch(/^--tonic-/);
+    expect(theme.cssVariables).toBeDefined();
+    expect(theme.cssVariablePrefix).toBe('tonic');
+    const cssVariableKeys = Object.keys(theme.cssVariables).filter(x => x.startsWith('--'));
+    expect(cssVariableKeys.length).toBeGreaterThan(0);
+    expect(cssVariableKeys[0]).toMatch(/^--tonic-/);
   });
 
   it('should apply custom prefix to CSS variables', () => {
     const theme = createTheme({ cssVariables: { prefix: 'custom' } });
-    expect(theme.vars).toBeDefined();
-    expect(theme.vars.prefix).toBe('custom');
-    expect(Object.keys(theme.vars).filter(x => x.startsWith('--'))[0]).toMatch(/^--custom-/);
+    expect(theme.cssVariables).toBeDefined();
+    expect(theme.cssVariablePrefix).toBe('custom');
+    const cssVariableKeys = Object.keys(theme.cssVariables).filter(x => x.startsWith('--'));
+    expect(cssVariableKeys.length).toBeGreaterThan(0);
+    expect(cssVariableKeys[0]).toMatch(/^--custom-/);
+  });
+
+  it('should allow an empty prefix for CSS variables', () => {
+    const theme = createTheme({ cssVariables: { prefix: '' } });
+    expect(theme.cssVariables).toBeDefined();
+    expect(theme.cssVariablePrefix).toBe('');
+    const cssVariableKeys = Object.keys(theme.cssVariables).filter(x => x.startsWith('--'));
+    expect(cssVariableKeys.length).toBeGreaterThan(0);
+    cssVariableKeys.forEach(key => {
+      const isValid = defaultThemeScales.some(scale => key.startsWith(`--${scale}`));
+      expect(isValid).toBe(true);
+    });
   });
 });

packages/react/src/theme/createTheme.js

@@ -48,10 +48,8 @@ const createTheme = (options = {}, ...args) => {
 
     // Merge CSS variables into the theme
     theme = merge(theme, {
-      vars: {
-        prefix: cssVariablePrefix,
-        ...cssVariables,
-      },
+      cssVariablePrefix,
+      cssVariables,
     });
   }
 

packages/styled-system/src/__tests__/sx.test.js

@@ -280,8 +280,8 @@ const defaultTheme = {
 test('should pass', () => {
   const theme = {
     ...defaultTheme,
-    vars: {
-      prefix: 'tonic',
+    cssVariablePrefix: 'tonic',
+    cssVariables: {
       '--tonic-borders-1': '.0625rem solid',
       '--tonic-borders-2': '.125rem solid',
       '--tonic-borders-3': '.1875rem solid',

packages/styled-system/src/config/__tests__/margin.test.js

@@ -7,8 +7,8 @@ const defaultTheme = {
 
 const defaultThemeWithCSSVariables = {
   ...defaultTheme,
-  vars: {
-    prefix: 'tonic',
+  cssVariablePrefix: 'tonic',
+  cssVariables: {
     '--tonic-breakpoints-0': '40em',
     '--tonic-breakpoints-1': '52em',
     '--tonic-breakpoints-2': '64em',

packages/styled-system/src/config/__tests__/position.test.js

@@ -6,8 +6,8 @@ const defaultTheme = {
 
 const defaultThemeWithCSSVariables = {
   ...defaultTheme,
-  vars: {
-    prefix: 'tonic',
+  cssVariablePrefix: 'tonic',
+  cssVariables: {
     '--tonic-space-0': 0,
     '--tonic-space-1': 4,
     '--tonic-space-2': 8,

packages/styled-system/src/utils/toCSSVariable.js → packages/styled-system/src/utils/css-vars.js

@@ -8,7 +8,7 @@
  *
  * @return {string} The CSS variable name.
 */
-const toCSSVariable = (name, options) => {
+export const toCSSVariable = (name, options) => {
   const {
     prefix = '',
     delimiter = '-',
@@ -19,5 +19,3 @@ const toCSSVariable = (name, options) => {
     .replace(/^-+|-+$/g, ''); // trim hyphens from beginning and end of string
   return `--${variableName}`;
 };
-
-export default toCSSVariable;

packages/styled-system/src/utils/transforms.js

@@ -1,5 +1,5 @@
 import get from './get';
-import toCSSVariable from './toCSSVariable';
+import { toCSSVariable } from './css-vars';
 
 // Check if a value is a simple CSS variable
 // e.g. var(--tonic-spacing-1)
@@ -11,11 +11,10 @@ const isSimpleCSSVariable = (value) => {
 // Negate the value, handling CSS variables and numeric values
 const toNegativeValue = (scale, absoluteValue, options) => {
   const theme = options?.props?.theme;
-  const hasCSSVariables = !!theme?.vars; // Defaults to false
   const n = getter(scale, absoluteValue, options);
 
   // Handle CSS variables for negative values
-  if (hasCSSVariables && isSimpleCSSVariable(n)) {
+  if (!!theme?.cssVariables && isSimpleCSSVariable(n)) {
     // https://stackoverflow.com/questions/49469344/using-negative-css-custom-properties
     return `calc(0px - ${n})`;
   }
@@ -30,15 +29,14 @@ const toNegativeValue = (scale, absoluteValue, options) => {
 
 export const getter = (scale, value, options) => {
   const theme = options?.props?.theme;
-  const hasCSSVariables = !!theme?.vars; // Defaults to false
   const result = get(scale, value);
 
-  if (result !== undefined && hasCSSVariables) {
-    // TODO: `theme?.config?.prefix` and `theme?.__cssVariableMap` are deprecated and will be removed in the next major release
+  if (result !== undefined && !!theme?.cssVariables) {
+    // TODO: `theme.config.prefix` and `theme.__cssVariableMap` are deprecated and will be removed in the next major release
     const cssVariablePrefixFallback = theme?.config?.prefix;
-    const cssVariablePrefix = (theme?.vars?.prefix) ?? cssVariablePrefixFallback;
+    const cssVariablePrefix = (theme?.cssVariablePrefix) ?? cssVariablePrefixFallback;
     const cssVariablesFallback = theme?.__cssVariableMap;
-    const cssVariables = (theme?.vars) ?? cssVariablesFallback;
+    const cssVariables = (theme?.cssVariables) ?? cssVariablesFallback;
     const contextScale = options?.context?.scale;
     const cssVariable = toCSSVariable(
       // | contextScale | value     |