Migrate to SCSS modules and add build-time theming

.gitignore

@@ -11,3 +11,6 @@ vite.config.ts.timestamp*
 .yarn/*
 !.yarn/releases
 !.yarn/plugins
+# Temporary documentation and planning files
+.tmp/
+tmp/

.prettierignore

@@ -1 +0,0 @@
-src/styles/types.ts

.storybook/main.ts

@@ -1,16 +1,20 @@
 import type { StorybookConfig } from "@storybook/react-vite";
 const config: StorybookConfig = {
   core: {
-    disableTelemetry: true
+    disableTelemetry: true,
   },
   stories: [
     "../src/Introduction.mdx",
     "../src/components/icons/Icons.mdx",
     "../src/**/*.stories.@(js|jsx|ts|tsx)",
   ],
 
-  addons: ["@storybook/addon-links", //"@storybook/addon-interactions",
-  "storybook-addon-pseudo-states", "@storybook/addon-a11y", "@storybook/addon-docs"],
+  addons: [
+    "@storybook/addon-links", //"@storybook/addon-interactions",
+    "storybook-addon-pseudo-states",
+    "@storybook/addon-a11y",
+    "@storybook/addon-docs",
+  ],
 
   framework: {
     name: "@storybook/react-vite",
@@ -32,32 +36,42 @@ const config: StorybookConfig = {
     },
   },
 
-  async viteFinal(config, { configType }) {
+  viteFinal: async (config, { configType }) => {
     // Workaround for Storybook 10.0.7 bug where MDX files generate file:// imports
     // See: https://github.com/storybookjs/storybook/issues (mdx-react-shim resolution)
     config.plugins = config.plugins || [];
     config.plugins.push({
-      name: 'fix-storybook-mdx-shim',
+      name: "fix-storybook-mdx-shim",
       resolveId(source) {
         // Intercept the malformed file:// URL and resolve to the correct package
-        if (source.includes('mdx-react-shim')) {
-          return this.resolve('@mdx-js/react', undefined, { skipSelf: true });
+        if (source.includes("mdx-react-shim")) {
+          return this.resolve("@mdx-js/react", undefined, { skipSelf: true });
         }
         return null;
       },
     });
 
     // Suppress Rollup warnings for production builds
-    if (configType === 'PRODUCTION') {
+    if (configType === "PRODUCTION") {
       config.build = config.build || {};
       config.build.rollupOptions = config.build.rollupOptions || {};
       const originalOnWarn = config.build.rollupOptions.onwarn;
       config.build.rollupOptions.onwarn = (warning, warn) => {
-        if (warning.message?.includes('mdx-react-shim')) return;
-        originalOnWarn ? originalOnWarn(warning, warn) : warn(warning);
+        if (warning.message?.includes("mdx-react-shim")) {
+          return;
+        }
+        if (originalOnWarn) {
+          originalOnWarn(warning, warn);
+        } else {
+          warn(warning);
+        }
       };
     }
 
+    // Ensure CSS modules specificity is correct
+    config.build = config.build || {};
+    config.build.cssCodeSplit = false;
+
     return config;
   },
 };

.storybook/preview.module.scss

@@ -0,0 +1,22 @@
+.cuiThemeBlock {
+  position: absolute;
+  inset: 0;
+  min-height: fill-available;
+
+  overflow: auto;
+  padding: 1rem;
+  box-sizing: border-box;
+  background: tokens.$clickStorybookGlobalBackground;
+
+  &.cuiLeft {
+    left: 0;
+  }
+
+  &.cuiRight {
+    left: 50vw;
+  }
+
+  &.cuiFill {
+    left: 0;
+  }
+}

.storybook/preview.tsx

@@ -1,23 +1,36 @@
 import React from "react";
 import type { Preview } from "@storybook/react-vite";
 import { Decorator } from "@storybook/react-vite";
-import styled from "styled-components";
 import { themes } from "storybook/theming";
-import ClickUIProvider from "../src/theme/ClickUIProvider/ClickUIProvider";
+import { ClickUIProvider } from "@/theme/ClickUIProvider";
+import clsx from "clsx";
+import styles from "./preview.module.scss";
 
-const ThemeBlock = styled.div<{ $left?: boolean; $bfill?: boolean }>(
-  ({ $left, $bfill: fill, theme }) => `
-      position: absolute;
-      top: 0.5rem;
-      left: ${$left || fill ? 0 : "50vw"};
-      right: 0;
-      height: fit-content;
-      bottom: 0;
-      overflow: auto;
-      padding: 1rem;
-      box-sizing: border-box;
-      background: ${theme.click.storybook.global.background};
-    `
+interface ThemeBlockProps {
+  left?: boolean;
+  fill?: boolean;
+  children: React.ReactNode;
+}
+
+const ThemeBlock: React.FC<ThemeBlockProps & { theme?: string }> = ({
+  left,
+  fill,
+  theme = "light",
+  children,
+}) => (
+  <div
+    className={clsx(styles.cuiThemeBlock, {
+      [styles.cuiLeft]: left || fill,
+      [styles.cuiRight]: !left && !fill,
+      [styles.cuiFill]: fill,
+    })}
+    style={{
+      // Set color-scheme to make light-dark() CSS function work
+      colorScheme: theme,
+    }}
+  >
+    {children}
+  </div>
 );
 
 export const globalTypes = {
@@ -26,27 +39,34 @@ export const globalTypes = {
     description: "Global theme for components",
     defaultValue: "dark",
     toolbar: {
-      // The icon for the toolbar item
       icon: "circlehollow",
-      // Array of options
       items: [
-        { value: "dark", icon: "moon", title: "dark" },
-        { value: "light", icon: "sun", title: "light" },
+        { value: "light", icon: "sun", title: "Light" },
+        { value: "dark", icon: "moon", title: "Dark" },
+        { value: "system", icon: "browser", title: "System" },
       ],
-      // Property that specifies if the name of the item will be displayed
       showName: true,
+      dynamicTitle: true,
     },
   },
 };
 const withTheme: Decorator = (StoryFn, context) => {
   const parameters = context.parameters;
-  const theme = parameters?.theme || context.globals.theme;
+  const theme = parameters?.theme || context.globals.theme || "light";
+
   return (
     <ClickUIProvider
+      key={`storybook-theme-${theme}`}
       theme={theme}
-      config={{ tooltip: { delayDuration: 0 } }}
+      config={{
+        tooltip: { delayDuration: 100 },
+        toast: { duration: 3000 },
+      }}
     >
-      <ThemeBlock $left>
+      <ThemeBlock
+        fill
+        theme={theme}
+      >
         <StoryFn />
       </ThemeBlock>
     </ClickUIProvider>
@@ -81,13 +101,9 @@ const preview: Preview = {
     },
     docs: {
       theme: themes.dark,
-      codePanel: true
+      codePanel: true,
     },
   },
-  argTypes: {
-    // Hide children prop from docs table - it doesn't serialize well as a control
-    children: { table: { disable: true } },
-  },
 };
 
 export const decorators = [withTheme];

.stylelintignore

@@ -0,0 +1,10 @@
+# Ignore files not yet migrated
+src/App.module.scss
+src/theme/
+
+# Ignore third-party or generated files
+src/styles/tokens-light-dark.scss
+node_modules
+dist
+build
+*.min.css

.stylelintrc.json

@@ -0,0 +1,76 @@
+{
+  "extends": ["stylelint-config-standard-scss"],
+  "plugins": ["stylelint-scss"],
+  "customSyntax": "postcss-scss",
+  "rules": {
+    "scss/at-rule-no-unknown": [
+      true,
+      {
+        "ignoreAtRules": ["use", "include", "mixin", "function", "return", "each", "if", "else"]
+      }
+    ],
+    "scss/dollar-variable-pattern": null,
+    "scss/at-mixin-pattern": null,
+    "scss/at-function-pattern": null,
+    "scss/percent-placeholder-pattern": null,
+    "selector-class-pattern": null,
+    "custom-property-pattern": null,
+    "keyframes-name-pattern": null,
+    "scss/at-extend-no-missing-placeholder": null,
+    "no-descending-specificity": null,
+    "scss/load-no-partial-leading-underscore": null,
+    "color-function-notation": null,
+    "media-feature-range-notation": null,
+    "alpha-value-notation": null,
+    "property-no-unknown": [
+      true,
+      {
+        "ignoreProperties": ["composes"]
+      }
+    ],
+    "function-no-unknown": [
+      true,
+      {
+        "ignoreFunctions": [
+          "tokens",
+          "var",
+          "calc",
+          "min",
+          "max",
+          "clamp",
+          "url",
+          "rgba",
+          "rgb",
+          "hsl",
+          "hsla",
+          "linear-gradient",
+          "radial-gradient"
+        ]
+      }
+    ],
+    "value-keyword-case": [
+      "lower",
+      {
+        "ignoreProperties": ["composes"]
+      }
+    ],
+    "scss/operator-no-newline-after": null,
+    "scss/operator-no-unspaced": null,
+    "declaration-empty-line-before": null,
+    "rule-empty-line-before": null,
+    "at-rule-empty-line-before": null,
+    "comment-empty-line-before": null,
+    "scss/double-slash-comment-empty-line-before": null,
+    "scss/comment-no-empty": null,
+    "no-invalid-position-at-import-rule": null,
+    "no-duplicate-selectors": null,
+    "selector-pseudo-class-no-unknown": [
+      true,
+      {
+        "ignorePseudoClasses": ["global"]
+      }
+    ],
+    "property-no-deprecated": null,
+    "declaration-property-value-keyword-no-deprecated": null
+  }
+}

.vscode/settings.json

@@ -1,2 +1,19 @@
 {
+  // TypeScript: Prioritize source files over declaration files
+  "typescript.preferences.autoImportFileExcludePatterns": [
+    "**/*.scss.d.ts",
+    "**/node_modules/**"
+  ],
+
+  // Hide generated .scss.d.ts files from search and file explorer
+  "files.exclude": {
+    "**/*.scss.d.ts": true
+  },
+
+  // Search settings to exclude generated files
+  "search.exclude": {
+    "**/*.scss.d.ts": true,
+    "**/node_modules": true,
+    "**/dist": true
+  }
 }