@instructure/emotion 11.7.3 → 11.7.4-pr-snapshot-1781695314229

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [11.7.4-pr-snapshot-1781695314229](https://github.com/instructure/instructure-ui/compare/v11.7.3...v11.7.4-pr-snapshot-1781695314229) (2026-06-17)
+
+
+### Features
+
+* **ui-scripts:** refactor theme type generation and fix token fetching script ([ab0536f](https://github.com/instructure/instructure-ui/commit/ab0536f81ffe9ae60f8b8cdc5038f4f323314416))
+
+
+
+
+
 ## [11.7.3](https://github.com/instructure/instructure-ui/compare/v11.7.2...v11.7.3) (2026-05-07)
 
 

package/LICENSE.md

@@ -2,6 +2,7 @@
 title: The MIT License (MIT)
 category: Getting Started
 order: 9
+isWIP: true
 ---
 
 # The MIT License (MIT)

package/{lib/styleUtils/mirrorShorthandEdges.js → babel.config.cjs}

@@ -1,16 +1,3 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-Object.defineProperty(exports, "mirrorShorthandEdges", {
-  enumerable: true,
-  get: function () {
-    return _mirrorShorthand.mirrorShorthandEdges;
-  }
-});
-var _mirrorShorthand = require("./mirrorShorthand");
 /*
  * The MIT License (MIT)
  *
@@ -34,4 +21,16 @@ var _mirrorShorthand = require("./mirrorShorthand");
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-var _default = exports.default = _mirrorShorthand.mirrorShorthandEdges;
+
+module.exports = {
+  presets: [
+    [
+      require('@instructure/ui-babel-preset'),
+      {
+        esModules: Boolean(process.env.ES_MODULES),
+        removeConsole: process.env.NODE_ENV === 'production',
+        transformImports: Boolean(process.env.TRANSFORM_IMPORTS)
+      }
+    ]
+  ]
+}

package/es/InstUISettingsProvider/index.js

@@ -26,7 +26,7 @@ import { useContext } from 'react';
 import { ThemeProvider } from '@emotion/react';
 import { TextDirectionContext } from '@instructure/ui-i18n';
 import { DeterministicIdContextProvider } from '@instructure/ui-react-utils';
-import { getTheme } from "../getTheme.js";
+import { getTheme } from '../getTheme.js';
 import { jsx as _jsx } from "@emotion/react/jsx-runtime";
 /**
  * ---

package/es/index.js

@@ -24,12 +24,12 @@
 /// <reference types="@emotion/react/types/css-prop" />
 
 export * from '@emotion/react';
-export { useComputedTheme } from "./useComputedTheme.js";
-export { InstUISettingsProvider } from "./InstUISettingsProvider/index.js";
-export { withStyle } from "./withStyle.js";
-export { getComponentThemeOverride } from "./getComponentThemeOverride.js";
-export { withStyleNew } from "./withStyleNew.js";
-export { ThemeablePropValues, makeThemeVars, getShorthandPropValue, mirrorShorthandCorners, mirrorShorthandEdges, calcSpacingFromShorthand, calcFocusOutlineStyles } from "./styleUtils/index.js";
-export { useStyle } from "./useStyle.js";
-export { useStyleNew } from "./useStyleNew.js";
-export { useTheme } from "./useTheme.js";
+export { useComputedTheme } from './useComputedTheme.js';
+export { InstUISettingsProvider } from './InstUISettingsProvider/index.js';
+export { withStyle } from './withStyle.js';
+export { getComponentThemeOverride } from './getComponentThemeOverride.js';
+export { withStyleNew } from './withStyleNew.js';
+export { ThemeablePropValues, makeThemeVars, getShorthandPropValue, mirrorShorthandCorners, mirrorShorthandEdges, calcSpacingFromShorthand, calcFocusOutlineStyles } from './styleUtils/index.js';
+export { useStyle } from './useStyle.js';
+export { useStyleNew } from './useStyleNew.js';
+export { useTheme } from './useTheme.js';

package/es/styleUtils/applyColorModifiers.js

@@ -0,0 +1,83 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { colorToHsla } from '@instructure/ui-color-utils';
+// Matches Tokens Studio's HSL modifier math: move L by `amount` (0–1) of the
+// remaining distance toward the endpoint, so the step shrinks as it approaches
+// black/white and never overshoots.
+const modifyLightness = (l, amount, type) => type === 'darken' ? Math.max(0, l - l * amount) : Math.min(1, l + (1 - l) * amount);
+const formatHsla = (h, s, l, a) => {
+  const hh = Math.round(h);
+  const ss = +(s * 100).toFixed(2);
+  const ll = +(l * 100).toFixed(2);
+  return a < 1 ? `hsla(${hh}, ${ss}%, ${ll}%, ${a})` : `hsl(${hh}, ${ss}%, ${ll}%)`;
+};
+const isModifyColor = val => typeof val === 'object' && val !== null && typeof val.value === 'string' && typeof val.modify === 'object' && val.modify !== null;
+const resolveModifyColor = ({
+  value,
+  modify
+}) => {
+  if (modify.type === 'darken' || modify.type === 'lighten') {
+    const {
+      h,
+      s,
+      l,
+      a
+    } = colorToHsla(value);
+    const newL = modifyLightness(l, modify.value, modify.type);
+    return formatHsla(h, s, newL, a);
+  }
+  return value;
+};
+
+/**
+ * Resolves a component theme object by applying color modifiers to any entries
+ * shaped as `{ value, modify: { type, value } }`. Entries with `modify.type` of
+ * `'darken'` or `'lighten'` are transformed in HSL space using the same math
+ * Tokens Studio applies (`space: "hsl"`): `amount` is a 0–1 fraction of the
+ * remaining distance to black/white. Plain values and unrecognized modifier
+ * types are passed through unchanged. Nested plain objects are walked
+ * recursively so modifiers anywhere in the tree get resolved.
+ *
+ * @param componentTheme - Theme map whose values can be CSS strings, `ModifyColor`
+ *   objects, or nested theme objects containing the same.
+ * @returns A new theme object mirroring the input shape, with every `ModifyColor`
+ *   collapsed to its final resolved color string.
+ */
+const applyColorModifiers = componentTheme => {
+  if (componentTheme == null) return {};
+  const result = {};
+  for (const key of Object.keys(componentTheme)) {
+    const entry = componentTheme[key];
+    if (isModifyColor(entry)) {
+      result[key] = resolveModifyColor(entry);
+    } else if (typeof entry === 'object' && entry !== null && !Array.isArray(entry)) {
+      result[key] = applyColorModifiers(entry);
+    } else {
+      result[key] = entry;
+    }
+  }
+  return result;
+};
+export default applyColorModifiers;
+export { applyColorModifiers };

package/es/styleUtils/calcSpacingFromShorthand.js

@@ -1,4 +1,3 @@
-import "core-js/modules/es.array.includes.js";
 /*
  * The MIT License (MIT)
  *

package/es/styleUtils/index.js

@@ -21,10 +21,11 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-export { ThemeablePropValues } from "./ThemeablePropValues.js";
-export { makeThemeVars } from "./makeThemeVars.js";
-export { getShorthandPropValue } from "./getShorthandPropValue.js";
-export { mirrorShorthandCorners } from "./mirrorShorthandCorners.js";
-export { mirrorShorthandEdges } from "./mirrorShorthandEdges.js";
-export { calcSpacingFromShorthand } from "./calcSpacingFromShorthand.js";
-export { calcFocusOutlineStyles } from "./calcFocusOutlineStyles.js";
+
+export { ThemeablePropValues } from './ThemeablePropValues.js';
+export { makeThemeVars } from './makeThemeVars.js';
+export { getShorthandPropValue } from './getShorthandPropValue.js';
+export { mirrorShorthandCorners } from './mirrorShorthandCorners.js';
+export { mirrorShorthandEdges } from './mirrorShorthandEdges.js';
+export { calcSpacingFromShorthand } from './calcSpacingFromShorthand.js';
+export { calcFocusOutlineStyles } from './calcFocusOutlineStyles.js';

package/es/styleUtils/mirrorShorthandCorners.js

@@ -21,6 +21,6 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-import { mirrorShorthandCorners } from "./mirrorShorthand.js";
+import { mirrorShorthandCorners } from './mirrorShorthand.js';
 export default mirrorShorthandCorners;
 export { mirrorShorthandCorners };

package/es/styleUtils/mirrorShorthandEdges.js

@@ -21,6 +21,6 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-import { mirrorShorthandEdges } from "./mirrorShorthand.js";
+import { mirrorShorthandEdges } from './mirrorShorthand.js';
 export default mirrorShorthandEdges;
 export { mirrorShorthandEdges };

package/es/useStyle.js

@@ -21,10 +21,15 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-import { useTheme } from "./useTheme.js";
-import { getComponentThemeOverride } from "./getComponentThemeOverride.js"; // returns the second parameter of a function
+
+import { useTheme } from './useTheme.js';
+import { getComponentThemeOverride } from './getComponentThemeOverride.js';
+
+// returns the second parameter of a function
+
 // TODO this is only used by the old themes, remove when everything uses the new
 // theming system
+
 /*
  * This is only used by the **old themes**, remove when everything uses the new
  * theming system (InstUI v12)

package/es/useStyleNew.js

@@ -21,8 +21,10 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-import { useTheme } from "./useTheme.js";
+
+import { useTheme } from './useTheme.js';
 import { mergeDeep } from '@instructure/ui-utils';
+import { applyColorModifiers } from './styleUtils/applyColorModifiers.js';
 
 // returns the second parameter of a function
 
@@ -64,11 +66,11 @@ const useStyleNew = useStyleParams => {
   const primitives = mergeDeep(theme.newTheme.primitives, primitiveOverrides);
   const semantics = mergeDeep(theme.newTheme.semantics?.(primitives), semanticsOverrides);
   const sharedTokens = mergeDeep(theme.newTheme.sharedTokens?.(semantics), sharedTokensOverrides);
-  const baseComponentTheme = generateComponentTheme ? generateComponentTheme({
+  const baseComponentTheme = applyColorModifiers(generateComponentTheme ? generateComponentTheme({
     primitives,
     semantics,
     sharedTokens
-  }) : theme.newTheme.components[componentWithTokensId]?.(semantics);
+  }) : theme.newTheme.components[componentWithTokensId]?.(semantics));
   const componentThemeFromSettingsProvider = mergeDeep(baseComponentTheme, componentOverridesFromSettingsProvider);
   const componentTheme = mergeDeep(componentThemeFromSettingsProvider, typeof themeOverride === 'function' ? themeOverride(componentThemeFromSettingsProvider, themeInContext) : themeOverride);
 

package/es/withStyle.js

@@ -27,9 +27,12 @@ import hoistNonReactStatics from 'hoist-non-react-statics';
 import { deepEqual as isEqual } from '@instructure/ui-utils';
 import { warn } from '@instructure/console';
 import { decorator } from '@instructure/ui-decorator';
-import { getComponentThemeOverride } from "./getComponentThemeOverride.js";
-import { useTheme } from "./useTheme.js"; // Extract is needed because it would allow number otherwise
+import { getComponentThemeOverride } from './getComponentThemeOverride.js';
+import { useTheme } from './useTheme.js';
+
+// Extract is needed because it would allow number otherwise
 // https://stackoverflow.com/a/51808262/319473
+
 // Unique name of an InstUI component
 import { jsx as _jsx } from "@emotion/react/jsx-runtime";
 const defaultValues = {
@@ -41,7 +44,11 @@ const defaultValues = {
  * ---
  * category: utilities/themes
  * ---
- * used for old (v11 and eariler) theming system
+ * Legacy decorator for the pre-v11.7 theming system. New components should use
+ * `withStyleNew` instead. Override patterns for components decorated with
+ * `withStyle` are documented on the
+ * [Legacy theme overrides](/#legacy-theme-overrides) docs page.
+ *
  * TODO delete when the theme migration is complete
  */
 const withStyle = decorator((ComposedComponent, generateStyle, generateComponentTheme) => {

package/es/withStyleNew.js

@@ -27,8 +27,12 @@ import hoistNonReactStatics from 'hoist-non-react-statics';
 import { deepEqual as isEqual, mergeDeep } from '@instructure/ui-utils';
 import { warn } from '@instructure/console';
 import { decorator } from '@instructure/ui-decorator';
-import { useTheme } from "./useTheme.js"; // Extract is needed because it would allow number otherwise
+import { useTheme } from './useTheme.js';
+import { applyColorModifiers } from './styleUtils/applyColorModifiers.js';
+
+// Extract is needed because it would allow number otherwise
 // https://stackoverflow.com/a/51808262/319473
+
 // Unique name of an InstUI component
 import { jsx as _jsx } from "@emotion/react/jsx-runtime";
 const defaultValues = {
@@ -41,11 +45,9 @@ const defaultValues = {
  * category: utilities/themes
  * ---
  *
- * A decorator or higher order component that makes a component themeable.
- *
- * It adds a `makeStyles` function and the generated `styles` object to the decorated Component's props. If it has an own theme, it also adds the `themeOverride` prop to the component.
- *
- * As a HOC:
+ * Decorator (or HOC) that makes a component themeable using InstUI's new
+ * theming system. Injects a `makeStyles` function and the
+ * generated `styles` object as props.
  *
  * ```js-code
  * import { withStyleNew } from '@instructure/emotion'
@@ -54,42 +56,18 @@ const defaultValues = {
  * export default withStyleNew(generateStyle)(ExampleComponent)
  * ```
  *
- * Themeable components inject their themed styles into the document
- * when they are mounted.
- *
- * ### Applying themes
- *
- * A themeable component’s theme can be configured via wrapping it in an
- * [InstUISettingsProvider](InstUISettingsProvider) component, and/or set
- * explicitly via its `themeOverride` prop.
+ * Optionally pass a `useTokensFrom` key as the second argument to consume
+ * another component's tokens (e.g. `withStyleNew(generateStyle, 'BaseButton')`).
  *
- * InstUISettingsProvider provides a theme object (e.g. the [canvas theme](/#canvas)).
- * These variables are mapped to the component's own variables in `theme.js` (see [theming](theming-basics) for more info).
- *
- * With the `themeOverride` prop you can directly set/override the component theme variables declared in theme.js. It accepts an object or a function. The function has the component's theme and the currently active main theme as its parameter.
- *
- * See more about the overrides on the [Using theme overrides](/#using-theme-overrides) docs page.
- *
- * ```jsx-code
- * {// global theme override}
- * <InstUISettingsProvider theme={{
- *   colors: { backgroundMedium: '#888' }
- * }}>
- *  {// component theme override}
- *   <ExampleComponent themeOverride={{ hoverColor: '#eee' }} />
- *
- *  {// component theme override with function}
- *   <ExampleComponent themeOverride={(componentTheme, currentTheme) => ({
- *     hoverBackground: componentTheme.background,
- *     activeBackground: currentTheme.colors.backgroundBrand
- *   })} />
- * </InstUISettingsProvider>
- * ```
+ * Override patterns (provider-scoped, per-component, primitives / semantics /
+ * sharedTokens layers, priority rules) are documented on the
+ * [New theme overrides](/#new-theme-overrides) docs page.
  *
  * @module withStyleNew
  *
- * @param {function} generateStyle - The function that returns the component's style object
- * @returns {ReactElement} The decorated WithStyle Component
+ * @param {function} generateStyle - Returns the component's style object
+ * @param {string}   [useTokensFrom] - Key of another component whose tokens this one should consume
+ * @returns {ReactElement} The decorated component
  */
 const withStyleNew = decorator((ComposedComponent, generateStyle, useTokensFrom, frozenTheme, generateComponentTheme) => {
   const displayName = ComposedComponent.displayName || ComposedComponent.name;
@@ -131,11 +109,11 @@ const withStyleNew = decorator((ComposedComponent, generateStyle, useTokensFrom,
     const semantics = mergeDeep(theme.newTheme.semantics?.(primitives), semanticsOverrides);
     const sharedTokens = mergeDeep(theme.newTheme.sharedTokens?.(semantics), sharedTokensOverrides);
     // Note: Some components do not have a theme, e.g., FormFieldMessages
-    const baseComponentTheme = generateComponentTheme ? generateComponentTheme({
+    const baseComponentTheme = applyColorModifiers(generateComponentTheme ? generateComponentTheme({
       primitives,
       semantics,
       sharedTokens
-    }) : theme.newTheme.components[componentId]?.(semantics);
+    }) : theme.newTheme.components[componentId]?.(semantics));
     const componentThemeFromSettingsProvider = mergeDeep(baseComponentTheme, componentOverridesFromSettingsProvider);
     const componentTheme = mergeDeep(componentThemeFromSettingsProvider,
     // @ts-ignore TODO-theme-types: fix typing

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@instructure/emotion",
-  "version": "11.7.3",
+  "version": "11.7.4-pr-snapshot-1781695314229",
+  "type": "module",
   "description": "A UI component library made by Instructure Inc.",
   "author": "Instructure, Inc. Engineering and Product Design",
   "module": "./es/index.js",
-  "main": "./lib/index.js",
   "types": "./types/index.d.ts",
   "repository": {
     "type": "git",
@@ -17,14 +17,14 @@
     "@babel/runtime": "^7.29.2",
     "@emotion/react": "^11",
     "hoist-non-react-statics": "^3.3.2",
-    "@instructure/console": "11.7.3",
-    "@instructure/ui-color-utils": "11.7.3",
-    "@instructure/ui-decorator": "11.7.3",
-    "@instructure/ui-react-utils": "11.7.3",
-    "@instructure/shared-types": "11.7.3",
-    "@instructure/ui-i18n": "11.7.3",
-    "@instructure/ui-themes": "11.7.3",
-    "@instructure/ui-utils": "11.7.3"
+    "@instructure/console": "11.7.4-pr-snapshot-1781695314229",
+    "@instructure/shared-types": "11.7.4-pr-snapshot-1781695314229",
+    "@instructure/ui-decorator": "11.7.4-pr-snapshot-1781695314229",
+    "@instructure/ui-i18n": "11.7.4-pr-snapshot-1781695314229",
+    "@instructure/ui-react-utils": "11.7.4-pr-snapshot-1781695314229",
+    "@instructure/ui-themes": "11.7.4-pr-snapshot-1781695314229",
+    "@instructure/ui-utils": "11.7.4-pr-snapshot-1781695314229",
+    "@instructure/ui-color-utils": "11.7.4-pr-snapshot-1781695314229"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",
@@ -32,7 +32,7 @@
     "@testing-library/user-event": "^14.6.1",
     "react-dom": "18.3.1",
     "vitest": "^3.2.2",
-    "@instructure/ui-babel-preset": "11.7.3"
+    "@instructure/ui-babel-preset": "11.7.4-pr-snapshot-1781695314229"
   },
   "peerDependencies": {
     "react": ">=18 <=19"
@@ -46,10 +46,8 @@
       "src": "./src/index.ts",
       "types": "./types/index.d.ts",
       "import": "./es/index.js",
-      "require": "./lib/index.js",
       "default": "./es/index.js"
     },
-    "./lib/*": "./lib/*",
     "./es/*": "./es/*",
     "./types/*": "./types/*",
     "./package.json": "./package.json",
@@ -59,7 +57,7 @@
     "lint": "ui-scripts lint",
     "lint:fix": "ui-scripts lint --fix",
     "clean": "ui-scripts clean",
-    "build": "ui-scripts build --modules es,cjs",
+    "build": "ui-scripts build",
     "build:watch": "pnpm run ts:check -- --watch & ui-scripts build --watch",
     "build:types": "tsc -p tsconfig.build.json ",
     "ts:check": "tsc -p tsconfig.build.json"

package/src/InstUISettingsProvider/README.md

@@ -62,7 +62,10 @@ ReactDOM.render(
 
 #### Theme overrides
 
-There are multiple ways to override themes in InstUI. You can read about how these work on the dedicated docs page: [Using theme overrides](/#using-theme-overrides).
+There are multiple ways to override themes in InstUI. You can read about how these work on the dedicated docs pages:
+
+- [Legacy theme overrides](/#legacy-theme-overrides).
+- [New theme overrides](/#new-theme-overrides).
 
 ### Text direction management
 

package/src/InstUISettingsProvider/index.tsx

@@ -28,7 +28,7 @@ import { ThemeProvider } from '@emotion/react'
 import { TextDirectionContext } from '@instructure/ui-i18n'
 import { DeterministicIdContextProvider } from '@instructure/ui-react-utils'
 
-import { getTheme } from '../getTheme'
+import { getTheme } from '../getTheme.js'
 
 import type { ThemeOrLegacyOverride } from '../EmotionTypes'
 import type { DeterministicIdProviderValue } from '@instructure/ui-react-utils'

package/src/getComponentThemeOverride.ts

@@ -28,7 +28,7 @@ import type {
   ComponentOverride
 } from './EmotionTypes'
 import type { ComponentTheme } from '@instructure/shared-types'
-import { ThemeOverrideProp } from './withStyleNew'
+import { ThemeOverrideProp } from './withStyleNew.js'
 import type { NewComponentTypes } from '@instructure/ui-themes'
 
 type ComponentName = keyof ComponentOverride | undefined

package/src/getTheme.ts

@@ -31,7 +31,7 @@ import type {
   ThemeOrLegacyOverride,
   SpecificThemeOverride
 } from './EmotionTypes'
-import { InstUIProviderProps } from './InstUISettingsProvider'
+import { InstUIProviderProps } from './InstUISettingsProvider/index.js'
 declare const process: Record<string, any> | undefined
 
 /**

package/src/index.ts

@@ -25,11 +25,11 @@
 
 export * from '@emotion/react'
 
-export { useComputedTheme } from './useComputedTheme'
-export { InstUISettingsProvider } from './InstUISettingsProvider'
-export { withStyle } from './withStyle'
-export { getComponentThemeOverride } from './getComponentThemeOverride'
-export { withStyleNew } from './withStyleNew'
+export { useComputedTheme } from './useComputedTheme.js'
+export { InstUISettingsProvider } from './InstUISettingsProvider/index.js'
+export { withStyle } from './withStyle.js'
+export { getComponentThemeOverride } from './getComponentThemeOverride.js'
+export { withStyleNew } from './withStyleNew.js'
 export {
   ThemeablePropValues,
   makeThemeVars,
@@ -38,11 +38,11 @@ export {
   mirrorShorthandEdges,
   calcSpacingFromShorthand,
   calcFocusOutlineStyles
-} from './styleUtils'
+} from './styleUtils/index.js'
 
-export { useStyle } from './useStyle'
-export { useStyleNew } from './useStyleNew'
-export { useTheme } from './useTheme'
+export { useStyle } from './useStyle.js'
+export { useStyleNew } from './useStyleNew.js'
+export { useTheme } from './useTheme.js'
 
 export type { InstUIProviderProps } from './InstUISettingsProvider'
 export type { ComponentStyle, StyleObject, Overrides } from './EmotionTypes'

package/src/styleUtils/applyColorModifiers.ts

@@ -0,0 +1,108 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { colorToHsla } from '@instructure/ui-color-utils'
+
+type ModifyColor = {
+  value: string
+  modify: {
+    type: 'lighten' | 'darken'
+    value: number
+  }
+}
+
+// Matches Tokens Studio's HSL modifier math: move L by `amount` (0–1) of the
+// remaining distance toward the endpoint, so the step shrinks as it approaches
+// black/white and never overshoots.
+const modifyLightness = (
+  l: number,
+  amount: number,
+  type: 'darken' | 'lighten'
+): number =>
+  type === 'darken'
+    ? Math.max(0, l - l * amount)
+    : Math.min(1, l + (1 - l) * amount)
+
+const formatHsla = (h: number, s: number, l: number, a: number): string => {
+  const hh = Math.round(h)
+  const ss = +(s * 100).toFixed(2)
+  const ll = +(l * 100).toFixed(2)
+  return a < 1
+    ? `hsla(${hh}, ${ss}%, ${ll}%, ${a})`
+    : `hsl(${hh}, ${ss}%, ${ll}%)`
+}
+
+const isModifyColor = (val: unknown): val is ModifyColor =>
+  typeof val === 'object' &&
+  val !== null &&
+  typeof (val as ModifyColor).value === 'string' &&
+  typeof (val as ModifyColor).modify === 'object' &&
+  (val as ModifyColor).modify !== null
+
+const resolveModifyColor = ({ value, modify }: ModifyColor): string => {
+  if (modify.type === 'darken' || modify.type === 'lighten') {
+    const { h, s, l, a } = colorToHsla(value)
+    const newL = modifyLightness(l, modify.value, modify.type)
+    return formatHsla(h, s, newL, a)
+  }
+  return value
+}
+
+/**
+ * Resolves a component theme object by applying color modifiers to any entries
+ * shaped as `{ value, modify: { type, value } }`. Entries with `modify.type` of
+ * `'darken'` or `'lighten'` are transformed in HSL space using the same math
+ * Tokens Studio applies (`space: "hsl"`): `amount` is a 0–1 fraction of the
+ * remaining distance to black/white. Plain values and unrecognized modifier
+ * types are passed through unchanged. Nested plain objects are walked
+ * recursively so modifiers anywhere in the tree get resolved.
+ *
+ * @param componentTheme - Theme map whose values can be CSS strings, `ModifyColor`
+ *   objects, or nested theme objects containing the same.
+ * @returns A new theme object mirroring the input shape, with every `ModifyColor`
+ *   collapsed to its final resolved color string.
+ */
+const applyColorModifiers = (
+  componentTheme: Record<string, unknown> | undefined | null
+): Record<string, unknown> => {
+  if (componentTheme == null) return {}
+  const result: Record<string, unknown> = {}
+  for (const key of Object.keys(componentTheme)) {
+    const entry = componentTheme[key]
+    if (isModifyColor(entry)) {
+      result[key] = resolveModifyColor(entry)
+    } else if (
+      typeof entry === 'object' &&
+      entry !== null &&
+      !Array.isArray(entry)
+    ) {
+      result[key] = applyColorModifiers(entry as Record<string, unknown>)
+    } else {
+      result[key] = entry
+    }
+  }
+  return result
+}
+
+export default applyColorModifiers
+export { applyColorModifiers }