Add colorFormat option to plugin-css and plugin-sass (#113)

* Add colorFormat option

* Clean up CLI test npm script

* Don’t try and use Sass resolution

* Update deps

.changeset/cyan-tips-clean.md

@@ -0,0 +1,5 @@
+---
+'@cobalt-ui/plugin-css': minor
+---
+
+Add colorFormat option

.changeset/proud-foxes-study.md

@@ -0,0 +1,5 @@
+---
+'@cobalt-ui/plugin-sass': minor
+---
+
+Add colorFormat option

docs/src/pages/docs/reference/config.md

@@ -81,6 +81,8 @@ export default {
 };
 ```
 
+_Note: individual plugins may override these settings per-platform. E.g. you may want a different color format for CSS/web than you do for native code._
+
 ## Syncing with Figma
 
 You can sync tokens with Figma by using the [Tokens Studio for Figma](/docs/guides/tokens-studio) plugin.

package.json

@@ -46,10 +46,10 @@
   "devDependencies": {
     "@changesets/changelog-github": "^0.4.8",
     "@changesets/cli": "^2.26.2",
-    "@typescript-eslint/eslint-plugin": "^6.5.0",
-    "@typescript-eslint/parser": "^6.5.0",
+    "@typescript-eslint/eslint-plugin": "^6.6.0",
+    "@typescript-eslint/parser": "^6.6.0",
     "del-cli": "^4.0.1",
-    "eslint": "^8.48.0",
+    "eslint": "^8.49.0",
     "eslint-config-prettier": "^9.0.0",
     "eslint-plugin-prettier": "^5.0.0",
     "js-yaml": "^4.1.0",

packages/cli/package.json

@@ -37,7 +37,7 @@
     "build:clean": "del dist",
     "build:ts": "tsc",
     "dev": "tsc -w",
-    "test": "run-p test:js test:ts",
+    "test": "run-p -s test:*",
     "test:js": "vitest run",
     "test:ts": "tsc --noEmit"
   },

packages/plugin-css/README.md

@@ -75,6 +75,8 @@ export default {
       prefix: '',
       /** enable P3 support? */
       p3: true,
+      /** normalize all colors */
+      colorFormat: 'hex',
     }),
   ],
 };
@@ -238,6 +240,25 @@ That will generate the following:
 
 [Learn more about modes](https://cobalt-ui.pages.dev/docs/guides/modes/)
 
+### Color Format
+
+By specifying a `colorFormat`, you can transform all your colors to [any browser-supported colorspace](https://www.w3.org/TR/css-color-4/). Any of the following colorspaces are accepted:
+
+- [hex](https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color) (default)
+- [rgb](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/rgb)
+- [hsl](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hsl)
+- [hwb](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hwb)
+- [lab](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/lab)
+- [lch](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/lch)
+- [oklab](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklab)
+- [oklch](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch)
+- [p3](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color)
+- [srgb-linear](https://developer.mozilla.org/en-US/docs/Web/CSS/color-interpolation-method)
+- [xyz-d50](https://developer.mozilla.org/en-US/docs/Web/CSS/color-interpolation-method)
+- [xyz-d65](https://developer.mozilla.org/en-US/docs/Web/CSS/color-interpolation-method)
+
+If you are unfamiliar with these colorspaces, the default `hex` value is best for most users (though [you should use OKLCH to define your colors](https://evilmartians.com/chronicles/oklch-in-css-why-quit-rgb-hsl)).
+
 ### Transform
 
 Inside plugin options, you can specify an optional `transform()` function.

packages/plugin-css/test/build.test.ts

@@ -56,6 +56,34 @@ describe('@cobalt-ui/plugin-css', () => {
   });
 
   describe('options', () => {
+    test('colorFormat', async () => {
+      const cwd = new URL(`./color-format/`, import.meta.url);
+      const tokens = JSON.parse(fs.readFileSync(new URL('./tokens.json', cwd), 'utf8'));
+      await build(tokens, {
+        outDir: cwd,
+        plugins: [
+          pluginCSS({
+            filename: 'actual.css',
+            colorFormat: 'oklch',
+            modeSelectors: [
+              {mode: 'light', selectors: ['@media (prefers-color-scheme: light)']},
+              {mode: 'dark', selectors: ['@media (prefers-color-scheme: dark)']},
+              {mode: 'light', tokens: ['color.*'], selectors: ['[data-color-theme="light"]']},
+              {mode: 'dark', tokens: ['color.*'], selectors: ['[data-color-theme="dark"]']},
+              {mode: 'light-colorblind', tokens: ['color.*'], selectors: ['[data-color-theme="light-colorblind"]']},
+              {mode: 'light-high-contrast', tokens: ['color.*'], selectors: ['[data-color-theme="light-high-contrast"]']},
+              {mode: 'dark-dimmed', tokens: ['color.*'], selectors: ['[data-color-theme="dark-dimmed"]']},
+              {mode: 'dark-high-contrast', tokens: ['color.*'], selectors: ['[data-color-theme="dark-high-contrast"]']},
+              {mode: 'dark-colorblind', tokens: ['color.*'], selectors: ['[data-color-theme="dark-colorblind"]']},
+            ],
+          }),
+        ],
+        color: {},
+        tokens: [],
+      });
+      expect(fs.readFileSync(new URL('./actual.css', cwd), 'utf8')).toMatchFileSnapshot(fileURLToPath(new URL('./want.css', cwd)));
+    });
+
     test('p3', async () => {
       const cwd = new URL(`./p3/`, import.meta.url);
       const tokens = JSON.parse(fs.readFileSync(new URL('./tokens.json', cwd), 'utf8'));

packages/plugin-css/test/color-format/tokens.json

@@ -0,0 +1,27 @@
+{
+  "color": {
+    "$type": "color",
+    "blue": {
+      "$value": "#218bff"
+    }
+  },
+  "border": {
+    "heavy": {
+      "$type": "border",
+      "$value": {"color": "#363636", "width": "3px", "style": "solid"}
+    }
+  },
+  "shadow": {
+    "simple": {
+      "$type": "shadow",
+      "$value": {"offsetX": 0, "offsetY": "4px", "blur": "8px", "spread": 0, "color": "rgb(0, 0, 0, 0.15)"}
+    }
+  },
+  "gradient": {
+    "$type": "gradient",
+    "$value": [
+      {"color": "#218bff", "position": 0},
+      {"color": "#e85aad", "position": 1}
+    ]
+  }
+}

packages/plugin-css/test/color-format/want.css

@@ -0,0 +1,12 @@
+/**
+ * Design Tokens
+ * Autogenerated from tokens.json.
+ * DO NOT EDIT!
+ */
+
+:root {
+  --border-heavy: 3px solid oklch(0.332889981838499 0 0);
+  --color-blue: oklch(0.6417644680341144 0.19507618434109797 254.9761894488772);
+  --gradient: oklch(0.6417644680341144 0.19507618434109797 254.9761894488772) 0%, oklch(0.6758651948287796 0.19530567236823002 347.4630536462303) 100%;
+  --shadow-simple: 0 4px 8px 0 oklch(0 0 0 / 0.15);
+}

packages/plugin-sass/README.md

@@ -196,6 +196,25 @@ In some scenarios this is preferable, but in others, this may result in too many
 
 [Read more](https://css-tricks.com/data-uris/)
 
+### Color Format
+
+By specifying a `colorFormat`, you can transform all your colors to [any browser-supported colorspace](https://www.w3.org/TR/css-color-4/). Any of the following colorspaces are accepted:
+
+- [hex](https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color) (default)
+- [rgb](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/rgb)
+- [hsl](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hsl)
+- [hwb](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hwb)
+- [lab](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/lab)
+- [lch](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/lch)
+- [oklab](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklab)
+- [oklch](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch)
+- [p3](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color)
+- [srgb-linear](https://developer.mozilla.org/en-US/docs/Web/CSS/color-interpolation-method)
+- [xyz-d50](https://developer.mozilla.org/en-US/docs/Web/CSS/color-interpolation-method)
+- [xyz-d65](https://developer.mozilla.org/en-US/docs/Web/CSS/color-interpolation-method)
+
+If you are unfamiliar with these colorspaces, the default `hex` value is best for most users (though [you should use OKLCH to define your colors](https://evilmartians.com/chronicles/oklch-in-css-why-quit-rgb-hsl)).
+
 ### Transform
 
 Inside plugin options, you can specify an optional `transform()` function: