feat(emotion,ui-scripts): resolve tokens studio color modifiers and emit hex

Forward Tokens Studio color modifiers (`$extensions.studio.tokens.modify`) through
the theme build scripts and resolve them at theme-apply time so semantic and
component tokens can chain darken/lighten/alpha.

- generateSemantics: emit the `{ value, modify }` payload for semantic tokens and
  recurse into it in resolveReferences (drop the `.value`/`.type` guard that
  serialized the payload to "[object Object]").
- generateComponents: only forward `$extensions` when `studio.tokens.modify` is
  present, so tokens carrying unrelated metadata no longer emit `modify: undefined`.
- applyColorModifiers: serialize the resolved color to hex (`#RRGGBBAA` when alpha
  < 1, `#RRGGBB` otherwise) so modifier-derived values match every other token.
- useComputedTheme/useStyleNew/withStyleNew: resolve modifiers on semantics before
  building component and shared tokens, so component-level modifiers chain on top
  of already-resolved semantic values; key component overrides by the component's
  own id rather than the token-source id.
- Bump @instructure/instructure-design-tokens to v1.4.0.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: HerrTopi

packages/emotion/src/styleUtils/applyColorModifiers.ts

@@ -21,7 +21,11 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-import { colorToHsla } from '@instructure/ui-color-utils'
+import {
+  colorToHsla,
+  color2hex,
+  colorToHex8
+} from '@instructure/ui-color-utils'
 
 type ModifyColor = {
   value: string
@@ -43,13 +47,11 @@ const modifyLightness = (
     ? 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 formatColor = (h: number, s: number, l: number, a: number): string => {
+  const hsla = `hsla(${Math.round(h)}, ${+(s * 100).toFixed(2)}%, ${+(
+    l * 100
+  ).toFixed(2)}%, ${a})`
+  return a < 1 ? colorToHex8(hsla) : color2hex(hsla)
 }
 
 const isModifyColor = (val: unknown): val is ModifyColor =>
@@ -63,12 +65,12 @@ 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 formatColor(h, s, newL, a)
   }
   if (modify.type === 'alpha') {
     const { h, s, l } = colorToHsla(value)
     const newA = Math.min(1, Math.max(0, Number(modify.value)))
-    return formatHsla(h, s, l, newA)
+    return formatColor(h, s, l, newA)
   }
   return value
 }

packages/emotion/src/useComputedTheme.ts

@@ -23,6 +23,7 @@
  */
 
 import { useTheme } from '@emotion/react'
+import { applyColorModifiers } from './styleUtils/applyColorModifiers.js'
 
 /**
  * ---
@@ -40,23 +41,25 @@ import { useTheme } from '@emotion/react'
  *          `components` and `sharedTokens` of the current theme.
  */
 export const useComputedTheme = () => {
-    const rawTheme = (useTheme() as any).newTheme
+  const rawTheme = (useTheme() as any).newTheme
 
-    const primitives = rawTheme?.primitives
-    const semantics = rawTheme?.semantics?.(primitives)
-    const components = Object.keys(rawTheme?.components).reduce(
-        (acc, component) => ({
-            ...acc,
-            [component]: rawTheme.components[component]?.(semantics)
-        }),
-        {}
+  const primitives = rawTheme?.primitives
+  const semantics = applyColorModifiers(rawTheme?.semantics?.(primitives))
+  const components = applyColorModifiers(
+    Object.keys(rawTheme?.components).reduce(
+      (acc, component) => ({
+        ...acc,
+        [component]: rawTheme.components[component]?.(semantics)
+      }),
+      {}
     )
-    const sharedTokens = rawTheme?.sharedTokens?.(semantics)
+  )
+  const sharedTokens = applyColorModifiers(rawTheme?.sharedTokens?.(semantics))
 
-    return {
-        primitives,
-        semantics,
-        components,
-        sharedTokens
-    }
-}
+  return {
+    primitives,
+    semantics,
+    components,
+    sharedTokens
+  }
+}

packages/emotion/src/useStyleNew.ts

@@ -108,18 +108,21 @@ const useStyleNew = <
   const semanticsOverrides = themeOverrideFromProvider?.semantics
   const sharedTokensOverrides = themeOverrideFromProvider?.sharedTokens
   const componentOverridesFromSettingsProvider =
-    themeOverrideFromProvider?.components?.[componentWithTokensId]
+    themeOverrideFromProvider?.components?.[
+      componentId as keyof NewComponentTypes
+    ]
 
   const primitives = mergeDeep(theme.newTheme.primitives, primitiveOverrides!)
 
-  const semantics = mergeDeep(
-    theme.newTheme.semantics?.(primitives),
-    semanticsOverrides!
+  const semantics = applyColorModifiers(
+    mergeDeep(theme.newTheme.semantics?.(primitives), semanticsOverrides!)
   )
 
-  const sharedTokens = mergeDeep(
-    theme.newTheme.sharedTokens?.(semantics),
-    sharedTokensOverrides as Record<string, unknown>
+  const sharedTokens = applyColorModifiers(
+    mergeDeep(
+      theme.newTheme.sharedTokens?.(semantics),
+      sharedTokensOverrides as Record<string, unknown>
+    )
   )
 
   const baseComponentTheme = applyColorModifiers(

packages/emotion/src/withStyleNew.tsx

@@ -132,8 +132,10 @@ const withStyleNew = decorator(
   ) => {
     const displayName = ComposedComponent.displayName || ComposedComponent.name
 
-    const componentId: keyof NewComponentTypes =
-      useTokensFrom ?? ComposedComponent.componentId?.replace('.', '')
+    const rawComponentId: keyof NewComponentTypes =
+      ComposedComponent.componentId?.replace('.', '')
+
+    const componentId: keyof NewComponentTypes = useTokensFrom ?? rawComponentId
 
     const WithStyle: ForwardRefExoticComponent<
       PropsWithoutRef<Props> & RefAttributes<any>
@@ -188,7 +190,7 @@ const withStyleNew = decorator(
       const semanticsOverrides = themeOverride?.semantics
       const sharedTokensOverrides = themeOverride?.sharedTokens
       const componentOverridesFromSettingsProvider =
-        themeOverride?.components?.[componentId]
+        themeOverride?.components?.[rawComponentId]
       const componentOverridesFromThemeOverrideProp = (
         componentProps as ThemeOverrideProp
       ).themeOverride
@@ -198,14 +200,15 @@ const withStyleNew = decorator(
         primitiveOverrides!
       )
 
-      const semantics = mergeDeep(
-        theme.newTheme.semantics?.(primitives),
-        semanticsOverrides!
+      const semantics = applyColorModifiers(
+        mergeDeep(theme.newTheme.semantics?.(primitives), semanticsOverrides!)
       )
 
-      const sharedTokens = mergeDeep(
-        theme.newTheme.sharedTokens?.(semantics),
-        sharedTokensOverrides as Record<string, unknown>
+      const sharedTokens = applyColorModifiers(
+        mergeDeep(
+          theme.newTheme.sharedTokens?.(semantics),
+          sharedTokensOverrides as Record<string, unknown>
+        )
       ) as SharedTokens
       // Note: Some components do not have a theme, e.g., FormFieldMessages
       const baseComponentTheme = applyColorModifiers(

packages/ui-scripts/lib/build/buildThemes/generateComponents.ts

@@ -36,7 +36,11 @@ const formatComponent = (collection: any, key?: string): any => {
   // metadata. Tokens Studio writes color modifiers there under `studio.tokens.modify`
   // (e.g. `{ type: 'darken', value: 0.1 }`); we forward that payload so the runtime
   // (`applyColorModifiers`) can resolve the final color at theme apply time.
-  if (value['$extensions']) {
+  if (
+    value['$extensions'] &&
+    value['$extensions']['studio.tokens'] &&
+    value['$extensions']['studio.tokens'].modify
+  ) {
     return {
       value: value.value,
       modify: value['$extensions']['studio.tokens'].modify

packages/ui-scripts/lib/build/buildThemes/generateSemantics.ts

@@ -91,6 +91,20 @@ const formatSemantic = (collection: any, key?: any): any => {
       return { ...acc, [key]: formatSemantic(value, key) }
     }, {})
   }
+  // `$extensions` is the Design Tokens Format spec's escape hatch for tool-specific
+  // metadata. Tokens Studio writes color modifiers there under `studio.tokens.modify`
+  // (e.g. `{ type: 'darken', value: 0.1 }`); we forward that payload so the runtime
+  // (`applyColorModifiers`) can resolve the final color at theme apply time.
+  if (
+    value['$extensions'] &&
+    value['$extensions']['studio.tokens'] &&
+    value['$extensions']['studio.tokens'].modify
+  ) {
+    return {
+      value: value.value,
+      modify: value['$extensions']['studio.tokens'].modify
+    }
+  }
   return value.value
 }
 
@@ -108,7 +122,7 @@ const formatReference = (reference: string): string => {
 
 export const resolveReferences = (semantics: any, key?: any): string => {
   const value = key ? semantics[key] : semantics
-  if (typeof value === 'object' && !value.value && !value.type) {
+  if (typeof value === 'object') {
     return Object.keys(value).reduce((acc, key, index) => {
       if (typeof value[key] === 'object') {
         return (

packages/ui-scripts/lib/build/buildThemes/setupThemes.ts

@@ -197,8 +197,8 @@ const setupThemes = async (targetPath: string, input: any): Promise<void> => {
         import type { Semantics } from "./semantics"
 
         const ${fullComponentName} = (semantic: Semantics): ${capitalize(
-            fullComponentName
-          )} => ({${componentThemeVars}})
+          fullComponentName
+        )} => ({${componentThemeVars}})
         export default ${fullComponentName}
           `
 

packages/ui-scripts/package.json

@@ -23,7 +23,7 @@
   "dependencies": {
     "@babel/cli": "^7.27.2",
     "@instructure/command-utils": "workspace:*",
-    "@instructure/instructure-design-tokens": "github:instructure/instructure-design-tokens#v1.3.0",
+    "@instructure/instructure-design-tokens": "github:instructure/instructure-design-tokens#v1.4.0",
     "dprint": "^0.55.1",
     "http-server": "^14.1.1",
     "lerna": "9.0.7",