This is a feature-branch pull-request from feature/css-vars to main (#2541)

## Summary:

- [WB-1816] Rework `semanticColor` tokens to be exported as CSS variables (#2481)
- [WB-1644.1] Modify ThemeSwitcher to use a data-wb-theme attribute for theming (#2557)
- [WB-1644.2] Convert border and sizing tokens to CSS variables (#2561)
- [🔥AUDIT🔥] Tokens: Export TS types correctly in package.json so consumers can use them correctly (#2564)

[WB-1816]: https://khanacademy.atlassian.net/browse/WB-1816?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

Issue: "none"

## Test plan:

Verify that all the components are now using CSS variables when `sizing`, `border` and `semanticColor` tokens are used.

<img width="2910" alt="Screenshot 2025-04-17 at 3 56 39 PM" src="https://github.com/user-attachments/assets/65602a0e-073c-4109-9b28-cfd7d11f4752" />

Author: jandrade

Reviewers: beaesguerra

Required Reviewers:

Approved By: beaesguerra

Checks: ✅ 34 checks were successful, ⏭️  8 checks have been skipped, ⏹️  15 checks were cancelled

Pull Request URL: #2541

Author: jandrade

.changeset/clean-ravens-happen.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/wonder-blocks-tokens": minor
+---
+
+Export `border` and `sizing` as CSS variables. Map JS tokens to css var counterparts

.changeset/gold-peaches-guess.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/wonder-blocks-form": patch
+---
+
+TextField: Fix outline-width on focus

.changeset/heavy-islands-tan.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/wonder-blocks-pill": patch
+---
+
+Use color-mix() for active background colors

.changeset/odd-turkeys-train.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/wonder-blocks-tokens": patch
+---
+
+Export TS types correctly in package.json so consumers can use them correctly

.changeset/silver-pumas-marry.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/wonder-blocks-tokens": major
+---
+
+Replaces `semanticColor` values with references to css variables. Creates a build step to convert semanticColor tokens to css variables that can be consumed via CSS imports.

.changeset/slimy-meals-tickle.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/wonder-blocks-theming": minor
+---
+
+Export THEME_DATA_ATTRIBUTE to centralize how the theme is set in WB

.changeset/ten-gorillas-invent.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/wonder-blocks-icon-button": patch
+---
+
+Simplify IconButton pseudo-classes

.changeset/tidy-humans-fail.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/wonder-blocks-theming": minor
+---
+
+Add ThemeSwitcher component to change themes using CSS variables

.changeset/yellow-lies-sort.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/wonder-blocks-tokens": minor
+---
+
+Update build script to use the new data-wb-theme attribute to generate styles.css. Fixes vite.config to allow importing css files in Storybbok

.storybook/main.ts

@@ -28,7 +28,7 @@ const config: StorybookConfig = {
         disableTelemetry: true,
     },
     framework: "@storybook/react-vite",
-    async viteFinal(config, options) {
+    async viteFinal(config) {
         // Merge custom configuration into the default config
         const {mergeConfig} = await import("vite");
 

.storybook/preview.tsx

@@ -1,13 +1,19 @@
 import * as React from "react";
 import wonderBlocksTheme from "./wonder-blocks-theme";
 import {Decorator} from "@storybook/react";
+import {RenderStateRoot} from "@khanacademy/wonder-blocks-core";
 import {semanticColor} from "@khanacademy/wonder-blocks-tokens";
 import {initAnnouncer} from "@khanacademy/wonder-blocks-announcer";
 import Link from "@khanacademy/wonder-blocks-link";
-import {ThemeSwitcherContext} from "@khanacademy/wonder-blocks-theming";
-import {RenderStateRoot} from "../packages/wonder-blocks-core/src";
+import {
+    ThemeSwitcherContext,
+    ThemeSwitcher,
+} from "@khanacademy/wonder-blocks-theming";
 import {Preview} from "@storybook/react";
 
+// Import the Wonder Blocks CSS variables
+import "@khanacademy/wonder-blocks-tokens/styles.css";
+
 /**
  * WB Official breakpoints
  * @see https://khanacademy.atlassian.net/wiki/spaces/WB/pages/2099970518/Layout+Breakpoints
@@ -111,14 +117,18 @@ const withThemeSwitcher: Decorator = (
         return (
             <RenderStateRoot>
                 <ThemeSwitcherContext.Provider value={theme}>
-                    <Story />
+                    <ThemeSwitcher theme={theme}>
+                        <Story />
+                    </ThemeSwitcher>
                 </ThemeSwitcherContext.Provider>
             </RenderStateRoot>
         );
     }
     return (
         <ThemeSwitcherContext.Provider value={theme}>
-            <Story />
+            <ThemeSwitcher theme={theme}>
+                <Story />
+            </ThemeSwitcher>
         </ThemeSwitcherContext.Provider>
     );
 };
@@ -202,7 +212,7 @@ const preview: Preview = {
                     },
                     {
                         value: "khanmigo",
-                        icon: "circle",
+                        icon: "comment",
                         title: "Khanmigo",
                     },
                 ],

__docs__/components/color.tsx

@@ -15,7 +15,7 @@ import {
     semanticColor,
     spacing,
 } from "@khanacademy/wonder-blocks-tokens";
-import {getTokenName} from "./tokens-util";
+import {getTokenName, maybeGetCssVariableInfo} from "./tokens-util";
 
 type Variant = "primitive" | "semantic" | "compact";
 
@@ -66,6 +66,8 @@ type ColorProps = {
 
 function Color({name, value, variant}: ColorProps) {
     function renderInfo() {
+        const rawValue = maybeGetCssVariableInfo(value).value;
+
         if (variant === "compact") {
             const tokenName = name.toString().split(".");
             return (
@@ -83,7 +85,7 @@ function Color({name, value, variant}: ColorProps) {
 
                     <Footnote>
                         Primitive:{" "}
-                        <em>{getTokenName(color, value) || value}</em>
+                        <em>{getTokenName(color, rawValue) || rawValue}</em>
                     </Footnote>
                 </View>
             );
@@ -114,10 +116,11 @@ function Color({name, value, variant}: ColorProps) {
                     {name}
                 </LabelSmall>
                 <Caption>
-                    Primitive: <em>{getTokenName(color, value) || value}</em>
+                    Primitive:{" "}
+                    <em>{getTokenName(color, rawValue) || rawValue}</em>
                 </Caption>
                 <LabelSmall>
-                    Value: <Footnote style={styles.code}>{value}</Footnote>
+                    Reference: <Footnote style={styles.code}>{value}</Footnote>
                 </LabelSmall>
             </>
         );
@@ -160,8 +163,8 @@ type ActionColorGroupProps = {
 };
 
 export function ActionColorGroup({category, group}: ActionColorGroupProps) {
-    return Object.entries(category).map(([state, colorGroup]) => (
-        <View style={styles.actionGroup}>
+    return Object.entries(category).map(([state, colorGroup], index) => (
+        <View style={styles.actionGroup} key={index}>
             <LabelLarge style={styles.capitalized}>{state}</LabelLarge>
             <Example style={colorGroup} />
             <ColorGroup

__docs__/components/token-table.tsx

@@ -3,6 +3,7 @@ import {StyleSheet} from "aphrodite";
 
 import {addStyle} from "@khanacademy/wonder-blocks-core";
 import {color, spacing} from "@khanacademy/wonder-blocks-tokens";
+import {maybeGetCssVariableInfo} from "./tokens-util";
 
 const StyledTable = addStyle("table");
 const StyledTr = addStyle("tr");
@@ -37,9 +38,18 @@ export default function TokenTable<T>({
     tokens,
 }: Props<T>): React.ReactElement {
     // Convert the tokens object into an array of objects.
-    const data = Object.entries(tokens).map(
-        ([key, value]) => ({label: key, value}) as T,
-    );
+    const data = Object.entries(tokens).map(([key, value]) => {
+        if (typeof value === "string") {
+            // Check if the value is a CSS variable so we can transform it into
+            // its actual value.
+            const {name: cssVariable, value: rawValue} =
+                maybeGetCssVariableInfo(value);
+
+            return {label: key, css: cssVariable, value: rawValue};
+        }
+
+        return {label: key, value};
+    });
 
     return (
         <StyledTable style={styles.table}>

__docs__/components/tokens-util.ts

@@ -65,7 +65,30 @@ export function getTokenName(tokens: Record<string, string>, value: string) {
         }
 
         if (tokens[property] === value) {
-            return property;
+            return maybeGetCssVariableInfo(value).name;
         }
     }
 }
+
+/**
+ * Given a string, evaluates if it is a CSS variable and returns its name and
+ * value. Otherwise, it returns the string as is.
+ *
+ * @param value The string to evaluate.
+ * @returns An object containing the name and value of the CSS variable or the
+ * original string.
+ */
+export function maybeGetCssVariableInfo(value: string) {
+    // If the value is a CSS variable, we need to transform it into its
+    // actual value.
+    if (value.startsWith("var(--")) {
+        const cssVariable = value.slice(4, -1);
+        const rawValue = getComputedStyle(
+            document.documentElement,
+        ).getPropertyValue(cssVariable);
+
+        return {name: cssVariable, value: rawValue};
+    }
+
+    return {name: value, value: value};
+}

__docs__/wonder-blocks-tabs/navigation-tabs.stories.tsx

@@ -299,7 +299,7 @@ export const HeaderWithNavigationTabsExample: StoryComponentType = {
             navigationTabsRoot: {
                 // set margin to negative value of header vertical spacing so
                 // that selected indicator lines up with header border
-                margin: `-${headerVerticalSpacing} 0`,
+                margin: `calc(${headerVerticalSpacing} * -1) 0`,
             },
         });
         const [currentTab, setCurrentTab] = React.useState(0);

__docs__/wonder-blocks-theming/theme-switcher.mdx

@@ -0,0 +1,29 @@
+import {Meta, Canvas} from "@storybook/blocks";
+import * as ThemeSwitcherStories from "./theme-switcher.stories";
+
+<Meta of={ThemeSwitcherStories} />
+
+# `ThemeSwitcher`
+
+`ThemeSwitcher` is a component that wraps a children with a reference to the
+selected theme. This uses a combination of custom data attributes
+(`data-wb-theme`) and CSS variables to apply the theme to the children. The
+default CSS variables are defined in the `:root` selector, and the
+theme-specific CSS variables are defined in the `data-wb-theme` selector. For
+more info about the CSS variables, see the
+`@khanacademy/wonder-blocks-tokens/styles.css` file.
+
+## Usage
+
+```tsx
+import {ThemeSwitcher} from "@khanacademy/wonder-blocks-theming";
+
+<ThemeSwitcher theme="default">
+    <Button>Themed button</Button>
+</ThemeSwitcher>;
+```
+
+This example demonstrates how to use the `ThemeSwitcher` component to switch
+between themes.
+
+<Canvas of={ThemeSwitcherStories.Default} />

__docs__/wonder-blocks-theming/theme-switcher.stories.tsx

@@ -0,0 +1,52 @@
+import {Meta, StoryObj} from "@storybook/react";
+import * as React from "react";
+
+import {
+    SupportedThemes,
+    ThemeSwitcher,
+} from "@khanacademy/wonder-blocks-theming";
+import {View} from "@khanacademy/wonder-blocks-core";
+import {sizing} from "@khanacademy/wonder-blocks-tokens";
+import Button from "@khanacademy/wonder-blocks-button";
+
+export default {
+    title: "Packages / Theming / ThemeSwitcher",
+    component: ThemeSwitcher,
+    parameters: {
+        // This is only for documentation purposes.
+        chromatic: {
+            disableSnapshot: true,
+        },
+    },
+    // Hide stories in the sidebar. Only show Docs.
+    tags: ["!dev"],
+} as Meta<typeof ThemeSwitcher>;
+
+type Story = StoryObj<typeof ThemeSwitcher>;
+
+export const Default: Story = (() => {
+    const [theme, setTheme] = React.useState<SupportedThemes>("default");
+
+    const changeTheme = () => {
+        // NOTE: Right now, this is just a placeholder, meaning that no visual
+        // changes are expected.
+        // TODO(WB-1896): Update this to use the `thunderblocks` theme.
+        const newTheme = theme === "khanmigo" ? "default" : "khanmigo";
+        setTheme(newTheme);
+    };
+
+    return (
+        <>
+            <View style={{gap: sizing.size_160, flexDirection: "row"}}>
+                <Button kind="secondary" onClick={changeTheme}>
+                    Switch theme
+                </Button>
+                <Button>Outside button (doesn&apos;t affect new theme)</Button>
+            </View>
+            <ThemeSwitcher theme={theme}>
+                <p>Theming demo using: {theme}</p>
+                <Button>Themed button</Button>
+            </ThemeSwitcher>
+        </>
+    );
+}) as Story;