{"id":18496448,"url":"https://github.com/oddbird/cascading-color-system","last_synced_at":"2026-01-21T08:38:22.953Z","repository":{"id":40399174,"uuid":"207023416","full_name":"oddbird/cascading-color-system","owner":"oddbird","description":"CSS Custom Property color-theming","archived":false,"fork":false,"pushed_at":"2024-06-17T15:19:10.000Z","size":1655,"stargazers_count":71,"open_issues_count":5,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-10-29T18:48:47.245Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"SCSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oddbird.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"oddbird","open_collective":"oddbird-open-source"}},"created_at":"2019-09-07T20:39:51.000Z","updated_at":"2024-06-25T05:50:56.000Z","dependencies_parsed_at":"2023-02-18T09:00:22.684Z","dependency_job_id":"a7cff2b3-98b4-4975-8dec-e939d3c97969","html_url":"https://github.com/oddbird/cascading-color-system","commit_stats":{"total_commits":96,"total_committers":5,"mean_commits":19.2,"dds":0.5520833333333333,"last_synced_commit":"9bf4ee743396c9e42d11e2ef8a6454179078318d"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddbird%2Fcascading-color-system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddbird%2Fcascading-color-system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddbird%2Fcascading-color-system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddbird%2Fcascading-color-system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oddbird","download_url":"https://codeload.github.com/oddbird/cascading-color-system/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239148751,"owners_count":19589850,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T13:29:29.086Z","updated_at":"2025-10-31T16:30:24.752Z","avatar_url":"https://github.com/oddbird.png","language":"SCSS","funding_links":["https://github.com/sponsors/oddbird","https://opencollective.com/oddbird-open-source"],"categories":[],"sub_categories":[],"readme":"# Cascading Colors\n\n[Demo Site](https://cascading-colors.netlify.app/) |\n[Documentation](https://www.oddbird.net/cascading-colors/docs/)\n\nGenerate dynamic and themable color palettes using CSS custom properties,\nand allow (persistent) user-adjustments with a bit of light-weight JS.\n\nWe provide both the Sass,\nand a pre-built CSS file.\nBoth allow adjustments to default settings --\nbut only the Sass files can change how many colors are generated.\n\n## Installation \u0026 Requirements\n\nDownload the files from [GitHub][gh],\nor install using npm or yarn:\n\n```bash\nnpm install cascading-color-systems --save-dev\nyarn add cascading-color-systems --dev\n```\n\n### CSS (minimal configuration)\n\nThe default configuration can be used as plain CSS:\n\n```css\n/* css */\n@import \"\u003cpath-to\u003e/cascading-color-systems/css/ccs.css\";\n```\n\n```html\n\u003c!-- html --\u003e\n\u003clink src=\"\u003cpath-to\u003e/cascading-color-systems/css/ccs.css\" rel=\"stylesheet\" /\u003e\n```\n\nYou can copy that file anywhere you want,\nand it works without dependencies.\n\n### Sass (full configuration)\n\nIf you want to use the Sass features,\nyou will need [Dart-Sass][sass] `v1.23+`\n(which may still be in Beta).\nThis was partially an experiment\nin the latest Sass feature: Modules.\n\nImport using the new module import syntax:\n\n```scss\n@use '\u003cpath-to\u003e/cascading-color-systems/' as ccs with (\n  /* configuration options */\n);\n```\n\n[gh]: https://github.com/oddbird/cascading-color-system/\n[sass]: https://www.npmjs.com/package/sass\n\n## Getting started\n\n### CCS Root\n\nBoth imports generate\ncore configuration options\nas CSS custom properties\n(set by Sass when applicable) eg:\n\n```scss\n[data-ccs=\"root\"] {\n  --ccs-prime--config: 330;\n  --ccs-lightness--config: 50%;\n  --ccs-saturation--config: 50%;\n  --ccs-contrast--config: 50%;\n  --ccs-fade-background--config: 0.9;\n}\n```\n\nAdd the `data-ccs='root'` attribute to your `html` element\nin order to make your Cascading Colors configuration\navailable to an entire page.\nThis attribute will also be used by JavaScript\nto apply dynamic user settings globally.\n\n### CCS Color Attributes\n\nCustom properties only re-calculate\nwhere they are defined --\nso we've created a\n`[data-ccs-colors]` attribute,\nwhich can be applied anywhere\nnew colors are needed.\n\nWe configure the default `color` and `background-color` settings:\n\n```scss\n[data-ccs-colors] {\n  background-color: var(--ccs-background, var(--ccs--bg-full));\n  color: var(--ccs-color, var(--ccs--fg-full));\n}\n```\n\nAlong with fallback values for light/dark modes,\nin case CSS custom properties are not supported:\n\n```scss\n[data-ccs-colors],\n[data-ccs-colors=\"light\"] {\n  background-color: $fallback-light;\n  color: $fallback-dark;\n}\n\n[data-ccs-colors=\"invert\"],\n[data-ccs-colors=\"dark\"] {\n  background-color: $fallback-dark;\n  color: $fallback-light;\n}\n```\n\nYou can override the default colors and backgrounds\nby defining `--ccs-color` and `--ccs-background`:\n\n```scss\n[data-ccs-colors] {\n  --ccs-background: var(--ccs-neutral--bg-full);\n  --ccs-color: var(--ccs-neutral--fg-full);\n}\n```\n\nThis attribute generates all your colors as custom properties:\n\n- `--ccs-prime`, `--ccs-*`:\n  Colors generated from the given `$hues`, `$saturation`, and `$lightness` --\n  along with any `neutral` colors,\n  which will use their own customizable (low) `$saturation`\n- `--ccs-*--fg-full` :\n  All color hues get a full-contrast foreground\n- `--ccs-*--bg-full` :\n  All color hues get a full-contrast background\n- `--ccs--bg-full` white or black, depending on light/dark mode\n- `--ccs--fg-full` white or black, depending on light/dark mode\n\nWe also provide the color attributes needed\nto generate a larger palette:\n\n- `--ccs-h--*`:\n  the calculated hue for each color,\n  after resolving user-settings, theme-settings, and global configuration\n- `--ccs-contrast`:\n  the calculated contrast range\n  based on theme, user, and global settings\n- `--ccs-l`, `--ccs-l--\u003cfg | bg\u003e-contrast`:\n  the calculated base lightness (user, theme, global)\n  and full-contrast fg/bg values\n- `--ccs-s`, `--ccs-s--\u003cfg | bg\u003e-contrast`:\n  the calculated base saturation (user, theme, global)\n  and full-contrast fg/bg values\n- `--ccs-mode`:\n  the calculated light (`1`) or dark (`-1`) mode\n  (user, theme, html, or system preference)\n- `--ccs-invert` the opposite of CCS-mode\n\nYou can pass explicit light/dark mode overrides in html\nby including a value with the attribute:\n\n```html\n\u003csection data-ccs-colors=\"light\"\u003e\n  \u003c!-- light background, dark foreground --\u003e\n\n  \u003cdiv data-ccs-colors=\"invert\"\u003e\n    \u003c!-- invert the colors (can't be nested multiple times) --\u003e\n  \u003c/div\u003e\n\u003c/section\u003e\n\n\u003csection data-ccs-colors=\"dark\"\u003e\n  \u003c!-- dark background, light foreground --\u003e\n\u003c/section\u003e\n```\n\n### CCS Color Palettes\n\nMore complex color palettes have to be generated in Sass,\nbased on the number of `$steps` desired\nto get from the base colors to their full-contrast versions.\n\nIf you import the static CSS file,\nwe generate a palette based on the default settings,\nwith 4 steps in either direction.\nEach step is named `--ccs-\u003chue\u003e--\u003cdirection\u003e\u003cstep\u003e`,\neg `--ccs-prime--fg1`, or `--ccs-accent--bg3`.\n\n### Creating Themes\n\nThemes can be used to pre-set any color values\n(especially the accent hue),\nand even show/hide user customization controls.\nWe provide several built-in themes,\nand you can add your own\nusing the `[data-ccs-theme]` attribute:\n\n```scss\n[data-ccs-theme=\"complement\"] {\n  /* set the accent color 180 degrees off the primary color */\n  --ccs-accent--theme: calc(var(--ccs-h--prime) + 180);\n}\n\n[data-ccs-theme=\"triad\"] {\n  /* triad logic */\n}\n```\n\n### Sass Configuration\n\nIn most cases,\nyou'll want to define the `prime` hue,\nand possibly a few other options --\nand then trigger a build from the module itself.\nHere's the code from one of my sites:\n\n```scss\n@use \"../../node_modules/cascading-color-systems/\" as ccs with (\n  $hues: 120, // shorthand for setting the prime hue only\n  $saturation: 70%,\n  $contrast: 48%,\n  $steps: 6,\n  $fade-background: 15%,\n  $fades: 0.75,\n  $build: true,\n);\n```\n\nThe `$build: true` configuration\nwill generate CSS output based on your settings.\nI recommend that for most use-cases,\nbut you can leave that out\nand apply individual mixins:\n\n```scss\n[data-ccs-colors] {\n  @include colors;\n}\n```\n\n### User Settings \u0026 JavaScript\n\nThe provided JS\ncan be hooked up to a form\nto accept user-input,\ngenerate custom properties based on their input,\nstore their preferences in `localStorage`,\nor revert back to the configured site defaults.\n\nUse the `dist.js` UMD module directly in a browser:\n\n```html\n\u003cscript type=\"text/javascript\" src=\"dist.js\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\"\u003e\n  ccs.default();\n\u003c/script\u003e\n```\n\nOr import and use `index.js`,\nif you have a modern build system with ES Module support:\n\n```js\nimport ccs from \"cascading-color-systems\";\n\nccs();\n```\n\n### HTML Attributes\n\nWe provide several attributes\nthat can be used to build\na user-interface for changing colors.\nThe `root` attribute is required:\n\n- `[data-ccs=\"root\"]`:\n  where user settings should be applied\n\n#### General Controls:\n\n- `[data-ccs=\"menu\"]`:\n  You can hide the settings menu and unset buttons by default,\n  and we'll show them when the JS is available\n- `[data-ccs-input=\"unset\"]`:\n  A button to unset all user preferences\n  and clear related local storage\n\n#### Light/Dark Mode:\n\nMode can be toggled with a button:\n\n- `[data-ccs-input=\"mode\"]`:\n  A button to toggle light/dark modes\n\nOr mode can be set explicitly using radio inputs:\n\n- `[data-ccs-input=\"light-mode\"]`:\n  Set light mode when checked\n- `[data-ccs-input=\"dark-mode\"]`:\n  Set dark mode when checked\n- `[data-ccs-input=\"auto-mode\"]`:\n  Unset explicit mode when checked,\n  and fallback on browser/operating-system settings\n\n#### Themes \u0026 Values:\n\n- `[data-ccs-input~=\"theme\"]`:\n  Allow users to select from available `theme` options.\n  Add `unset-values` to revert all other theme values\n  when changing themes.\n- `[data-ccs-input=\"hue\"]`:\n  Allow users to change the primary hue\n- `[data-ccs-input=\"saturation\"]`:\n  Allow users to adjust the baseline saturation\n- `[data-ccs-input=\"lightness\"]`:\n  Allow users to adjust the baseline lightness\n- `[data-ccs-input=\"contrast\"]`:\n  Allow users to adjust the contrast range\n\nThemes can also use `[data-ccs-field]` attributes\nwith the values above\nto show and hide inputs/labels based on a given theme.\nFor example, a high-contrast theme\nmight not accept user `contrast` input:\n\n```scss\n[data-ccs-theme=\"contrast\"] {\n  --ccs-contrast: 200%; /* override all other contrast settings */\n  --ccs-custom-contrast: none; /* hide [data-ccs-field=\"contrast\"] */\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foddbird%2Fcascading-color-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foddbird%2Fcascading-color-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foddbird%2Fcascading-color-system/lists"}