Rename 'createThemeVars' to 'createThemeContract' (#52)

Author: markdalgleish

.changeset/thirty-peas-dance.md

@@ -0,0 +1,26 @@
+---
+'@vanilla-extract/babel-plugin': minor
+'@vanilla-extract/css': minor
+---
+
+Rename `createThemeVars` to `createThemeContract`
+
+**BREAKING CHANGE**
+
+```diff
+import {
+-  createThemeVars,
++  createThemeContract,
+  createTheme
+} from '@vanilla-extract/css';
+
+-export const vars = createThemeVars({
++export const vars = createThemeContract({
+  color: {
+    brand: null
+  },
+  font: {
+    body: null
+  }
+});
+```

README.md

@@ -41,7 +41,7 @@ Basically, it’s [“CSS Modules](https://github.com/css-modules/css-modules)-i
 
 import { createTheme, style } from '@vanilla-extract/css';
 
-export const [themeClass, themeVars] = createTheme({
+export const [themeClass, vars] = createTheme({
   color: {
     brand: 'blue'
   },
@@ -51,8 +51,8 @@ export const [themeClass, themeVars] = createTheme({
 });
 
 export const exampleStyle = style({
-  backgroundColor: themeVars.color.brand,
-  fontFamily: themeVars.font.body,
+  backgroundColor: vars.color.brand,
+  fontFamily: vars.font.body,
   color: 'white',
   padding: 10
 });
@@ -86,7 +86,7 @@ document.write(`
   - [globalStyle](#globalstyle)
   - [createTheme](#createtheme)
   - [createGlobalTheme](#createglobaltheme)
-  - [createThemeVars](#createthemevars)
+  - [createThemeContract](#createthemecontract)
   - [assignVars](#assignvars)
   - [createVar](#createvar)
   - [fallbackVar](#fallbackvar)
@@ -215,10 +215,12 @@ CSS Variables, simple pseudos, selectors and media/feature queries are all suppo
 
 ```ts
 import { style } from '@vanilla-extract/css';
+import { vars } from './vars.css.ts';
 
 export const className = style({
   display: 'flex',
   vars: {
+    [vars.localVar]: 'green',
     '--global-variable': 'purple'
   },
   ':hover': {
@@ -321,12 +323,14 @@ globalStyle(`${parentClass} > a`, {
 
 ### createTheme
 
-Creates a locally scoped theme class and a collection of scoped CSS Variables.
+Creates a locally scoped theme class and a theme contract which can be consumed within your styles.
 
 ```ts
-import { createTheme, style } from '@vanilla-extract/css';
+// theme.css.ts
+
+import { createTheme } from '@vanilla-extract/css';
 
-export const [themeClass, themeVars] = createTheme({
+export const [themeClass, vars] = createTheme({
   color: {
     brand: 'blue'
   },
@@ -336,12 +340,14 @@ export const [themeClass, themeVars] = createTheme({
 });
 ```
 
-You can create theme variants by passing a collection of theme variables as the first argument to `createTheme`.
+You can create theme variants by passing a theme contract as the first argument to `createTheme`.
 
 ```ts
-import { createTheme, style } from '@vanilla-extract/css';
+// themes.css.ts
+
+import { createTheme } from '@vanilla-extract/css';
 
-export const [themeA, themeVars] = createTheme({
+export const [themeA, vars] = createTheme({
   color: {
     brand: 'blue'
   },
@@ -350,7 +356,7 @@ export const [themeA, themeVars] = createTheme({
   }
 });
 
-export const themeB = createTheme(themeVars, {
+export const themeB = createTheme(vars, {
   color: {
     brand: 'pink'
   },
@@ -367,9 +373,11 @@ export const themeB = createTheme(themeVars, {
 Creates a theme attached to a global selector, but with locally scoped variable names.
 
 ```ts
+// theme.css.ts
+
 import { createGlobalTheme } from '@vanilla-extract/css';
 
-export const themeVars = createGlobalTheme(':root', {
+export const vars = createGlobalTheme(':root', {
   color: {
     brand: 'blue'
   },
@@ -381,19 +389,23 @@ export const themeVars = createGlobalTheme(':root', {
 
 > 💡 All theme variants must provide a value for every variable or it’s a type error.
 
-### createThemeVars
+### createThemeContract
+
+Creates a contract for themes to implement.
 
-Creates a collection of CSS Variables without coupling them to a specific theme variant.
+**Ensure this function is called within a `.css.ts` context, otherwise variable names will be mismatched between themes.**
 
 > 💡 This is useful if you want to split your themes into different bundles. In this case, your themes would be defined in separate files, but we'll keep this example simple.
 
 ```ts
+// themes.css.ts
+
 import {
-  createThemeVars,
+  createThemeContract,
   createTheme
 } from '@vanilla-extract/css';
 
-export const themeVars = createThemeVars({
+export const vars = createThemeContract({
   color: {
     brand: null
   },
@@ -402,7 +414,7 @@ export const themeVars = createThemeVars({
   }
 });
 
-export const themeA = createTheme(themeVars, {
+export const themeA = createTheme(vars, {
   color: {
     brand: 'blue'
   },
@@ -411,7 +423,7 @@ export const themeA = createTheme(themeVars, {
   }
 });
 
-export const themeB = createTheme(themeVars, {
+export const themeB = createTheme(vars, {
   color: {
     brand: 'pink'
   },
@@ -428,9 +440,9 @@ Assigns a collection of CSS Variables anywhere within a style block.
 > 💡 This is useful for creating responsive themes since it can be used within `@media` blocks.
 
 ```ts
-import { style, createThemeVars, assignVars } from '@vanilla-extract/css';
+import { createThemeContract, style, assignVars } from '@vanilla-extract/css';
 
-export const themeVars = createThemeVars({
+export const vars = createThemeContract({
   space: {
     small: null,
     medium: null,
@@ -439,14 +451,14 @@ export const themeVars = createThemeVars({
 });
 
 export const responsiveSpaceTheme = style({
-  vars: assignVars(themeVars.space, {
+  vars: assignVars(vars.space, {
     small: '4px',
     medium: '8px',
     large: '16px'
   }),
   '@media': {
     'screen and (min-width: 1024px)': {
-      vars: assignVars(themeVars.space, {
+      vars: assignVars(vars.space, {
         small: '8px',
         medium: '16px',
         large: '32px'
@@ -613,13 +625,13 @@ $ yarn add --dev @vanilla-extract/dynamic
 
 ### createInlineTheme
 
-Generates a custom theme at runtime as an inline style object.
+Implements a theme contract at runtime as an inline style object.
 
 ```ts
 import { createInlineTheme } from '@vanilla-extract/dynamic';
-import { themeVars, exampleStyle } from './styles.css.ts';
+import { vars, exampleStyle } from './styles.css.ts';
 
-const customTheme = createInlineTheme(themeVars, {
+const customTheme = createInlineTheme(vars, {
   small: '4px',
   medium: '8px',
   large: '16px'
@@ -634,14 +646,14 @@ document.write(`
 
 ### setElementTheme
 
-Sets a collection of CSS Variables on an element.
+Implements a theme contract on an element.
 
 ```ts
 import { setElementTheme } from '@vanilla-extract/dynamic';
-import { themeVars } from './styles.css.ts';
+import { vars } from './styles.css.ts';
 
 const element = document.getElementById('myElement');
-setElementTheme(element, themeVars, {
+setElementTheme(element, vars, {
   small: '4px',
   medium: '8px',
   large: '16px'
@@ -656,10 +668,10 @@ Sets a single var on an element.
 
 ```ts
 import { setElementVar } from '@vanilla-extract/dynamic';
-import { themeVars } from './styles.css.ts';
+import { vars } from './styles.css.ts';
 
 const element = document.getElementById('myElement');
-setElementVar(element, themeVars.color.brand, 'darksalmon');
+setElementVar(element, vars.color.brand, 'darksalmon');
 ```
 
 ## Utility functions

docs/treat-migration-guide.md

@@ -72,32 +72,32 @@ module.exports = {
 If you only have a single theme, you can keep things simple by using `createGlobalTheme` and targeting `:root`. If you do this, your variables will just work without having to wire anything up to the document.
 
 ```ts
-// themeVars.css.ts
+// vars.css.ts
 
 import { createGlobalTheme } from '@vanilla-extract/css';
 
-export const themeVars = createGlobalTheme(':root', {
+export const vars = createGlobalTheme(':root', {
   ...tokens
 });
 ```
 
 If you have multiple themes, or if you want to avoid the global scope, use the [`createTheme`](https://github.com/seek-oss/vanilla-extract#createtheme) function instead.
 
 ```ts
-// themeVars.css.ts
+// vars.css.ts
 
 import { createTheme } from '@vanilla-extract/css';
 
-export const [themeA, themeVars] = createTheme({
+export const [themeA, vars] = createTheme({
   ...tokens
 });
 
-export const themeB = createTheme(themeVars, {
+export const themeB = createTheme(vars, {
   ...tokens
 });
 ```
 
-If you're bundle-splitting your themes, you'll probably want the [`createThemeVars`](https://github.com/seek-oss/vanilla-extract#createthemevars) function.
+If you're bundle-splitting your themes, you'll probably want the [`createThemeContract`](https://github.com/seek-oss/vanilla-extract#createthemecontract) function.
 
 ## `TreatProvider`
 
@@ -234,10 +234,10 @@ To get access to variables, we now import theme variables from the `.css.ts` fil
 -}))
 
 +import { style } from '@vanilla-extract/css';
-+import { themeVars } from '../themeVars.css';
++import { vars } from '../vars.css';
 +
 +export const className = style({
-+  paddingTop: themeVars.space.small
++  paddingTop: vars.space.small
 +});
 ```
 
@@ -262,10 +262,10 @@ Simple calculations (addition, subtraction, multiplication, division) are covere
 
 +import { style } from '@vanilla-extract/css';
 +import { calc } from '@vanilla-extract/css-utils';
-+import { themeVars } from '../themeVars.css';
++import { vars } from '../vars.css';
 +
 +const className = style({
-+  marginTop: calc.negate(themeVars.space.small)
++  marginTop: calc.negate(vars.space.small)
 +});
 ```
 
@@ -285,14 +285,14 @@ export const className = style((theme) => ({
 Since this calculation is not yet supported natively in CSS, this lighter background would need to become part of your theme definition. In this case, we'll introduce a new `color` variable called `brandLight`. Notice that in this context we're able to execute arbitrary JavaScript code.
 
 ```ts
-// themeVars.css.ts
+// vars.css.ts
 
 import { createGlobalTheme } from '@vanilla-extract/css';
 import { lighten } from 'polished';
 
 const brandColor = 'blue';
 
-export const themeVars = createGlobalTheme(':root', {
+export const vars = createGlobalTheme(':root', {
   color: {
     brand: brandColor,
     brandLight: lighten(0.2, brandColor)
@@ -306,13 +306,13 @@ You would then update your styles to use this new CSS Variable instead.
 -import { style } from 'treat';
 -import { lighten } from 'polished';
 +import { style } from '@vanilla-extract/css';
-+import { themeVars } from '../themeVars.css';
++import { vars } from '../vars.css';
 
 -export const className = style(theme => ({
 -  background: lighten(0.2, theme.color.brand)
 -}));
 +export const className = style({
-+  background: themeVars.color.brandLight
++  background: vars.color.brandLight
 +});
 ```
 

packages/babel-plugin/src/index.test.ts

@@ -370,34 +370,34 @@ describe('babel plugin', () => {
     const source = `
       import { createGlobalTheme } from '@vanilla-extract/css';
 
-      const themeVars = createGlobalTheme(':root', { foo: 'bar' });
+      const vars = createGlobalTheme(':root', { foo: 'bar' });
     `;
 
     expect(transform(source)).toMatchInlineSnapshot(`
       "import { setFileScope, endFileScope } from '@vanilla-extract/css/fileScope';
       setFileScope(\\"src/dir/mockFilename.css.ts\\", \\"@vanilla-extract/babel-plugin\\");
       import { createGlobalTheme } from '@vanilla-extract/css';
-      const themeVars = createGlobalTheme(':root', {
+      const vars = createGlobalTheme(':root', {
         foo: 'bar'
       });
       endFileScope()"
     `);
   });
 
-  it('should handle createThemeVars', () => {
+  it('should handle createThemeContract', () => {
     const source = `
-      import { createThemeVars } from '@vanilla-extract/css';
+      import { createThemeContract } from '@vanilla-extract/css';
 
-      const themeVars = createThemeVars({
+      const vars = createThemeContract({
         foo: 'bar'
       });
     `;
 
     expect(transform(source)).toMatchInlineSnapshot(`
       "import { setFileScope, endFileScope } from '@vanilla-extract/css/fileScope';
       setFileScope(\\"src/dir/mockFilename.css.ts\\", \\"@vanilla-extract/babel-plugin\\");
-      import { createThemeVars } from '@vanilla-extract/css';
-      const themeVars = createThemeVars({
+      import { createThemeContract } from '@vanilla-extract/css';
+      const vars = createThemeContract({
         foo: 'bar'
       });
       endFileScope()"

packages/babel-plugin/src/index.ts

@@ -38,7 +38,7 @@ const styleFunctions = [
   >),
   'globalStyle',
   'createGlobalTheme',
-  'createThemeVars',
+  'createThemeContract',
   'globalFontFace',
   'globalKeyframes',
 ];