@diskette/palette 0.8.0 → 0.9.1

package/README.md

@@ -1 +1,409 @@
 # @diskette/palette
+
+A color palette library based on [Radix Colors](https://www.radix-ui.com/colors) with support for both sRGB and Display P3 color spaces.
+
+## Installation
+
+```bash
+npm install @diskette/palette
+# or
+pnpm add @diskette/palette
+```
+
+## Usage
+
+### Importing Colors
+
+```ts
+// Import all colors
+import colors from '@diskette/palette'
+
+// Import specific colors
+import { blue, red, gray } from '@diskette/palette/colors'
+
+// Import a single color
+import blue from '@diskette/palette/colors/blue'
+```
+
+### Color Structure
+
+Each color provides values for both color spaces and light/dark themes:
+
+```ts
+import blue from '@diskette/palette/colors/blue'
+
+// sRGB values (hex)
+blue.srgb.light.blue9 // '#0090ff'
+blue.srgb.dark.blue9 // '#0090ff'
+
+// Display P3 values
+blue.p3.light.blue9 // 'color(display-p3 0.247 0.556 0.969)'
+blue.p3.dark.blue9 // 'color(display-p3 0.247 0.556 0.969)'
+
+// Alpha variants
+blue.srgb.light.blueA9 // '#0090ff' (with alpha)
+
+// Surface (translucent overlay)
+blue.surface.srgb.light // '#f1f9ffcc'
+blue.surface.p3.dark // 'color(display-p3 0.0706 0.1255 0.2196 / 0.5)'
+
+// Semantic values
+blue.contrast // 'white'
+blue.indicator // 'blue9'
+blue.track // 'blue9'
+```
+
+### Generating CSS
+
+Use the `css` utility to generate CSS custom properties:
+
+```ts
+import { css } from '@diskette/palette'
+import blue from '@diskette/palette/colors/blue'
+
+// Generate scale variables for light theme
+const blue = css.scale('light', blue)
+// Output: :root, .light, .light-theme { --blue-1: #fbfdff; ... }
+
+// Generate alpha variants
+css.scale('lightAlpha', blue)
+
+// Generate semantic tokens
+css.semantic('blue', blue)
+// Output: :root { --blue-contrast: white; } ...
+```
+
+### Alpha Colors
+
+For transparency overlays:
+
+```ts
+import { blackAlpha, whiteAlpha } from '@diskette/palette/colors'
+
+blackAlpha.srgb.blackA5 // 'rgba(0, 0, 0, 0.3)'
+whiteAlpha.p3.whiteA5 // 'color(display-p3 1 1 1 / 0.3)'
+```
+
+## Available Colors
+
+### Accent Colors
+
+`amber`, `blue`, `bronze`, `brown`, `crimson`, `cyan`, `gold`, `grass`, `gray`, `green`, `indigo`, `iris`, `jade`, `lime`, `mint`, `orange`, `pink`, `plum`, `purple`, `red`, `ruby`, `sky`, `teal`, `tomato`, `violet`, `yellow`
+
+### Gray Scales
+
+`gray`, `mauve`, `olive`, `sage`, `sand`, `slate`
+
+### Alpha Colors
+
+`blackAlpha`, `whiteAlpha`
+
+## Color Scale
+
+Each color provides a 12-step scale following Radix Colors conventions:
+
+| Step | Use Case                      |
+| ---- | ----------------------------- |
+| 1-2  | App backgrounds               |
+| 3-4  | Component backgrounds         |
+| 5    | Hovered component backgrounds |
+| 6    | Active/selected backgrounds   |
+| 7    | Borders and separators        |
+| 8    | Hovered borders, focus rings  |
+| 9    | Solid backgrounds             |
+| 10   | Hovered solid backgrounds     |
+| 11   | Low-contrast text             |
+| 12   | High-contrast text            |
+
+## API Reference
+
+### `css.scale(scheme, config)`
+
+Generates CSS custom properties for a color scale.
+
+```ts
+css.scale(scheme: 'light' | 'lightAlpha' | 'dark' | 'darkAlpha', config: ColorConfig): string
+```
+
+<details>
+<summary>Example output</summary>
+
+```css
+:root,
+.light,
+.light-theme {
+  amber1: #fefdfb;
+  amber2: #fefbe9;
+  amber3: #fff7c2;
+  amber4: #ffee9c;
+  amber5: #fbe577;
+  amber6: #f3d673;
+  amber7: #e9c162;
+  amber8: #e2a336;
+  amber9: #ffc53d;
+  amber10: #ffba18;
+  amber11: #ab6400;
+  amber12: #4f3422;
+}
+
+@supports (color: color(display-p3 1 1 1)) {
+  @media (color-gamut: p3) {
+    :root,
+    .light,
+    .light-theme {
+      amber1: color(display-p3 0.995 0.992 0.985);
+      amber2: color(display-p3 0.994 0.986 0.921);
+      amber3: color(display-p3 0.994 0.969 0.782);
+      amber4: color(display-p3 0.989 0.937 0.65);
+      amber5: color(display-p3 0.97 0.902 0.527);
+      amber6: color(display-p3 0.936 0.844 0.506);
+      amber7: color(display-p3 0.89 0.762 0.443);
+      amber8: color(display-p3 0.85 0.65 0.3);
+      amber9: color(display-p3 1 0.77 0.26);
+      amber10: color(display-p3 0.959 0.741 0.274);
+      amber11: color(display-p3 0.64 0.4 0);
+      amber12: color(display-p3 0.294 0.208 0.145);
+    }
+  }
+}
+```
+
+</details>
+
+Output includes `@supports` and `@media (color-gamut: p3)` blocks for Display P3 fallbacks.
+
+### `css.alpha(config)`
+
+Generates CSS custom properties for alpha color scales (blackAlpha, whiteAlpha).
+
+```ts
+css.alpha(config: AlphaConfig): string
+```
+
+### `css.semantic(name, config)`
+
+Generates semantic CSS custom properties for a color.
+
+```ts
+css.semantic(name: string, config: ColorConfig): string
+```
+
+<details>
+<summary>Example output</summary>
+
+```css
+:root {
+  --amber-contrast: #21201c;
+}
+
+:root,
+.light,
+.light-theme {
+  --amber-surface: #fefae4cc;
+  --amber-indicator: var(--amber-9);
+  --amber-track: var(--amber-9);
+  @supports (color: color(display-p3 1 1 1)) {
+    @media (color-gamut: p3) {
+      --amber-surface: color(display-p3 0.9922 0.9843 0.902 / 0.8);
+    }
+  }
+}
+
+.dark,
+.dark-theme {
+  --amber-surface: #271f1380;
+  --amber-indicator: var(--amber-9);
+  --amber-track: var(--amber-9);
+  @supports (color: color(display-p3 1 1 1)) {
+    @media (color-gamut: p3) {
+      --amber-surface: color(display-p3 0.1412 0.1176 0.0784 / 0.5);
+    }
+  }
+}
+```
+
+</details>
+
+## Examples
+
+### Generate a Complete CSS File
+
+```ts
+// scripts/generate-css.ts
+import { writeFileSync } from 'node:fs'
+import { css, colors } from '@diskette/palette'
+import { blackAlpha, whiteAlpha } from '@diskette/palette/colors'
+
+let output = ''
+
+// Generate scales for all colors
+for (const color of colors) {
+  output += css.scale('light', color)
+  output += css.scale('lightAlpha', color)
+  output += css.scale('dark', color)
+  output += css.scale('darkAlpha', color)
+}
+
+// Generate alpha colors
+output += css.alpha(blackAlpha)
+output += css.alpha(whiteAlpha)
+
+writeFileSync('dist/colors.css', output)
+```
+
+### Generate CSS for Selected Colors
+
+```ts
+// scripts/generate-theme.ts
+import { writeFileSync } from 'node:fs'
+import { css } from '@diskette/palette'
+import blue from '@diskette/palette/colors/blue'
+import gray from '@diskette/palette/colors/gray'
+
+const output = [
+  // Base scales
+  css.scale('light', blue),
+  css.scale('dark', blue),
+  css.scale('light', gray),
+  css.scale('dark', gray),
+
+  // Semantic tokens
+  css.semantic('blue', blue),
+  css.semantic('gray', gray),
+].join('\n')
+
+writeFileSync('src/styles/theme.css', output)
+```
+
+### Generate CSS with Custom Build Script
+
+```ts
+// build-colors.ts
+import { writeFileSync, mkdirSync } from 'node:fs'
+import { css, colors } from '@diskette/palette'
+
+mkdirSync('dist', { recursive: true })
+
+// Generate individual files per color
+for (const color of colors) {
+  const name = Object.keys(color.srgb.light)[0].replace(/\d+$/, '')
+
+  const content = [
+    css.scale('light', color),
+    css.scale('dark', color),
+    css.semantic(name, color),
+  ].join('\n')
+
+  writeFileSync(`dist/${name}.css`, content)
+}
+
+// Generate combined file
+let combined = ''
+for (const color of colors) {
+  const name = Object.keys(color.srgb.light)[0].replace(/\d+$/, '')
+  combined += css.scale('light', color)
+  combined += css.scale('dark', color)
+  combined += css.semantic(name, color)
+}
+writeFileSync('dist/all-colors.css', combined)
+```
+
+### Use with vanilla-extract
+
+```ts
+// src/styles/colors.css.ts
+import { createGlobalTheme } from '@vanilla-extract/css'
+import blue from '@diskette/palette/colors/blue'
+import gray from '@diskette/palette/colors/gray'
+
+// Create CSS variables from the palette
+createGlobalTheme(':root', {
+  colors: {
+    blue1: blue.srgb.light.blue1,
+    blue2: blue.srgb.light.blue2,
+    blue3: blue.srgb.light.blue3,
+    // ... etc
+    blue9: blue.srgb.light.blue9,
+    blue10: blue.srgb.light.blue10,
+    blue11: blue.srgb.light.blue11,
+    blue12: blue.srgb.light.blue12,
+    gray1: gray.srgb.light.gray1,
+    // ... etc
+  },
+})
+
+// For dark mode
+createGlobalTheme('.dark', {
+  colors: {
+    blue1: blue.srgb.dark.blue1,
+    blue2: blue.srgb.dark.blue2,
+    // ... etc
+  },
+})
+```
+
+### Generate Semantic Tokens Only
+
+```ts
+// scripts/semantic-tokens.ts
+import { writeFileSync } from 'node:fs'
+import { css, colors } from '@diskette/palette'
+
+let output = ''
+
+for (const color of colors) {
+  // Extract color name from first key (e.g., "blue1" -> "blue")
+  const name = Object.keys(color.srgb.light)[0].replace(/\d+$/, '')
+  output += css.semantic(name, color)
+}
+
+writeFileSync('dist/semantic.css', output)
+```
+
+### Access Colors Directly in JavaScript
+
+```ts
+import blue from '@diskette/palette/colors/blue'
+
+// Use in CSS-in-JS libraries
+const styles = {
+  button: {
+    backgroundColor: blue.srgb.light.blue9,
+    color: blue.contrast,
+    '&:hover': {
+      backgroundColor: blue.srgb.light.blue10,
+    },
+  },
+}
+
+// Use P3 colors for wider gamut displays
+const p3Styles = {
+  button: {
+    backgroundColor: blue.p3.light.blue9,
+  },
+}
+
+// Access surface colors for overlays
+const overlay = {
+  backgroundColor: blue.surface.srgb.light, // '#f1f9ffcc'
+}
+```
+
+### NPM Script Integration
+
+```json
+{
+  "scripts": {
+    "build:css": "tsx scripts/generate-css.ts",
+    "build": "pnpm build:css && vite build"
+  }
+}
+```
+
+## Credits
+
+Color values are derived from [Radix Colors](https://www.radix-ui.com/colors) by [WorkOS](https://workos.com/).
+
+## License
+
+MIT

package/dist/colors/amber.d.ts

@@ -114,5 +114,15 @@ declare const _default: {
     contrast: string;
     indicator: string;
     track: string;
+    surface: {
+        srgb: {
+            light: string;
+            dark: string;
+        };
+        p3: {
+            light: string;
+            dark: string;
+        };
+    };
 };
 export default _default;

package/dist/colors/amber.js

@@ -114,4 +114,14 @@ export default {
     contrast: '#21201c',
     indicator: 'amber9',
     track: 'amber9',
+    surface: {
+        srgb: {
+            light: '#fefae4cc',
+            dark: '#271f1380',
+        },
+        p3: {
+            light: 'color(display-p3 0.9922 0.9843 0.902 / 0.8)',
+            dark: 'color(display-p3 0.1412 0.1176 0.0784 / 0.5)',
+        },
+    },
 };

package/dist/colors/blue.d.ts

@@ -114,5 +114,15 @@ declare const _default: {
     contrast: string;
     indicator: string;
     track: string;
+    surface: {
+        srgb: {
+            light: string;
+            dark: string;
+        };
+        p3: {
+            light: string;
+            dark: string;
+        };
+    };
 };
 export default _default;

package/dist/colors/blue.js

@@ -114,4 +114,14 @@ export default {
     contrast: 'white',
     indicator: 'blue9',
     track: 'blue9',
+    surface: {
+        srgb: {
+            light: '#f1f9ffcc',
+            dark: '#11213d80',
+        },
+        p3: {
+            light: 'color(display-p3 0.9529 0.9765 0.9961 / 0.8)',
+            dark: 'color(display-p3 0.0706 0.1255 0.2196 / 0.5)',
+        },
+    },
 };

package/dist/colors/bronze.d.ts

@@ -114,5 +114,15 @@ declare const _default: {
     contrast: string;
     indicator: string;
     track: string;
+    surface: {
+        srgb: {
+            light: string;
+            dark: string;
+        };
+        p3: {
+            light: string;
+            dark: string;
+        };
+    };
 };
 export default _default;

package/dist/colors/bronze.js

@@ -114,4 +114,14 @@ export default {
     contrast: 'white',
     indicator: 'bronze9',
     track: 'bronze9',
+    surface: {
+        srgb: {
+            light: '#fdf5f3cc',
+            dark: '#27211d80',
+        },
+        p3: {
+            light: 'color(display-p3 0.9843 0.9608 0.9529 / 0.8)',
+            dark: 'color(display-p3 0.1412 0.1255 0.1176 / 0.5)',
+        },
+    },
 };

package/dist/colors/brown.d.ts

@@ -114,5 +114,15 @@ declare const _default: {
     contrast: string;
     indicator: string;
     track: string;
+    surface: {
+        srgb: {
+            light: string;
+            dark: string;
+        };
+        p3: {
+            light: string;
+            dark: string;
+        };
+    };
 };
 export default _default;

package/dist/colors/brown.js

@@ -114,4 +114,14 @@ export default {
     contrast: 'white',
     indicator: 'brown9',
     track: 'brown9',
+    surface: {
+        srgb: {
+            light: '#fbf8f4cc',
+            dark: '#271f1b80',
+        },
+        p3: {
+            light: 'color(display-p3 0.9843 0.9725 0.9569 / 0.8)',
+            dark: 'color(display-p3 0.1412 0.1176 0.102 / 0.5)',
+        },
+    },
 };

package/dist/colors/crimson.d.ts

@@ -114,5 +114,15 @@ declare const _default: {
     contrast: string;
     indicator: string;
     track: string;
+    surface: {
+        srgb: {
+            light: string;
+            dark: string;
+        };
+        p3: {
+            light: string;
+            dark: string;
+        };
+    };
 };
 export default _default;

package/dist/colors/crimson.js

@@ -114,4 +114,14 @@ export default {
     contrast: 'white',
     indicator: 'crimson9',
     track: 'crimson9',
+    surface: {
+        srgb: {
+            light: '#fef5f8cc',
+            dark: '#2f151f80',
+        },
+        p3: {
+            light: 'color(display-p3 0.9922 0.9608 0.9725 / 0.8)',
+            dark: 'color(display-p3 0.1647 0.0863 0.1176 / 0.5)',
+        },
+    },
 };

package/dist/colors/cyan.d.ts

@@ -114,5 +114,15 @@ declare const _default: {
     contrast: string;
     indicator: string;
     track: string;
+    surface: {
+        srgb: {
+            light: string;
+            dark: string;
+        };
+        p3: {
+            light: string;
+            dark: string;
+        };
+    };
 };
 export default _default;

package/dist/colors/cyan.js

@@ -114,4 +114,14 @@ export default {
     contrast: 'white',
     indicator: 'cyan9',
     track: 'cyan9',
+    surface: {
+        srgb: {
+            light: '#eff9facc',
+            dark: '#11252d80',
+        },
+        p3: {
+            light: 'color(display-p3 0.9412 0.9765 0.9804 / 0.8)',
+            dark: 'color(display-p3 0.0784 0.1412 0.1725 / 0.5)',
+        },
+    },
 };

package/dist/colors/gold.d.ts

@@ -114,5 +114,15 @@ declare const _default: {
     contrast: string;
     indicator: string;
     track: string;
+    surface: {
+        srgb: {
+            light: string;
+            dark: string;
+        };
+        p3: {
+            light: string;
+            dark: string;
+        };
+    };
 };
 export default _default;

package/dist/colors/gold.js

@@ -114,4 +114,14 @@ export default {
     contrast: 'white',
     indicator: 'gold9',
     track: 'gold9',
+    surface: {
+        srgb: {
+            light: '#f9f8efcc',
+            dark: '#25231d80',
+        },
+        p3: {
+            light: 'color(display-p3 0.9765 0.9725 0.9412 / 0.8)',
+            dark: 'color(display-p3 0.1412 0.1333 0.1098 / 0.5)',
+        },
+    },
 };

package/dist/colors/grass.d.ts

@@ -114,5 +114,15 @@ declare const _default: {
     contrast: string;
     indicator: string;
     track: string;
+    surface: {
+        srgb: {
+            light: string;
+            dark: string;
+        };
+        p3: {
+            light: string;
+            dark: string;
+        };
+    };
 };
 export default _default;

package/dist/colors/grass.js

@@ -114,4 +114,14 @@ export default {
     contrast: 'white',
     indicator: 'grass9',
     track: 'grass9',
+    surface: {
+        srgb: {
+            light: '#f3faf3cc',
+            dark: '#19231b80',
+        },
+        p3: {
+            light: 'color(display-p3 0.9569 0.9804 0.9569 / 0.8)',
+            dark: 'color(display-p3 0.102 0.1333 0.102 / 0.5)',
+        },
+    },
 };

package/dist/colors/gray.d.ts

@@ -114,5 +114,15 @@ declare const _default: {
     contrast: string;
     indicator: string;
     track: string;
+    surface: {
+        srgb: {
+            light: string;
+            dark: string;
+        };
+        p3: {
+            light: string;
+            dark: string;
+        };
+    };
 };
 export default _default;

package/dist/colors/gray.js

@@ -114,4 +114,14 @@ export default {
     contrast: 'white',
     indicator: 'gray9',
     track: 'gray9',
+    surface: {
+        srgb: {
+            light: '#ffffffcc',
+            dark: '#21212180',
+        },
+        p3: {
+            light: 'color(display-p3 1 1 1 / 0.8)',
+            dark: 'color(display-p3 0.1255 0.1255 0.1255 / 0.5)',
+        },
+    },
 };