feat: add Open edX Dark theme

example/src/MyComponent.jsx

@@ -5,6 +5,7 @@ import {
 } from '@openedx/paragon';
 // eslint-disable-next-line import/no-extraneous-dependencies
 import { FavoriteBorder } from '@openedx/paragon/icons';
+import ThemeSwitcher from './ThemeSwitcher';
 
 function MyComponent() {
   const [value, setValue] = useState('');
@@ -13,9 +14,12 @@ function MyComponent() {
 
   return (
     <Container className="p-5">
-      <Stack direction="horizontal" gap={2}>
-        <h1>My Form</h1>
-        <Bubble variant="error">1</Bubble>
+      <Stack direction="horizontal" gap={2} className="justify-content-between align-items-center">
+        <Stack direction="horizontal" gap={2}>
+          <h1>My Form</h1>
+          <Bubble variant="error">1</Bubble>
+        </Stack>
+        <ThemeSwitcher />
       </Stack>
       <Form>
         <Form.Group>

example/src/ThemeSwitcher.jsx

@@ -0,0 +1,38 @@
+import React, { useEffect, useState } from 'react';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { Form } from '@openedx/paragon';
+
+// Paragon ships each theme as a separate, self-contained stylesheet. Switching
+// themes means loading the corresponding CSS — here we swap a single <link>
+// between the built light and dark bundles served at /paragon-dist
+// (see webpack.dev.config.js). Run `make build` at the repo root first.
+const THEME_HREF = {
+  light: '/paragon-dist/light.min.css',
+  dark: '/paragon-dist/dark.min.css',
+};
+
+function ThemeSwitcher() {
+  const [theme, setTheme] = useState('light');
+
+  useEffect(() => {
+    let link = document.getElementById('paragon-theme');
+    if (!link) {
+      link = document.createElement('link');
+      link.id = 'paragon-theme';
+      link.rel = 'stylesheet';
+      document.head.appendChild(link);
+    }
+    link.href = THEME_HREF[theme];
+  }, [theme]);
+
+  return (
+    <Form.Switch
+      checked={theme === 'dark'}
+      onChange={(e) => setTheme(e.target.checked ? 'dark' : 'light')}
+    >
+      Dark theme
+    </Form.Switch>
+  );
+}
+
+export default ThemeSwitcher;

example/webpack.dev.config.js

@@ -25,4 +25,20 @@ config.resolveLoader = {
   ],
 };
 
+// Serve Paragon's built theme stylesheets (dist/light.min.css, dist/dark.min.css)
+// at /paragon-dist so the ThemeSwitcher demo can swap between them via a <link>.
+// Requires `make build` (or `npm run build`) at the repo root to populate ./dist.
+const existingStatic = config.devServer && config.devServer.static;
+let staticDirs = [];
+if (Array.isArray(existingStatic)) {
+  staticDirs = [...existingStatic];
+} else if (existingStatic) {
+  staticDirs = [existingStatic];
+}
+staticDirs.push({
+  directory: path.resolve(__dirname, '..', 'dist'),
+  publicPath: '/paragon-dist',
+});
+config.devServer = { ...(config.devServer || {}), static: staticDirs };
+
 module.exports = config;

lib/build-scss.js

@@ -104,7 +104,9 @@ const compileAndWriteStyleSheets = ({
   ];
 
   const postCSSCompilation = ora(`Compilation for ${capitalize(name)} stylesheet...`).start();
-  postCSS(commonPostCssPlugins)
+  // Return the promise so callers can await it; theme variants share a single
+  // theme-urls.json, so they must be built sequentially (see buildScssCommand).
+  return postCSS(commonPostCssPlugins)
     .process(compiledStyleSheet.css, { from: stylesPath, map: false })
     .then((result) => {
       postCSSCompilation.succeed(`Successfully compiled ${capitalize(name)} theme stylesheet`);
@@ -151,7 +153,7 @@ const compileAndWriteStyleSheets = ({
  *
  * @param {Array<string>} commandArgs - Command line arguments for building SCSS stylesheets.
  */
-function buildScssCommand(commandArgs) {
+async function buildScssCommand(commandArgs) {
   const defaultArgs = {
     corePath: path.resolve(process.cwd(), 'styles/scss/core/core.scss'),
     excludeCore: false,
@@ -168,21 +170,25 @@ function buildScssCommand(commandArgs) {
     defaultThemeVariants,
   } = minimist(commandArgs, { default: defaultArgs, boolean: ['excludeCore'] });
 
+  // Discover theme variant dirs synchronously, before any await. Core + variants
+  // are then built sequentially because they share a single theme-urls.json
+  // (concurrent builds would race and drop one).
+  const themeDirs = fs.readdirSync(themesPath, { withFileTypes: true })
+    .filter((item) => item.isDirectory());
+
   // Core CSS
   if (!excludeCore) {
-    compileAndWriteStyleSheets({
+    await compileAndWriteStyleSheets({
       name: 'core',
       stylesPath: corePath,
       outDir,
     });
   }
 
   // Theme variants CSS
-  const themeDirs = fs.readdirSync(themesPath, { withFileTypes: true })
-    .filter((item) => item.isDirectory());
-
   for (const themeDir of themeDirs) {
-    compileAndWriteStyleSheets({
+    // eslint-disable-next-line no-await-in-loop
+    await compileAndWriteStyleSheets({
       name: themeDir.name,
       stylesPath: `${themesPath}/${themeDir.name}/index.css`,
       outDir,

package.json

@@ -54,7 +54,7 @@
     "build-types": "tsc --emitDeclarationOnly",
     "playroom:start": "npm run playroom:start --workspace=www",
     "playroom:build": "npm run playroom:build --workspace=www",
-    "build-tokens": "./bin/paragon-scripts.js build-tokens --build-dir ./styles/css",
+    "build-tokens": "./bin/paragon-scripts.js build-tokens --build-dir ./styles/css --all-themes",
     "build-tokens:watch": "npx nodemon --ignore styles/css -x \"npm run build-tokens\"",
     "serve-theme-css": "./bin/paragon-scripts.js serve-theme-css --build-dir ./dist --theme-name='Custom Theme Name'",
     "replace-variables-usage-with-css": "./bin/paragon-scripts.js replace-variables -p src -t usage",

src/Card/index.scss

@@ -125,7 +125,7 @@ a.pgn__card {
     }
 
     %header-title {
-      color: var(--pgn-color-black);
+      color: var(--pgn-color-headings-base);
       font-weight: var(--pgn-typography-font-weight-bold);
       text-align: start;
     }
@@ -270,7 +270,7 @@ a.pgn__card {
     }
 
     .pgn__card-section-title {
-      color: var(--pgn-color-black);
+      color: var(--pgn-color-headings-base);
       font-weight: var(--pgn-typography-font-weight-bold);
       font-size: var(--pgn-typography-font-size-h5-base);
       margin-bottom: var(--pgn-spacing-card-spacer-y);
@@ -396,7 +396,7 @@ a.pgn__card {
 
     .pgn__card-status__heading {
       font-size: var(--pgn-typography-font-size-h4-base);
-      color: var(--pgn-color-black);
+      color: var(--pgn-color-headings-base);
       display: flex;
       font-weight: var(--pgn-typography-font-weight-bold);
       line-height: 1.5rem;

src/Collapsible/index.scss

@@ -67,7 +67,7 @@
     cursor: pointer;
     align-items: center;
     text-decoration: underline;
-    color: theme-color("primary", "default");
+    color: var(--pgn-color-theme-default-primary);
     padding: var(--pgn-spacing-collapsible-card-spacer-basic-y) var(--pgn-spacing-collapsible-card-spacer-basic-x);
   }
 

src/ColorPicker/index.scss

@@ -24,7 +24,7 @@
 }
 
 .pgn__color-modal {
-  background: var(--pgn-color-white);
+  background: var(--pgn-color-bg-base);
   padding-bottom: .1rem;
   margin-bottom: var(--pgn-spacing-spacer-base);
 }

src/DataTable/index.scss

@@ -139,11 +139,11 @@
   width: 100%;
 
   &.is-striped tr:nth-child(even) {
-    background-color: var(--pgn-color-light-200);
+    background-color: var(--pgn-color-data-table-bg-striped);
   }
 
   th {
-    background-color: var(--pgn-color-light-300);
+    background-color: var(--pgn-color-data-table-bg-header);
     padding: var(--pgn-spacing-data-table-padding-cell);
     text-align: start;
   }
@@ -296,7 +296,7 @@
 }
 
 .pgn__data-table__overflow-actions-menu {
-  background: var(--pgn-color-white);
+  background: var(--pgn-color-bg-base);
   padding: var(--pgn-spacing-spacer-2);
   box-shadow: var(--pgn-elevation-box-shadow-level-1);
   border-radius: 4px;

src/Form/_index.scss

@@ -503,7 +503,7 @@ select.form-control {
   }
 
   &:focus {
-    border-color: var(--pgn-color-black);
+    border-color: var(--pgn-color-gray-900);
 
     &::before {
       border-radius: var(--pgn-size-form-control-border-radio-indicator-radius);
@@ -632,7 +632,7 @@ select.form-control {
     max-height: 15rem;
     overflow-y: scroll;
     position: absolute;
-    background-color: var(--pgn-color-white);
+    background-color: var(--pgn-color-bg-base);
     width: calc(100% - .5rem);
     z-index: var(--pgn-elevation-dropdown-zindex);
     top: 3.125rem;
@@ -658,7 +658,7 @@ select.form-control {
       .spinner-border {
         width: var(--pgn-size-form-autosuggest-spinner-width);
         height: var(--pgn-size-form-autosuggest-spinner-height);
-        border: var(--pgn-size-form-autosuggest-border-width) solid var(--pgn-color-black);
+        border: var(--pgn-size-form-autosuggest-border-width) solid var(--pgn-color-gray-900);
         border-right-color: transparent;
       }
     }

src/Menu/README.md

@@ -77,7 +77,7 @@ A ``Menu`` can be implemented to appear inside a `modalpopup` for a wide variety
       <ModalPopup positionRef={target} isOpen={isOpen} onClose={close} style={{
         width: 500, height: 50
       }}>
-      <div className="bg-white">
+      <div style={{ backgroundColor: 'var(--pgn-color-bg-base)' }}>
         <Menu>
           <MenuItem as={Button} variant="tertiary" size="inline" onClick= {()=>setSelected('Beans')}>Beans</MenuItem>
           <MenuItem as={Button} variant="tertiary" size="inline" onClick= {()=>setSelected('Greens')}>Greens</MenuItem>

src/Modal/_ModalDialog.scss

@@ -185,7 +185,7 @@
   &::before {
     content: "";
     background-color: transparent;
-    background-image: linear-gradient(#605C5C, #B8BEBE, transparent 50%);
+    background-image: linear-gradient(var(--pgn-color-modal-content-scroll-shadow-from), var(--pgn-color-modal-content-scroll-shadow-to), transparent 50%);
     display: block;
     height: 20px;
     position: sticky;
@@ -203,8 +203,8 @@
     background-image:
       linear-gradient(
         360deg,
-        #605C5C,
-        #B8BEBE,
+        var(--pgn-color-modal-content-scroll-shadow-from),
+        var(--pgn-color-modal-content-scroll-shadow-to),
         transparent 50%
       );
     display: block;

src/Modal/index.scss

@@ -62,7 +62,7 @@
   }
 
   &::before {
-    border-top-color: rgba(0, 0, 0, .2);
+    border-top-color: var(--pgn-color-modal-content-border);
   }
 }
 
@@ -98,7 +98,7 @@
 .pgn__modal-popup__arrow-top-start::after,
 .pgn__modal-popup__arrow-top::after {
   bottom: var(--pgn-size-border-width);
-  border-top-color: var(--pgn-color-white);
+  border-top-color: var(--pgn-color-bg-base);
 }
 
 [data-popper-placement^="right"] .pgn__modal-popup__arrow-auto,

src/Modal/modal-layer.mdx

@@ -27,7 +27,7 @@ A generic component for creating accessibile modal layer objects. The modal laye
         <Button variant="outline-primary" onClick={open}>Open modal layer</Button>
       </div>
       <ModalLayer isOpen={isOpen} onClose={close}>
-        <div role="dialog" aria-label="My dialog" className="mw-sm p-5 bg-white mx-auto my-5">
+        <div role="dialog" aria-label="My dialog" className="mw-sm p-5 mx-auto my-5 border rounded" style={{ backgroundColor: 'var(--pgn-color-bg-base)' }}>
           <h1>I'm a dialog box</h1>
           <p>
             <Button variant="primary" className="mie-2">A button</Button>
@@ -67,7 +67,7 @@ A generic component for creating accessibile modal layer objects. The modal laye
         <Button variant="outline-primary" onClick={open}>Open small modal layer</Button>
       </div>
       <ModalLayer isOpen={isOpen} onClose={close}>
-        <div role="dialog" aria-label="My dialog" className="mw-sm p-5 bg-white mx-auto my-5">
+        <div role="dialog" aria-label="My dialog" className="mw-sm p-5 mx-auto my-5 border rounded" style={{ backgroundColor: 'var(--pgn-color-bg-base)' }}>
           <h1>I'm a dialog box</h1>
           <p>
             <Button variant="primary" className="mie-2">A button</Button>

src/Modal/modal-popup.mdx

@@ -40,8 +40,8 @@ A proper way to implement this is to use [callback refs](https://react.dev/refer
         isOpen={isOpen}
         onClose={close}>
         <div
-          className="bg-white p-3 rounded shadow"
-          style={{textAlign: 'start'}}>
+          className="p-3 rounded shadow border"
+          style={{textAlign: 'start', backgroundColor: 'var(--pgn-color-bg-base)'}}>
           <p>This could be a menu or tray.</p>
 
           <Button variant="primary" className="mie-2">Action</Button>
@@ -78,8 +78,8 @@ The arrow modifier positions an inner element of the modal popup so it appears c
         isOpen={isOpen}
         onClose={close}>
         <div
-          className="bg-white p-3 rounded shadow border"
-          style={{textAlign: 'start'}}>
+          className="p-3 rounded shadow border"
+          style={{textAlign: 'start', backgroundColor: 'var(--pgn-color-bg-base)'}}>
           <p>This could be a menu or tray.</p>
 
           <Button variant="primary" className="mie-2">Action</Button>

src/ProductTour/Checkpoint.scss

@@ -89,8 +89,8 @@
     border-right:
       solid var(--pgn-size-product-tour-checkpoint-arrow-transparent)
       var(--pgn-color-product-tour-checkpoint-arrow-border-transparent);
-    filter: drop-shadow(0 4px 2px rgba(0, 0, 0, .1));
-    -webkit-filter: drop-shadow(0 4px 2px rgba(0, 0, 0, .1));
+    filter: drop-shadow(0 4px 2px var(--pgn-color-product-tour-checkpoint-box-shadow));
+    -webkit-filter: drop-shadow(0 4px 2px var(--pgn-color-product-tour-checkpoint-box-shadow));
   }
 }
 
@@ -131,7 +131,7 @@
     border-right:
       solid var(--pgn-size-product-tour-checkpoint-arrow-transparent)
       var(--pgn-color-product-tour-checkpoint-arrow-border-transparent);
-    filter: drop-shadow(3px 1px 2px rgba(0, 0, 0, .1));
+    filter: drop-shadow(3px 1px 2px var(--pgn-color-product-tour-checkpoint-box-shadow));
   }
 }
 
@@ -153,6 +153,6 @@
     border-right:
       solid var(--pgn-size-product-tour-checkpoint-arrow-top)
       var(--pgn-color-product-tour-checkpoint-arrow-border-top);
-    filter: drop-shadow(-3px 1px 2px rgba(0, 0, 0, .1));
+    filter: drop-shadow(-3px 1px 2px var(--pgn-color-product-tour-checkpoint-box-shadow));
   }
 }

src/SelectableBox/index.scss

@@ -21,7 +21,7 @@
   box-shadow: var(--pgn-elevation-box-shadow-level-1);
   border-radius: var(--pgn-spacing-selectable-box-border-radius);
   text-align: start;
-  background: var(--pgn-color-white);
+  background: var(--pgn-color-bg-base);
 
   &:focus-visible {
     outline: 1px solid var(--pgn-color-primary-700);

src/Sheet/index.scss

@@ -34,7 +34,7 @@
 .pgn__sheet-component {
   position: fixed;
   padding: 1.25rem;
-  background-color: var(--pgn-color-white);
+  background-color: var(--pgn-color-bg-base);
   z-index: var(--pgn-elevation-sheet-zindex-main);
 
   &.pgn__sheet__dark {

src/Skeleton/index.scss

@@ -1,3 +1,8 @@
 .react-loading-skeleton {
   z-index: unset;
+  // Map react-loading-skeleton's own custom properties to theme-aware Paragon
+  // grays so the placeholder shimmer adapts to light/dark instead of staying
+  // a fixed light gray (which appears as a bright patch on dark surfaces).
+  --base-color: var(--pgn-color-gray-200) !important;
+  --highlight-color: var(--pgn-color-gray-300) !important;
 }