feat(nextra-theme-docs): primary color.lightness theme config (#3592)

* feat(nextra-theme-docs): primary lightness * docs: add lightness to slider tester * chore: prettier * chore: lint is angry with order * docs: reword theme colour description, and add callout for white/grey example * chore: create changeset
shuding · Oct 29, 2024 · d755012 · d755012
1 parent a80f3ce
commit d755012
Show file tree

Hide file tree

Showing 7 changed files with 90 additions and 26 deletions.
diff --git a/.changeset/big-years-agree.md b/.changeset/big-years-agree.md
@@ -0,0 +1,5 @@
+---
+"nextra-theme-docs": feat
+---
+
+feat(nextra-theme-docs): add new theme config option `color.lightness`
diff --git a/docs/components/_slider.tsx b/docs/components/_slider.tsx
@@ -43,3 +43,25 @@ export function Saturation() {
     </div>
   )
 }
+
+export function Lightness() {
+  return (
+    <div className="flex h-6 items-center gap-2">
+      <input
+        type="range"
+        min="0"
+        max="100"
+        step="1"
+        onChange={e => {
+          const value = `${e.target.value}%`
+          e.target.nextSibling!.textContent = value
+          document.documentElement.style.setProperty(
+            '--nextra-primary-lightness',
+            value
+          )
+        }}
+      />
+      <label className="text-sm text-gray-500 w-14" />
+    </div>
+  )
+}
diff --git a/docs/pages/docs/docs-theme/theme-configuration.mdx b/docs/pages/docs/docs-theme/theme-configuration.mdx
@@ -1,4 +1,4 @@
-import { Hue, Saturation } from '@components/_slider'
+import { Hue, Lightness, Saturation } from '@components/_slider'
 import { Screenshot } from 'components/screenshot'
 import { Callout } from 'nextra/components'
 import logoImage from 'public/assets/docs/logo.png'
@@ -146,25 +146,48 @@ Customize the theme behavior of the website.
 
 ### Theme Color
 
-You can adjust the theme color of the website by setting primary hue and
-saturation values for light and dark themes.
+You can adjust the theme color of the website by setting primary hue, saturation
+and lightness (HSL) values for light and dark themes.
 
 <Table>
 
-|                       |                                             |                                           |
-| --------------------- | ------------------------------------------- | ----------------------------------------- |
-| color.hue             | `number \| { dark: number; light: number }` | The hue of the primary theme color        |
-| color.saturation      | `number \| { dark: number; light: number }` | The saturation of the primary theme color |
-| backgroundColor.dark  | `string` in format `RRR,GGG,BBB`            | Background color for light theme          |
-| backgroundColor.light | `string` in format `RRR,GGG,BBB`            | Background color for dark theme           |
+|                       |                                             |                                                     |
+| --------------------- | ------------------------------------------- | --------------------------------------------------- |
+| color.hue             | `number \| { dark: number; light: number }` | The hue of the primary theme color (0 - 360)        |
+| color.saturation      | `number \| { dark: number; light: number }` | The saturation of the primary theme color (0 - 100) |
+| color.lightness       | `number \| { dark: number; light: number }` | The lightness of the primary theme color (0 - 100)  |
+| backgroundColor.dark  | `string` in format `RRR,GGG,BBB`            | Background color for light theme                    |
+| backgroundColor.light | `string` in format `RRR,GGG,BBB`            | Background color for dark theme                     |
 
 </Table>
 
 Try it out for this website:
 
-| Hue     | Saturation     |
-| ------- | -------------- |
-| <Hue /> | <Saturation /> |
+| Hue (H) | Saturation (S) | Lightness (L) |
+| ------- | -------------- | ------------- |
+| <Hue /> | <Saturation /> | <Lightness/>  |
+
+<Callout>
+
+You can adjust the lightness independently for dark or light mode to increase
+legibility. For example, to have a neutral primary color you can set the primary
+colour to be white `HSL(0, 0%, 100%)` on dark theme and gray `HSL(0, 0%, 50%)`
+for light theme.
+
+```jsx filename="theme.config.jsx"
+export default {
+  color: {
+    hue: 0,
+    saturation: 0,
+    lightness: {
+      dark: 100,
+      light: 50
+    }
+  }
+}
+```
+
+</Callout>
 
 ## Navbar
 

diff --git a/packages/nextra-theme-docs/src/components/head.tsx b/packages/nextra-theme-docs/src/components/head.tsx
@@ -15,13 +15,17 @@ export function Head(): ReactElement {
     typeof themeConfig.head === 'function'
       ? themeConfig.head({})
       : themeConfig.head
-  const { hue, saturation } = themeConfig.color
+  const { hue, saturation, lightness } = themeConfig.color
   const { dark: darkHue, light: lightHue } =
     typeof hue === 'number' ? { dark: hue, light: hue } : hue
   const { dark: darkSaturation, light: lightSaturation } =
     typeof saturation === 'number'
       ? { dark: saturation, light: saturation }
       : saturation
+  const { dark: darkLightness, light: lightLightness } =
+    typeof lightness === 'number'
+      ? { dark: lightness, light: lightness }
+      : lightness
 
   const bgColor = themeConfig.backgroundColor
 
@@ -56,7 +60,7 @@ export function Head(): ReactElement {
         name="viewport"
         content="width=device-width, initial-scale=1.0, viewport-fit=cover"
       />
-      <style>{`:root{--nextra-primary-hue:${lightHue}deg;--nextra-primary-saturation:${lightSaturation}%;--nextra-navbar-height:64px;--nextra-menu-height:3.75rem;--nextra-banner-height:2.5rem;--nextra-bg:${bgColor.light};}.dark{--nextra-primary-hue:${darkHue}deg;--nextra-primary-saturation:${darkSaturation}%;--nextra-bg:${bgColor.dark};}`}</style>
+      <style>{`:root{--nextra-primary-hue:${lightHue}deg;--nextra-primary-saturation:${lightSaturation}%;--nextra-primary-lightness:${lightLightness}%;--nextra-navbar-height:64px;--nextra-menu-height:3.75rem;--nextra-banner-height:2.5rem;--nextra-bg:${bgColor.light};}.dark{--nextra-primary-hue:${darkHue}deg;--nextra-primary-saturation:${darkSaturation}%;--nextra-primary-lightness:${darkLightness}%;--nextra-bg:${bgColor.dark};}`}</style>
       {head}
     </NextHead>
   )

diff --git a/packages/nextra-theme-docs/src/constants.tsx b/packages/nextra-theme-docs/src/constants.tsx
@@ -42,6 +42,10 @@ export const DEFAULT_THEME: DocsThemeConfig = {
       dark: 204,
       light: 212
     },
+    lightness: {
+      dark: 55,
+      light: 45
+    },
     saturation: 100
   },
   darkMode: true,

diff --git a/packages/nextra-theme-docs/src/schemas.ts b/packages/nextra-theme-docs/src/schemas.ts
@@ -98,6 +98,12 @@ export const themeSchema = /* @__PURE__ */ (() =>
           dark: z.number(),
           light: z.number()
         })
+      ),
+      lightness: z.number().or(
+        z.strictObject({
+          dark: z.number(),
+          light: z.number()
+        })
       )
     }),
     project: z.strictObject({

diff --git a/packages/nextra-theme-docs/tailwind.config.ts b/packages/nextra-theme-docs/tailwind.config.ts
@@ -5,7 +5,7 @@ const makePrimaryColor: any =
   (l: number) =>
   ({ opacityValue }: { opacityValue?: string }) => {
     return (
-      `hsl(var(--nextra-primary-hue) var(--nextra-primary-saturation) ${l}%` +
+      `hsl(var(--nextra-primary-hue) var(--nextra-primary-saturation) calc(var(--nextra-primary-lightness) + ${l}%)` +
       (opacityValue ? ` / ${opacityValue})` : ')')
     )
   }
@@ -52,17 +52,17 @@ export default {
       blue: colors.blue,
       yellow: colors.yellow,
       primary: {
-        50: makePrimaryColor(97),
-        100: makePrimaryColor(94),
-        200: makePrimaryColor(86),
-        300: makePrimaryColor(77),
-        400: makePrimaryColor(66),
-        500: makePrimaryColor(50),
-        600: makePrimaryColor(45),
-        700: makePrimaryColor(39),
-        750: makePrimaryColor(35),
-        800: makePrimaryColor(32),
-        900: makePrimaryColor(24)
+        50: makePrimaryColor(52),
+        100: makePrimaryColor(49),
+        200: makePrimaryColor(41),
+        300: makePrimaryColor(32),
+        400: makePrimaryColor(21),
+        500: makePrimaryColor(5),
+        600: makePrimaryColor(0),
+        700: makePrimaryColor(-6),
+        750: makePrimaryColor(-10),
+        800: makePrimaryColor(-13),
+        900: makePrimaryColor(-11)
       }
     }
   },