Merge pull request #4 from mirisuzanne/more-colors

Allow arbitrary color names

Author: mirisuzanne

.sassdocrc

@@ -12,6 +12,7 @@ groups:
     config: Global Settings
     fallbacks: Fallback Colors & Modes
     modes: Dynamic Modes
+    themes: Creating Themes
   'Sass (optional)':
     palettes: Color Palettes
     tools: Additional Tools

CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.1.0-beta.11 - 2019/12/31
+
+This release adds support for arbitrary color names,
+allowing you to define more complex and customized cascading themes.
+
+- BREAKING: Replaced individual `$*-hue` settings with a combined `$hues` map
+  of (`string`) color name keys with (`number` | `null`) hue values.
+  This allows the tool to generate any number of colors.
+  The default `('prime', 'accent', 'neutral')` shorthand
+  creates identical default settings to previous releases.
+  Acceptable shorthands:
+  - a single `number` | `null` value will be assigned a key: `prime`
+  - a `string` | `list` (of strings) will generate keys with `null` values
+- BREAKING: Added a `$colors` list argument (first) in both the
+  `colors()` and `gradient()` mixins --
+  set to the list of `$hues` map-keys by default
+- BREAKING: Since `accent` colors are no longer hard-coded,
+  the built-in themes have replaced `--ccs-accent--theme` settings
+  with more generic `--ccs-theme--1` and `--ccs-theme--2` --
+  which can be assigned to other color names as needed.
+- NEW: Any color with `neutral` in the name
+  will use the neutral saturation,
+  rather than the default saturation
+
 ## 0.1.0-beta.10 - 2019/12/5
 
 - BUGFIX: Source & cascade order was causing HTML modes to fail

README.md

@@ -63,32 +63,15 @@ Import using the new module import syntax:
 Both imports generate
 core configuration options
 as CSS custom properties
-(set by Sass when applicable):
+(set by Sass when applicable) eg:
 
 ```scss
 [data-ccs='root'] {
-  --ccs-prime--config: #{$prime-hue or 330};
-  --ccs-accent--config: #{$accent-hue or null};
-  --ccs-lightness--config: #{$lightness or null};
-  --ccs-saturation--config: #{$saturation or null};
-  --ccs-contrast--config: #{$contrast or null};
-  --ccs-fade-background--config: #{$fade-background};
-}
-```
-
-This also configures a light/dark-mode toggle,
-and fallback values for both modes:
-
-```scss
-// fallback values, in case variables are not supported
-[data-ccs='root'] {
-  background-color: $fallback-light;
-  color: $fallback-dark;
-
-  @media (prefers-color-scheme: dark) {
-    background-color: $fallback-dark;
-    color: $fallback-light;
-  }
+  --ccs-prime--config: 330;
+  --ccs-lightness--config: 50%;
+  --ccs-saturation--config: 50%;
+  --ccs-contrast--config: 50%;
+  --ccs-fade-background--config: 0.9;
 }
 ```
 
@@ -107,35 +90,61 @@ so we've created a
 which can be applied anywhere
 new colors are needed.
 
-This attribute provides your base colors as custom properties:
-
-- `--ccs-prime`, `--ccs-accent`:
-  Prime and accent hues, with base lightness and saturation
-- `--ccs-neutral`:
-  The neutral hue gets base lightness
-  and full-contrast saturation
-- `--ccs-<prime | accent | neutral >--fg-full` :
-  All three hues get a full-contrast foreground
-- `--ccs-<prime | accent | neutral >--bg-full` :
-  All three hues get a full-contrast background
+We configure the default `color` and `background-color` settings:
+
+```scss
+[data-ccs-colors] {
+  background-color: var(--ccs-background, var(--ccs--bg-full));
+  color: var(--ccs-color, var(--ccs--fg-full));
+}
+```
+
+Along with fallback values for light/dark modes,
+in case CSS custom properties are not supported:
+
+```scss
+[data-ccs-colors],
+[data-ccs-colors='light'] {
+  background-color: $fallback-light;
+  color: $fallback-dark;
+}
+
+[data-ccs-colors='invert'],
+[data-ccs-colors='dark'] {
+  background-color: $fallback-dark;
+  color: $fallback-light;
+}
+```
+
+You can override the default colors and backgrounds
+by defining `--ccs-color` and `--ccs-background`:
+
+```scss
+[data-ccs-colors] {
+  --ccs-background: var(--ccs-neutral--bg-full);
+  --ccs-color: var(--ccs-neutral--fg-full);
+}
+```
+
+This attribute generates all your colors as custom properties:
+
+- `--ccs-prime`, `--ccs-*`:
+  Colors generated from the given `$hues`, `$saturation`, and `$lightness` --
+  along with any `neutral` colors,
+  which will use their own customizable (low) `$saturation`
+- `--ccs-*--fg-full` :
+  All color hues get a full-contrast foreground
+- `--ccs-*--bg-full` :
+  All color hues get a full-contrast background
 - `--ccs--bg-full` white or black, depending on light/dark mode
 - `--ccs--fg-full` white or black, depending on light/dark mode
 
 We also provide the color attributes needed
 to generate a larger palette:
 
-- `--ccs-h--prime`:
-  the calculated primary hue,
-  based on user-settings, theme-settings, and global configuration
-- `--ccs-h--accent`:
-  the calculated accent hue,
-  based on theme-settings, and global configuration
-  (there is currently no direct user input for accent hue)
-- `--ccs-h--neutral`:
-  the calculated neutral hue,
-  based on theme-settings and global configuration;
-  generally either `--ccs-h--prime` (the default)
-  or `--ccs-h--accent`
+- `--ccs-h--*`:
+  the calculated hue for each color,
+  afterresolving user-settings, theme-settings, and global configuration
 - `--ccs-contrast`:
   the calculated contrast range
   based on theme, user, and global settings
@@ -202,14 +211,14 @@ using the `[data-ccs-theme]` attribute:
 ### Sass Configuration
 
 In most cases,
-you'll want to define the `$prime-hue`,
+you'll want to define the `prime` hue,
 and possibly a few other options --
 and then trigger a build from the module itself.
 Here's the code from one of my sites:
 
 ```scss
 @use "../../node_modules/cascading-color-systems/" as ccs with (
-  $prime-hue: 0,
+  $hues: 120, // shorthand for setting the prime hue only
   $saturation: 70%,
   $contrast: 48%,
   $steps: 6,

css/ccs.css

@@ -100,6 +100,11 @@ <h2 data-ccs-colors="invert">accent</h2>
       <div style="--show: var(--accent-gradient), var(--accent-gradient--fade)"></div>
     </section>
 
+    <section class="palette" role="presentation">
+      <h2 data-ccs-colors="invert">special</h2>
+      <div style="--show: var(--special-gradient), var(--special-gradient--fade)"></div>
+    </section>
+
     <section class="palette" role="presentation">
       <h2 data-ccs-colors="invert">neutral</h2>
       <div style="--show: var(--neutral-gradient), var(--neutral-gradient--fade)"></div>

css/ccs.css.map

@@ -1,6 +1,6 @@
 {
   "name": "cascading-color-systems",
-  "version": "0.1.0-beta.10",
+  "version": "0.1.0-beta.11",
   "description": "generate dynamic color palettes with custom properties",
   "main": "dist.js",
   "module": "index.js",

index.html

@@ -15,32 +15,45 @@
 ///
 /// @group config
 
-// Prime Hue
-// ---------
-/// The color-wheel hue that will act as our default
-/// for generating all color palettes.
-/// Hue values should be set without `deg` units.
-///
-/// - Sass: `$prime-hue: 330;`
-/// - CSS: `--ccs-prime--config: 330;`
-///
-/// @type number | null
+// Hues
+// ----
+/// The colors to generate, and optional default hues for each color.
+/// To set both color-names and hues, provide an explicit map.
+/// - If you provide a songle hue value,
+///   we'll assign it to the required `prime` key.
+/// - If you provide a list of color names, we
+///   we'll assign them all default `null` hue values.
+///
+/// Two color names are given special treatment:
+/// - `prime` is required, a defaults to `330` if undefined
+/// - `neutral` colors (including `neutral` anywhere in a color-name)
+///   will use the `$neutral-saturation` or most-desaturated value
+/// @type map | list | string | number | null
 /// @group config
-$prime-hue: null !default;
+$hues: (
+  'prime',
+  'accent',
+  'neutral',
+) !default;
 
-// Accent Hue
-// ----------
-/// The color-wheel hue that will act as our default
-/// for generating accent colors.
-/// Leave unset, or use Sass `null` value to generate all palettes from the prime hue.
-/// Hue values should be set without `deg` units.
-///
-/// - Sass: `$accent-hue: 120;`
-/// - CSS: `--ccs-accent--config: 120;`
-///
-/// @type number | null
-/// @group config
-$accent-hue: null !default;
+// Convert $hues to a map, or error on invalid hues
+@if (type-of($hues) != 'map') {
+  @if (type-of($hues) == 'list') or (type-of($hues) == 'string') {
+    $hues-list: $hues;
+    $hues: ();
+
+    @each $color in $hues-list {
+      $hues: map-merge($hues, ($color: null));
+    }
+  } @else if (type-of($hues) == 'number') or (not $hues) {
+    $hues: ('prime': $hues);
+  }
+}
+
+// Require a prime hue
+@if not (map-has-key($hues, 'prime')) {
+  @error 'Please provide a `prime` hue';
+}
 
 // Lightness
 // ---------
@@ -96,17 +109,6 @@ $contrast: null !default;
 /// @group config
 $fade-background: null !default;
 
-// Neutral Hue
-// -----------
-/// By default, neutral colors are created from the prime hue.
-///
-/// - Sass: `$neutral-hue: 330;`
-/// - CSS: `--ccs-neutral--config: 330;`
-///
-/// @type percentage | null
-/// @group config
-$neutral-hue: null !default;
-
 // Neutral Saturation
 // ------------------
 /// By default, neutral saturation is set to
@@ -127,13 +129,13 @@ $neutral-saturation: null !default;
 /// for browsers that don't support
 /// CSS custom properties.
 /// The default value is based on
-/// `$prime-hue`, `$saturation`, `$lightness`,
+/// `map-get($hues, 'prime')`, `$saturation`, `$lightness`,
 /// and maximum `$contrast`.
 ///
 /// @type color
 /// @group config
 $fallback-dark: hsl(
-  $prime-hue or 330,
+  map-get($hues, 'prime') or 330,
   ($saturation or 50%) - ($contrast or 45%),
   ($lightness or 50%) - ($contrast or 45%)
 ) !default;
@@ -144,13 +146,13 @@ $fallback-dark: hsl(
 /// for browsers that don't support
 /// CSS custom properties.
 /// The default value is based on
-/// `$prime-hue`, `$saturation`, `$lightness`,
+/// `map-get($hues, 'prime')`, `$saturation`, `$lightness`,
 /// and maximum `$contrast`.
 ///
 /// @type color
 /// @group config
 $fallback-light: hsl(
-  $prime-hue or 330,
+  map-get($hues, 'prime') or 330,
   ($saturation or 50%) - ($contrast or 45%),
   ($lightness or 50%) + ($contrast or 45%)
 ) !default;