App UI Kit v4 to v5 Migration Guide

Version 5 of the App UI Kit includes new design tokens that replace the v4 tokens with a new naming system and improved semantic structure.

This page provides the complete mapping from v4 to v5 design tokens to help you upgrade your app.

For more information about design tokens and when to use them, see the design tokens overview.

There are also some breaking changes in the component library. For the full list of changes, see the changelog .

The App UI Kit v5 introduces a new design token system with:

• Improved semantic naming: Tokens now have clearer, more descriptive names.
• Better organization: Tokens are grouped by purpose (action, content, feedback, and so on).
• Enhanced consistency: More consistent naming patterns across all token types.

• If you only use App UI Kit components: You don't need to do anything. The components will automatically use the new v5 tokens.

• If you use design tokens directly in your CSS or TypeScript: You'll need to update your code to use the new v5 token names.

Run the app-ui-kit-v5 Canva CLI apps migrate command in your app's project directory to use the Canva CLI to automatically migrate your app to use App UI Kit v5:

npx @canva/cli@latest apps migrate app-ui-kit-v5

It automatically runs through the code changes required to install the updated dependencies, migrates design tokens, and changes component properties.

1. Update your dependencies: Upgrade to the latest version of @canva/app-ui-kit.
2. Find and replace tokens: Use the tables below to map your v4 tokens to v5 tokens.
3. Update components: There are some small breaking changes to component properties in v5.
4. Test your app: Verify that your app still looks and works correctly.

Here's an example of migrating a CSS class from v4 to v5 tokens:

Before (v4 tokens):

.my-component {
  background-color: var(--ui-kit-color-primary);
  color: var(--ui-kit-color-typography-primary);
  padding: var(--ui-kit-space-2);
}

After (v5 tokens):

.my-component {
  background-color: var(--ui-kit-color-action-primary-bg);
  color: var(--ui-kit-color-content-fg);
  padding: var(--ui-kit-space-200);
}

The tables below show the complete mapping from v4 to v5 design tokens.

In addition to design token changes, App UI Kit v5 includes several component updates:

• Breaking: React 19 is now required and React 18 support was removed.

  Migration: Update your project to use React v19.

• Breaking: Removed deprecated title prop.

  Migration: Use tooltipLabel instead of title.

// Before (v4)
<Link title="Click here" href="/example">Link text</Link>

// After (v5)
<Link tooltipLabel="Click here" href="/example">Link text</Link>

• Breaking: The source parameter in onChange callback is now optional.

  Migration: Check for undefined values in your callback handler.

// Before (v4)
<ColorSelector onChange={(color, source) => {
  // source was always defined
  console.log(source);
}} />

// After (v5)
<ColorSelector onChange={(color, source) => {
  // source might be undefined
  if (source) {
    console.log(source);
  }
}} />

• Breaking: Default alignY property changed from implicit to stretch.

  Migration: To use the old behavior, explicitly set alignY="start".

// Before (v4) - implicit start alignment
<Column>Content</Column>

// After (v5) - explicit start alignment needed
<Column alignY="start">Content</Column>

• Breaking: Replaced truncateText prop with maxWidth prop.
• Breaking: Changed size values: "small" is now "xsmall".
• Breaking: Pill has a rounder appearance for consistency with other Canva elements.
• Breaking: Removed tone property.

// Before (v4)
<Pill size="small" truncateText>Text</Pill>
<InputPill truncateText={false}>Text</InputPill>

// After (v5)
<Pill size="xsmall" maxWidth='25u'>Text</Pill>
<InputPill maxWidth='100%'>Text</InputPill>

• Breaking: Removed the default colorSurface background color from the html tag.

  A migration isn't be required, the Canva environment has changed to accommodate this.

• Added: LinkButton component for in-app actions that don't open URLs.

  Use LinkButton instead of Button when you need link-style interactions without navigation