feat: improve the shades generating algorithm and add test cases

Author: upupming

.github/workflows/ci.yml

@@ -24,6 +24,7 @@ jobs:
       - name: Install and Build 🔧
         run: |
           pnpm i
+          pnpm test
           pnpm run build
           for d in examples/* ; do
               (cd "$d" && pnpm run build && cp -r dist/ ../../dist/"${d:9}" && cp -r dist/ ../../dist)

README.md

@@ -7,11 +7,12 @@
     - [Override auto-generated shade values](#override-auto-generated-shade-values)
     - [Customized palette keys](#customized-palette-keys)
     - [Full configurations](#full-configurations)
-    - [Reference](#reference)
+    - [About shades generating algorithm](#about-shades-generating-algorithm)
+    - [Credits](#credits)
 
 Adds multiple themes support for Tailwind CSS and Windi CSS.
 
-You can just develop your app with one theme and it will work with multiple themes color palettes, all you need is just to specify your default (for shade `500`) color values for your theme pallette. We will generate all shades from `50` to `900` for you, following the built-in shade name convention of the [default color values](https://tailwindcss.com/docs/customizing-colors).
+You can just develop your app with one theme and it will work with multiple themes color palettes, all you need is just to specify your default color values for your theme pallette. We will generate all shades from `50` to `900` for you, following the built-in shade name convention of the [default color values](https://tailwindcss.com/docs/customizing-colors).
 
 | Dracula (default theme)     | Material                      |
 | --------------------------- | ----------------------------- |
@@ -242,7 +243,7 @@ As the [tailwindcss docs says](https://tailwindcss.com/docs/customizing-colors#g
 
 > Bad news, color is complicated and despite trying dozens of different tools, we’ve yet to find one that does a good job generating these sorts of color palettes. We picked all of Tailwind’s default colors by hand, meticulously balancing them by eye and testing them in real designs to make sure we were happy with them.
 
-You can specify all (or just a part of) the shades of a color if you want, this will overwrite the auto-generated shade value. It will be super useful if you find the auto-generated not satisfying. Below is an example configuration, you can explore more on the [`override-shades`](examples/override-shades) example:
+Although our shade generating algorithm is okay in most cases, you may still find the auto-generated shades not satisfying. You can specify all (or just a part of) the shades of a color if you want, this will overwrite the auto-generated shade value. Below is an example configuration, you can explore more on the [`override-shades`](examples/override-shades) example:
 
 ```js
 themeable({
@@ -301,39 +302,42 @@ themeable({
 This is the type definition of this plugin, you can dive into the source code to see more, all the type definitions are well documented for your convenience. If you have any questions, please fell free to open an issue. And new theme contribution is welcome!
 
 ```ts
-interface ThemeableOptions {
-    /**
-     * Support a list of theme definitions, the user should define the colors of the theme follow the contribute of Dracula theme.
-     * See https://draculatheme.com/contribute#color-palette
-     * @default []
-     */
-    themes?: Theme[];
-    /**
-     * Prefix of the class to enable a theme, for example the container with class `${classPrefix}-dracula` will enable dracula theme in its children elements
-     * @default `themeable`
-     */
-    classPrefix?: string;
-    /** The lighten step for auto generated shades smaller than the default `500` color
-     * For example, if you passed `#50FA7B` as the `green` theme key, and `shadeLightenStep` is 8,
-     * then we will use this color as the `DEFAULT` and shade `500` to generate all other shades of `green`,
-     * for shade smaller than `500`, we will add the lightness up `shadeLightenStep` in per 100 gap.
-     * Color `#50FA7B` converted to HSL is [135, 94, 64], so the shade `400` will be computed to [135, 94, 72]
-     * @default 8
-     */
-    shadeLightenStep?: number;
-    /** Similar with `shadeLightenStep` but for shades larger than `500`
-     * @default 11
-     */
-    shadeDarkenStep?: number;
-    /** When not specify any theme in HTML, the `defaultTheme` will be used
-     * @default `dracula`
-     */
-    defaultTheme?: string;
+export interface ThemeableOptions {
+  /**
+   * Support a list of theme definitions, the user should define the colors of the theme follow the contribute of Dracula theme.
+   * See https://draculatheme.com/contribute#color-palette
+   * @default []
+   */
+  themes?: Theme[]
+  /**
+   * Prefix of the class to enable a theme, for example the container with class `${classPrefix}-dracula` will enable dracula theme in its children elements
+   * @default `themeable`
+   */
+  classPrefix?: string
+  /** When not specify any theme in HTML, the `defaultTheme` will be used
+   * @default `dracula`
+   */
+  defaultTheme?: string
+  /**
+   * This will allow you the change the difference in saturation between each shade of color. By default we use  1.771968374684816 because these are the averages that steps change in tailwind's default colors. Thanks to https://tw-shade-gen.netlify.app/
+   */
+  saturationFactor?: number
+  /**
+   * This will allow you the change the difference in lightness between each shade of color. By default we use 7.3903743315508015 because these are the averages that steps change in tailwind's default colors. Thanks to https://tw-shade-gen.netlify.app/
+   */
+  lightFactor?: number
 }
 ```
 
-## Reference
+## About shades generating algorithm
 
-1. https://github.com/dracula/tailwind
-2. https://github.com/anheric/tailwindshades
-3. [Theming Tailwind with CSS Variables](https://www.youtube.com/watch?v=MAtaT8BZEAo)
+The shades generating algorithm will find a best shade number (`50`-`900`) for your color, and then generate darker and lighter shades with fixed saturation and lightness step (`saturationFactor` and `lightFactor`).
+
+## Credits
+
+1. Idea of shades generation
+    1. https://github.com/dracula/tailwind
+    2. https://github.com/nickgraffis/tailwind-color-generator
+    3. https://github.com/anheric/tailwindshades
+2. Idea of theming
+    1. [Theming Tailwind with CSS Variables](https://www.youtube.com/watch?v=MAtaT8BZEAo)

babel.config.js

@@ -0,0 +1,7 @@
+// https://jestjs.io/docs/getting-started#using-typescript
+module.exports = {
+  presets: [
+    ['@babel/preset-env', { targets: { node: 'current' } }],
+    '@babel/preset-typescript'
+  ]
+}

examples/customized-palette-keys/vite.config.ts

@@ -5,5 +5,5 @@ export default defineConfig({
   plugins: [
     WindiCSS()
   ],
-  base: '/tailwindcss-themeable/customized-palette-keys/'
+  base: './'
 })

examples/override-shades/vite.config.ts

@@ -5,5 +5,5 @@ export default defineConfig({
   plugins: [
     WindiCSS()
   ],
-  base: '/tailwindcss-themeable/override-shades/'
+  base: './'
 })

examples/tailwind/index.html

@@ -21,7 +21,9 @@
         top-0
         flex
         justify-between
-        bg-themeable-selection
+        bg-themeable-background
+        border-themeable-selection
+        shadow-lg shadow-themeable-foreground
         px-8
         py-4
         text-themeable-foreground
@@ -35,14 +37,15 @@
           <div class="dropdown block relative">
             <button
               class="
-                bg-themeable-cyan
+                bg-themeable-cyan-500
                 text-themeable-background
                 font-semibold
                 py-2
                 px-4
                 rounded
                 inline-flex
                 items-center
+                focus:outline-transparent
               "
             >
               <span class="mr-1">Theme</span>
@@ -110,8 +113,17 @@
       </ul>
     </nav>
 
-    <div class="m-8 space-y-4 mb-20 text-themeable-foreground">
-      <figure class="md:flex rounded-xl p-8 md:p-0 bg-themeable-selection">
+    <div class="m-16 space-y-16 mb-20 text-themeable-foreground">
+      <figure
+        class="
+          md:flex
+          rounded-xl
+          p-8
+          md:p-0
+          bg-themeable-selection
+          shadow-lg shadow-themeable-foreground
+        "
+      >
         <img
           class="
             w-32
@@ -129,12 +141,14 @@
         <div class="pt-6 md:p-8 text-center md:text-left space-y-4">
           <blockquote>
             <p class="text-lg font-semibold">
-              Multiple themes support for tailwindcss. Developing with one theme
-              and it works with multiple themes, all you need is just to define
-              your default (for shade <code>500</code>) color values for your
-              theme. We will generate all shades from <code>50</code> to
-              <code>900</code> for you, following the built-in shade name
-              convention of the
+              Adds multiple themes support for Tailwind CSS and Windi CSS.
+            </p>
+            <p class="text-lg font-semibold">
+              You can just develop your app with one theme and it will work with
+              multiple themes color palettes, all you need is just to specify
+              your default color values for your theme pallette. We will
+              generate all shades from <code>50</code> to <code>900</code> for
+              you, following the built-in shade name convention of the
               <a
                 href="https://tailwindcss.com/docs/customizing-colors"
                 class="text-link"
@@ -143,8 +157,8 @@
             </p>
           </blockquote>
           <figcaption class="font-medium">
-            <div class="text-themeable-cyan-600">Yiming Li</div>
-            <div class="text-themeable-foreground-600">GitHub ID: upupming</div>
+            <div class="text-themeable-cyan-50">Author: Yiming Li</div>
+            <div class="text-themeable-foreground">GitHub ID: upupming</div>
           </figcaption>
         </div>
       </figure>
@@ -153,8 +167,8 @@
           relative
           z-10
           rounded-xl
-          shadow-lg
-          divide-y-2 divide-themeable-orange
+          shadow-lg shadow-themeable-foreground
+          divide-y-2 divide-themeable-orange-500
           flex flex-col
         "
       >
@@ -163,12 +177,13 @@
             class="
               flex-none
               w-48
-              bg-themeable-orange-200
+              border-themeable-orange-500 border-t-2 border-l-2
+              bg-themeable-orange-50
+              text-themeable-orange-500
               rounded-tl-xl
               text-lg
               leading-6
               font-semibold
-              text-themeable-orange
               px-4
               py-3
               p-8
@@ -193,10 +208,7 @@
               </dd>
             </div>
             <div class="space-y-1">
-              <dd
-                class="text-themeable-foreground-600 text-sm"
-                style="opacity: 1"
-              >
+              <dd class="text-themeable-foreground text-sm" style="opacity: 1">
                 We follow the
                 <a href="https://draculatheme.com/contribute" class="text-link"
                   >Dracula color palette definition</a
@@ -220,12 +232,13 @@
             class="
               flex-none
               w-48
-              bg-themeable-orange-200
+              bg-themeable-orange-50
+              text-themeable-orange-500
+              border-themeable-orange-500 border-b-2 border-l-2
               rounded-bl-xl
               text-lg
               leading-6
               font-semibold
-              text-themeable-orange
               px-4
               py-3
               p-8
@@ -240,10 +253,20 @@
               bg-themeable-selection
               rounded-br-xl
               overflow-hidden
-              text-themeable-foreground-600
+              text-themeable-foreground
             "
           >
-            <dl class="px-4 py-6 p-6 space-y-6">
+            <dl
+              class="
+                px-4
+                py-6
+                p-6
+                grid
+                space-x-2 space-y-2
+                lg:grid-cols-3
+                grid-cols-1
+              "
+            >
               <div class="space-y-2">
                 <dt class="font-mono text-xs">
                   bg-themeable-background-{50-900}

examples/tailwind/style.css

@@ -11,8 +11,8 @@
 }
 
 .text-link {
-  @apply text-themeable-cyan-700
-    hover:text-themeable-cyan-800
+  @apply text-themeable-orange-500
+    hover:text-themeable-orange-600
     transition;
 }
 

examples/tailwind/vite.config.ts

@@ -1,3 +1,3 @@
 export default {
-  base: '/tailwindcss-themeable/tailwind/'
+  base: './'
 }