feat(many): add solution for using both old and new token system in the same app

Author: HerrTopi

docs/contributor-docs/migrating-to-new-tokens.md

@@ -0,0 +1,35 @@
+---
+title: Migrating components to new theming system
+category: Contributor Guides
+order: 01
+---
+
+# Token migration
+
+The new token system consists of auto-generated tokens form design. They can be imported from `ui-themes`.
+
+## Changing tokens only
+
+The migration strategy with the least amount of effort is only changing tokens. This approach keeps the component as class-based and retains the `View` component.
+
+Changes needed:
+
+- Import token types from `@instructure/ui-themes` instead of `@instructure/shared-types`
+- Update `generateStyle` function to use `NewComponentTypes['ComponentName']` for the theme parameter
+- Replace old theme tokens with new token names from the design system
+- Replace `@withStyleRework` decorator with `@withStyle` and remove `generateComponentTheme`
+- delete `theme.ts`
+
+If tokens are from a different (usually parent) components, add the `componentID` of that component as second paramater of `@withStyle` and use that name in the `generateStyle` function in `style.ts`: `NewComponentTypes['ParentComponentNameWithTheTokens']`
+
+`generateStyle` accepts a third parameter as well, which are the `sharedTokens`. These provide tokens for shared behaviors such as focus rings, shadows or margins. `'@instructure/emotion'` has various util functions that uses these, such as `calcMarginFromShorthand` and `calcFocusOutlineStyles`.
+
+## Removing View
+
+For some components it makes sense to remove the `View` component underneath the component structure. Most of the time, `View` only provides margins, focus rings, or minor visual aid. These can be replicated - in most cases - by the `sharedTokens` and their utils.
+
+Ideally all occurrences of `View` would be eliminated from the codebase.
+
+## Transforming class based components to functional
+
+The ultimate goal is to migrate all components to functional based ones. Currently it's not a priority and detailed migration guides will be available later. For the time being, `Avatar` or `RadioInput` can be used as starting reference points.

packages/__docs__/package.json

@@ -50,6 +50,7 @@
     "@instructure/ui-color-utils": "workspace:*",
     "@instructure/ui-date-input": "workspace:*",
     "@instructure/ui-date-time-input": "workspace:*",
+    "@instructure/ui-decorator": "workspace:*",
     "@instructure/ui-dialog": "workspace:*",
     "@instructure/ui-dom-utils": "workspace:*",
     "@instructure/ui-drawer-layout": "workspace:*",

packages/__docs__/resolve.mjs

@@ -58,6 +58,7 @@ const alias = {
     import.meta.dirname,
     '../ui-date-time-input/src/'
   ),
+  '@instructure/ui-decorator$': path.resolve(import.meta.dirname, '../ui-decorator/src/'),
   '@instructure/ui-dialog$': path.resolve(import.meta.dirname, '../ui-dialog/src/'),
   '@instructure/ui-docs-client$': path.resolve(
     import.meta.dirname,

packages/__docs__/src/App/index.tsx

@@ -32,7 +32,8 @@ import {
 } from 'react'
 
 import { Alert } from '@instructure/ui-alerts'
-import { InstUISettingsProvider, withStyle, Global } from '@instructure/emotion'
+import { InstUISettingsProvider, Global } from '@instructure/emotion'
+import { withStyleForDocs as withStyle } from '../withStyleForDocs'
 import { Flex } from '@instructure/ui-flex'
 import { Text } from '@instructure/ui-text'
 import { View } from '@instructure/ui-view'

packages/__docs__/src/ColorBand/index.tsx

@@ -27,7 +27,7 @@ import { Component } from 'react'
 import { Flex } from '@instructure/ui-flex'
 import { View } from '@instructure/ui-view'
 
-import { withStyle } from '@instructure/emotion'
+import { withStyleForDocs as withStyle } from '../withStyleForDocs'
 import generateStyle from './styles'
 import generateComponentTheme from './theme'
 import { allowedProps } from './props'

packages/__docs__/src/ColorSwatch/index.tsx

@@ -25,7 +25,7 @@
 import { Component } from 'react'
 
 import { isValid } from '@instructure/ui-color-utils'
-import { withStyle } from '@instructure/emotion'
+import { withStyleForDocs as withStyle } from '../withStyleForDocs'
 
 import generateStyle from './styles'
 import generateComponentTheme from './theme'

packages/__docs__/src/ComponentTheme/index.tsx

@@ -24,7 +24,7 @@
 
 import { Component } from 'react'
 
-import { withStyle } from '@instructure/emotion'
+import { withStyleForDocs as withStyle } from '../withStyleForDocs'
 import { Table } from '@instructure/ui-table'
 import { View } from '@instructure/ui-view'
 

packages/__docs__/src/Document/index.tsx

@@ -29,7 +29,7 @@ import { View } from '@instructure/ui-view'
 import { Tabs } from '@instructure/ui-tabs'
 import type { TabsProps } from '@instructure/ui-tabs'
 import { SourceCodeEditor } from '@instructure/ui-source-code-editor'
-import { withStyle } from '@instructure/emotion'
+import { withStyleForDocs as withStyle } from '../withStyleForDocs'
 
 import generateStyle from './styles'
 

packages/__docs__/src/Figure/index.tsx

@@ -34,7 +34,7 @@ import { List } from '@instructure/ui-list'
 import { Responsive } from '@instructure/ui-responsive'
 import { View } from '@instructure/ui-view'
 
-import { withStyle } from '@instructure/emotion'
+import { withStyleForDocs as withStyle } from '../withStyleForDocs'
 
 import generateStyle from './styles'
 import generateComponentTheme from './theme'

packages/__docs__/src/Hero/index.tsx

@@ -35,7 +35,7 @@ import { IconGithubSolid, IconCheckMarkSolid } from '@instructure/ui-icons'
 import { AccessibleContent } from '@instructure/ui-a11y-content'
 import { InlineSVG, SVGIcon } from '@instructure/ui-svg-images'
 
-import { withStyle } from '@instructure/emotion'
+import { withStyleForDocs as withStyle } from '../withStyleForDocs'
 
 import generateStyle from './styles'
 import generateComponentTheme from './theme'