Finalize v11 migration experience content

[tay1orjones]

To ensure alignment between user expectation and content, we need to take a high level look through the existing migration page on the website and define areas that need updated or added.

Outcome is to identify individual deliverables that need to be accomplished in the following areas:

• Define migration journeys for PALs, frameworks
• Do a content pass on the website
  • What are we missing?
  • What should change?

Outcome/Checklist:

• Update the developer migration overview page
  • Make sure our value prop is clear
  • Give an overview of changes in the format of: what we changed, why, what the impact is to you
• Update the migration guide
  • Create component table and prioritize prop review
• Improve our reference guide
  • Remove TODO notes
  • Remove upgrade paths

[joshblack]

Overview

Ready to make the migration to Carbon v11 Beta? There are breaking changes along with net new features that your product can now consume. Getting started with Carbon has never been easier!

• Carbon v11 Beta -> Carbon v11

Overview

Carbon v11 focuses on quality of life updates for designers and developers including token and prop renaming for ease of use, component API updates for a more predictable developer experience, and introducing CSS grid for accurate layout building in line with the design language.

• Accessibility primitives
• Other updates
• What's the immediate value add?
• Light mode, dark mode

With no changes to the IBM Design Language, v11 will not require any brand-driven product redesigns.

Migrating to Carbon v11 comes with many changes to our system that will help designers and developers build faster, increase flexibility, and improve ease of use.

• Needs clarity

What’s changing

• Needs to be cleaned up

What's not changing

• Assets that are deprecated in v10 will remain in v11 and will be removed in v12.

Getting started

Notes

• Any way to find a way to link to a broad overview of the changes
• Need to make sure the value is really clear
  • What is this and why do I care / how does it help me

[joshblack]

migrating/guide/develop

• Guide -> Migration Guide

Here you can find information on how to migrate your code from Carbon v10 to v11. As with any major version, there are some exciting features we’re looking forward to sharing with you. We hope to make your transition as smooth as possible by detailing all of the updates below.

Changelog

• This information should live in the release tag for the changelog

Components

• Rename to packages

• carbon-components and carbon-components-react are not being deprecated until close to v12

• What is this change

• What this means for me

• How to migrate

• Resources

Styles

Using Dart-Sass, we are finally able to use the Module System, dropping the import-once helpers that have being causing awful compilation and build times

• Faster
• Cleaner
• Cite performance improvements in Storybook

How to migrate

• Section for talking about the path changes and linking out to our reference guide
  • Include common paths
• Separate out dart sass and sass modules and import changes
• Call out that you can use this with @import and that you don't have to change your project to use Sass Modules

Color Tokens

• Make sure the link to the color tokens migration table is up-to-date
• Nice to call out compatibility mode that is offered, as well
• This also introduces a layering model, learn more here

CSS Grid

• This section should explicitly state that flexbox grid is not going away, you do not need to update to CSS Grid to be on v11
  • Use FlexGrid instead of Grid
  • 12 column grid isn't going away, but it's now 16 by default. How to configure 12 column grid in FlexGrid?
• New features
  • CSS Grid, new react components

Theming

• light prop has been deprecated, use Layer instead
• New features
  • inline theming
  • light/dark mode support
  • New react components

Updates to @carbon/icons-react

• There are no longer size exports from our package to reduce our package footprint when installed
• You can now import icons directly from the @carbon/react package
• You can change the size of an icon through the size prop

Component API

Questions

• Should we offer a component-by-component change overview?
• Remove event handler updates

Size prop

className prop

New Components

• We can call out that there are new components but it's not migration material

Notifications

• How do we document v10 component to v11 component migration materials

Questions

• What would it look like to set this page up as a "migration guide" with "upgrade paths"?
• Call out that we are dropping support for IE11

[joshblack]

Next Steps

• Update the overview page
  • Make sure our value prop is clear
  • Give an overview of changes in the format of: what we changed, why, what the impact is to you
• Update the migration guide
  • Create component table and prioritize prop review
• Improve our reference guide
  • Remove TODO notes
  • Remove upgrade paths

[tay1orjones]

Closed via carbon-design-system/carbon-website#2834