This live demo contains only a preview of functionality and styles available for this component. View the full demo on Storybook for additional information such as its version, controls, and API documentation.
Accessibility testing status
For every latest release, Carbon runs tests on all components to meet the accessibility requirements. These different statuses report the work that Carbon has done in the back end. These tests appear only when the components are stable.
This live demo contains only a preview of functionality and styles available for this component. View the full demo on Storybook for additional information such as its version, controls, and API documentation.
Accessibility testing status
For every latest release, Carbon runs tests on all components to meet the accessibility requirements. These different statuses report the work that Carbon has done in the back end. These tests appear only when the components are stable.
Loading spinners are used when retrieving data or performing slow computations.
They notify to the user that their request is being processed. Although they do
not provide details about what is occurring on the back-end, they reassure the
user that their action is being processed.
Use a loading spinner whenever the wait time is anticipated to be longer than
diff --git a/components/menu-buttons/accessibility/index.html b/components/menu-buttons/accessibility/index.html
index ba1a1e73277..01e9980bff1 100644
--- a/components/menu-buttons/accessibility/index.html
+++ b/components/menu-buttons/accessibility/index.html
@@ -17,7 +17,7 @@
No accessibility annotations are needed for overflow menus, but keep these
considerations in mind if you are modifying Carbon or creating a custom
component.
Coming soon! The accessibility information for the menu button and combo
-button is going to be updated soon.
For every latest release, Carbon runs tests on all components to meet the accessibility requirements. These different statuses report the work that Carbon has done in the back end. These tests appear only when the components are stable.
Tests that ensure additional states of the component are accessible. This could be interactive states of a component or its multiple variants.
Automated or manual testing has been temporarily deferred.
Tests that ensure focus is properly managed, and all interactive functions of a component have a proper keyboard-accessible equivalent.
Test data is either not available or not applicable for this component state.
This manual testing ensures that the visual information on the screen is properly conveyed and read correctly by screen readers such as JAWS, VoiceOver, and NVDA.
A human has manually tested this component, e.g. screen reader testing.
For every latest release, Carbon runs tests on all components to meet the accessibility requirements. These different statuses report the work that Carbon has done in the back end. These tests appear only when the components are stable.
Tests that ensure additional states of the component are accessible. This could be interactive states of a component or its multiple variants.
Automated or manual testing has been temporarily deferred.
Tests that ensure focus is properly managed, and all interactive functions of a component have a proper keyboard-accessible equivalent.
Test data is either not available or not applicable for this component state.
This manual testing ensures that the visual information on the screen is properly conveyed and read correctly by screen readers such as JAWS, VoiceOver, and NVDA.
A human has manually tested this component, e.g. screen reader testing.
Carbon bakes keyboard operation into its components, improving the experience of
blind users and others who operate via keyboard. Carbon also incorporates other
accessibility considerations, some of which are described below.
Keyboard interaction
Each overflow menu is in the tab order and is activated by Space or Enter.
When the menu is open, the first item takes focus. Focus is moved between menu
diff --git a/components/menu/accessibility/index.html b/components/menu/accessibility/index.html
index bdc0e1be51d..4c5a71eac3c 100644
--- a/components/menu/accessibility/index.html
+++ b/components/menu/accessibility/index.html
@@ -14,7 +14,7 @@
}
}
})
-
For every latest release, Carbon runs tests on all components to meet the accessibility requirements. These different statuses report the work that Carbon has done in the back end. These tests appear only when the components are stable.
Tests that ensure additional states of the component are accessible. This could be interactive states of a component or its multiple variants.
Automated or manual testing has been temporarily deferred.
Tests that ensure focus is properly managed, and all interactive functions of a component have a proper keyboard-accessible equivalent.
Passes all automated tests with no reported accessibility violations.
This manual testing ensures that the visual information on the screen is properly conveyed and read correctly by screen readers such as JAWS, VoiceOver, and NVDA.
A human has manually tested this component, e.g. screen reader testing.
For every latest release, Carbon runs tests on all components to meet the accessibility requirements. These different statuses report the work that Carbon has done in the back end. These tests appear only when the components are stable.
Tests that ensure additional states of the component are accessible. This could be interactive states of a component or its multiple variants.
Automated or manual testing has been temporarily deferred.
Tests that ensure focus is properly managed, and all interactive functions of a component have a proper keyboard-accessible equivalent.
Passes all automated tests with no reported accessibility violations.
This manual testing ensures that the visual information on the screen is properly conveyed and read correctly by screen readers such as JAWS, VoiceOver, and NVDA.
A human has manually tested this component, e.g. screen reader testing.
This live demo contains only a preview of functionality and styles available for this component. View the full demo on Storybook for additional information such as its version, controls, and API documentation.
Accessibility testing status
For every latest release, Carbon runs tests on all components to meet the accessibility requirements. These different statuses report the work that Carbon has done in the back end. These tests appear only when the components are stable.
This live demo contains only a preview of functionality and styles available for this component. View the full demo on Storybook for additional information such as its version, controls, and API documentation.
Accessibility testing status
For every latest release, Carbon runs tests on all components to meet the accessibility requirements. These different statuses report the work that Carbon has done in the back end. These tests appear only when the components are stable.
A menu is a disclosure component that appears with a set of actions relevant to
a specific control, interface area, data element, or application view.
Typically, this context is determined by the user’s current selection prior to
invoking the menu. Menus can be opened from components such as menu buttons or
diff --git a/data-visualization/simple-charts/index.html b/data-visualization/simple-charts/index.html
index 0506618ea74..934df65c26b 100644
--- a/data-visualization/simple-charts/index.html
+++ b/data-visualization/simple-charts/index.html
@@ -16,7 +16,7 @@
})
Simple charts offer a way to visualize data sets in an intuitive, easy to
understand way. Every chart should tell a story and should reflect the content
-on the page where it is found.
Area charts are similar to line charts, but the areas below the lines are filled with colors or patterns. Stacked charts are useful for comparing proportional contributions within a category. They plot the relative value that each data series contributes to the total.
A grouped bar chart, also known as a clustered bar graph, multi-set bar chart, or grouped column chart, is a type of bar graph that is used to compare values across multiple categories.
Stacked bar charts are useful for comparing proportional contributions within a category. They plot the relative value that each data series contributes to the total.
Bubble charts use data points and bubbles to plot measures anywhere along a scale. One measure is plotted along each axis. The size of the bubble represents the third measure. You can use bubble charts to represent financial data or any data where measured values are related.
Scatter plot visualizations use data points to plot two measures anywhere along a scale, not only at regular tick marks. You can use scatter plots to explore correlations between different measures.
Stepped line charts plot data at regular intervals, forming a series of steps between data points. You can use line visualizations to show trends over time and compare several data sets.
\n```\n","type":"Mdx","contentDigest":"75fff0a6d31e5e68bd45d82e2dee6e32","owner":"gatsby-plugin-mdx","counter":5261},"frontmatter":{"title":"Spatial Charts","description":"Discover spatial patterns and hierarchies, showcasing tree maps, circle packs, and geospatial charts."},"exports":{},"rawBody":"---\ntitle: Spatial Charts\ndescription:\n Discover spatial patterns and hierarchies, showcasing tree maps, circle packs,\n and geospatial charts.\n---\n\nimport { getDemoGroupByTitle } from '../../../data/data-visualization';\n\nimport { AnchorLinks, AnchorLink } from 'gatsby-theme-carbon';\nimport ChartDemoGroup from '../../../components/data-visualization/ChartDemoGroup.js';\n\n\n\nDiscover spatial patterns and hierarchies, showcasing tree maps, circle packs,\nand geospatial charts. Explore the interplay of data elements through tree maps,\ncircle packs, and geospatial charts, revealing spatial relationships and\nhierarchical structures within your data.\n\n\n\n\n\n**Note:** Some of the charts below are not included in the carbon-charts\nrepository yet. To see our roadmap, make feature requests, or contribute, please\ngo to the\n[carbon-charts repository](https://github.com/carbon-design-system/carbon-charts).\n\n\n\n\n Heat maps\n Tree maps\n Circle packs\n Geospatial charts\n\n\n## Heat maps\n\nA heat map is a two-dimensional visualization in which individual values\ncontained in a matrix are represented as colors. This technique makes it easy to\nvisualize complex data at a glance. When it comes to heat maps, the most common\ncolor ranges are expressed in either sequential and diverging color scales\naccording to the type of data represented.\n\n#### Sequential scales\n\nSequential scales use a blended progression, typically of a single color, from\nthe lowest contrast to the highest contrast values, representing lows to highs.\nIt’s best practice to use a sequential scale with values that are all positive\nor all negative. Sequential heat maps can leverage the full range of the palette\n(from 10–100) to maximize contrast. Please note that the 3:1 minimum contrast\nrequirement does not apply to heat maps.\n\n\n\n
\n When cells get extremely small, a white border can hinder the intended effect.\n
\n\n#### Heat map behaviors\n\nAxis ticks and legend can be used to leverage the chart potential giving the\nusers additional information and dedicated kinds of interaction.\n\n\n\n\n\n\n
Exploration of a domain axis hover behavior
\n\n\n\n\n#### Divergent scales\n\nDiverging scales show color progression in two directions: dialing down the\ncontrast of the first hue from one end to a neutral color at the midpoint, then\nincreasing the contrast of the second hue to the other end of the scale. The\nneutral midpoint is often referred to as the \"inflection point\" (for example, a\n0 value midway between -100 and +100).\n\n[Divergent scales](/data-visualization/color-palettes#diverging-palettes)\nrequire three colors for their correspondent values (min, max, and inflection\npoint) and Carbon has provided two approved palettes for divergent\nvisualizations. Although the examples here use the \"discrete\" (stepped scale)\nprovided by the Carbon palette, divergent heat maps often leverage \"continuous\"\nvalues (gradients) to accommodate situations that require more than 10 values.\n\n#### Inflection points\n\nWhile min/max values can be automatically detected from data, inflection points\ncan vary depending on data type. We default to zero in order to accommodate the\nmost common cases and include a feature flag within the code to specify\nexceptions. The data for a divergent heat map does not need to be symmetrical on\neither side of the inflection point. For example, the data set could have a zero\nvalue between -20 and +100 as well.\n\n## Tree maps\n\nTree maps can work for visualizing a part-to-whole relationship among a large\nnumber of categories—as long as the data is hierarchical and exact comparisons\nbetween the categories is not a primary concern.\n\nWhen dealing with large amounts of data in a constrained space, tree structured\nnodelink diagrams (like the network diagram shown above), grow too complex to be\nuseful. Tree maps provide an attractive alternative by maintaining a\nhierarchical structure while displaying rectangular quantities for each category\nand subcategory via area size.\n\n
\n \n
\n\n#### Divergent tree maps\n\nDivergent tree maps combine Carbon's divergent color palette with the\nhierarchical structure of a tree map. Each rectangle has an area proportional to\na specified dimension of the data, but the rectangles can also be colored\nindependently according to an additional indicator.\n\nAs with [heat maps](#heat-maps), the diverging palette shows color progression\nin either direction from an inflection point (for example, a 0 value midway\nbetween -10 and +10). In the example below, the inflection point is simply an\naverage. Tourism can be mapped by the number of visitors to a certain country,\nbut the visualization can also compare this data to a yearly average. For\ninstance, even though one country may have a lot of visitors compared to another\ncountry, tourism for that country may fall below its annual average.\n\n\n\n\n\n\n
\n Example of a divergent tree map adding color as a second variable to a basic\n tree map structure\n
Detail of a comparative tooltip on a divergent tree map
\n\n\n\n\n## Circle packs\n\nA circle pack is a hierarchical visualization of data. It’s equivalent to a\nTreemap or a Dendrogram—where each node of the tree is represented as a circle\nand sub-nodes are represented as circles within a parent. The size of each\ncircle can also be used to represent an additional arbitrary value, such as\npopulation or file size. Color may also be used to assign categories or to\nrepresent an additional variable. Although they’re not as space efficient,\nCircle Packs reveal hierarchical structure better than Treemaps.\n\nFor Circle Packs with more than two levels of hierarchy, zoom functionality\nallows users to explore the data without compromising the contrast accessibility\nof the chart. We advise against disabling the zoom functionality except in cases\nsuch as preview charts, cards that expand to full view with the chart, etc.\n\n
\n \n
\n\n## Geospatial charts\n\n### Geographic overlays\n\n#### Choropleth map\n\nA map that uses differences in shading, coloring, or the placing of symbols\nwithin predefined areas to indicate the average values of a property or quantity\nin those areas.\n\n\n\n\n\n\n\n\n\n### Proportional symbol map\n\nSymbols driven by data are overlayed in geographical regions. A bubble is the\nsymbol most commonly used in this instance—with the area of the circle\nproportional to its value in the dataset.\n\n\n\n\n\n\n\n\n\n### Connection map\n\nConnection Maps are drawn by connecting points placed on a map by straight or\ncurved lines.\n\nWhile Connection Maps are great for showing connections and relationships\ngeographically, they can also be used to display map routes through a single\nchain of links. Connection Maps can also be useful in revealing spatial patterns\nthrough the distribution of connections or by how concentrated connections are\non a map.\n\n\n\n\n\n\n\n\n\n### Geospatial distortions\n\n#### Density-equalizing cartograms\n\nDensity-equalizing cartograms are the most common type of cartogram. In this\nsituation the mapping variable takes the place of the land area or distance in\nthe map, causing the map to become distorted in proportion to the substitute\nvariable.\n\nCartograms are useful for visualizing populations through different lenses — for\ninstance, ethnicities, political parties, or religious affiliation. Carbon does\nnot have a coded component for cartograms but online generators like\n[go-cart.io](https://go-cart.io/) allow you to upload your own data sets and\ndownload an .svg file.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n#### Dorling cartograms\n\nThe Dorling Cartogram is a technique for representing data for areas that avoids\ngeography in favor of (normally) a geometric shape that represents the unit\nareas. Circles are usually chosen since they can be neatly positioned.\n\nAs with the density-equalizing cartogram above, the larger the total population,\nthe larger the representation of the country.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n### Mapbox\n\nFor more dynamic, real-time mapping, Carbon has created four themes using\n[Mapbox](https://www.mapbox.com/). Mapbox is a developer platform used across\nindustries to create custom maps that can be easily integrated into websites and\napps. These themes can be used as is, or in conjunction with Carbon-styled data\npoints.\n\nThese styles can be used as is, or as a backdrop for other geospatial data sets.\nFor more complex data sets that require the full breadth of the Carbon charts\npalette, we suggest using either the White or the Gray 100 style for the most\naccessible results.\n\n\n\n\n\n\n
Example of a Carbon’s Gray 100 theme style in Mapbox
\n\n\n\n\n#### Applying the Carbon Mapbox themes\n\nFor instructions on how to use Mapbox GL JS please read this\n[Mapbox quickstart documentation](https://docs.mapbox.com/mapbox-gl-js/api/#quickstart).\n\nIn addition to the instructions above, when initializing a new map you can apply\nany of the 4 Carbon themes by providing the stylesheet location to the library.\n\n| Theme | Style sheet location |\n| ---------- | -------------------------------------------------------------- |\n| _White_ | `mapbox://styles/carbondesignsystem/ck7c8cfpp08h61irrudv7f1xg` |\n| _Gray 10_ | `mapbox://styles/carbondesignsystem/ck7c8ce1y05h61ipb2fixfe76` |\n| _Gray 90_ | `mapbox://styles/carbondesignsystem/ck7c8ccac08jj1imhvd2g4qfb` |\n| _Gray 100_ | `mapbox://styles/carbondesignsystem/ck7c89g8708gy1imlz9g5o6h9` |\n\nExample\n\n```html\n\n```\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/data-visualization/spatial-charts/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-data-visualization-spatial-charts-index-mdx","path":"/data-visualization/spatial-charts/","result":{"pageContext":{"frontmatter":{"title":"Spatial Charts","description":"Discover spatial patterns and hierarchies, showcasing tree maps, circle packs, and geospatial charts."},"relativePagePath":"/data-visualization/spatial-charts/index.mdx","titleType":"prepend","MdxNode":{"id":"2943d2de-6969-5771-b6c0-8a60a5ef9d11","children":[],"parent":"086aae7b-4dc4-5f82-ad71-6b648cbc340b","internal":{"content":"---\ntitle: Spatial Charts\ndescription:\n Discover spatial patterns and hierarchies, showcasing tree maps, circle packs,\n and geospatial charts.\n---\n\nimport { getDemoGroupByTitle } from '../../../data/data-visualization';\n\nimport { AnchorLinks, AnchorLink } from 'gatsby-theme-carbon';\nimport ChartDemoGroup from '../../../components/data-visualization/ChartDemoGroup.js';\n\n\n\nDiscover spatial patterns and hierarchies, showcasing tree maps, circle packs,\nand geospatial charts. Explore the interplay of data elements through tree maps,\ncircle packs, and geospatial charts, revealing spatial relationships and\nhierarchical structures within your data.\n\n\n\n\n\n**Note:** Some of the charts below are not included in the carbon-charts\nrepository yet. To see our roadmap, make feature requests, or contribute, please\ngo to the\n[carbon-charts repository](https://github.com/carbon-design-system/carbon-charts).\n\n\n\n\n Heat maps\n Tree maps\n Circle packs\n Geospatial charts\n\n\n## Heat maps\n\nA heat map is a two-dimensional visualization in which individual values\ncontained in a matrix are represented as colors. This technique makes it easy to\nvisualize complex data at a glance. When it comes to heat maps, the most common\ncolor ranges are expressed in either sequential and diverging color scales\naccording to the type of data represented.\n\n#### Sequential scales\n\nSequential scales use a blended progression, typically of a single color, from\nthe lowest contrast to the highest contrast values, representing lows to highs.\nIt’s best practice to use a sequential scale with values that are all positive\nor all negative. Sequential heat maps can leverage the full range of the palette\n(from 10–100) to maximize contrast. Please note that the 3:1 minimum contrast\nrequirement does not apply to heat maps.\n\n\n\n
\n When cells get extremely small, a white border can hinder the intended effect.\n
\n\n#### Heat map behaviors\n\nAxis ticks and legend can be used to leverage the chart potential giving the\nusers additional information and dedicated kinds of interaction.\n\n\n\n\n\n\n
Exploration of a domain axis hover behavior
\n\n\n\n\n#### Divergent scales\n\nDiverging scales show color progression in two directions: dialing down the\ncontrast of the first hue from one end to a neutral color at the midpoint, then\nincreasing the contrast of the second hue to the other end of the scale. The\nneutral midpoint is often referred to as the \"inflection point\" (for example, a\n0 value midway between -100 and +100).\n\n[Divergent scales](/data-visualization/color-palettes#diverging-palettes)\nrequire three colors for their correspondent values (min, max, and inflection\npoint) and Carbon has provided two approved palettes for divergent\nvisualizations. Although the examples here use the \"discrete\" (stepped scale)\nprovided by the Carbon palette, divergent heat maps often leverage \"continuous\"\nvalues (gradients) to accommodate situations that require more than 10 values.\n\n#### Inflection points\n\nWhile min/max values can be automatically detected from data, inflection points\ncan vary depending on data type. We default to zero in order to accommodate the\nmost common cases and include a feature flag within the code to specify\nexceptions. The data for a divergent heat map does not need to be symmetrical on\neither side of the inflection point. For example, the data set could have a zero\nvalue between -20 and +100 as well.\n\n## Tree maps\n\nTree maps can work for visualizing a part-to-whole relationship among a large\nnumber of categories—as long as the data is hierarchical and exact comparisons\nbetween the categories is not a primary concern.\n\nWhen dealing with large amounts of data in a constrained space, tree structured\nnodelink diagrams (like the network diagram shown above), grow too complex to be\nuseful. Tree maps provide an attractive alternative by maintaining a\nhierarchical structure while displaying rectangular quantities for each category\nand subcategory via area size.\n\n
\n \n
\n\n#### Divergent tree maps\n\nDivergent tree maps combine Carbon's divergent color palette with the\nhierarchical structure of a tree map. Each rectangle has an area proportional to\na specified dimension of the data, but the rectangles can also be colored\nindependently according to an additional indicator.\n\nAs with [heat maps](#heat-maps), the diverging palette shows color progression\nin either direction from an inflection point (for example, a 0 value midway\nbetween -10 and +10). In the example below, the inflection point is simply an\naverage. Tourism can be mapped by the number of visitors to a certain country,\nbut the visualization can also compare this data to a yearly average. For\ninstance, even though one country may have a lot of visitors compared to another\ncountry, tourism for that country may fall below its annual average.\n\n\n\n\n\n\n
\n Example of a divergent tree map adding color as a second variable to a basic\n tree map structure\n
Detail of a comparative tooltip on a divergent tree map
\n\n\n\n\n## Circle packs\n\nA circle pack is a hierarchical visualization of data. It’s equivalent to a\nTreemap or a Dendrogram—where each node of the tree is represented as a circle\nand sub-nodes are represented as circles within a parent. The size of each\ncircle can also be used to represent an additional arbitrary value, such as\npopulation or file size. Color may also be used to assign categories or to\nrepresent an additional variable. Although they’re not as space efficient,\nCircle Packs reveal hierarchical structure better than Treemaps.\n\nFor Circle Packs with more than two levels of hierarchy, zoom functionality\nallows users to explore the data without compromising the contrast accessibility\nof the chart. We advise against disabling the zoom functionality except in cases\nsuch as preview charts, cards that expand to full view with the chart, etc.\n\n
\n \n
\n\n## Geospatial charts\n\n### Geographic overlays\n\n#### Choropleth map\n\nA map that uses differences in shading, coloring, or the placing of symbols\nwithin predefined areas to indicate the average values of a property or quantity\nin those areas.\n\n\n\n\n\n\n\n\n\n### Proportional symbol map\n\nSymbols driven by data are overlayed in geographical regions. A bubble is the\nsymbol most commonly used in this instance—with the area of the circle\nproportional to its value in the dataset.\n\n\n\n\n\n\n\n\n\n### Connection map\n\nConnection Maps are drawn by connecting points placed on a map by straight or\ncurved lines.\n\nWhile Connection Maps are great for showing connections and relationships\ngeographically, they can also be used to display map routes through a single\nchain of links. Connection Maps can also be useful in revealing spatial patterns\nthrough the distribution of connections or by how concentrated connections are\non a map.\n\n\n\n\n\n\n\n\n\n### Geospatial distortions\n\n#### Density-equalizing cartograms\n\nDensity-equalizing cartograms are the most common type of cartogram. In this\nsituation the mapping variable takes the place of the land area or distance in\nthe map, causing the map to become distorted in proportion to the substitute\nvariable.\n\nCartograms are useful for visualizing populations through different lenses — for\ninstance, ethnicities, political parties, or religious affiliation. Carbon does\nnot have a coded component for cartograms but online generators like\n[go-cart.io](https://go-cart.io/) allow you to upload your own data sets and\ndownload an .svg file.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n#### Dorling cartograms\n\nThe Dorling Cartogram is a technique for representing data for areas that avoids\ngeography in favor of (normally) a geometric shape that represents the unit\nareas. Circles are usually chosen since they can be neatly positioned.\n\nAs with the density-equalizing cartogram above, the larger the total population,\nthe larger the representation of the country.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n### Mapbox\n\nFor more dynamic, real-time mapping, Carbon has created four themes using\n[Mapbox](https://www.mapbox.com/). Mapbox is a developer platform used across\nindustries to create custom maps that can be easily integrated into websites and\napps. These themes can be used as is, or in conjunction with Carbon-styled data\npoints.\n\nThese styles can be used as is, or as a backdrop for other geospatial data sets.\nFor more complex data sets that require the full breadth of the Carbon charts\npalette, we suggest using either the White or the Gray 100 style for the most\naccessible results.\n\n\n\n\n\n\n
Example of a Carbon’s Gray 100 theme style in Mapbox
\n\n\n\n\n#### Applying the Carbon Mapbox themes\n\nFor instructions on how to use Mapbox GL JS please read this\n[Mapbox quickstart documentation](https://docs.mapbox.com/mapbox-gl-js/api/#quickstart).\n\nIn addition to the instructions above, when initializing a new map you can apply\nany of the 4 Carbon themes by providing the stylesheet location to the library.\n\n| Theme | Style sheet location |\n| ---------- | -------------------------------------------------------------- |\n| _White_ | `mapbox://styles/carbondesignsystem/ck7c8cfpp08h61irrudv7f1xg` |\n| _Gray 10_ | `mapbox://styles/carbondesignsystem/ck7c8ce1y05h61ipb2fixfe76` |\n| _Gray 90_ | `mapbox://styles/carbondesignsystem/ck7c8ccac08jj1imhvd2g4qfb` |\n| _Gray 100_ | `mapbox://styles/carbondesignsystem/ck7c89g8708gy1imlz9g5o6h9` |\n\nExample\n\n```html\n\n```\n","type":"Mdx","contentDigest":"75fff0a6d31e5e68bd45d82e2dee6e32","owner":"gatsby-plugin-mdx","counter":5262},"frontmatter":{"title":"Spatial Charts","description":"Discover spatial patterns and hierarchies, showcasing tree maps, circle packs, and geospatial charts."},"exports":{},"rawBody":"---\ntitle: Spatial Charts\ndescription:\n Discover spatial patterns and hierarchies, showcasing tree maps, circle packs,\n and geospatial charts.\n---\n\nimport { getDemoGroupByTitle } from '../../../data/data-visualization';\n\nimport { AnchorLinks, AnchorLink } from 'gatsby-theme-carbon';\nimport ChartDemoGroup from '../../../components/data-visualization/ChartDemoGroup.js';\n\n\n\nDiscover spatial patterns and hierarchies, showcasing tree maps, circle packs,\nand geospatial charts. Explore the interplay of data elements through tree maps,\ncircle packs, and geospatial charts, revealing spatial relationships and\nhierarchical structures within your data.\n\n\n\n\n\n**Note:** Some of the charts below are not included in the carbon-charts\nrepository yet. To see our roadmap, make feature requests, or contribute, please\ngo to the\n[carbon-charts repository](https://github.com/carbon-design-system/carbon-charts).\n\n\n\n\n Heat maps\n Tree maps\n Circle packs\n Geospatial charts\n\n\n## Heat maps\n\nA heat map is a two-dimensional visualization in which individual values\ncontained in a matrix are represented as colors. This technique makes it easy to\nvisualize complex data at a glance. When it comes to heat maps, the most common\ncolor ranges are expressed in either sequential and diverging color scales\naccording to the type of data represented.\n\n#### Sequential scales\n\nSequential scales use a blended progression, typically of a single color, from\nthe lowest contrast to the highest contrast values, representing lows to highs.\nIt’s best practice to use a sequential scale with values that are all positive\nor all negative. Sequential heat maps can leverage the full range of the palette\n(from 10–100) to maximize contrast. Please note that the 3:1 minimum contrast\nrequirement does not apply to heat maps.\n\n\n\n
\n When cells get extremely small, a white border can hinder the intended effect.\n
\n\n#### Heat map behaviors\n\nAxis ticks and legend can be used to leverage the chart potential giving the\nusers additional information and dedicated kinds of interaction.\n\n\n\n\n\n\n
Exploration of a domain axis hover behavior
\n\n\n\n\n#### Divergent scales\n\nDiverging scales show color progression in two directions: dialing down the\ncontrast of the first hue from one end to a neutral color at the midpoint, then\nincreasing the contrast of the second hue to the other end of the scale. The\nneutral midpoint is often referred to as the \"inflection point\" (for example, a\n0 value midway between -100 and +100).\n\n[Divergent scales](/data-visualization/color-palettes#diverging-palettes)\nrequire three colors for their correspondent values (min, max, and inflection\npoint) and Carbon has provided two approved palettes for divergent\nvisualizations. Although the examples here use the \"discrete\" (stepped scale)\nprovided by the Carbon palette, divergent heat maps often leverage \"continuous\"\nvalues (gradients) to accommodate situations that require more than 10 values.\n\n#### Inflection points\n\nWhile min/max values can be automatically detected from data, inflection points\ncan vary depending on data type. We default to zero in order to accommodate the\nmost common cases and include a feature flag within the code to specify\nexceptions. The data for a divergent heat map does not need to be symmetrical on\neither side of the inflection point. For example, the data set could have a zero\nvalue between -20 and +100 as well.\n\n## Tree maps\n\nTree maps can work for visualizing a part-to-whole relationship among a large\nnumber of categories—as long as the data is hierarchical and exact comparisons\nbetween the categories is not a primary concern.\n\nWhen dealing with large amounts of data in a constrained space, tree structured\nnodelink diagrams (like the network diagram shown above), grow too complex to be\nuseful. Tree maps provide an attractive alternative by maintaining a\nhierarchical structure while displaying rectangular quantities for each category\nand subcategory via area size.\n\n
\n \n
\n\n#### Divergent tree maps\n\nDivergent tree maps combine Carbon's divergent color palette with the\nhierarchical structure of a tree map. Each rectangle has an area proportional to\na specified dimension of the data, but the rectangles can also be colored\nindependently according to an additional indicator.\n\nAs with [heat maps](#heat-maps), the diverging palette shows color progression\nin either direction from an inflection point (for example, a 0 value midway\nbetween -10 and +10). In the example below, the inflection point is simply an\naverage. Tourism can be mapped by the number of visitors to a certain country,\nbut the visualization can also compare this data to a yearly average. For\ninstance, even though one country may have a lot of visitors compared to another\ncountry, tourism for that country may fall below its annual average.\n\n\n\n\n\n\n
\n Example of a divergent tree map adding color as a second variable to a basic\n tree map structure\n
Detail of a comparative tooltip on a divergent tree map
\n\n\n\n\n## Circle packs\n\nA circle pack is a hierarchical visualization of data. It’s equivalent to a\nTreemap or a Dendrogram—where each node of the tree is represented as a circle\nand sub-nodes are represented as circles within a parent. The size of each\ncircle can also be used to represent an additional arbitrary value, such as\npopulation or file size. Color may also be used to assign categories or to\nrepresent an additional variable. Although they’re not as space efficient,\nCircle Packs reveal hierarchical structure better than Treemaps.\n\nFor Circle Packs with more than two levels of hierarchy, zoom functionality\nallows users to explore the data without compromising the contrast accessibility\nof the chart. We advise against disabling the zoom functionality except in cases\nsuch as preview charts, cards that expand to full view with the chart, etc.\n\n
\n \n
\n\n## Geospatial charts\n\n### Geographic overlays\n\n#### Choropleth map\n\nA map that uses differences in shading, coloring, or the placing of symbols\nwithin predefined areas to indicate the average values of a property or quantity\nin those areas.\n\n\n\n\n\n\n\n\n\n### Proportional symbol map\n\nSymbols driven by data are overlayed in geographical regions. A bubble is the\nsymbol most commonly used in this instance—with the area of the circle\nproportional to its value in the dataset.\n\n\n\n\n\n\n\n\n\n### Connection map\n\nConnection Maps are drawn by connecting points placed on a map by straight or\ncurved lines.\n\nWhile Connection Maps are great for showing connections and relationships\ngeographically, they can also be used to display map routes through a single\nchain of links. Connection Maps can also be useful in revealing spatial patterns\nthrough the distribution of connections or by how concentrated connections are\non a map.\n\n\n\n\n\n\n\n\n\n### Geospatial distortions\n\n#### Density-equalizing cartograms\n\nDensity-equalizing cartograms are the most common type of cartogram. In this\nsituation the mapping variable takes the place of the land area or distance in\nthe map, causing the map to become distorted in proportion to the substitute\nvariable.\n\nCartograms are useful for visualizing populations through different lenses — for\ninstance, ethnicities, political parties, or religious affiliation. Carbon does\nnot have a coded component for cartograms but online generators like\n[go-cart.io](https://go-cart.io/) allow you to upload your own data sets and\ndownload an .svg file.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n#### Dorling cartograms\n\nThe Dorling Cartogram is a technique for representing data for areas that avoids\ngeography in favor of (normally) a geometric shape that represents the unit\nareas. Circles are usually chosen since they can be neatly positioned.\n\nAs with the density-equalizing cartogram above, the larger the total population,\nthe larger the representation of the country.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n### Mapbox\n\nFor more dynamic, real-time mapping, Carbon has created four themes using\n[Mapbox](https://www.mapbox.com/). Mapbox is a developer platform used across\nindustries to create custom maps that can be easily integrated into websites and\napps. These themes can be used as is, or in conjunction with Carbon-styled data\npoints.\n\nThese styles can be used as is, or as a backdrop for other geospatial data sets.\nFor more complex data sets that require the full breadth of the Carbon charts\npalette, we suggest using either the White or the Gray 100 style for the most\naccessible results.\n\n\n\n\n\n\n
Example of a Carbon’s Gray 100 theme style in Mapbox
\n\n\n\n\n#### Applying the Carbon Mapbox themes\n\nFor instructions on how to use Mapbox GL JS please read this\n[Mapbox quickstart documentation](https://docs.mapbox.com/mapbox-gl-js/api/#quickstart).\n\nIn addition to the instructions above, when initializing a new map you can apply\nany of the 4 Carbon themes by providing the stylesheet location to the library.\n\n| Theme | Style sheet location |\n| ---------- | -------------------------------------------------------------- |\n| _White_ | `mapbox://styles/carbondesignsystem/ck7c8cfpp08h61irrudv7f1xg` |\n| _Gray 10_ | `mapbox://styles/carbondesignsystem/ck7c8ce1y05h61ipb2fixfe76` |\n| _Gray 90_ | `mapbox://styles/carbondesignsystem/ck7c8ccac08jj1imhvd2g4qfb` |\n| _Gray 100_ | `mapbox://styles/carbondesignsystem/ck7c89g8708gy1imlz9g5o6h9` |\n\nExample\n\n```html\n\n```\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/data-visualization/spatial-charts/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/developing/frameworks/react/page-data.json b/page-data/developing/frameworks/react/page-data.json
index 2dfe9029899..f108f55d0f1 100644
--- a/page-data/developing/frameworks/react/page-data.json
+++ b/page-data/developing/frameworks/react/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-developing-frameworks-react-mdx","path":"/developing/frameworks/react/","result":{"pageContext":{"frontmatter":{"title":"Frameworks","description":"The Carbon Design System is built React first, with official support for Web Components. We also support core parts of the system in Angular, vanilla JS, Vue, Svelte, and Lightning Web Components.","tabs":["React","Web Components","Angular","Vue","Svelte","LWC","Vanilla","Other frameworks"]},"relativePagePath":"/developing/frameworks/react.mdx","titleType":"prepend","MdxNode":{"id":"e1739cb8-4a50-528e-8b1b-0d2617847149","children":[],"parent":"952fe1b5-f2e8-5700-bf93-319d3ea37928","internal":{"content":"---\ntitle: Frameworks\ndescription:\n The Carbon Design System is built React first, with official support for Web\n Components. We also support core parts of the system in Angular, vanilla JS,\n Vue, Svelte, and Lightning Web Components.\ntabs:\n [\n 'React',\n 'Web Components',\n 'Angular',\n 'Vue',\n 'Svelte',\n 'LWC',\n 'Vanilla',\n 'Other frameworks',\n ]\n---\n\n\n\nThe Carbon React library provides front-end developers and engineers a\ncollection of reusable React components to build websites and user interfaces.\nAdopting the library enables developers to use consistent markup, styles, and\nbehavior in prototype and production work.\n\n\n\n\n\nInstall\nGetting started\nDevelopment\nTroubleshooting\n\n\n\n## Resources\n\n\n\n \n\n\n\n \n\n \n \n \n \n \n\n\n## Install\n\n Using npm: \n\n```bash\nnpm install --save @carbon/react\n```\n\n\n If you prefer <a href=\"https://yarnpkg.com\">Yarn</a>:\n\n\n```bash\nyarn add @carbon/react\n```\n\n## Getting started\n\nThe `@carbon/react` package provides components, styles and icons for the Carbon\nDesign System.\n\nComponents require the use of a build pipeline in your project. This could be in\nthe form of a bundler, framework, or other build tool. Some examples include\nNext.js, Vite, Parcel, and Webpack. A comprehensive list is available in the\n[react documentation](https://react.dev/learn/start-a-new-react-project).\n\nTo use a component, you can import it directly from the package:\n\n```js\nimport { Button } from '@carbon/react';\n\nfunction MyComponent() {\n return ;\n}\n```\n\nTo include the styles for a specific component, you can either import all the\nstyles from the project or include the styles for a specific component:\n\n```js\n// Bring in all the styles for Carbon in your root/global stylesheet\n@use '@carbon/react';\n\n// Or bring in the styles for one component\n@use '@carbon/react/scss/components/button';\n```\n\n### Icons\n\nThe @carbon/react package also provides icon components that you can include in\nyour project. You can import these icon components from the\n`@carbon/react/icons` entrypoint:\n\n```js\nimport { Add } from '@carbon/react/icons';\n\nfunction MyComponent() {\n return ;\n}\n```\n\nA full list of available icons is provided in the\n[icon library](/guidelines/icons/library/).\n\nFor a more in depth introduction to using `@carbon/react` in a webpack-based\napp, [check out our React tutorial](/developing/react-tutorial/overview/).\n\n## Development\n\nPlease refer to the\n[Contribution Guidelines](https://github.com/carbon-design-system/carbon/blob/v10/.github/CONTRIBUTING.md)\nbefore starting any work.\n\n### Using the server\n\nWe use [Storybook](https://github.com/storybookjs/storybook) for developing\ncomponents.\n\n Start the server: \n\n```bash\nyarn storybook\n```\n\n2. Open browser to `http://localhost:9000/`.\n\n3. Develop components in their respective folders (`/components` or\n `/internal`).\n\n4. Author stories within the `*.stories.js*` files.\n\n### List of available components\n\nView available React Components in\n[the `@carbon/react` storybook](http://react.carbondesignsystem.com). Usage\ninformation is available under the \"docs\" tab.\n\n## Troubleshooting\n\nIf you experience any issues while getting set up with Carbon Components React,\nplease head over to the\n[GitHub repo](https://github.com/carbon-design-system/carbon/tree/v10/packages/react)\nfor more guidelines and support. Please\n[create an issue](https://github.com/carbon-design-system/carbon/issues) if your\nissue does not already exist.\n","type":"Mdx","contentDigest":"a3bd0012dea155e8567bdb219f1cbd6a","owner":"gatsby-plugin-mdx","counter":5278},"frontmatter":{"title":"Frameworks","description":"The Carbon Design System is built React first, with official support for Web Components. We also support core parts of the system in Angular, vanilla JS, Vue, Svelte, and Lightning Web Components.","tabs":["React","Web Components","Angular","Vue","Svelte","LWC","Vanilla","Other frameworks"]},"exports":{},"rawBody":"---\ntitle: Frameworks\ndescription:\n The Carbon Design System is built React first, with official support for Web\n Components. We also support core parts of the system in Angular, vanilla JS,\n Vue, Svelte, and Lightning Web Components.\ntabs:\n [\n 'React',\n 'Web Components',\n 'Angular',\n 'Vue',\n 'Svelte',\n 'LWC',\n 'Vanilla',\n 'Other frameworks',\n ]\n---\n\n\n\nThe Carbon React library provides front-end developers and engineers a\ncollection of reusable React components to build websites and user interfaces.\nAdopting the library enables developers to use consistent markup, styles, and\nbehavior in prototype and production work.\n\n\n\n\n\nInstall\nGetting started\nDevelopment\nTroubleshooting\n\n\n\n## Resources\n\n\n\n \n\n\n\n \n\n \n \n \n \n \n\n\n## Install\n\n Using npm: \n\n```bash\nnpm install --save @carbon/react\n```\n\n\n If you prefer <a href=\"https://yarnpkg.com\">Yarn</a>:\n\n\n```bash\nyarn add @carbon/react\n```\n\n## Getting started\n\nThe `@carbon/react` package provides components, styles and icons for the Carbon\nDesign System.\n\nComponents require the use of a build pipeline in your project. This could be in\nthe form of a bundler, framework, or other build tool. Some examples include\nNext.js, Vite, Parcel, and Webpack. A comprehensive list is available in the\n[react documentation](https://react.dev/learn/start-a-new-react-project).\n\nTo use a component, you can import it directly from the package:\n\n```js\nimport { Button } from '@carbon/react';\n\nfunction MyComponent() {\n return ;\n}\n```\n\nTo include the styles for a specific component, you can either import all the\nstyles from the project or include the styles for a specific component:\n\n```js\n// Bring in all the styles for Carbon in your root/global stylesheet\n@use '@carbon/react';\n\n// Or bring in the styles for one component\n@use '@carbon/react/scss/components/button';\n```\n\n### Icons\n\nThe @carbon/react package also provides icon components that you can include in\nyour project. You can import these icon components from the\n`@carbon/react/icons` entrypoint:\n\n```js\nimport { Add } from '@carbon/react/icons';\n\nfunction MyComponent() {\n return ;\n}\n```\n\nA full list of available icons is provided in the\n[icon library](/guidelines/icons/library/).\n\nFor a more in depth introduction to using `@carbon/react` in a webpack-based\napp, [check out our React tutorial](/developing/react-tutorial/overview/).\n\n## Development\n\nPlease refer to the\n[Contribution Guidelines](https://github.com/carbon-design-system/carbon/blob/v10/.github/CONTRIBUTING.md)\nbefore starting any work.\n\n### Using the server\n\nWe use [Storybook](https://github.com/storybookjs/storybook) for developing\ncomponents.\n\n Start the server: \n\n```bash\nyarn storybook\n```\n\n2. Open browser to `http://localhost:9000/`.\n\n3. Develop components in their respective folders (`/components` or\n `/internal`).\n\n4. Author stories within the `*.stories.js*` files.\n\n### List of available components\n\nView available React Components in\n[the `@carbon/react` storybook](http://react.carbondesignsystem.com). Usage\ninformation is available under the \"docs\" tab.\n\n## Troubleshooting\n\nIf you experience any issues while getting set up with Carbon Components React,\nplease head over to the\n[GitHub repo](https://github.com/carbon-design-system/carbon/tree/v10/packages/react)\nfor more guidelines and support. Please\n[create an issue](https://github.com/carbon-design-system/carbon/issues) if your\nissue does not already exist.\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/developing/frameworks/react.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-developing-frameworks-react-mdx","path":"/developing/frameworks/react/","result":{"pageContext":{"frontmatter":{"title":"Frameworks","description":"The Carbon Design System is built React first, with official support for Web Components. We also support core parts of the system in Angular, vanilla JS, Vue, Svelte, and Lightning Web Components.","tabs":["React","Web Components","Angular","Vue","Svelte","LWC","Vanilla","Other frameworks"]},"relativePagePath":"/developing/frameworks/react.mdx","titleType":"prepend","MdxNode":{"id":"e1739cb8-4a50-528e-8b1b-0d2617847149","children":[],"parent":"952fe1b5-f2e8-5700-bf93-319d3ea37928","internal":{"content":"---\ntitle: Frameworks\ndescription:\n The Carbon Design System is built React first, with official support for Web\n Components. We also support core parts of the system in Angular, vanilla JS,\n Vue, Svelte, and Lightning Web Components.\ntabs:\n [\n 'React',\n 'Web Components',\n 'Angular',\n 'Vue',\n 'Svelte',\n 'LWC',\n 'Vanilla',\n 'Other frameworks',\n ]\n---\n\n\n\nThe Carbon React library provides front-end developers and engineers a\ncollection of reusable React components to build websites and user interfaces.\nAdopting the library enables developers to use consistent markup, styles, and\nbehavior in prototype and production work.\n\n\n\n\n\nInstall\nGetting started\nDevelopment\nTroubleshooting\n\n\n\n## Resources\n\n\n\n \n\n\n\n \n\n \n \n \n \n \n\n\n## Install\n\n Using npm: \n\n```bash\nnpm install --save @carbon/react\n```\n\n\n If you prefer <a href=\"https://yarnpkg.com\">Yarn</a>:\n\n\n```bash\nyarn add @carbon/react\n```\n\n## Getting started\n\nThe `@carbon/react` package provides components, styles and icons for the Carbon\nDesign System.\n\nComponents require the use of a build pipeline in your project. This could be in\nthe form of a bundler, framework, or other build tool. Some examples include\nNext.js, Vite, Parcel, and Webpack. A comprehensive list is available in the\n[react documentation](https://react.dev/learn/start-a-new-react-project).\n\nTo use a component, you can import it directly from the package:\n\n```js\nimport { Button } from '@carbon/react';\n\nfunction MyComponent() {\n return ;\n}\n```\n\nTo include the styles for a specific component, you can either import all the\nstyles from the project or include the styles for a specific component:\n\n```js\n// Bring in all the styles for Carbon in your root/global stylesheet\n@use '@carbon/react';\n\n// Or bring in the styles for one component\n@use '@carbon/react/scss/components/button';\n```\n\n### Icons\n\nThe @carbon/react package also provides icon components that you can include in\nyour project. You can import these icon components from the\n`@carbon/react/icons` entrypoint:\n\n```js\nimport { Add } from '@carbon/react/icons';\n\nfunction MyComponent() {\n return ;\n}\n```\n\nA full list of available icons is provided in the\n[icon library](/guidelines/icons/library/).\n\nFor a more in depth introduction to using `@carbon/react` in a webpack-based\napp, [check out our React tutorial](/developing/react-tutorial/overview/).\n\n## Development\n\nPlease refer to the\n[Contribution Guidelines](https://github.com/carbon-design-system/carbon/blob/v10/.github/CONTRIBUTING.md)\nbefore starting any work.\n\n### Using the server\n\nWe use [Storybook](https://github.com/storybookjs/storybook) for developing\ncomponents.\n\n Start the server: \n\n```bash\nyarn storybook\n```\n\n2. Open browser to `http://localhost:9000/`.\n\n3. Develop components in their respective folders (`/components` or\n `/internal`).\n\n4. Author stories within the `*.stories.js*` files.\n\n### List of available components\n\nView available React Components in\n[the `@carbon/react` storybook](http://react.carbondesignsystem.com). Usage\ninformation is available under the \"docs\" tab.\n\n## Troubleshooting\n\nIf you experience any issues while getting set up with Carbon Components React,\nplease head over to the\n[GitHub repo](https://github.com/carbon-design-system/carbon/tree/v10/packages/react)\nfor more guidelines and support. Please\n[create an issue](https://github.com/carbon-design-system/carbon/issues) if your\nissue does not already exist.\n","type":"Mdx","contentDigest":"a3bd0012dea155e8567bdb219f1cbd6a","owner":"gatsby-plugin-mdx","counter":5277},"frontmatter":{"title":"Frameworks","description":"The Carbon Design System is built React first, with official support for Web Components. We also support core parts of the system in Angular, vanilla JS, Vue, Svelte, and Lightning Web Components.","tabs":["React","Web Components","Angular","Vue","Svelte","LWC","Vanilla","Other frameworks"]},"exports":{},"rawBody":"---\ntitle: Frameworks\ndescription:\n The Carbon Design System is built React first, with official support for Web\n Components. We also support core parts of the system in Angular, vanilla JS,\n Vue, Svelte, and Lightning Web Components.\ntabs:\n [\n 'React',\n 'Web Components',\n 'Angular',\n 'Vue',\n 'Svelte',\n 'LWC',\n 'Vanilla',\n 'Other frameworks',\n ]\n---\n\n\n\nThe Carbon React library provides front-end developers and engineers a\ncollection of reusable React components to build websites and user interfaces.\nAdopting the library enables developers to use consistent markup, styles, and\nbehavior in prototype and production work.\n\n\n\n\n\nInstall\nGetting started\nDevelopment\nTroubleshooting\n\n\n\n## Resources\n\n\n\n \n\n\n\n \n\n \n \n \n \n \n\n\n## Install\n\n Using npm: \n\n```bash\nnpm install --save @carbon/react\n```\n\n\n If you prefer <a href=\"https://yarnpkg.com\">Yarn</a>:\n\n\n```bash\nyarn add @carbon/react\n```\n\n## Getting started\n\nThe `@carbon/react` package provides components, styles and icons for the Carbon\nDesign System.\n\nComponents require the use of a build pipeline in your project. This could be in\nthe form of a bundler, framework, or other build tool. Some examples include\nNext.js, Vite, Parcel, and Webpack. A comprehensive list is available in the\n[react documentation](https://react.dev/learn/start-a-new-react-project).\n\nTo use a component, you can import it directly from the package:\n\n```js\nimport { Button } from '@carbon/react';\n\nfunction MyComponent() {\n return ;\n}\n```\n\nTo include the styles for a specific component, you can either import all the\nstyles from the project or include the styles for a specific component:\n\n```js\n// Bring in all the styles for Carbon in your root/global stylesheet\n@use '@carbon/react';\n\n// Or bring in the styles for one component\n@use '@carbon/react/scss/components/button';\n```\n\n### Icons\n\nThe @carbon/react package also provides icon components that you can include in\nyour project. You can import these icon components from the\n`@carbon/react/icons` entrypoint:\n\n```js\nimport { Add } from '@carbon/react/icons';\n\nfunction MyComponent() {\n return ;\n}\n```\n\nA full list of available icons is provided in the\n[icon library](/guidelines/icons/library/).\n\nFor a more in depth introduction to using `@carbon/react` in a webpack-based\napp, [check out our React tutorial](/developing/react-tutorial/overview/).\n\n## Development\n\nPlease refer to the\n[Contribution Guidelines](https://github.com/carbon-design-system/carbon/blob/v10/.github/CONTRIBUTING.md)\nbefore starting any work.\n\n### Using the server\n\nWe use [Storybook](https://github.com/storybookjs/storybook) for developing\ncomponents.\n\n Start the server: \n\n```bash\nyarn storybook\n```\n\n2. Open browser to `http://localhost:9000/`.\n\n3. Develop components in their respective folders (`/components` or\n `/internal`).\n\n4. Author stories within the `*.stories.js*` files.\n\n### List of available components\n\nView available React Components in\n[the `@carbon/react` storybook](http://react.carbondesignsystem.com). Usage\ninformation is available under the \"docs\" tab.\n\n## Troubleshooting\n\nIf you experience any issues while getting set up with Carbon Components React,\nplease head over to the\n[GitHub repo](https://github.com/carbon-design-system/carbon/tree/v10/packages/react)\nfor more guidelines and support. Please\n[create an issue](https://github.com/carbon-design-system/carbon/issues) if your\nissue does not already exist.\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/developing/frameworks/react.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/developing/frameworks/svelte/page-data.json b/page-data/developing/frameworks/svelte/page-data.json
index 229b3e2c908..ecbbddfeab1 100644
--- a/page-data/developing/frameworks/svelte/page-data.json
+++ b/page-data/developing/frameworks/svelte/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-developing-frameworks-svelte-mdx","path":"/developing/frameworks/svelte/","result":{"pageContext":{"frontmatter":{"title":"Frameworks","description":"The Carbon Design System is built React first, with official support for Web Components. We also support core parts of the system in Angular, vanilla JS, Vue, Svelte, and Lightning Web Components.","tabs":["React","Web Components","Angular","Vue","Svelte","LWC","Vanilla","Other frameworks"]},"relativePagePath":"/developing/frameworks/svelte.mdx","titleType":"prepend","MdxNode":{"id":"7e9f775e-c54a-55b6-a7af-4b10f43eca8a","children":[],"parent":"9dde4ec8-d623-5ca4-a9ef-49371b79ccdb","internal":{"content":"---\ntitle: Frameworks\ndescription:\n The Carbon Design System is built React first, with official support for Web\n Components. We also support core parts of the system in Angular, vanilla JS,\n Vue, Svelte, and Lightning Web Components.\ntabs:\n [\n 'React',\n 'Web Components',\n 'Angular',\n 'Vue',\n 'Svelte',\n 'LWC',\n 'Vanilla',\n 'Other frameworks',\n ]\n---\n\n\n\nThe library provides front-end developers & engineers a collection of reusable\nSvelte components to build websites and user interfaces. Adopting the library\nenables developers to use consistent markup, styles, and behavior in prototype\nand production work.\n\n\n\n\n\nThe Svelte library is maintained by members of the Carbon community. For\nsupport, contact the\n[Carbon Svelte team](https://github.com/IBM/carbon-components-svelte/issues/new).\n\n\n\n## Resources\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n\n## Development\n\nPlease refer to the\n[contributing guidelines](https://github.com/IBM/carbon-components-svelte/blob/master/CONTRIBUTING.md)\nbefore starting any work.\n","type":"Mdx","contentDigest":"a07679152cfce62680804b78043da373","owner":"gatsby-plugin-mdx","counter":5277},"frontmatter":{"title":"Frameworks","description":"The Carbon Design System is built React first, with official support for Web Components. We also support core parts of the system in Angular, vanilla JS, Vue, Svelte, and Lightning Web Components.","tabs":["React","Web Components","Angular","Vue","Svelte","LWC","Vanilla","Other frameworks"]},"exports":{},"rawBody":"---\ntitle: Frameworks\ndescription:\n The Carbon Design System is built React first, with official support for Web\n Components. We also support core parts of the system in Angular, vanilla JS,\n Vue, Svelte, and Lightning Web Components.\ntabs:\n [\n 'React',\n 'Web Components',\n 'Angular',\n 'Vue',\n 'Svelte',\n 'LWC',\n 'Vanilla',\n 'Other frameworks',\n ]\n---\n\n\n\nThe library provides front-end developers & engineers a collection of reusable\nSvelte components to build websites and user interfaces. Adopting the library\nenables developers to use consistent markup, styles, and behavior in prototype\nand production work.\n\n\n\n\n\nThe Svelte library is maintained by members of the Carbon community. For\nsupport, contact the\n[Carbon Svelte team](https://github.com/IBM/carbon-components-svelte/issues/new).\n\n\n\n## Resources\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n\n## Development\n\nPlease refer to the\n[contributing guidelines](https://github.com/IBM/carbon-components-svelte/blob/master/CONTRIBUTING.md)\nbefore starting any work.\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/developing/frameworks/svelte.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-developing-frameworks-svelte-mdx","path":"/developing/frameworks/svelte/","result":{"pageContext":{"frontmatter":{"title":"Frameworks","description":"The Carbon Design System is built React first, with official support for Web Components. We also support core parts of the system in Angular, vanilla JS, Vue, Svelte, and Lightning Web Components.","tabs":["React","Web Components","Angular","Vue","Svelte","LWC","Vanilla","Other frameworks"]},"relativePagePath":"/developing/frameworks/svelte.mdx","titleType":"prepend","MdxNode":{"id":"7e9f775e-c54a-55b6-a7af-4b10f43eca8a","children":[],"parent":"9dde4ec8-d623-5ca4-a9ef-49371b79ccdb","internal":{"content":"---\ntitle: Frameworks\ndescription:\n The Carbon Design System is built React first, with official support for Web\n Components. We also support core parts of the system in Angular, vanilla JS,\n Vue, Svelte, and Lightning Web Components.\ntabs:\n [\n 'React',\n 'Web Components',\n 'Angular',\n 'Vue',\n 'Svelte',\n 'LWC',\n 'Vanilla',\n 'Other frameworks',\n ]\n---\n\n\n\nThe library provides front-end developers & engineers a collection of reusable\nSvelte components to build websites and user interfaces. Adopting the library\nenables developers to use consistent markup, styles, and behavior in prototype\nand production work.\n\n\n\n\n\nThe Svelte library is maintained by members of the Carbon community. For\nsupport, contact the\n[Carbon Svelte team](https://github.com/IBM/carbon-components-svelte/issues/new).\n\n\n\n## Resources\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n\n## Development\n\nPlease refer to the\n[contributing guidelines](https://github.com/IBM/carbon-components-svelte/blob/master/CONTRIBUTING.md)\nbefore starting any work.\n","type":"Mdx","contentDigest":"a07679152cfce62680804b78043da373","owner":"gatsby-plugin-mdx","counter":5278},"frontmatter":{"title":"Frameworks","description":"The Carbon Design System is built React first, with official support for Web Components. We also support core parts of the system in Angular, vanilla JS, Vue, Svelte, and Lightning Web Components.","tabs":["React","Web Components","Angular","Vue","Svelte","LWC","Vanilla","Other frameworks"]},"exports":{},"rawBody":"---\ntitle: Frameworks\ndescription:\n The Carbon Design System is built React first, with official support for Web\n Components. We also support core parts of the system in Angular, vanilla JS,\n Vue, Svelte, and Lightning Web Components.\ntabs:\n [\n 'React',\n 'Web Components',\n 'Angular',\n 'Vue',\n 'Svelte',\n 'LWC',\n 'Vanilla',\n 'Other frameworks',\n ]\n---\n\n\n\nThe library provides front-end developers & engineers a collection of reusable\nSvelte components to build websites and user interfaces. Adopting the library\nenables developers to use consistent markup, styles, and behavior in prototype\nand production work.\n\n\n\n\n\nThe Svelte library is maintained by members of the Carbon community. For\nsupport, contact the\n[Carbon Svelte team](https://github.com/IBM/carbon-components-svelte/issues/new).\n\n\n\n## Resources\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n\n## Development\n\nPlease refer to the\n[contributing guidelines](https://github.com/IBM/carbon-components-svelte/blob/master/CONTRIBUTING.md)\nbefore starting any work.\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/developing/frameworks/svelte.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/developing/frameworks/vue/page-data.json b/page-data/developing/frameworks/vue/page-data.json
index 61ccd4d0b0a..1369744b12d 100644
--- a/page-data/developing/frameworks/vue/page-data.json
+++ b/page-data/developing/frameworks/vue/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-developing-frameworks-vue-mdx","path":"/developing/frameworks/vue/","result":{"pageContext":{"frontmatter":{"title":"Frameworks","description":"The Carbon Design System is built React first, with official support for Web Components. We also support core parts of the system in Angular, vanilla JS, Vue, Svelte, and Lightning Web Components.","tabs":["React","Web Components","Angular","Vue","Svelte","LWC","Vanilla","Other frameworks"]},"relativePagePath":"/developing/frameworks/vue.mdx","titleType":"prepend","MdxNode":{"id":"77b01671-3af7-5bbe-b480-2f1f61b118da","children":[],"parent":"84edc456-acf5-5361-b774-a297db92b717","internal":{"content":"---\ntitle: Frameworks\ndescription:\n The Carbon Design System is built React first, with official support for Web\n Components. We also support core parts of the system in Angular, vanilla JS,\n Vue, Svelte, and Lightning Web Components.\ntabs:\n [\n 'React',\n 'Web Components',\n 'Angular',\n 'Vue',\n 'Svelte',\n 'LWC',\n 'Vanilla',\n 'Other frameworks',\n ]\n---\n\n\n\nThe library provides front-end developers & engineers a collection of reusable\nVue components to build websites and user interfaces. Adopting the library\nenables developers to use consistent markup, styles, and behavior in prototype\nand production work.\n\n\n\n\n\nThe Vue library is maintained by members of the Carbon community. For support,\ncontact the\n[Carbon Vue team](https://github.com/carbon-design-system/carbon-components-vue/issues/new/choose).\n\n\n\n## Resources\n\n\n\n \n\n\n\n \n\n \n \n \n \n \n\n\n## Getting started\n\nAssuming we're starting with a new Vue CLI project:\n\n```bash\nnpm create vue@latest\ncd vue-project\n```\n\n```bash\nnpm install @carbon/vue\n```\n\nIn src/main.js, after `import App from './App.vue'`, add the following to\ninclude the carbon styles and components.\n\n```js\nimport 'carbon-components/css/carbon-components.css';\nimport CarbonComponentsVue from '@carbon/vue';\n\nconst app = createApp(App);\napp.use(CarbonComponentsVue);\napp.mount('#app');\n// remove the line: createApp(App).mount('#app')\n```\n\nReplace the contents of src/components/HelloWorld.vue with the following\n\n```html\n\n\n\n
\n
Example use of @carbon/vue
\n \n Hello {{yourName}}\n \n Welcome to @carbon/vue {{yourName}}\n \n
\n Lorem ipsum dolor sit amet, consectetur adipisicing elit, seed do\n eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad\n minim veniam, quis nostrud exercitation ullamco laboris nisi ut\n aliquip ex ea commodo consequat.\n
\n \n \n
\n\n\n\n```\n\nThat's it! Now start the server and start building.\n\n```bash\nnpm run dev\n```\n\n_Note: This isn't the only way to bootstrap a_ `carbon-components-vue`\n_application, but the combination of_ `Vue CLI` _and the_ `carbon-components`\n_scss is our recommended setup._ See\n[Hello carbon vue3](https://github.com/IBM/hello-carbon-vue3) for a complete\nexample app.\n\n### List of available components\n\nView available Vue Components [here](http://vue.carbondesignsystem.com). Usage\ninformation is available in the notes provided with each story.\n\n## Troubleshooting\n\nIf you experience any issues while getting set up with Carbon Components Vue,\nplease head over to the\n[GitHub repo](https://github.com/carbon-design-system/carbon-components-vue) for\nmore guidelines and support. Please\n[create an issue](https://github.com/carbon-design-system/carbon-components-vue/issues)\nif your issue does not already exist.\n","type":"Mdx","contentDigest":"a380c709c4c6b04d757662a82ec3ff1a","owner":"gatsby-plugin-mdx","counter":5281},"frontmatter":{"title":"Frameworks","description":"The Carbon Design System is built React first, with official support for Web Components. We also support core parts of the system in Angular, vanilla JS, Vue, Svelte, and Lightning Web Components.","tabs":["React","Web Components","Angular","Vue","Svelte","LWC","Vanilla","Other frameworks"]},"exports":{},"rawBody":"---\ntitle: Frameworks\ndescription:\n The Carbon Design System is built React first, with official support for Web\n Components. We also support core parts of the system in Angular, vanilla JS,\n Vue, Svelte, and Lightning Web Components.\ntabs:\n [\n 'React',\n 'Web Components',\n 'Angular',\n 'Vue',\n 'Svelte',\n 'LWC',\n 'Vanilla',\n 'Other frameworks',\n ]\n---\n\n\n\nThe library provides front-end developers & engineers a collection of reusable\nVue components to build websites and user interfaces. Adopting the library\nenables developers to use consistent markup, styles, and behavior in prototype\nand production work.\n\n\n\n\n\nThe Vue library is maintained by members of the Carbon community. For support,\ncontact the\n[Carbon Vue team](https://github.com/carbon-design-system/carbon-components-vue/issues/new/choose).\n\n\n\n## Resources\n\n\n\n \n\n\n\n \n\n \n \n \n \n \n\n\n## Getting started\n\nAssuming we're starting with a new Vue CLI project:\n\n```bash\nnpm create vue@latest\ncd vue-project\n```\n\n```bash\nnpm install @carbon/vue\n```\n\nIn src/main.js, after `import App from './App.vue'`, add the following to\ninclude the carbon styles and components.\n\n```js\nimport 'carbon-components/css/carbon-components.css';\nimport CarbonComponentsVue from '@carbon/vue';\n\nconst app = createApp(App);\napp.use(CarbonComponentsVue);\napp.mount('#app');\n// remove the line: createApp(App).mount('#app')\n```\n\nReplace the contents of src/components/HelloWorld.vue with the following\n\n```html\n\n\n\n
\n
Example use of @carbon/vue
\n \n Hello {{yourName}}\n \n Welcome to @carbon/vue {{yourName}}\n \n
\n Lorem ipsum dolor sit amet, consectetur adipisicing elit, seed do\n eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad\n minim veniam, quis nostrud exercitation ullamco laboris nisi ut\n aliquip ex ea commodo consequat.\n
\n \n \n
\n\n\n\n```\n\nThat's it! Now start the server and start building.\n\n```bash\nnpm run dev\n```\n\n_Note: This isn't the only way to bootstrap a_ `carbon-components-vue`\n_application, but the combination of_ `Vue CLI` _and the_ `carbon-components`\n_scss is our recommended setup._ See\n[Hello carbon vue3](https://github.com/IBM/hello-carbon-vue3) for a complete\nexample app.\n\n### List of available components\n\nView available Vue Components [here](http://vue.carbondesignsystem.com). Usage\ninformation is available in the notes provided with each story.\n\n## Troubleshooting\n\nIf you experience any issues while getting set up with Carbon Components Vue,\nplease head over to the\n[GitHub repo](https://github.com/carbon-design-system/carbon-components-vue) for\nmore guidelines and support. Please\n[create an issue](https://github.com/carbon-design-system/carbon-components-vue/issues)\nif your issue does not already exist.\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/developing/frameworks/vue.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-developing-frameworks-vue-mdx","path":"/developing/frameworks/vue/","result":{"pageContext":{"frontmatter":{"title":"Frameworks","description":"The Carbon Design System is built React first, with official support for Web Components. We also support core parts of the system in Angular, vanilla JS, Vue, Svelte, and Lightning Web Components.","tabs":["React","Web Components","Angular","Vue","Svelte","LWC","Vanilla","Other frameworks"]},"relativePagePath":"/developing/frameworks/vue.mdx","titleType":"prepend","MdxNode":{"id":"77b01671-3af7-5bbe-b480-2f1f61b118da","children":[],"parent":"84edc456-acf5-5361-b774-a297db92b717","internal":{"content":"---\ntitle: Frameworks\ndescription:\n The Carbon Design System is built React first, with official support for Web\n Components. We also support core parts of the system in Angular, vanilla JS,\n Vue, Svelte, and Lightning Web Components.\ntabs:\n [\n 'React',\n 'Web Components',\n 'Angular',\n 'Vue',\n 'Svelte',\n 'LWC',\n 'Vanilla',\n 'Other frameworks',\n ]\n---\n\n\n\nThe library provides front-end developers & engineers a collection of reusable\nVue components to build websites and user interfaces. Adopting the library\nenables developers to use consistent markup, styles, and behavior in prototype\nand production work.\n\n\n\n\n\nThe Vue library is maintained by members of the Carbon community. For support,\ncontact the\n[Carbon Vue team](https://github.com/carbon-design-system/carbon-components-vue/issues/new/choose).\n\n\n\n## Resources\n\n\n\n \n\n\n\n \n\n \n \n \n \n \n\n\n## Getting started\n\nAssuming we're starting with a new Vue CLI project:\n\n```bash\nnpm create vue@latest\ncd vue-project\n```\n\n```bash\nnpm install @carbon/vue\n```\n\nIn src/main.js, after `import App from './App.vue'`, add the following to\ninclude the carbon styles and components.\n\n```js\nimport 'carbon-components/css/carbon-components.css';\nimport CarbonComponentsVue from '@carbon/vue';\n\nconst app = createApp(App);\napp.use(CarbonComponentsVue);\napp.mount('#app');\n// remove the line: createApp(App).mount('#app')\n```\n\nReplace the contents of src/components/HelloWorld.vue with the following\n\n```html\n\n\n\n
\n
Example use of @carbon/vue
\n \n Hello {{yourName}}\n \n Welcome to @carbon/vue {{yourName}}\n \n
\n Lorem ipsum dolor sit amet, consectetur adipisicing elit, seed do\n eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad\n minim veniam, quis nostrud exercitation ullamco laboris nisi ut\n aliquip ex ea commodo consequat.\n
\n \n \n
\n\n\n\n```\n\nThat's it! Now start the server and start building.\n\n```bash\nnpm run dev\n```\n\n_Note: This isn't the only way to bootstrap a_ `carbon-components-vue`\n_application, but the combination of_ `Vue CLI` _and the_ `carbon-components`\n_scss is our recommended setup._ See\n[Hello carbon vue3](https://github.com/IBM/hello-carbon-vue3) for a complete\nexample app.\n\n### List of available components\n\nView available Vue Components [here](http://vue.carbondesignsystem.com). Usage\ninformation is available in the notes provided with each story.\n\n## Troubleshooting\n\nIf you experience any issues while getting set up with Carbon Components Vue,\nplease head over to the\n[GitHub repo](https://github.com/carbon-design-system/carbon-components-vue) for\nmore guidelines and support. Please\n[create an issue](https://github.com/carbon-design-system/carbon-components-vue/issues)\nif your issue does not already exist.\n","type":"Mdx","contentDigest":"a380c709c4c6b04d757662a82ec3ff1a","owner":"gatsby-plugin-mdx","counter":5280},"frontmatter":{"title":"Frameworks","description":"The Carbon Design System is built React first, with official support for Web Components. We also support core parts of the system in Angular, vanilla JS, Vue, Svelte, and Lightning Web Components.","tabs":["React","Web Components","Angular","Vue","Svelte","LWC","Vanilla","Other frameworks"]},"exports":{},"rawBody":"---\ntitle: Frameworks\ndescription:\n The Carbon Design System is built React first, with official support for Web\n Components. We also support core parts of the system in Angular, vanilla JS,\n Vue, Svelte, and Lightning Web Components.\ntabs:\n [\n 'React',\n 'Web Components',\n 'Angular',\n 'Vue',\n 'Svelte',\n 'LWC',\n 'Vanilla',\n 'Other frameworks',\n ]\n---\n\n\n\nThe library provides front-end developers & engineers a collection of reusable\nVue components to build websites and user interfaces. Adopting the library\nenables developers to use consistent markup, styles, and behavior in prototype\nand production work.\n\n\n\n\n\nThe Vue library is maintained by members of the Carbon community. For support,\ncontact the\n[Carbon Vue team](https://github.com/carbon-design-system/carbon-components-vue/issues/new/choose).\n\n\n\n## Resources\n\n\n\n \n\n\n\n \n\n \n \n \n \n \n\n\n## Getting started\n\nAssuming we're starting with a new Vue CLI project:\n\n```bash\nnpm create vue@latest\ncd vue-project\n```\n\n```bash\nnpm install @carbon/vue\n```\n\nIn src/main.js, after `import App from './App.vue'`, add the following to\ninclude the carbon styles and components.\n\n```js\nimport 'carbon-components/css/carbon-components.css';\nimport CarbonComponentsVue from '@carbon/vue';\n\nconst app = createApp(App);\napp.use(CarbonComponentsVue);\napp.mount('#app');\n// remove the line: createApp(App).mount('#app')\n```\n\nReplace the contents of src/components/HelloWorld.vue with the following\n\n```html\n\n\n\n
\n
Example use of @carbon/vue
\n \n Hello {{yourName}}\n \n Welcome to @carbon/vue {{yourName}}\n \n
\n Lorem ipsum dolor sit amet, consectetur adipisicing elit, seed do\n eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad\n minim veniam, quis nostrud exercitation ullamco laboris nisi ut\n aliquip ex ea commodo consequat.\n
\n \n \n
\n\n\n\n```\n\nThat's it! Now start the server and start building.\n\n```bash\nnpm run dev\n```\n\n_Note: This isn't the only way to bootstrap a_ `carbon-components-vue`\n_application, but the combination of_ `Vue CLI` _and the_ `carbon-components`\n_scss is our recommended setup._ See\n[Hello carbon vue3](https://github.com/IBM/hello-carbon-vue3) for a complete\nexample app.\n\n### List of available components\n\nView available Vue Components [here](http://vue.carbondesignsystem.com). Usage\ninformation is available in the notes provided with each story.\n\n## Troubleshooting\n\nIf you experience any issues while getting set up with Carbon Components Vue,\nplease head over to the\n[GitHub repo](https://github.com/carbon-design-system/carbon-components-vue) for\nmore guidelines and support. Please\n[create an issue](https://github.com/carbon-design-system/carbon-components-vue/issues)\nif your issue does not already exist.\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/developing/frameworks/vue.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/developing/frameworks/web-components/page-data.json b/page-data/developing/frameworks/web-components/page-data.json
index ea0aa04e2e8..560b2d3e8b9 100644
--- a/page-data/developing/frameworks/web-components/page-data.json
+++ b/page-data/developing/frameworks/web-components/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-developing-frameworks-web-components-mdx","path":"/developing/frameworks/web-components/","result":{"pageContext":{"frontmatter":{"title":"Frameworks","description":"The Carbon Design System is built React first, with official support for Web Components. We also support core parts of the system in Angular, vanilla JS, Vue, Svelte, and Lightning Web Components.","tabs":["React","Web Components","Angular","Vue","Svelte","LWC","Vanilla","Other frameworks"]},"relativePagePath":"/developing/frameworks/web-components.mdx","titleType":"prepend","MdxNode":{"id":"80fa9d98-e456-53aa-8adb-a53b8104e277","children":[],"parent":"69e5ac22-53a3-5d31-a57f-340656b5339f","internal":{"content":"---\ntitle: Frameworks\ndescription:\n The Carbon Design System is built React first, with official support for Web\n Components. We also support core parts of the system in Angular, vanilla JS,\n Vue, Svelte, and Lightning Web Components.\ntabs:\n [\n 'React',\n 'Web Components',\n 'Angular',\n 'Vue',\n 'Svelte',\n 'LWC',\n 'Vanilla',\n 'Other frameworks',\n ]\n---\n\n\n\nThe library provides front-end developers and engineers a collection of reusable\nweb components to build websites and user interfaces. Adopting the library\nenables developers to use consistent markup, styles, and behavior in prototype\nand production work.\n\nThis library uses Custom Elements v1 and Shadow DOM v1 specs.\n\n\n\n\n\nFor support, contact the\n[Carbon Web Components team](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues/new/choose).\n\nInfo on Carbon Web Components v1 can be found\n[here](https://v10.carbondesignsystem.com/developing/frameworks/web-components).\n\n\n\n## Resources\n\n\n\n \n\n\n\n \n\n \n \n \n \n \n\n\n## Getting started\n\n### Using CDN\n\n#### How to install\n\nAll components are available via CDN. This means that they can be added to your\napplication without the need of any bundler configuration. Each component is\navailable by the `latest` tag, or referencing a specific version (starting at\nversion `v1.16.0`):\n\n```html\n\n\n\n\n\n```\n\nThese are the list of available components via CDN:\n\n- accordion.min.js\n- breadcrumb.min.js\n- button.min.js\n- checkbox.min.js\n- code-snippet.min.js\n- combo-box.min.js\n- content-switcher.min.js\n- copy.min.js\n- copy-button.min.js\n- data-table.min.js\n- date-picker.min.js\n- dropdown.min.js\n- file-uploader.min.js\n- floating-menu.min.js\n- form.min.js\n- inline-loading.min.js\n- layer.min.js\n- link.min.js\n- list.min.js\n- loading.min.js\n- modal.min.js\n- multi-select.min.js\n- notification.min.js\n- number-input.min.js\n- overflow-menu.min.js\n- pagination.min.js\n- progress-indicator.min.js\n- radio-button.min.js\n- search.min.js\n- select.min.js\n- skeleton-placeholder.min.js\n- skeleton-text.min.js\n- skip-to-content.min.js\n- slider.min.js\n- structured-list.min.js\n- tabs.min.js\n- tag.min.js\n- text-input.min.js\n- textarea.min.js\n- tile.min.js\n- toggle.min.js\n- toggle-tip.min.js\n- tooltip.min.js\n- ui-shell.min.js\n\nTo use the right-to-left (RTL) version of the artifacts, change the file\nextention from `.min.js` to `.rtl.min.js`. For example:\n\n```html\n\n\n\n\n\n```\n\n#### Basic usage\n\nThe CDN artifacts define the custom elements for the browser, so they can be\ndirectly used once the script tag has been added to the page. For example:\n\n```html\n\n\n \n \n \n \n \n
\n \n Foo\n Bar\n Baz\n \n
\n \n\n```\n\nOur example at [CodeSandbox](https://codesandbox.io) shows usage with only CDN\nartifacts:\n\n[](https://codesandbox.io/s/github/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components/examples/codesandbox/cdn)\n\n### Using ES imports\n\n#### How to install\n\nTo install `@carbon/web-components` in your project, you will need to run the\nfollowing command using [npm](https://www.npmjs.com/):\n\n```bash\nnpm install -S @carbon/web-components\n```\n\nIf you prefer [Yarn](https://yarnpkg.com/en/), use the following command\ninstead:\n\n```bash\nyarn add @carbon/web-components\n```\n\n#### Basic usage\n\nOur example at [CodeSandbox](https://codesandbox.io) shows the most basic usage:\n\n[](https://codesandbox.io/s/github/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components/examples/codesandbox/basic)\n\nThe first thing you need to do is **set up a module bundler** to resolve\nECMAScript `import`s. The above example uses [Webpack](https://webpack.js.org)\nbut you can use other bundlers like [Rollup](https://rollupjs.org/) too.\n\nOnce you set up a module bundler, you can start importing our component modules,\nfor example:\n\n```javascript\nimport '@carbon/web-components/es/components/dropdown/index.js';\n```\n\nOnce you've imported the component modules, you can use our components in the\nsame manner as native HTML tags, for example:\n\n```html\n\n Foo\n Bar\n Baz\n\n```\n\n### List of available components\n\nView available web components\n[here](https://web-components.carbondesignsystem.com). Usage information is\navailable in the notes provided with each story.\n\n### JavaScript framework integration\n\nIn addition to the available web component versions of Carbon components, this\nlibrary also supports usage with JavaScript frameworks like Angular, React, and\nVue if the desire is to use instead of the pure framework versions of Carbon\ncomponents. Specifically for React, this library comes with a wrapper\nimplementation around the Carbon Web Components for more seamless integration\nwith your React application.\n\nThis is achievable since web components is the modern browser standard, and\nworks well with other front-end frameworks that exist in the application. In\nturn, this also comes with the benefits of encapsulation within the Shadow DOM.\n\n\n\n**Note:** The approaches above detail the usage of Carbon Web Components within\npopular JavaScript frameworks. The APIs are based on how the web components are\nused, and differ from its pure framework counterparts (Carbon React, Carbon\nAngular, Carbon Vue).\n\n\n\n## Troubleshooting\n\nIf you experience any issues while getting set up with Carbon Web Components,\nplease head over to the\n[GitHub repo](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components)\nfor more guidelines and support. Please\n[create an issue](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues)\nif your issue does not already exist.\n","type":"Mdx","contentDigest":"7e5f0e535eab8199e699ec606ad6ce7a","owner":"gatsby-plugin-mdx","counter":5282},"frontmatter":{"title":"Frameworks","description":"The Carbon Design System is built React first, with official support for Web Components. We also support core parts of the system in Angular, vanilla JS, Vue, Svelte, and Lightning Web Components.","tabs":["React","Web Components","Angular","Vue","Svelte","LWC","Vanilla","Other frameworks"]},"exports":{},"rawBody":"---\ntitle: Frameworks\ndescription:\n The Carbon Design System is built React first, with official support for Web\n Components. We also support core parts of the system in Angular, vanilla JS,\n Vue, Svelte, and Lightning Web Components.\ntabs:\n [\n 'React',\n 'Web Components',\n 'Angular',\n 'Vue',\n 'Svelte',\n 'LWC',\n 'Vanilla',\n 'Other frameworks',\n ]\n---\n\n\n\nThe library provides front-end developers and engineers a collection of reusable\nweb components to build websites and user interfaces. Adopting the library\nenables developers to use consistent markup, styles, and behavior in prototype\nand production work.\n\nThis library uses Custom Elements v1 and Shadow DOM v1 specs.\n\n\n\n\n\nFor support, contact the\n[Carbon Web Components team](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues/new/choose).\n\nInfo on Carbon Web Components v1 can be found\n[here](https://v10.carbondesignsystem.com/developing/frameworks/web-components).\n\n\n\n## Resources\n\n\n\n \n\n\n\n \n\n \n \n \n \n \n\n\n## Getting started\n\n### Using CDN\n\n#### How to install\n\nAll components are available via CDN. This means that they can be added to your\napplication without the need of any bundler configuration. Each component is\navailable by the `latest` tag, or referencing a specific version (starting at\nversion `v1.16.0`):\n\n```html\n\n\n\n\n\n```\n\nThese are the list of available components via CDN:\n\n- accordion.min.js\n- breadcrumb.min.js\n- button.min.js\n- checkbox.min.js\n- code-snippet.min.js\n- combo-box.min.js\n- content-switcher.min.js\n- copy.min.js\n- copy-button.min.js\n- data-table.min.js\n- date-picker.min.js\n- dropdown.min.js\n- file-uploader.min.js\n- floating-menu.min.js\n- form.min.js\n- inline-loading.min.js\n- layer.min.js\n- link.min.js\n- list.min.js\n- loading.min.js\n- modal.min.js\n- multi-select.min.js\n- notification.min.js\n- number-input.min.js\n- overflow-menu.min.js\n- pagination.min.js\n- progress-indicator.min.js\n- radio-button.min.js\n- search.min.js\n- select.min.js\n- skeleton-placeholder.min.js\n- skeleton-text.min.js\n- skip-to-content.min.js\n- slider.min.js\n- structured-list.min.js\n- tabs.min.js\n- tag.min.js\n- text-input.min.js\n- textarea.min.js\n- tile.min.js\n- toggle.min.js\n- toggle-tip.min.js\n- tooltip.min.js\n- ui-shell.min.js\n\nTo use the right-to-left (RTL) version of the artifacts, change the file\nextention from `.min.js` to `.rtl.min.js`. For example:\n\n```html\n\n\n\n\n\n```\n\n#### Basic usage\n\nThe CDN artifacts define the custom elements for the browser, so they can be\ndirectly used once the script tag has been added to the page. For example:\n\n```html\n\n\n \n \n \n \n \n
\n \n Foo\n Bar\n Baz\n \n
\n \n\n```\n\nOur example at [CodeSandbox](https://codesandbox.io) shows usage with only CDN\nartifacts:\n\n[](https://codesandbox.io/s/github/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components/examples/codesandbox/cdn)\n\n### Using ES imports\n\n#### How to install\n\nTo install `@carbon/web-components` in your project, you will need to run the\nfollowing command using [npm](https://www.npmjs.com/):\n\n```bash\nnpm install -S @carbon/web-components\n```\n\nIf you prefer [Yarn](https://yarnpkg.com/en/), use the following command\ninstead:\n\n```bash\nyarn add @carbon/web-components\n```\n\n#### Basic usage\n\nOur example at [CodeSandbox](https://codesandbox.io) shows the most basic usage:\n\n[](https://codesandbox.io/s/github/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components/examples/codesandbox/basic)\n\nThe first thing you need to do is **set up a module bundler** to resolve\nECMAScript `import`s. The above example uses [Webpack](https://webpack.js.org)\nbut you can use other bundlers like [Rollup](https://rollupjs.org/) too.\n\nOnce you set up a module bundler, you can start importing our component modules,\nfor example:\n\n```javascript\nimport '@carbon/web-components/es/components/dropdown/index.js';\n```\n\nOnce you've imported the component modules, you can use our components in the\nsame manner as native HTML tags, for example:\n\n```html\n\n Foo\n Bar\n Baz\n\n```\n\n### List of available components\n\nView available web components\n[here](https://web-components.carbondesignsystem.com). Usage information is\navailable in the notes provided with each story.\n\n### JavaScript framework integration\n\nIn addition to the available web component versions of Carbon components, this\nlibrary also supports usage with JavaScript frameworks like Angular, React, and\nVue if the desire is to use instead of the pure framework versions of Carbon\ncomponents. Specifically for React, this library comes with a wrapper\nimplementation around the Carbon Web Components for more seamless integration\nwith your React application.\n\nThis is achievable since web components is the modern browser standard, and\nworks well with other front-end frameworks that exist in the application. In\nturn, this also comes with the benefits of encapsulation within the Shadow DOM.\n\n\n\n**Note:** The approaches above detail the usage of Carbon Web Components within\npopular JavaScript frameworks. The APIs are based on how the web components are\nused, and differ from its pure framework counterparts (Carbon React, Carbon\nAngular, Carbon Vue).\n\n\n\n## Troubleshooting\n\nIf you experience any issues while getting set up with Carbon Web Components,\nplease head over to the\n[GitHub repo](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components)\nfor more guidelines and support. Please\n[create an issue](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues)\nif your issue does not already exist.\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/developing/frameworks/web-components.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-developing-frameworks-web-components-mdx","path":"/developing/frameworks/web-components/","result":{"pageContext":{"frontmatter":{"title":"Frameworks","description":"The Carbon Design System is built React first, with official support for Web Components. We also support core parts of the system in Angular, vanilla JS, Vue, Svelte, and Lightning Web Components.","tabs":["React","Web Components","Angular","Vue","Svelte","LWC","Vanilla","Other frameworks"]},"relativePagePath":"/developing/frameworks/web-components.mdx","titleType":"prepend","MdxNode":{"id":"80fa9d98-e456-53aa-8adb-a53b8104e277","children":[],"parent":"69e5ac22-53a3-5d31-a57f-340656b5339f","internal":{"content":"---\ntitle: Frameworks\ndescription:\n The Carbon Design System is built React first, with official support for Web\n Components. We also support core parts of the system in Angular, vanilla JS,\n Vue, Svelte, and Lightning Web Components.\ntabs:\n [\n 'React',\n 'Web Components',\n 'Angular',\n 'Vue',\n 'Svelte',\n 'LWC',\n 'Vanilla',\n 'Other frameworks',\n ]\n---\n\n\n\nThe library provides front-end developers and engineers a collection of reusable\nweb components to build websites and user interfaces. Adopting the library\nenables developers to use consistent markup, styles, and behavior in prototype\nand production work.\n\nThis library uses Custom Elements v1 and Shadow DOM v1 specs.\n\n\n\n\n\nFor support, contact the\n[Carbon Web Components team](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues/new/choose).\n\nInfo on Carbon Web Components v1 can be found\n[here](https://v10.carbondesignsystem.com/developing/frameworks/web-components).\n\n\n\n## Resources\n\n\n\n \n\n\n\n \n\n \n \n \n \n \n\n\n## Getting started\n\n### Using CDN\n\n#### How to install\n\nAll components are available via CDN. This means that they can be added to your\napplication without the need of any bundler configuration. Each component is\navailable by the `latest` tag, or referencing a specific version (starting at\nversion `v1.16.0`):\n\n```html\n\n\n\n\n\n```\n\nThese are the list of available components via CDN:\n\n- accordion.min.js\n- breadcrumb.min.js\n- button.min.js\n- checkbox.min.js\n- code-snippet.min.js\n- combo-box.min.js\n- content-switcher.min.js\n- copy.min.js\n- copy-button.min.js\n- data-table.min.js\n- date-picker.min.js\n- dropdown.min.js\n- file-uploader.min.js\n- floating-menu.min.js\n- form.min.js\n- inline-loading.min.js\n- layer.min.js\n- link.min.js\n- list.min.js\n- loading.min.js\n- modal.min.js\n- multi-select.min.js\n- notification.min.js\n- number-input.min.js\n- overflow-menu.min.js\n- pagination.min.js\n- progress-indicator.min.js\n- radio-button.min.js\n- search.min.js\n- select.min.js\n- skeleton-placeholder.min.js\n- skeleton-text.min.js\n- skip-to-content.min.js\n- slider.min.js\n- structured-list.min.js\n- tabs.min.js\n- tag.min.js\n- text-input.min.js\n- textarea.min.js\n- tile.min.js\n- toggle.min.js\n- toggle-tip.min.js\n- tooltip.min.js\n- ui-shell.min.js\n\nTo use the right-to-left (RTL) version of the artifacts, change the file\nextention from `.min.js` to `.rtl.min.js`. For example:\n\n```html\n\n\n\n\n\n```\n\n#### Basic usage\n\nThe CDN artifacts define the custom elements for the browser, so they can be\ndirectly used once the script tag has been added to the page. For example:\n\n```html\n\n\n \n \n \n \n \n
\n \n Foo\n Bar\n Baz\n \n
\n \n\n```\n\nOur example at [CodeSandbox](https://codesandbox.io) shows usage with only CDN\nartifacts:\n\n[](https://codesandbox.io/s/github/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components/examples/codesandbox/cdn)\n\n### Using ES imports\n\n#### How to install\n\nTo install `@carbon/web-components` in your project, you will need to run the\nfollowing command using [npm](https://www.npmjs.com/):\n\n```bash\nnpm install -S @carbon/web-components\n```\n\nIf you prefer [Yarn](https://yarnpkg.com/en/), use the following command\ninstead:\n\n```bash\nyarn add @carbon/web-components\n```\n\n#### Basic usage\n\nOur example at [CodeSandbox](https://codesandbox.io) shows the most basic usage:\n\n[](https://codesandbox.io/s/github/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components/examples/codesandbox/basic)\n\nThe first thing you need to do is **set up a module bundler** to resolve\nECMAScript `import`s. The above example uses [Webpack](https://webpack.js.org)\nbut you can use other bundlers like [Rollup](https://rollupjs.org/) too.\n\nOnce you set up a module bundler, you can start importing our component modules,\nfor example:\n\n```javascript\nimport '@carbon/web-components/es/components/dropdown/index.js';\n```\n\nOnce you've imported the component modules, you can use our components in the\nsame manner as native HTML tags, for example:\n\n```html\n\n Foo\n Bar\n Baz\n\n```\n\n### List of available components\n\nView available web components\n[here](https://web-components.carbondesignsystem.com). Usage information is\navailable in the notes provided with each story.\n\n### JavaScript framework integration\n\nIn addition to the available web component versions of Carbon components, this\nlibrary also supports usage with JavaScript frameworks like Angular, React, and\nVue if the desire is to use instead of the pure framework versions of Carbon\ncomponents. Specifically for React, this library comes with a wrapper\nimplementation around the Carbon Web Components for more seamless integration\nwith your React application.\n\nThis is achievable since web components is the modern browser standard, and\nworks well with other front-end frameworks that exist in the application. In\nturn, this also comes with the benefits of encapsulation within the Shadow DOM.\n\n\n\n**Note:** The approaches above detail the usage of Carbon Web Components within\npopular JavaScript frameworks. The APIs are based on how the web components are\nused, and differ from its pure framework counterparts (Carbon React, Carbon\nAngular, Carbon Vue).\n\n\n\n## Troubleshooting\n\nIf you experience any issues while getting set up with Carbon Web Components,\nplease head over to the\n[GitHub repo](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components)\nfor more guidelines and support. Please\n[create an issue](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues)\nif your issue does not already exist.\n","type":"Mdx","contentDigest":"7e5f0e535eab8199e699ec606ad6ce7a","owner":"gatsby-plugin-mdx","counter":5281},"frontmatter":{"title":"Frameworks","description":"The Carbon Design System is built React first, with official support for Web Components. We also support core parts of the system in Angular, vanilla JS, Vue, Svelte, and Lightning Web Components.","tabs":["React","Web Components","Angular","Vue","Svelte","LWC","Vanilla","Other frameworks"]},"exports":{},"rawBody":"---\ntitle: Frameworks\ndescription:\n The Carbon Design System is built React first, with official support for Web\n Components. We also support core parts of the system in Angular, vanilla JS,\n Vue, Svelte, and Lightning Web Components.\ntabs:\n [\n 'React',\n 'Web Components',\n 'Angular',\n 'Vue',\n 'Svelte',\n 'LWC',\n 'Vanilla',\n 'Other frameworks',\n ]\n---\n\n\n\nThe library provides front-end developers and engineers a collection of reusable\nweb components to build websites and user interfaces. Adopting the library\nenables developers to use consistent markup, styles, and behavior in prototype\nand production work.\n\nThis library uses Custom Elements v1 and Shadow DOM v1 specs.\n\n\n\n\n\nFor support, contact the\n[Carbon Web Components team](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues/new/choose).\n\nInfo on Carbon Web Components v1 can be found\n[here](https://v10.carbondesignsystem.com/developing/frameworks/web-components).\n\n\n\n## Resources\n\n\n\n \n\n\n\n \n\n \n \n \n \n \n\n\n## Getting started\n\n### Using CDN\n\n#### How to install\n\nAll components are available via CDN. This means that they can be added to your\napplication without the need of any bundler configuration. Each component is\navailable by the `latest` tag, or referencing a specific version (starting at\nversion `v1.16.0`):\n\n```html\n\n\n\n\n\n```\n\nThese are the list of available components via CDN:\n\n- accordion.min.js\n- breadcrumb.min.js\n- button.min.js\n- checkbox.min.js\n- code-snippet.min.js\n- combo-box.min.js\n- content-switcher.min.js\n- copy.min.js\n- copy-button.min.js\n- data-table.min.js\n- date-picker.min.js\n- dropdown.min.js\n- file-uploader.min.js\n- floating-menu.min.js\n- form.min.js\n- inline-loading.min.js\n- layer.min.js\n- link.min.js\n- list.min.js\n- loading.min.js\n- modal.min.js\n- multi-select.min.js\n- notification.min.js\n- number-input.min.js\n- overflow-menu.min.js\n- pagination.min.js\n- progress-indicator.min.js\n- radio-button.min.js\n- search.min.js\n- select.min.js\n- skeleton-placeholder.min.js\n- skeleton-text.min.js\n- skip-to-content.min.js\n- slider.min.js\n- structured-list.min.js\n- tabs.min.js\n- tag.min.js\n- text-input.min.js\n- textarea.min.js\n- tile.min.js\n- toggle.min.js\n- toggle-tip.min.js\n- tooltip.min.js\n- ui-shell.min.js\n\nTo use the right-to-left (RTL) version of the artifacts, change the file\nextention from `.min.js` to `.rtl.min.js`. For example:\n\n```html\n\n\n\n\n\n```\n\n#### Basic usage\n\nThe CDN artifacts define the custom elements for the browser, so they can be\ndirectly used once the script tag has been added to the page. For example:\n\n```html\n\n\n \n \n \n \n \n
\n \n Foo\n Bar\n Baz\n \n
\n \n\n```\n\nOur example at [CodeSandbox](https://codesandbox.io) shows usage with only CDN\nartifacts:\n\n[](https://codesandbox.io/s/github/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components/examples/codesandbox/cdn)\n\n### Using ES imports\n\n#### How to install\n\nTo install `@carbon/web-components` in your project, you will need to run the\nfollowing command using [npm](https://www.npmjs.com/):\n\n```bash\nnpm install -S @carbon/web-components\n```\n\nIf you prefer [Yarn](https://yarnpkg.com/en/), use the following command\ninstead:\n\n```bash\nyarn add @carbon/web-components\n```\n\n#### Basic usage\n\nOur example at [CodeSandbox](https://codesandbox.io) shows the most basic usage:\n\n[](https://codesandbox.io/s/github/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components/examples/codesandbox/basic)\n\nThe first thing you need to do is **set up a module bundler** to resolve\nECMAScript `import`s. The above example uses [Webpack](https://webpack.js.org)\nbut you can use other bundlers like [Rollup](https://rollupjs.org/) too.\n\nOnce you set up a module bundler, you can start importing our component modules,\nfor example:\n\n```javascript\nimport '@carbon/web-components/es/components/dropdown/index.js';\n```\n\nOnce you've imported the component modules, you can use our components in the\nsame manner as native HTML tags, for example:\n\n```html\n\n Foo\n Bar\n Baz\n\n```\n\n### List of available components\n\nView available web components\n[here](https://web-components.carbondesignsystem.com). Usage information is\navailable in the notes provided with each story.\n\n### JavaScript framework integration\n\nIn addition to the available web component versions of Carbon components, this\nlibrary also supports usage with JavaScript frameworks like Angular, React, and\nVue if the desire is to use instead of the pure framework versions of Carbon\ncomponents. Specifically for React, this library comes with a wrapper\nimplementation around the Carbon Web Components for more seamless integration\nwith your React application.\n\nThis is achievable since web components is the modern browser standard, and\nworks well with other front-end frameworks that exist in the application. In\nturn, this also comes with the benefits of encapsulation within the Shadow DOM.\n\n\n\n**Note:** The approaches above detail the usage of Carbon Web Components within\npopular JavaScript frameworks. The APIs are based on how the web components are\nused, and differ from its pure framework counterparts (Carbon React, Carbon\nAngular, Carbon Vue).\n\n\n\n## Troubleshooting\n\nIf you experience any issues while getting set up with Carbon Web Components,\nplease head over to the\n[GitHub repo](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components)\nfor more guidelines and support. Please\n[create an issue](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues)\nif your issue does not already exist.\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/developing/frameworks/web-components.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/developing/react-tutorial/faq/page-data.json b/page-data/developing/react-tutorial/faq/page-data.json
index 87af00f6f3f..aceda3a4d92 100644
--- a/page-data/developing/react-tutorial/faq/page-data.json
+++ b/page-data/developing/react-tutorial/faq/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-developing-react-tutorial-faq-mdx","path":"/developing/react-tutorial/faq/","result":{"pageContext":{"frontmatter":{"title":"FAQs","description":"Welcome to Carbon! This tutorial will guide you in creating a React app using Next.js with the Carbon Design System.","tabs":["Overview","Step 1","Step 2","Step 3","Step 4","Step 5","Wrapping up","FAQ"]},"relativePagePath":"/developing/react-tutorial/faq.mdx","titleType":"prepend","MdxNode":{"id":"8c34cd13-e861-54a2-9c98-c16bb5f57d2b","children":[],"parent":"8e78702f-c384-5415-8e3e-dcd13ec51bcc","internal":{"content":"---\ntitle: FAQs\ndescription:\n Welcome to Carbon! This tutorial will guide you in creating a React app using\n Next.js with the Carbon Design System.\ntabs:\n [\n 'Overview',\n 'Step 1',\n 'Step 2',\n 'Step 3',\n 'Step 4',\n 'Step 5',\n 'Wrapping up',\n 'FAQ',\n ]\n---\n\n### I am getting an error that says `yarn lockfile missing`. How do I fix this?\n\n- This error can occur when the `yarn.lock` file is either missing or differs\n from the one used in the tutorial step. To fix this, you can go to the GitHub\n branch for the step you are on, find the `yarn.lock` file, and copy that file\n into your working directory. You may need to delete your `node_modules` folder\n and run `yarn` afterwards.\n\n### I am getting a `yarn offline cache` error. How do I fix this?\n\n- Try running\n `rm -rf .yarn-offline-mirror node_modules && yarn cache clean && yarn install`\n and push up any changes. If this still does not work, ensure your `yarn.lock`\n file matches the one at the start of the tutorial step\n\n### How can I show others my completion status?\n\n- Proof of your completion of the tutorial can be seen by filtering the PR list\n to show your five PRs with the `status: approved` label.\n\n- You can filter the pull request list to show only pull requests authored by\n your username. Replace `YOURUSERNAMEHERE` with your username in the following\n link:\n\n - https://github.com/carbon-design-system/carbon-tutorial-nextjs/pulls?q=author%3AYOURUSERNAMEHERE\n\n- It can also be demonstrated by deploying your app. Please see further\n documentation\n [here](/developing/react-tutorial/step-5#build-for-production-and-deploy).\n","type":"Mdx","contentDigest":"eff9ff83434bea2a9a0455bb9909c227","owner":"gatsby-plugin-mdx","counter":5280},"frontmatter":{"title":"FAQs","description":"Welcome to Carbon! This tutorial will guide you in creating a React app using Next.js with the Carbon Design System.","tabs":["Overview","Step 1","Step 2","Step 3","Step 4","Step 5","Wrapping up","FAQ"]},"exports":{},"rawBody":"---\ntitle: FAQs\ndescription:\n Welcome to Carbon! This tutorial will guide you in creating a React app using\n Next.js with the Carbon Design System.\ntabs:\n [\n 'Overview',\n 'Step 1',\n 'Step 2',\n 'Step 3',\n 'Step 4',\n 'Step 5',\n 'Wrapping up',\n 'FAQ',\n ]\n---\n\n### I am getting an error that says `yarn lockfile missing`. How do I fix this?\n\n- This error can occur when the `yarn.lock` file is either missing or differs\n from the one used in the tutorial step. To fix this, you can go to the GitHub\n branch for the step you are on, find the `yarn.lock` file, and copy that file\n into your working directory. You may need to delete your `node_modules` folder\n and run `yarn` afterwards.\n\n### I am getting a `yarn offline cache` error. How do I fix this?\n\n- Try running\n `rm -rf .yarn-offline-mirror node_modules && yarn cache clean && yarn install`\n and push up any changes. If this still does not work, ensure your `yarn.lock`\n file matches the one at the start of the tutorial step\n\n### How can I show others my completion status?\n\n- Proof of your completion of the tutorial can be seen by filtering the PR list\n to show your five PRs with the `status: approved` label.\n\n- You can filter the pull request list to show only pull requests authored by\n your username. Replace `YOURUSERNAMEHERE` with your username in the following\n link:\n\n - https://github.com/carbon-design-system/carbon-tutorial-nextjs/pulls?q=author%3AYOURUSERNAMEHERE\n\n- It can also be demonstrated by deploying your app. Please see further\n documentation\n [here](/developing/react-tutorial/step-5#build-for-production-and-deploy).\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/developing/react-tutorial/faq.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-developing-react-tutorial-faq-mdx","path":"/developing/react-tutorial/faq/","result":{"pageContext":{"frontmatter":{"title":"FAQs","description":"Welcome to Carbon! This tutorial will guide you in creating a React app using Next.js with the Carbon Design System.","tabs":["Overview","Step 1","Step 2","Step 3","Step 4","Step 5","Wrapping up","FAQ"]},"relativePagePath":"/developing/react-tutorial/faq.mdx","titleType":"prepend","MdxNode":{"id":"8c34cd13-e861-54a2-9c98-c16bb5f57d2b","children":[],"parent":"8e78702f-c384-5415-8e3e-dcd13ec51bcc","internal":{"content":"---\ntitle: FAQs\ndescription:\n Welcome to Carbon! This tutorial will guide you in creating a React app using\n Next.js with the Carbon Design System.\ntabs:\n [\n 'Overview',\n 'Step 1',\n 'Step 2',\n 'Step 3',\n 'Step 4',\n 'Step 5',\n 'Wrapping up',\n 'FAQ',\n ]\n---\n\n### I am getting an error that says `yarn lockfile missing`. How do I fix this?\n\n- This error can occur when the `yarn.lock` file is either missing or differs\n from the one used in the tutorial step. To fix this, you can go to the GitHub\n branch for the step you are on, find the `yarn.lock` file, and copy that file\n into your working directory. You may need to delete your `node_modules` folder\n and run `yarn` afterwards.\n\n### I am getting a `yarn offline cache` error. How do I fix this?\n\n- Try running\n `rm -rf .yarn-offline-mirror node_modules && yarn cache clean && yarn install`\n and push up any changes. If this still does not work, ensure your `yarn.lock`\n file matches the one at the start of the tutorial step\n\n### How can I show others my completion status?\n\n- Proof of your completion of the tutorial can be seen by filtering the PR list\n to show your five PRs with the `status: approved` label.\n\n- You can filter the pull request list to show only pull requests authored by\n your username. Replace `YOURUSERNAMEHERE` with your username in the following\n link:\n\n - https://github.com/carbon-design-system/carbon-tutorial-nextjs/pulls?q=author%3AYOURUSERNAMEHERE\n\n- It can also be demonstrated by deploying your app. Please see further\n documentation\n [here](/developing/react-tutorial/step-5#build-for-production-and-deploy).\n","type":"Mdx","contentDigest":"eff9ff83434bea2a9a0455bb9909c227","owner":"gatsby-plugin-mdx","counter":5282},"frontmatter":{"title":"FAQs","description":"Welcome to Carbon! This tutorial will guide you in creating a React app using Next.js with the Carbon Design System.","tabs":["Overview","Step 1","Step 2","Step 3","Step 4","Step 5","Wrapping up","FAQ"]},"exports":{},"rawBody":"---\ntitle: FAQs\ndescription:\n Welcome to Carbon! This tutorial will guide you in creating a React app using\n Next.js with the Carbon Design System.\ntabs:\n [\n 'Overview',\n 'Step 1',\n 'Step 2',\n 'Step 3',\n 'Step 4',\n 'Step 5',\n 'Wrapping up',\n 'FAQ',\n ]\n---\n\n### I am getting an error that says `yarn lockfile missing`. How do I fix this?\n\n- This error can occur when the `yarn.lock` file is either missing or differs\n from the one used in the tutorial step. To fix this, you can go to the GitHub\n branch for the step you are on, find the `yarn.lock` file, and copy that file\n into your working directory. You may need to delete your `node_modules` folder\n and run `yarn` afterwards.\n\n### I am getting a `yarn offline cache` error. How do I fix this?\n\n- Try running\n `rm -rf .yarn-offline-mirror node_modules && yarn cache clean && yarn install`\n and push up any changes. If this still does not work, ensure your `yarn.lock`\n file matches the one at the start of the tutorial step\n\n### How can I show others my completion status?\n\n- Proof of your completion of the tutorial can be seen by filtering the PR list\n to show your five PRs with the `status: approved` label.\n\n- You can filter the pull request list to show only pull requests authored by\n your username. Replace `YOURUSERNAMEHERE` with your username in the following\n link:\n\n - https://github.com/carbon-design-system/carbon-tutorial-nextjs/pulls?q=author%3AYOURUSERNAMEHERE\n\n- It can also be demonstrated by deploying your app. Please see further\n documentation\n [here](/developing/react-tutorial/step-5#build-for-production-and-deploy).\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/developing/react-tutorial/faq.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/developing/react-tutorial/step-3/page-data.json b/page-data/developing/react-tutorial/step-3/page-data.json
index d2024640f72..e1d032d7c2c 100644
--- a/page-data/developing/react-tutorial/step-3/page-data.json
+++ b/page-data/developing/react-tutorial/step-3/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-developing-react-tutorial-step-3-mdx","path":"/developing/react-tutorial/step-3/","result":{"pageContext":{"frontmatter":{"title":"3. Using APIs","description":"Welcome to Carbon! This tutorial will guide you in creating a React app using Next.js with the Carbon Design System.","tabs":["Overview","Step 1","Step 2","Step 3","Step 4","Step 5","Wrapping up","FAQ"]},"relativePagePath":"/developing/react-tutorial/step-3.mdx","titleType":"prepend","MdxNode":{"id":"eda9fc2a-eade-572d-98dd-8ef839e770bd","children":[],"parent":"e313048c-3ecc-5af7-bc7f-a9bc46f9924c","internal":{"content":"---\ntitle: 3. Using APIs\ndescription:\n Welcome to Carbon! This tutorial will guide you in creating a React app using\n Next.js with the Carbon Design System.\ntabs:\n [\n 'Overview',\n 'Step 1',\n 'Step 2',\n 'Step 3',\n 'Step 4',\n 'Step 5',\n 'Wrapping up',\n 'FAQ',\n ]\n---\n\nimport Preview from 'components/Preview';\n\n\n\nThis step takes our static components and populates them with data from the\nGitHub GraphQL API – loading states and all. We'll be displaying Carbon\nrepository information in a data table.\n\n\n\n\n\nFork, clone and branch\nInstall dependencies\nFetch data\nPopulate data table\nAdd loading\nAdd pagination\nSubmit pull request\n\n\n\n### Preview\n\nThe [GitHub REST API](https://docs.github.com/en/rest?apiVersion=2022-11-28) is\nvery well documented, we'll use it to fetch Carbon-related data for this Carbon\ntutorial.\n\nTo do so, we'll be using\n[Octokit Core](https://github.com/octokit/core.js/#readme), a client that makes\nit easy to interact with GitHub's APIs.\n\nA\n[preview](https://carbon-tutorial-nextjs-git-v11-next-step-4-carbon-design-system.vercel.app/)\nof what you will build (see repositories page):\n\n\n\n## Fork, clone and branch\n\nThis tutorial has an accompanying GitHub repository called\n[carbon-tutorial-nextjs](https://github.com/carbon-design-system/carbon-tutorial-nextjs)\nthat we'll use as a starting point for each step. If you haven't forked and\ncloned that repository yet, and haven't added the upstream remote, go ahead and\ndo so by following the\n[step 1 instructions](/developing/react-tutorial/step-1#fork-clone-and-branch).\n\n### Branch\n\nWith your repository all set up, let's check out the branch for this tutorial\nstep's starting point.\n\n```bash\ngit fetch upstream\ngit checkout -b v11-next-step-3 upstream/v11-next-step-3\n```\n\n### Build and start app\n\nInstall the app's dependencies and build the app:\n\n```bash\nyarn && yarn build\n```\n\nThen, start the app:\n\n```bash\nyarn start\n```\n\nYou should see something similar to where the\n[previous step](/developing/react-tutorial/step-2) left off. Stop your app with\n`CTRL-C` and let's get everything installed.\n\n## Install dependencies\n\nWe'll need to install `@octokit/core`, a package that allows us to query GitHub\nAPIs easily. Stop your development server with `CTRL-C` and install the octokit\ndependency with:\n\n```bash\nyarn add @octokit/core@4.2.0\n```\n\nThen, start the app again. If your app's currently running, you'll need to\nrestart it.\n\n```bash\nyarn dev\n```\n\n## Fetch data\n\n### Imports\n\nWe'll be using [React Hooks](https://reactjs.org/docs/hooks-intro.html) to call\na function to fetch our data when the component renders.\n\nImport React's [useEffect](https://reactjs.org/docs/hooks-effect.html) by\nmodifying the `React` import in `src/app/repos/page.js`.\n\n```javascript path=src/app/repos/page.js\nimport React, { useEffect } from 'react';\n```\n\nAdd the following import below the react import in `RepoPage`:\n\n```javascript path=src/app/repos/page.js\nimport { Octokit } from '@octokit/core';\n```\n\n### Initializing Octokit client\n\nDirectly below all your imports, initialize an octokit client which we'll use to\nquery our `RepoTable` data:\n\n```javascript path=src/app/repos/page.js\nconst octokitClient = new Octokit({});\n```\n\n### API Request\n\nNext, we'll assemble our GitHub API request to fetch a list of repositories that\nbelong to the `carbon-design-system` GitHub organization. We'll do this by using\na `useEffect` hook that will use octokit to query GitHub's API\n[repositories endpoint](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#list-organization-repositories).\n\nLet's declare a `useEffect` hook immediately below the component definition and\nabove the return. We'll use this to query GitHub's API when the component first\nrenders:\n\n```javascript path=src/app/repos/page.js\nfunction RepoPage() {\n useEffect(() => {\n async function getCarbonRepos() {\n const res = await octokitClient.request('GET /orgs/{org}/repos', {\n org: 'carbon-design-system',\n per_page: 75,\n sort: 'updated',\n direction: 'desc',\n });\n\n if (res.status === 200) {\n console.log(res.data);\n } else {\n console.log('Error obtaining repository data');\n }\n }\n\n getCarbonRepos();\n }, []);\n```\n\nAt this point, if you navigate to the Repositories page `/repos` in your running\napp and view your browser's console (e.g.\n[Chrome DevTools](https://developer.chrome.com/docs/devtools/)), you should see\nthe response from GitHub!\n\n### Helpers\n\nOur last column in the data table will be a comma-separated list of repository\nand home page links, so let's create a component called `LinkList`.\n\nImport `Link` at the top of `/app/repos/page.js`. The imports should look like\nthis.\n\n```javascript path=src/app/repos/page.js\nimport { Link, Grid, Column } from '@carbon/react';\n```\n\nThen use `Link` in this component. It has two props (`url` and `homepageUrl`)\nand returns an unordered list. If the repository does not have a home page URL,\nonly render the repository link.\n\n```javascript path=src/app/repos/page.js\nconst LinkList = ({ url, homepageUrl }) => (\n
\n
\n GitHub\n
\n {homepageUrl && (\n
\n | \n Homepage\n
\n )}\n
\n);\n```\n\nAs a final helper, let's create a function that transforms row data to our\nexpected header keys. Notice how we're using our new `LinkList` component to\ngenerate the value of the `links` key in each row.\n\n```javascript path=src/app/repos/page.js\nconst getRowItems = (rows) =>\n rows.map((row) => ({\n ...row,\n key: row.id,\n stars: row.stargazers_count,\n issueCount: row.open_issues_count,\n createdAt: new Date(row.created_at).toLocaleDateString(),\n updatedAt: new Date(row.updated_at).toLocaleDateString(),\n links: ,\n }));\n```\n\n### Populate data table\n\nNow that we have our data, let's dispose of our dummy `rows` and populate the\ndata table with real data.\n\nFirst, towards the top of `RepoPage` delete the `rows` array because we no\nlonger need the example rows.\n\nNext, let's add a couple variables that will help us store useful information\nwhen fetching the data and keep track of the loading state.\n\nWe'll be using [React Hooks](https://reactjs.org/docs/hooks-intro.html) again to\nmanage our state.\n\nImport React's [useState](https://reactjs.org/docs/hooks-state.html) by\nmodifying the `React` import.\n\n```javascript path=src/app/repos/page.js\nimport React, { useEffect, useState } from 'react';\n```\n\nThen, inside the `RepoPage` component:\n\n```javascript path=src/app/repos/page.js\nfunction RepoPage() {\n const [loading, setLoading] = useState(true);\n const [error, setError] = useState();\n const [rows, setRows] = useState([]);\n```\n\nNow, instead of using `console.log` to log the github data response, let's treat\nthe response data by passing it through our `getRowItems` helper and saving the\nresult in our new `rows` variable. Replace the `console.log(res.data);` line\ninside `if (res.status === 200)` with:\n\n```javascript path=src/app/repos/page.js\nsetRows(getRowItems(res.data));\n```\n\nLet's also replace our error log line inside the `else` statement with:\n\n```javascript path=src/app/repos/page.js\nsetError('Error obtaining repository data');\n```\n\nTo complete our `getCarbonRepos` function, let's set the loading state to false\nright after the `else` statement:\n\n```javascript path=src/app/repos/page.js\nif (res.status === 200) {\n setRows(getRowItems(res.data));\n} else {\n setError('Error obtaining repository data');\n}\nsetLoading(false);\n```\n\nFinally, let's modify our component's `return()` statement to display different\ninformation depending on the states of our request: loading, error or complete.\nReplace the current return statement with:\n\n```javascript path=src/app/repos/page.js\nif (loading) {\n return 'Loading...';\n}\n\nif (error) {\n return `Error! ${error}`;\n}\n\n// If we're here, we've got our data!\nreturn (\n \n \n \n \n \n);\n```\n\n### Render repository descriptions\n\nThe data table component and its pieces use a common React pattern called\n[render props](https://reactjs.org/docs/render-props.html). This is a really\npowerful way for libraries to give developers control of rendering and\nmanipulating their data.\n\nRevisiting `RepoTable.js`, we are already passing in our row objects along with\nheaders for each column. The `render` prop is being used to tell the data table\nhow to render the headers and rows. That prop takes a function that receives the\nprocessed headers and rows as arguments as well as some helper functions for\nrendering the table.\n\nOne common hurdle with the data table is how to access data that might not\ncorrespond with a table column but is needed to compute the value of a cell that\ndoes. The data table component processes and controls only the row properties\nwhich corresponds to headers (columns). Because of this, the `rows` object you\nget access to in the render prop function is _different_ than the one you passed\nin to the `rows` prop.\n\nWe need to modify one aspect of the data table because if you expand a row, it\nsays `Row description`. We want to update that with the repository description\ncoming from the GitHub API. This is an example of where we need a simple look-up\nfunction to find the data we care about - data that does not directly correspond\nto a column.\n\nTo do so, in `RepoTable.js`, add this look-up function as the first lines inside\nthe `RepoTable`. This should go immediately before the component's `return()`.\n\n```javascript path=src/app/repos/RepoTable.js\nconst getRowDescription = (rowId) => {\n const row = rows.find(({ id }) => id === rowId);\n return row ? row.description : '';\n};\n```\n\nFinally, in `RepoTable.js`, replace `
\n```\n\n## Add loading\n\nAt this point, the first time that you visit the repositories page, we're\nquerying the GitHub API and rendering the response through the `DataTable`\ncomponent. We could stop here, but there's more to be done! Let's replace the\n`Loading...` string with the\n[DataTableSkeleton component](https://react.carbondesignsystem.com/?path=/story/components-datatable--skeleton).\n\nTo do so, back to `RepoPage`, add the `DataTableSkeleton` import by modifying\nthe existing `@carbon/react` import.\n\n```javascript path=src/app/repos/page.js\nimport { Link, DataTableSkeleton, Grid, Column } from '@carbon/react';\n```\n\nThen replace the `if (loading) return 'Loading...';` with:\n\n```javascript path=src/app/repos/page.js\nif (loading) {\n return (\n \n \n \n \n \n );\n}\n```\n\nWe need to tell the loading skeleton how many rows to render, so let's use 10\nskeleton rows to prepare for the next enhancement...\n\n## Add pagination\n\nPagination! Instead of rendering every repository, let's add pagination to the\ndata table to only render 10 at a time. Depending on your specific requirements,\nyou may need to fetch new data each time that you interact with the pagination\ncomponent, but for simplicity, we're going to make one request to fetch all\ndata, and then paginate the in-memory row data.\n\nInitialize the new state variables that we'll use for pagination as the first\nlines inside the `RepoPage`.\n\n```javascript path=src/app/repos/page.js\nfunction RepoPage() {\n const [firstRowIndex, setFirstRowIndex] = useState(0);\n const [currentPageSize, setCurrentPageSize] = useState(10);\n...\n```\n\nThis initializes the total number of rows and the index of the first row to `0`,\nand the page size to `10` as we also specified in our loading skeleton.\n\nThen we need to update our `RepoTable` `rows` prop to only render the subset of\nrows for the current \"page\". Update\n`` to:\n\n```javascript path=src/app/repos/page.js\n\n```\n\n\n\n**Note:** We only pass the rows that we want our table to display. We can do\nthis by slicing the array of rows depending on the first item and the page size.\n\n\n\nFinally, let's add the `Pagination` to update our state variables and cause the\ndata table to render new rows.\n\nImport `Pagination` by updating the `@carbon/react` import.\n\n```javascript path=src/app/repos/page.js\nimport {\n Link,\n DataTableSkeleton,\n Pagination,\n Grid,\n Column,\n} from '@carbon/react';\n```\n\nImmediately after the `RepoTable` closing tag (`/>`), add the `Pagination`\ncomponent using the state variables that we previously initialized.\n\n```javascript path=src/app/repos/page.js\n {\n if (pageSize !== currentPageSize) {\n setCurrentPageSize(pageSize);\n }\n setFirstRowIndex(pageSize * (page - 1));\n }}\n/>\n```\n\n\n\n**Note:** The `Pagination` component isn't inherently connected in any way to\nthe `DataTable` - we need to tell it what to do when a change occurs using the\n`onChange` prop. This includes both page size changes and displaying different\nrows.\n\n\n\n\n\n**Note:** Like the other Carbon React components, `Pagination` component\nexamples can be found in\n[Storybook](https://react.carbondesignsystem.com/?path=/story/components-pagination--pagination)\nby browsing the story and knobs.\n\n\n\nThat does it! Your data table should fetch GitHub data on first render. You can\nexpand each row to see the repository's description. You can modify the\npagination items per page and cycle through pages or jump to a specific page of\nrepositories.\n\n## Submit pull request\n\nWe're going to submit a pull request to verify completion of this tutorial step.\n\n### Continuous integration (CI) check\n\nRun the CI check to make sure we're all set to submit a pull request.\n\n```bash\nyarn ci-check\n```\n\n\n\n**Note:** Having issues running the CI check?\n[Step 1]()\nhas troubleshooting notes that may help.\n\n\n\n### Git commit and push\n\nBefore we can create a pull request, format your code, then stage and commit all\nof your changes:\n\n```bash\nyarn format\ngit add --all && git commit -m \"feat(tutorial): complete step 3\"\n```\n\nThen, push to your repository:\n\n```bash\ngit push origin v11-next-step-3\n```\n\n\n\n**Note:** Having issues pushing your changes?\n[Step 1](/developing/react-tutorial/step-1#git-commit-and-push) has\ntroubleshooting notes that may help.\n\n\n\n### Pull request (PR)\n\nFinally, visit\n[carbon-tutorial-nextjs](https://github.com/carbon-design-system/carbon-tutorial-nextjs)\nto \"Compare & pull request\". In doing so, make sure that you are comparing to\n`v11-next-step-3` into `base: v11-next-step-3`.\n\n\n\n**Note:** Expect your tutorial step PRs to be reviewed by the Carbon team but\nnot merged. We'll close your PR so we can keep the repository's remote branches\npristine and ready for the next person!\n\n\n\n\n\n**Note:** If your PR fails the CircleCI test with the error\n`Can't make a request in offline mode`, try running the following command:\n`rm -rf .yarn-offline-mirror node_modules && yarn cache clean && yarn install`.\nAdd and commit the changes once this completes, and try pushing again.\n\n\n","type":"Mdx","contentDigest":"f397d3dbba2c6d67ab4728660c1169aa","owner":"gatsby-plugin-mdx","counter":5287},"frontmatter":{"title":"3. Using APIs","description":"Welcome to Carbon! This tutorial will guide you in creating a React app using Next.js with the Carbon Design System.","tabs":["Overview","Step 1","Step 2","Step 3","Step 4","Step 5","Wrapping up","FAQ"]},"exports":{},"rawBody":"---\ntitle: 3. Using APIs\ndescription:\n Welcome to Carbon! This tutorial will guide you in creating a React app using\n Next.js with the Carbon Design System.\ntabs:\n [\n 'Overview',\n 'Step 1',\n 'Step 2',\n 'Step 3',\n 'Step 4',\n 'Step 5',\n 'Wrapping up',\n 'FAQ',\n ]\n---\n\nimport Preview from 'components/Preview';\n\n\n\nThis step takes our static components and populates them with data from the\nGitHub GraphQL API – loading states and all. We'll be displaying Carbon\nrepository information in a data table.\n\n\n\n\n\nFork, clone and branch\nInstall dependencies\nFetch data\nPopulate data table\nAdd loading\nAdd pagination\nSubmit pull request\n\n\n\n### Preview\n\nThe [GitHub REST API](https://docs.github.com/en/rest?apiVersion=2022-11-28) is\nvery well documented, we'll use it to fetch Carbon-related data for this Carbon\ntutorial.\n\nTo do so, we'll be using\n[Octokit Core](https://github.com/octokit/core.js/#readme), a client that makes\nit easy to interact with GitHub's APIs.\n\nA\n[preview](https://carbon-tutorial-nextjs-git-v11-next-step-4-carbon-design-system.vercel.app/)\nof what you will build (see repositories page):\n\n\n\n## Fork, clone and branch\n\nThis tutorial has an accompanying GitHub repository called\n[carbon-tutorial-nextjs](https://github.com/carbon-design-system/carbon-tutorial-nextjs)\nthat we'll use as a starting point for each step. If you haven't forked and\ncloned that repository yet, and haven't added the upstream remote, go ahead and\ndo so by following the\n[step 1 instructions](/developing/react-tutorial/step-1#fork-clone-and-branch).\n\n### Branch\n\nWith your repository all set up, let's check out the branch for this tutorial\nstep's starting point.\n\n```bash\ngit fetch upstream\ngit checkout -b v11-next-step-3 upstream/v11-next-step-3\n```\n\n### Build and start app\n\nInstall the app's dependencies and build the app:\n\n```bash\nyarn && yarn build\n```\n\nThen, start the app:\n\n```bash\nyarn start\n```\n\nYou should see something similar to where the\n[previous step](/developing/react-tutorial/step-2) left off. Stop your app with\n`CTRL-C` and let's get everything installed.\n\n## Install dependencies\n\nWe'll need to install `@octokit/core`, a package that allows us to query GitHub\nAPIs easily. Stop your development server with `CTRL-C` and install the octokit\ndependency with:\n\n```bash\nyarn add @octokit/core@4.2.0\n```\n\nThen, start the app again. If your app's currently running, you'll need to\nrestart it.\n\n```bash\nyarn dev\n```\n\n## Fetch data\n\n### Imports\n\nWe'll be using [React Hooks](https://reactjs.org/docs/hooks-intro.html) to call\na function to fetch our data when the component renders.\n\nImport React's [useEffect](https://reactjs.org/docs/hooks-effect.html) by\nmodifying the `React` import in `src/app/repos/page.js`.\n\n```javascript path=src/app/repos/page.js\nimport React, { useEffect } from 'react';\n```\n\nAdd the following import below the react import in `RepoPage`:\n\n```javascript path=src/app/repos/page.js\nimport { Octokit } from '@octokit/core';\n```\n\n### Initializing Octokit client\n\nDirectly below all your imports, initialize an octokit client which we'll use to\nquery our `RepoTable` data:\n\n```javascript path=src/app/repos/page.js\nconst octokitClient = new Octokit({});\n```\n\n### API Request\n\nNext, we'll assemble our GitHub API request to fetch a list of repositories that\nbelong to the `carbon-design-system` GitHub organization. We'll do this by using\na `useEffect` hook that will use octokit to query GitHub's API\n[repositories endpoint](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#list-organization-repositories).\n\nLet's declare a `useEffect` hook immediately below the component definition and\nabove the return. We'll use this to query GitHub's API when the component first\nrenders:\n\n```javascript path=src/app/repos/page.js\nfunction RepoPage() {\n useEffect(() => {\n async function getCarbonRepos() {\n const res = await octokitClient.request('GET /orgs/{org}/repos', {\n org: 'carbon-design-system',\n per_page: 75,\n sort: 'updated',\n direction: 'desc',\n });\n\n if (res.status === 200) {\n console.log(res.data);\n } else {\n console.log('Error obtaining repository data');\n }\n }\n\n getCarbonRepos();\n }, []);\n```\n\nAt this point, if you navigate to the Repositories page `/repos` in your running\napp and view your browser's console (e.g.\n[Chrome DevTools](https://developer.chrome.com/docs/devtools/)), you should see\nthe response from GitHub!\n\n### Helpers\n\nOur last column in the data table will be a comma-separated list of repository\nand home page links, so let's create a component called `LinkList`.\n\nImport `Link` at the top of `/app/repos/page.js`. The imports should look like\nthis.\n\n```javascript path=src/app/repos/page.js\nimport { Link, Grid, Column } from '@carbon/react';\n```\n\nThen use `Link` in this component. It has two props (`url` and `homepageUrl`)\nand returns an unordered list. If the repository does not have a home page URL,\nonly render the repository link.\n\n```javascript path=src/app/repos/page.js\nconst LinkList = ({ url, homepageUrl }) => (\n
\n
\n GitHub\n
\n {homepageUrl && (\n
\n | \n Homepage\n
\n )}\n
\n);\n```\n\nAs a final helper, let's create a function that transforms row data to our\nexpected header keys. Notice how we're using our new `LinkList` component to\ngenerate the value of the `links` key in each row.\n\n```javascript path=src/app/repos/page.js\nconst getRowItems = (rows) =>\n rows.map((row) => ({\n ...row,\n key: row.id,\n stars: row.stargazers_count,\n issueCount: row.open_issues_count,\n createdAt: new Date(row.created_at).toLocaleDateString(),\n updatedAt: new Date(row.updated_at).toLocaleDateString(),\n links: ,\n }));\n```\n\n### Populate data table\n\nNow that we have our data, let's dispose of our dummy `rows` and populate the\ndata table with real data.\n\nFirst, towards the top of `RepoPage` delete the `rows` array because we no\nlonger need the example rows.\n\nNext, let's add a couple variables that will help us store useful information\nwhen fetching the data and keep track of the loading state.\n\nWe'll be using [React Hooks](https://reactjs.org/docs/hooks-intro.html) again to\nmanage our state.\n\nImport React's [useState](https://reactjs.org/docs/hooks-state.html) by\nmodifying the `React` import.\n\n```javascript path=src/app/repos/page.js\nimport React, { useEffect, useState } from 'react';\n```\n\nThen, inside the `RepoPage` component:\n\n```javascript path=src/app/repos/page.js\nfunction RepoPage() {\n const [loading, setLoading] = useState(true);\n const [error, setError] = useState();\n const [rows, setRows] = useState([]);\n```\n\nNow, instead of using `console.log` to log the github data response, let's treat\nthe response data by passing it through our `getRowItems` helper and saving the\nresult in our new `rows` variable. Replace the `console.log(res.data);` line\ninside `if (res.status === 200)` with:\n\n```javascript path=src/app/repos/page.js\nsetRows(getRowItems(res.data));\n```\n\nLet's also replace our error log line inside the `else` statement with:\n\n```javascript path=src/app/repos/page.js\nsetError('Error obtaining repository data');\n```\n\nTo complete our `getCarbonRepos` function, let's set the loading state to false\nright after the `else` statement:\n\n```javascript path=src/app/repos/page.js\nif (res.status === 200) {\n setRows(getRowItems(res.data));\n} else {\n setError('Error obtaining repository data');\n}\nsetLoading(false);\n```\n\nFinally, let's modify our component's `return()` statement to display different\ninformation depending on the states of our request: loading, error or complete.\nReplace the current return statement with:\n\n```javascript path=src/app/repos/page.js\nif (loading) {\n return 'Loading...';\n}\n\nif (error) {\n return `Error! ${error}`;\n}\n\n// If we're here, we've got our data!\nreturn (\n \n \n \n \n \n);\n```\n\n### Render repository descriptions\n\nThe data table component and its pieces use a common React pattern called\n[render props](https://reactjs.org/docs/render-props.html). This is a really\npowerful way for libraries to give developers control of rendering and\nmanipulating their data.\n\nRevisiting `RepoTable.js`, we are already passing in our row objects along with\nheaders for each column. The `render` prop is being used to tell the data table\nhow to render the headers and rows. That prop takes a function that receives the\nprocessed headers and rows as arguments as well as some helper functions for\nrendering the table.\n\nOne common hurdle with the data table is how to access data that might not\ncorrespond with a table column but is needed to compute the value of a cell that\ndoes. The data table component processes and controls only the row properties\nwhich corresponds to headers (columns). Because of this, the `rows` object you\nget access to in the render prop function is _different_ than the one you passed\nin to the `rows` prop.\n\nWe need to modify one aspect of the data table because if you expand a row, it\nsays `Row description`. We want to update that with the repository description\ncoming from the GitHub API. This is an example of where we need a simple look-up\nfunction to find the data we care about - data that does not directly correspond\nto a column.\n\nTo do so, in `RepoTable.js`, add this look-up function as the first lines inside\nthe `RepoTable`. This should go immediately before the component's `return()`.\n\n```javascript path=src/app/repos/RepoTable.js\nconst getRowDescription = (rowId) => {\n const row = rows.find(({ id }) => id === rowId);\n return row ? row.description : '';\n};\n```\n\nFinally, in `RepoTable.js`, replace `
\n```\n\n## Add loading\n\nAt this point, the first time that you visit the repositories page, we're\nquerying the GitHub API and rendering the response through the `DataTable`\ncomponent. We could stop here, but there's more to be done! Let's replace the\n`Loading...` string with the\n[DataTableSkeleton component](https://react.carbondesignsystem.com/?path=/story/components-datatable--skeleton).\n\nTo do so, back to `RepoPage`, add the `DataTableSkeleton` import by modifying\nthe existing `@carbon/react` import.\n\n```javascript path=src/app/repos/page.js\nimport { Link, DataTableSkeleton, Grid, Column } from '@carbon/react';\n```\n\nThen replace the `if (loading) return 'Loading...';` with:\n\n```javascript path=src/app/repos/page.js\nif (loading) {\n return (\n \n \n \n \n \n );\n}\n```\n\nWe need to tell the loading skeleton how many rows to render, so let's use 10\nskeleton rows to prepare for the next enhancement...\n\n## Add pagination\n\nPagination! Instead of rendering every repository, let's add pagination to the\ndata table to only render 10 at a time. Depending on your specific requirements,\nyou may need to fetch new data each time that you interact with the pagination\ncomponent, but for simplicity, we're going to make one request to fetch all\ndata, and then paginate the in-memory row data.\n\nInitialize the new state variables that we'll use for pagination as the first\nlines inside the `RepoPage`.\n\n```javascript path=src/app/repos/page.js\nfunction RepoPage() {\n const [firstRowIndex, setFirstRowIndex] = useState(0);\n const [currentPageSize, setCurrentPageSize] = useState(10);\n...\n```\n\nThis initializes the total number of rows and the index of the first row to `0`,\nand the page size to `10` as we also specified in our loading skeleton.\n\nThen we need to update our `RepoTable` `rows` prop to only render the subset of\nrows for the current \"page\". Update\n`` to:\n\n```javascript path=src/app/repos/page.js\n\n```\n\n\n\n**Note:** We only pass the rows that we want our table to display. We can do\nthis by slicing the array of rows depending on the first item and the page size.\n\n\n\nFinally, let's add the `Pagination` to update our state variables and cause the\ndata table to render new rows.\n\nImport `Pagination` by updating the `@carbon/react` import.\n\n```javascript path=src/app/repos/page.js\nimport {\n Link,\n DataTableSkeleton,\n Pagination,\n Grid,\n Column,\n} from '@carbon/react';\n```\n\nImmediately after the `RepoTable` closing tag (`/>`), add the `Pagination`\ncomponent using the state variables that we previously initialized.\n\n```javascript path=src/app/repos/page.js\n {\n if (pageSize !== currentPageSize) {\n setCurrentPageSize(pageSize);\n }\n setFirstRowIndex(pageSize * (page - 1));\n }}\n/>\n```\n\n\n\n**Note:** The `Pagination` component isn't inherently connected in any way to\nthe `DataTable` - we need to tell it what to do when a change occurs using the\n`onChange` prop. This includes both page size changes and displaying different\nrows.\n\n\n\n\n\n**Note:** Like the other Carbon React components, `Pagination` component\nexamples can be found in\n[Storybook](https://react.carbondesignsystem.com/?path=/story/components-pagination--pagination)\nby browsing the story and knobs.\n\n\n\nThat does it! Your data table should fetch GitHub data on first render. You can\nexpand each row to see the repository's description. You can modify the\npagination items per page and cycle through pages or jump to a specific page of\nrepositories.\n\n## Submit pull request\n\nWe're going to submit a pull request to verify completion of this tutorial step.\n\n### Continuous integration (CI) check\n\nRun the CI check to make sure we're all set to submit a pull request.\n\n```bash\nyarn ci-check\n```\n\n\n\n**Note:** Having issues running the CI check?\n[Step 1]()\nhas troubleshooting notes that may help.\n\n\n\n### Git commit and push\n\nBefore we can create a pull request, format your code, then stage and commit all\nof your changes:\n\n```bash\nyarn format\ngit add --all && git commit -m \"feat(tutorial): complete step 3\"\n```\n\nThen, push to your repository:\n\n```bash\ngit push origin v11-next-step-3\n```\n\n\n\n**Note:** Having issues pushing your changes?\n[Step 1](/developing/react-tutorial/step-1#git-commit-and-push) has\ntroubleshooting notes that may help.\n\n\n\n### Pull request (PR)\n\nFinally, visit\n[carbon-tutorial-nextjs](https://github.com/carbon-design-system/carbon-tutorial-nextjs)\nto \"Compare & pull request\". In doing so, make sure that you are comparing to\n`v11-next-step-3` into `base: v11-next-step-3`.\n\n\n\n**Note:** Expect your tutorial step PRs to be reviewed by the Carbon team but\nnot merged. We'll close your PR so we can keep the repository's remote branches\npristine and ready for the next person!\n\n\n\n\n\n**Note:** If your PR fails the CircleCI test with the error\n`Can't make a request in offline mode`, try running the following command:\n`rm -rf .yarn-offline-mirror node_modules && yarn cache clean && yarn install`.\nAdd and commit the changes once this completes, and try pushing again.\n\n\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/developing/react-tutorial/step-3.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-developing-react-tutorial-step-3-mdx","path":"/developing/react-tutorial/step-3/","result":{"pageContext":{"frontmatter":{"title":"3. Using APIs","description":"Welcome to Carbon! This tutorial will guide you in creating a React app using Next.js with the Carbon Design System.","tabs":["Overview","Step 1","Step 2","Step 3","Step 4","Step 5","Wrapping up","FAQ"]},"relativePagePath":"/developing/react-tutorial/step-3.mdx","titleType":"prepend","MdxNode":{"id":"eda9fc2a-eade-572d-98dd-8ef839e770bd","children":[],"parent":"e313048c-3ecc-5af7-bc7f-a9bc46f9924c","internal":{"content":"---\ntitle: 3. Using APIs\ndescription:\n Welcome to Carbon! This tutorial will guide you in creating a React app using\n Next.js with the Carbon Design System.\ntabs:\n [\n 'Overview',\n 'Step 1',\n 'Step 2',\n 'Step 3',\n 'Step 4',\n 'Step 5',\n 'Wrapping up',\n 'FAQ',\n ]\n---\n\nimport Preview from 'components/Preview';\n\n\n\nThis step takes our static components and populates them with data from the\nGitHub GraphQL API – loading states and all. We'll be displaying Carbon\nrepository information in a data table.\n\n\n\n\n\nFork, clone and branch\nInstall dependencies\nFetch data\nPopulate data table\nAdd loading\nAdd pagination\nSubmit pull request\n\n\n\n### Preview\n\nThe [GitHub REST API](https://docs.github.com/en/rest?apiVersion=2022-11-28) is\nvery well documented, we'll use it to fetch Carbon-related data for this Carbon\ntutorial.\n\nTo do so, we'll be using\n[Octokit Core](https://github.com/octokit/core.js/#readme), a client that makes\nit easy to interact with GitHub's APIs.\n\nA\n[preview](https://carbon-tutorial-nextjs-git-v11-next-step-4-carbon-design-system.vercel.app/)\nof what you will build (see repositories page):\n\n\n\n## Fork, clone and branch\n\nThis tutorial has an accompanying GitHub repository called\n[carbon-tutorial-nextjs](https://github.com/carbon-design-system/carbon-tutorial-nextjs)\nthat we'll use as a starting point for each step. If you haven't forked and\ncloned that repository yet, and haven't added the upstream remote, go ahead and\ndo so by following the\n[step 1 instructions](/developing/react-tutorial/step-1#fork-clone-and-branch).\n\n### Branch\n\nWith your repository all set up, let's check out the branch for this tutorial\nstep's starting point.\n\n```bash\ngit fetch upstream\ngit checkout -b v11-next-step-3 upstream/v11-next-step-3\n```\n\n### Build and start app\n\nInstall the app's dependencies and build the app:\n\n```bash\nyarn && yarn build\n```\n\nThen, start the app:\n\n```bash\nyarn start\n```\n\nYou should see something similar to where the\n[previous step](/developing/react-tutorial/step-2) left off. Stop your app with\n`CTRL-C` and let's get everything installed.\n\n## Install dependencies\n\nWe'll need to install `@octokit/core`, a package that allows us to query GitHub\nAPIs easily. Stop your development server with `CTRL-C` and install the octokit\ndependency with:\n\n```bash\nyarn add @octokit/core@4.2.0\n```\n\nThen, start the app again. If your app's currently running, you'll need to\nrestart it.\n\n```bash\nyarn dev\n```\n\n## Fetch data\n\n### Imports\n\nWe'll be using [React Hooks](https://reactjs.org/docs/hooks-intro.html) to call\na function to fetch our data when the component renders.\n\nImport React's [useEffect](https://reactjs.org/docs/hooks-effect.html) by\nmodifying the `React` import in `src/app/repos/page.js`.\n\n```javascript path=src/app/repos/page.js\nimport React, { useEffect } from 'react';\n```\n\nAdd the following import below the react import in `RepoPage`:\n\n```javascript path=src/app/repos/page.js\nimport { Octokit } from '@octokit/core';\n```\n\n### Initializing Octokit client\n\nDirectly below all your imports, initialize an octokit client which we'll use to\nquery our `RepoTable` data:\n\n```javascript path=src/app/repos/page.js\nconst octokitClient = new Octokit({});\n```\n\n### API Request\n\nNext, we'll assemble our GitHub API request to fetch a list of repositories that\nbelong to the `carbon-design-system` GitHub organization. We'll do this by using\na `useEffect` hook that will use octokit to query GitHub's API\n[repositories endpoint](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#list-organization-repositories).\n\nLet's declare a `useEffect` hook immediately below the component definition and\nabove the return. We'll use this to query GitHub's API when the component first\nrenders:\n\n```javascript path=src/app/repos/page.js\nfunction RepoPage() {\n useEffect(() => {\n async function getCarbonRepos() {\n const res = await octokitClient.request('GET /orgs/{org}/repos', {\n org: 'carbon-design-system',\n per_page: 75,\n sort: 'updated',\n direction: 'desc',\n });\n\n if (res.status === 200) {\n console.log(res.data);\n } else {\n console.log('Error obtaining repository data');\n }\n }\n\n getCarbonRepos();\n }, []);\n```\n\nAt this point, if you navigate to the Repositories page `/repos` in your running\napp and view your browser's console (e.g.\n[Chrome DevTools](https://developer.chrome.com/docs/devtools/)), you should see\nthe response from GitHub!\n\n### Helpers\n\nOur last column in the data table will be a comma-separated list of repository\nand home page links, so let's create a component called `LinkList`.\n\nImport `Link` at the top of `/app/repos/page.js`. The imports should look like\nthis.\n\n```javascript path=src/app/repos/page.js\nimport { Link, Grid, Column } from '@carbon/react';\n```\n\nThen use `Link` in this component. It has two props (`url` and `homepageUrl`)\nand returns an unordered list. If the repository does not have a home page URL,\nonly render the repository link.\n\n```javascript path=src/app/repos/page.js\nconst LinkList = ({ url, homepageUrl }) => (\n
\n
\n GitHub\n
\n {homepageUrl && (\n
\n | \n Homepage\n
\n )}\n
\n);\n```\n\nAs a final helper, let's create a function that transforms row data to our\nexpected header keys. Notice how we're using our new `LinkList` component to\ngenerate the value of the `links` key in each row.\n\n```javascript path=src/app/repos/page.js\nconst getRowItems = (rows) =>\n rows.map((row) => ({\n ...row,\n key: row.id,\n stars: row.stargazers_count,\n issueCount: row.open_issues_count,\n createdAt: new Date(row.created_at).toLocaleDateString(),\n updatedAt: new Date(row.updated_at).toLocaleDateString(),\n links: ,\n }));\n```\n\n### Populate data table\n\nNow that we have our data, let's dispose of our dummy `rows` and populate the\ndata table with real data.\n\nFirst, towards the top of `RepoPage` delete the `rows` array because we no\nlonger need the example rows.\n\nNext, let's add a couple variables that will help us store useful information\nwhen fetching the data and keep track of the loading state.\n\nWe'll be using [React Hooks](https://reactjs.org/docs/hooks-intro.html) again to\nmanage our state.\n\nImport React's [useState](https://reactjs.org/docs/hooks-state.html) by\nmodifying the `React` import.\n\n```javascript path=src/app/repos/page.js\nimport React, { useEffect, useState } from 'react';\n```\n\nThen, inside the `RepoPage` component:\n\n```javascript path=src/app/repos/page.js\nfunction RepoPage() {\n const [loading, setLoading] = useState(true);\n const [error, setError] = useState();\n const [rows, setRows] = useState([]);\n```\n\nNow, instead of using `console.log` to log the github data response, let's treat\nthe response data by passing it through our `getRowItems` helper and saving the\nresult in our new `rows` variable. Replace the `console.log(res.data);` line\ninside `if (res.status === 200)` with:\n\n```javascript path=src/app/repos/page.js\nsetRows(getRowItems(res.data));\n```\n\nLet's also replace our error log line inside the `else` statement with:\n\n```javascript path=src/app/repos/page.js\nsetError('Error obtaining repository data');\n```\n\nTo complete our `getCarbonRepos` function, let's set the loading state to false\nright after the `else` statement:\n\n```javascript path=src/app/repos/page.js\nif (res.status === 200) {\n setRows(getRowItems(res.data));\n} else {\n setError('Error obtaining repository data');\n}\nsetLoading(false);\n```\n\nFinally, let's modify our component's `return()` statement to display different\ninformation depending on the states of our request: loading, error or complete.\nReplace the current return statement with:\n\n```javascript path=src/app/repos/page.js\nif (loading) {\n return 'Loading...';\n}\n\nif (error) {\n return `Error! ${error}`;\n}\n\n// If we're here, we've got our data!\nreturn (\n \n \n \n \n \n);\n```\n\n### Render repository descriptions\n\nThe data table component and its pieces use a common React pattern called\n[render props](https://reactjs.org/docs/render-props.html). This is a really\npowerful way for libraries to give developers control of rendering and\nmanipulating their data.\n\nRevisiting `RepoTable.js`, we are already passing in our row objects along with\nheaders for each column. The `render` prop is being used to tell the data table\nhow to render the headers and rows. That prop takes a function that receives the\nprocessed headers and rows as arguments as well as some helper functions for\nrendering the table.\n\nOne common hurdle with the data table is how to access data that might not\ncorrespond with a table column but is needed to compute the value of a cell that\ndoes. The data table component processes and controls only the row properties\nwhich corresponds to headers (columns). Because of this, the `rows` object you\nget access to in the render prop function is _different_ than the one you passed\nin to the `rows` prop.\n\nWe need to modify one aspect of the data table because if you expand a row, it\nsays `Row description`. We want to update that with the repository description\ncoming from the GitHub API. This is an example of where we need a simple look-up\nfunction to find the data we care about - data that does not directly correspond\nto a column.\n\nTo do so, in `RepoTable.js`, add this look-up function as the first lines inside\nthe `RepoTable`. This should go immediately before the component's `return()`.\n\n```javascript path=src/app/repos/RepoTable.js\nconst getRowDescription = (rowId) => {\n const row = rows.find(({ id }) => id === rowId);\n return row ? row.description : '';\n};\n```\n\nFinally, in `RepoTable.js`, replace `
\n```\n\n## Add loading\n\nAt this point, the first time that you visit the repositories page, we're\nquerying the GitHub API and rendering the response through the `DataTable`\ncomponent. We could stop here, but there's more to be done! Let's replace the\n`Loading...` string with the\n[DataTableSkeleton component](https://react.carbondesignsystem.com/?path=/story/components-datatable--skeleton).\n\nTo do so, back to `RepoPage`, add the `DataTableSkeleton` import by modifying\nthe existing `@carbon/react` import.\n\n```javascript path=src/app/repos/page.js\nimport { Link, DataTableSkeleton, Grid, Column } from '@carbon/react';\n```\n\nThen replace the `if (loading) return 'Loading...';` with:\n\n```javascript path=src/app/repos/page.js\nif (loading) {\n return (\n \n \n \n \n \n );\n}\n```\n\nWe need to tell the loading skeleton how many rows to render, so let's use 10\nskeleton rows to prepare for the next enhancement...\n\n## Add pagination\n\nPagination! Instead of rendering every repository, let's add pagination to the\ndata table to only render 10 at a time. Depending on your specific requirements,\nyou may need to fetch new data each time that you interact with the pagination\ncomponent, but for simplicity, we're going to make one request to fetch all\ndata, and then paginate the in-memory row data.\n\nInitialize the new state variables that we'll use for pagination as the first\nlines inside the `RepoPage`.\n\n```javascript path=src/app/repos/page.js\nfunction RepoPage() {\n const [firstRowIndex, setFirstRowIndex] = useState(0);\n const [currentPageSize, setCurrentPageSize] = useState(10);\n...\n```\n\nThis initializes the total number of rows and the index of the first row to `0`,\nand the page size to `10` as we also specified in our loading skeleton.\n\nThen we need to update our `RepoTable` `rows` prop to only render the subset of\nrows for the current \"page\". Update\n`` to:\n\n```javascript path=src/app/repos/page.js\n\n```\n\n\n\n**Note:** We only pass the rows that we want our table to display. We can do\nthis by slicing the array of rows depending on the first item and the page size.\n\n\n\nFinally, let's add the `Pagination` to update our state variables and cause the\ndata table to render new rows.\n\nImport `Pagination` by updating the `@carbon/react` import.\n\n```javascript path=src/app/repos/page.js\nimport {\n Link,\n DataTableSkeleton,\n Pagination,\n Grid,\n Column,\n} from '@carbon/react';\n```\n\nImmediately after the `RepoTable` closing tag (`/>`), add the `Pagination`\ncomponent using the state variables that we previously initialized.\n\n```javascript path=src/app/repos/page.js\n {\n if (pageSize !== currentPageSize) {\n setCurrentPageSize(pageSize);\n }\n setFirstRowIndex(pageSize * (page - 1));\n }}\n/>\n```\n\n\n\n**Note:** The `Pagination` component isn't inherently connected in any way to\nthe `DataTable` - we need to tell it what to do when a change occurs using the\n`onChange` prop. This includes both page size changes and displaying different\nrows.\n\n\n\n\n\n**Note:** Like the other Carbon React components, `Pagination` component\nexamples can be found in\n[Storybook](https://react.carbondesignsystem.com/?path=/story/components-pagination--pagination)\nby browsing the story and knobs.\n\n\n\nThat does it! Your data table should fetch GitHub data on first render. You can\nexpand each row to see the repository's description. You can modify the\npagination items per page and cycle through pages or jump to a specific page of\nrepositories.\n\n## Submit pull request\n\nWe're going to submit a pull request to verify completion of this tutorial step.\n\n### Continuous integration (CI) check\n\nRun the CI check to make sure we're all set to submit a pull request.\n\n```bash\nyarn ci-check\n```\n\n\n\n**Note:** Having issues running the CI check?\n[Step 1]()\nhas troubleshooting notes that may help.\n\n\n\n### Git commit and push\n\nBefore we can create a pull request, format your code, then stage and commit all\nof your changes:\n\n```bash\nyarn format\ngit add --all && git commit -m \"feat(tutorial): complete step 3\"\n```\n\nThen, push to your repository:\n\n```bash\ngit push origin v11-next-step-3\n```\n\n\n\n**Note:** Having issues pushing your changes?\n[Step 1](/developing/react-tutorial/step-1#git-commit-and-push) has\ntroubleshooting notes that may help.\n\n\n\n### Pull request (PR)\n\nFinally, visit\n[carbon-tutorial-nextjs](https://github.com/carbon-design-system/carbon-tutorial-nextjs)\nto \"Compare & pull request\". In doing so, make sure that you are comparing to\n`v11-next-step-3` into `base: v11-next-step-3`.\n\n\n\n**Note:** Expect your tutorial step PRs to be reviewed by the Carbon team but\nnot merged. We'll close your PR so we can keep the repository's remote branches\npristine and ready for the next person!\n\n\n\n\n\n**Note:** If your PR fails the CircleCI test with the error\n`Can't make a request in offline mode`, try running the following command:\n`rm -rf .yarn-offline-mirror node_modules && yarn cache clean && yarn install`.\nAdd and commit the changes once this completes, and try pushing again.\n\n\n","type":"Mdx","contentDigest":"f397d3dbba2c6d67ab4728660c1169aa","owner":"gatsby-plugin-mdx","counter":5286},"frontmatter":{"title":"3. Using APIs","description":"Welcome to Carbon! This tutorial will guide you in creating a React app using Next.js with the Carbon Design System.","tabs":["Overview","Step 1","Step 2","Step 3","Step 4","Step 5","Wrapping up","FAQ"]},"exports":{},"rawBody":"---\ntitle: 3. Using APIs\ndescription:\n Welcome to Carbon! This tutorial will guide you in creating a React app using\n Next.js with the Carbon Design System.\ntabs:\n [\n 'Overview',\n 'Step 1',\n 'Step 2',\n 'Step 3',\n 'Step 4',\n 'Step 5',\n 'Wrapping up',\n 'FAQ',\n ]\n---\n\nimport Preview from 'components/Preview';\n\n\n\nThis step takes our static components and populates them with data from the\nGitHub GraphQL API – loading states and all. We'll be displaying Carbon\nrepository information in a data table.\n\n\n\n\n\nFork, clone and branch\nInstall dependencies\nFetch data\nPopulate data table\nAdd loading\nAdd pagination\nSubmit pull request\n\n\n\n### Preview\n\nThe [GitHub REST API](https://docs.github.com/en/rest?apiVersion=2022-11-28) is\nvery well documented, we'll use it to fetch Carbon-related data for this Carbon\ntutorial.\n\nTo do so, we'll be using\n[Octokit Core](https://github.com/octokit/core.js/#readme), a client that makes\nit easy to interact with GitHub's APIs.\n\nA\n[preview](https://carbon-tutorial-nextjs-git-v11-next-step-4-carbon-design-system.vercel.app/)\nof what you will build (see repositories page):\n\n\n\n## Fork, clone and branch\n\nThis tutorial has an accompanying GitHub repository called\n[carbon-tutorial-nextjs](https://github.com/carbon-design-system/carbon-tutorial-nextjs)\nthat we'll use as a starting point for each step. If you haven't forked and\ncloned that repository yet, and haven't added the upstream remote, go ahead and\ndo so by following the\n[step 1 instructions](/developing/react-tutorial/step-1#fork-clone-and-branch).\n\n### Branch\n\nWith your repository all set up, let's check out the branch for this tutorial\nstep's starting point.\n\n```bash\ngit fetch upstream\ngit checkout -b v11-next-step-3 upstream/v11-next-step-3\n```\n\n### Build and start app\n\nInstall the app's dependencies and build the app:\n\n```bash\nyarn && yarn build\n```\n\nThen, start the app:\n\n```bash\nyarn start\n```\n\nYou should see something similar to where the\n[previous step](/developing/react-tutorial/step-2) left off. Stop your app with\n`CTRL-C` and let's get everything installed.\n\n## Install dependencies\n\nWe'll need to install `@octokit/core`, a package that allows us to query GitHub\nAPIs easily. Stop your development server with `CTRL-C` and install the octokit\ndependency with:\n\n```bash\nyarn add @octokit/core@4.2.0\n```\n\nThen, start the app again. If your app's currently running, you'll need to\nrestart it.\n\n```bash\nyarn dev\n```\n\n## Fetch data\n\n### Imports\n\nWe'll be using [React Hooks](https://reactjs.org/docs/hooks-intro.html) to call\na function to fetch our data when the component renders.\n\nImport React's [useEffect](https://reactjs.org/docs/hooks-effect.html) by\nmodifying the `React` import in `src/app/repos/page.js`.\n\n```javascript path=src/app/repos/page.js\nimport React, { useEffect } from 'react';\n```\n\nAdd the following import below the react import in `RepoPage`:\n\n```javascript path=src/app/repos/page.js\nimport { Octokit } from '@octokit/core';\n```\n\n### Initializing Octokit client\n\nDirectly below all your imports, initialize an octokit client which we'll use to\nquery our `RepoTable` data:\n\n```javascript path=src/app/repos/page.js\nconst octokitClient = new Octokit({});\n```\n\n### API Request\n\nNext, we'll assemble our GitHub API request to fetch a list of repositories that\nbelong to the `carbon-design-system` GitHub organization. We'll do this by using\na `useEffect` hook that will use octokit to query GitHub's API\n[repositories endpoint](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#list-organization-repositories).\n\nLet's declare a `useEffect` hook immediately below the component definition and\nabove the return. We'll use this to query GitHub's API when the component first\nrenders:\n\n```javascript path=src/app/repos/page.js\nfunction RepoPage() {\n useEffect(() => {\n async function getCarbonRepos() {\n const res = await octokitClient.request('GET /orgs/{org}/repos', {\n org: 'carbon-design-system',\n per_page: 75,\n sort: 'updated',\n direction: 'desc',\n });\n\n if (res.status === 200) {\n console.log(res.data);\n } else {\n console.log('Error obtaining repository data');\n }\n }\n\n getCarbonRepos();\n }, []);\n```\n\nAt this point, if you navigate to the Repositories page `/repos` in your running\napp and view your browser's console (e.g.\n[Chrome DevTools](https://developer.chrome.com/docs/devtools/)), you should see\nthe response from GitHub!\n\n### Helpers\n\nOur last column in the data table will be a comma-separated list of repository\nand home page links, so let's create a component called `LinkList`.\n\nImport `Link` at the top of `/app/repos/page.js`. The imports should look like\nthis.\n\n```javascript path=src/app/repos/page.js\nimport { Link, Grid, Column } from '@carbon/react';\n```\n\nThen use `Link` in this component. It has two props (`url` and `homepageUrl`)\nand returns an unordered list. If the repository does not have a home page URL,\nonly render the repository link.\n\n```javascript path=src/app/repos/page.js\nconst LinkList = ({ url, homepageUrl }) => (\n
\n
\n GitHub\n
\n {homepageUrl && (\n
\n | \n Homepage\n
\n )}\n
\n);\n```\n\nAs a final helper, let's create a function that transforms row data to our\nexpected header keys. Notice how we're using our new `LinkList` component to\ngenerate the value of the `links` key in each row.\n\n```javascript path=src/app/repos/page.js\nconst getRowItems = (rows) =>\n rows.map((row) => ({\n ...row,\n key: row.id,\n stars: row.stargazers_count,\n issueCount: row.open_issues_count,\n createdAt: new Date(row.created_at).toLocaleDateString(),\n updatedAt: new Date(row.updated_at).toLocaleDateString(),\n links: ,\n }));\n```\n\n### Populate data table\n\nNow that we have our data, let's dispose of our dummy `rows` and populate the\ndata table with real data.\n\nFirst, towards the top of `RepoPage` delete the `rows` array because we no\nlonger need the example rows.\n\nNext, let's add a couple variables that will help us store useful information\nwhen fetching the data and keep track of the loading state.\n\nWe'll be using [React Hooks](https://reactjs.org/docs/hooks-intro.html) again to\nmanage our state.\n\nImport React's [useState](https://reactjs.org/docs/hooks-state.html) by\nmodifying the `React` import.\n\n```javascript path=src/app/repos/page.js\nimport React, { useEffect, useState } from 'react';\n```\n\nThen, inside the `RepoPage` component:\n\n```javascript path=src/app/repos/page.js\nfunction RepoPage() {\n const [loading, setLoading] = useState(true);\n const [error, setError] = useState();\n const [rows, setRows] = useState([]);\n```\n\nNow, instead of using `console.log` to log the github data response, let's treat\nthe response data by passing it through our `getRowItems` helper and saving the\nresult in our new `rows` variable. Replace the `console.log(res.data);` line\ninside `if (res.status === 200)` with:\n\n```javascript path=src/app/repos/page.js\nsetRows(getRowItems(res.data));\n```\n\nLet's also replace our error log line inside the `else` statement with:\n\n```javascript path=src/app/repos/page.js\nsetError('Error obtaining repository data');\n```\n\nTo complete our `getCarbonRepos` function, let's set the loading state to false\nright after the `else` statement:\n\n```javascript path=src/app/repos/page.js\nif (res.status === 200) {\n setRows(getRowItems(res.data));\n} else {\n setError('Error obtaining repository data');\n}\nsetLoading(false);\n```\n\nFinally, let's modify our component's `return()` statement to display different\ninformation depending on the states of our request: loading, error or complete.\nReplace the current return statement with:\n\n```javascript path=src/app/repos/page.js\nif (loading) {\n return 'Loading...';\n}\n\nif (error) {\n return `Error! ${error}`;\n}\n\n// If we're here, we've got our data!\nreturn (\n \n \n \n \n \n);\n```\n\n### Render repository descriptions\n\nThe data table component and its pieces use a common React pattern called\n[render props](https://reactjs.org/docs/render-props.html). This is a really\npowerful way for libraries to give developers control of rendering and\nmanipulating their data.\n\nRevisiting `RepoTable.js`, we are already passing in our row objects along with\nheaders for each column. The `render` prop is being used to tell the data table\nhow to render the headers and rows. That prop takes a function that receives the\nprocessed headers and rows as arguments as well as some helper functions for\nrendering the table.\n\nOne common hurdle with the data table is how to access data that might not\ncorrespond with a table column but is needed to compute the value of a cell that\ndoes. The data table component processes and controls only the row properties\nwhich corresponds to headers (columns). Because of this, the `rows` object you\nget access to in the render prop function is _different_ than the one you passed\nin to the `rows` prop.\n\nWe need to modify one aspect of the data table because if you expand a row, it\nsays `Row description`. We want to update that with the repository description\ncoming from the GitHub API. This is an example of where we need a simple look-up\nfunction to find the data we care about - data that does not directly correspond\nto a column.\n\nTo do so, in `RepoTable.js`, add this look-up function as the first lines inside\nthe `RepoTable`. This should go immediately before the component's `return()`.\n\n```javascript path=src/app/repos/RepoTable.js\nconst getRowDescription = (rowId) => {\n const row = rows.find(({ id }) => id === rowId);\n return row ? row.description : '';\n};\n```\n\nFinally, in `RepoTable.js`, replace `
\n```\n\n## Add loading\n\nAt this point, the first time that you visit the repositories page, we're\nquerying the GitHub API and rendering the response through the `DataTable`\ncomponent. We could stop here, but there's more to be done! Let's replace the\n`Loading...` string with the\n[DataTableSkeleton component](https://react.carbondesignsystem.com/?path=/story/components-datatable--skeleton).\n\nTo do so, back to `RepoPage`, add the `DataTableSkeleton` import by modifying\nthe existing `@carbon/react` import.\n\n```javascript path=src/app/repos/page.js\nimport { Link, DataTableSkeleton, Grid, Column } from '@carbon/react';\n```\n\nThen replace the `if (loading) return 'Loading...';` with:\n\n```javascript path=src/app/repos/page.js\nif (loading) {\n return (\n \n \n \n \n \n );\n}\n```\n\nWe need to tell the loading skeleton how many rows to render, so let's use 10\nskeleton rows to prepare for the next enhancement...\n\n## Add pagination\n\nPagination! Instead of rendering every repository, let's add pagination to the\ndata table to only render 10 at a time. Depending on your specific requirements,\nyou may need to fetch new data each time that you interact with the pagination\ncomponent, but for simplicity, we're going to make one request to fetch all\ndata, and then paginate the in-memory row data.\n\nInitialize the new state variables that we'll use for pagination as the first\nlines inside the `RepoPage`.\n\n```javascript path=src/app/repos/page.js\nfunction RepoPage() {\n const [firstRowIndex, setFirstRowIndex] = useState(0);\n const [currentPageSize, setCurrentPageSize] = useState(10);\n...\n```\n\nThis initializes the total number of rows and the index of the first row to `0`,\nand the page size to `10` as we also specified in our loading skeleton.\n\nThen we need to update our `RepoTable` `rows` prop to only render the subset of\nrows for the current \"page\". Update\n`` to:\n\n```javascript path=src/app/repos/page.js\n\n```\n\n\n\n**Note:** We only pass the rows that we want our table to display. We can do\nthis by slicing the array of rows depending on the first item and the page size.\n\n\n\nFinally, let's add the `Pagination` to update our state variables and cause the\ndata table to render new rows.\n\nImport `Pagination` by updating the `@carbon/react` import.\n\n```javascript path=src/app/repos/page.js\nimport {\n Link,\n DataTableSkeleton,\n Pagination,\n Grid,\n Column,\n} from '@carbon/react';\n```\n\nImmediately after the `RepoTable` closing tag (`/>`), add the `Pagination`\ncomponent using the state variables that we previously initialized.\n\n```javascript path=src/app/repos/page.js\n {\n if (pageSize !== currentPageSize) {\n setCurrentPageSize(pageSize);\n }\n setFirstRowIndex(pageSize * (page - 1));\n }}\n/>\n```\n\n\n\n**Note:** The `Pagination` component isn't inherently connected in any way to\nthe `DataTable` - we need to tell it what to do when a change occurs using the\n`onChange` prop. This includes both page size changes and displaying different\nrows.\n\n\n\n\n\n**Note:** Like the other Carbon React components, `Pagination` component\nexamples can be found in\n[Storybook](https://react.carbondesignsystem.com/?path=/story/components-pagination--pagination)\nby browsing the story and knobs.\n\n\n\nThat does it! Your data table should fetch GitHub data on first render. You can\nexpand each row to see the repository's description. You can modify the\npagination items per page and cycle through pages or jump to a specific page of\nrepositories.\n\n## Submit pull request\n\nWe're going to submit a pull request to verify completion of this tutorial step.\n\n### Continuous integration (CI) check\n\nRun the CI check to make sure we're all set to submit a pull request.\n\n```bash\nyarn ci-check\n```\n\n\n\n**Note:** Having issues running the CI check?\n[Step 1]()\nhas troubleshooting notes that may help.\n\n\n\n### Git commit and push\n\nBefore we can create a pull request, format your code, then stage and commit all\nof your changes:\n\n```bash\nyarn format\ngit add --all && git commit -m \"feat(tutorial): complete step 3\"\n```\n\nThen, push to your repository:\n\n```bash\ngit push origin v11-next-step-3\n```\n\n\n\n**Note:** Having issues pushing your changes?\n[Step 1](/developing/react-tutorial/step-1#git-commit-and-push) has\ntroubleshooting notes that may help.\n\n\n\n### Pull request (PR)\n\nFinally, visit\n[carbon-tutorial-nextjs](https://github.com/carbon-design-system/carbon-tutorial-nextjs)\nto \"Compare & pull request\". In doing so, make sure that you are comparing to\n`v11-next-step-3` into `base: v11-next-step-3`.\n\n\n\n**Note:** Expect your tutorial step PRs to be reviewed by the Carbon team but\nnot merged. We'll close your PR so we can keep the repository's remote branches\npristine and ready for the next person!\n\n\n\n\n\n**Note:** If your PR fails the CircleCI test with the error\n`Can't make a request in offline mode`, try running the following command:\n`rm -rf .yarn-offline-mirror node_modules && yarn cache clean && yarn install`.\nAdd and commit the changes once this completes, and try pushing again.\n\n\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/developing/react-tutorial/step-3.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/developing/react-tutorial/step-4/page-data.json b/page-data/developing/react-tutorial/step-4/page-data.json
index 78dcf1a28ca..dcf446f4ce8 100644
--- a/page-data/developing/react-tutorial/step-4/page-data.json
+++ b/page-data/developing/react-tutorial/step-4/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-developing-react-tutorial-step-4-mdx","path":"/developing/react-tutorial/step-4/","result":{"pageContext":{"frontmatter":{"title":"4. Creating components","description":"Welcome to Carbon! This tutorial will guide you in creating a React app using Next.js with the Carbon Design System.","tabs":["Overview","Step 1","Step 2","Step 3","Step 4","Step 5","Wrapping up","FAQ"]},"relativePagePath":"/developing/react-tutorial/step-4.mdx","titleType":"prepend","MdxNode":{"id":"5a012e6e-1914-5138-8c7f-fa672debbfb4","children":[],"parent":"c63627a7-f18c-55ae-98d5-929c1520b851","internal":{"content":"---\ntitle: 4. Creating components\ndescription:\n Welcome to Carbon! This tutorial will guide you in creating a React app using\n Next.js with the Carbon Design System.\ntabs:\n [\n 'Overview',\n 'Step 1',\n 'Step 2',\n 'Step 3',\n 'Step 4',\n 'Step 5',\n 'Wrapping up',\n 'FAQ',\n ]\n---\n\nimport Preview from 'components/Preview';\n\n\n\nWith two pages comprised entirely of Carbon components, let's revisit the\nlanding page and build a couple components of our own by using Carbon pictograms\nand tokens.\n\n\n\n\n\nFork, clone and branch\nReview design\nCreate components\nUse components\nAdd styling\nCheck accessibility\nSubmit pull request\n\n\n\n## Preview\n\nCarbon provides a solid foundation for building web applications through its\ncolor palette, layout, spacing, type, as well as common building blocks in the\nform of components. So far, we've only used Carbon components to build out two\npages.\n\nNext, we're going to use Carbon assets to build application-specific components.\nWe'll do so by including accessibility and responsive considerations all\nthroughout.\n\nA\n[preview](https://carbon-tutorial-nextjs-git-v11-next-step-5-carbon-design-system.vercel.app/)\nof what you'll build (see bottom of page):\n\n\n\n## Fork, clone and branch\n\nThis tutorial has an accompanying GitHub repository called\n[carbon-tutorial-nextjs](https://github.com/carbon-design-system/carbon-tutorial-nextjs)\nthat we'll use as a starting point for each step. If you haven't forked and\ncloned that repository yet, and haven't added the upstream remote, go ahead and\ndo so by following the\n[step 1 instructions](/developing/react-tutorial/step-1#fork-clone-and-branch).\n\n### Branch\n\nWith your repository all set up, let's check out the branch for this tutorial\nstep's starting point.\n\n```bash\ngit fetch upstream\ngit checkout -b v11-next-step-4 upstream/v11-next-step-4\n```\n\n\n\n**Note:** This builds on top of step 3, but be sure to check out the upstream\nstep 4 branch because it includes the static assets required to get through this\nstep.\n\n\n\n### Build and start app\n\nInstall the app's dependencies (in case you're starting fresh in your current\ndirectory and not continuing from the previous step):\n\n```bash\nyarn\n```\n\nThen, start the app:\n\n```bash\nyarn dev\n```\n\nYou should see something similar to where the\n[previous step](/developing/react-tutorial/step-3) left off.\n\n## Review design\n\nHere's what we're building – an informational section that has a heading and\nthree subheadings. Each subheading has accompanying copy and a pictogram. We'll\nassume that this informational section is used elsewhere on the site, meaning\nit's a great opportunity to build it as a reusable component. As for naming,\nwe'll call it an `InfoSection` with three `InfoCard`s as children.\n\n\n\n
Info section layout
\n\n## Create components\n\nFirst we need files for the components, so create an `Info` folder in\n`src/components`. Even though we're building multiple components, their names\nall start with `Info`, so it makes sense to have them share one folder in\ncomponents. Create these files:\n\n### Add files\n\n```bash\nsrc/components/Info\n├──_info.scss\n└──Info.js\n```\n\nImport `_info.scss` in `app.scss` after all of the `tutorial-header.scss`\nimport.\n\n```scss path=src/app/globals.scss\n@use '@/components/Info/info';\n```\n\n### InfoSection component\n\nLet's create the parent component that includes the \"The Principles\" heading.\nThat markup currently looks like this in `LandingPage`:\n\n```jsx path=src/app/home/page.js\n\n \n \n
The Principles
\n \n \n Carbon is Open\n \n \n Carbon is Modular\n \n \n Carbon is Consistent\n \n \n\n```\n\nWe want to do a few things when abstracting it to a component. First, we only\nwant this component's class names; we don't want to include `landing-page__r3`\nas that's specific to the landing page. For that we'll use React `props` so we\ncan pass in and use `props.className`.\n\nWe'll also:\n\n- Add component class names like `info-section`, `info-card`, and\n `info-section__heading`\n- We will be using the `Grid` and `Column` components\n- Replace `The Principles` with `{props.heading}`\n- Replace columns 2 - 4 with `{props.children}`\n\nUsing `props` we can render any heading and any number of children components\n(`InfoCard` that we'll build soon.)\n\n```javascript path=src/components/Info/Info.js\nimport { Grid, Column } from '@carbon/react';\n\nconst InfoSection = (props) => (\n \n \n
{props.heading}
\n \n {props.children}\n \n);\n```\n\nAt this point let's import our needed styles and add styling for the new class\nnames that we just added.\n\n```scss path=src/components/Info/_info.scss\n@use '@carbon/react/scss/type' as *;\n\n.info-section__heading {\n @include type-style('heading-01');\n padding-bottom: $spacing-08;\n}\n```\n\n### InfoCard component\n\nNext up we're going to build a component for columns 2 - 4, which currently\nlooks like `Carbon is Open`. At the bottom of\n`Info.js`, add:\n\n```javascript path=src/components/Info/Info.js\nconst InfoCard = (props) => {\n return (\n \n
\n
\n {`${splitHeading[0]} `}\n {splitHeading[1]}\n
\n
{props.body}
\n
\n {props.icon()}\n \n );\n};\n\nexport { InfoSection, InfoCard };\n```\n\n\n\n**Note:** Make sure to export the two components!\n\n\n\nIn doing so, we:\n\n- Added `info-card` classes\n- Used `props` to render the heading, body copy, and icon\n- Set columns to match the grid\n\n## Use components\n\nNothing is styled yet, but with our components built let's put them to use. In\n`LandingPage`, import the components towards the top of the file.\n\n```javascript path=src/app/home/page.js\nimport { InfoSection, InfoCard } from '@/components/Info/Info';\n```\n\nNext, we will install the pictograms we will use in the header.\n\n```bash\nyarn add @carbon/pictograms-react\n```\n\nWhile we're at the top of `LandingPage`, import the pictograms that we'll need\nas well.\n\n```javascript path=src/app/home/page.js\nimport {\n Advocate,\n Globe,\n AcceleratingTransformation,\n} from '@carbon/pictograms-react';\n```\n\nWith everything imported, replace the current:\n\n```jsx path=src/app/home/page.js\n\n \n \n \n
The Principles
\n \n \n Carbon is Open\n \n \n Carbon is Modular\n \n \n Carbon is Consistent\n \n \n \n\n```\n\nWith the new components:\n\n```javascript path=src/app/home/page.js\n\n }\n />\n }\n />\n }\n />\n\n```\n\n\n\n**Note:** Now is a good time to resize your browser from phone to large viewport\nwidths to see how the responsive grid is working before we add further styling.\n\n\n\n## Add styling\n\nHere's our design showing the spacing tokens that we need to add. We also need\nto set type style and borders.\n\n\n\n### Layout\n\nStarting with layout, import the following carbon styles to\n`src/components/Info/_info.scss`. Make sure to import the needed carbon styles.\n\n```scss path=src/components/Info/_info.scss\n@use '@carbon/react/scss/spacing' as *;\n@use '@carbon/react/scss/breakpoint' as *;\n@use '@carbon/react/scss/theme' as *;\n```\n\nWe will then add the following styles to the same file to style our info cards.\n\n```scss path=src/components/Info/_info.scss\n.info-card {\n margin-top: $spacing-09;\n display: flex;\n flex-direction: column;\n padding-left: 1rem;\n\n svg {\n margin-top: $spacing-09;\n }\n\n @include breakpoint(sm) {\n padding-left: 0;\n }\n\n div {\n flex-grow: 1; // fill space so icons are bottom aligned\n }\n\n // top border in only small breakpoints to prevent overrides\n @include breakpoint-down(lg) {\n padding-left: 0;\n margin-top: 0;\n flex-direction: row-reverse;\n\n &:not(:nth-child(2)) {\n padding-top: $spacing-10;\n }\n\n svg {\n margin-top: -0.25rem;\n margin-right: 2rem;\n min-width: 48px;\n min-height: 48px;\n }\n }\n\n @include breakpoint(lg) {\n margin-top: 0;\n padding-left: 0;\n\n &:not(:nth-child(2)) {\n border-left: 1px solid $border-subtle-01;\n padding-left: 1rem;\n }\n\n svg {\n margin-top: $spacing-12;\n }\n }\n\n // left border in all items\n @include breakpoint(xlg) {\n margin-top: 0;\n border-left: 1px solid $border-subtle-01;\n padding-left: 1rem;\n\n svg {\n margin-top: $spacing-12;\n }\n }\n}\n```\n\nOnce you save, go ahead and resize your browser to see the responsive layout at\nthe different breakpoints. Make sure to review these color and spacing tokens.\nThere are also a few breakpoint mixins that may be new to you.\n\n### Type\n\nOur `InfoCard` headings look to be too small. We need to increase their font\nsizes according to the design spec. Lets update the heading with the following\ntype style:\n\n```scss path=src/components/Info/_info.scss\n.info-card__heading {\n @include type-style('productive-heading-03');\n}\n```\n\nAlso, the design has the last word in each subheading as bold. To accomplish\nthat, add this helper function after the import in `Info.js`.\n\n```javascript path=src/components/Info/Info.js\n// Take in a phrase and separate the third word in an array\nfunction createArrayFromPhrase(phrase) {\n const splitPhrase = phrase.split(' ');\n const thirdWord = splitPhrase.pop();\n return [splitPhrase.join(' '), thirdWord];\n}\n```\n\nThen, update `InfoCard` to use `createArrayFromPhrase`.\n\n```javascript path=src/components/Info/Info.js\nconst InfoCard = (props) => {\n const splitHeading = createArrayFromPhrase(props.heading);\n\n return (\n \n
\n {`${splitHeading[0]} `}\n {splitHeading[1]}\n
\n
{props.body}
\n {props.icon()}\n \n );\n};\n```\n\nFinally, add the declaration block in `_info.scss` to set `InfoCard` body copy\nstyles and to bottom-align the pictograms.\n\n```scss path=src/components/Info/_info.scss\n.info-card__body {\n margin-top: $spacing-06;\n flex-grow: 1; // fill space so pictograms are bottom aligned\n @include type-style('body-long-01');\n\n // prevent large line lengths between small and medium viewports\n @include breakpoint-between(321px, md) {\n max-width: 75%;\n }\n}\n```\n\n## Check accessibility\n\nWe've added new markup and styles, so it's a good practice to check\n[Equal Access Checker](https://www.ibm.com/able/toolkit/tools/) and make sure\nour rendered markup is on the right track for accessibility.\n\nWith the browser extension installed, Chrome in this example, open Dev Tools and\nrun Accessibility Assessment.\n\n## Submit pull request\n\nWe're going to submit a pull request to verify completion of this tutorial step.\n\n### Continuous integration (CI) check\n\nRun the CI check to make sure we're all set to submit a pull request.\n\n```bash\nyarn ci-check\n```\n\n\n\n**Note:** Having issues running the CI check?\n[Step 1]()\nhas troubleshooting notes that may help.\n\n\n\n### Git commit and push\n\nBefore we can create a pull request, format your code, then stage and commit all\nof your changes:\n\n```bash\nyarn format\ngit add --all && git commit -m \"feat(tutorial): complete step 4\"\n```\n\nThen, push to your repository:\n\n```bash\ngit push origin v11-next-step-4\n```\n\n\n\n**Note:** Having issues pushing your changes?\n[Step 1](/developing/react-tutorial/step-1#git-commit-and-push) has\ntroubleshooting notes that may help.\n\n\n\n### Pull request (PR)\n\nFinally, visit\n[carbon-tutorial-nextjs](https://github.com/carbon-design-system/carbon-tutorial-nextjs)\nto \"Compare & pull request\". In doing so, make sure that you are comparing to\n`v11-next-step-4` into `base: v11-next-step-4`.\n\n\n\n**Note:** Expect your tutorial step PRs to be reviewed by the Carbon team but\nnot merged. We'll close your PR so we can keep the repository's remote branches\npristine and ready for the next person!\n\n\n\n\n\n**Note:** If your PR fails the CircleCI test with the error\n`Can't make a request in offline mode`, try running the following command:\n`rm -rf .yarn-offline-mirror node_modules && yarn cache clean && yarn install`.\nAdd and commit the changes once this completes, and try pushing again.\n\n\n","type":"Mdx","contentDigest":"7e616c2257a4cc2cf2272a48fa8ff6ed","owner":"gatsby-plugin-mdx","counter":5286},"frontmatter":{"title":"4. Creating components","description":"Welcome to Carbon! This tutorial will guide you in creating a React app using Next.js with the Carbon Design System.","tabs":["Overview","Step 1","Step 2","Step 3","Step 4","Step 5","Wrapping up","FAQ"]},"exports":{},"rawBody":"---\ntitle: 4. Creating components\ndescription:\n Welcome to Carbon! This tutorial will guide you in creating a React app using\n Next.js with the Carbon Design System.\ntabs:\n [\n 'Overview',\n 'Step 1',\n 'Step 2',\n 'Step 3',\n 'Step 4',\n 'Step 5',\n 'Wrapping up',\n 'FAQ',\n ]\n---\n\nimport Preview from 'components/Preview';\n\n\n\nWith two pages comprised entirely of Carbon components, let's revisit the\nlanding page and build a couple components of our own by using Carbon pictograms\nand tokens.\n\n\n\n\n\nFork, clone and branch\nReview design\nCreate components\nUse components\nAdd styling\nCheck accessibility\nSubmit pull request\n\n\n\n## Preview\n\nCarbon provides a solid foundation for building web applications through its\ncolor palette, layout, spacing, type, as well as common building blocks in the\nform of components. So far, we've only used Carbon components to build out two\npages.\n\nNext, we're going to use Carbon assets to build application-specific components.\nWe'll do so by including accessibility and responsive considerations all\nthroughout.\n\nA\n[preview](https://carbon-tutorial-nextjs-git-v11-next-step-5-carbon-design-system.vercel.app/)\nof what you'll build (see bottom of page):\n\n\n\n## Fork, clone and branch\n\nThis tutorial has an accompanying GitHub repository called\n[carbon-tutorial-nextjs](https://github.com/carbon-design-system/carbon-tutorial-nextjs)\nthat we'll use as a starting point for each step. If you haven't forked and\ncloned that repository yet, and haven't added the upstream remote, go ahead and\ndo so by following the\n[step 1 instructions](/developing/react-tutorial/step-1#fork-clone-and-branch).\n\n### Branch\n\nWith your repository all set up, let's check out the branch for this tutorial\nstep's starting point.\n\n```bash\ngit fetch upstream\ngit checkout -b v11-next-step-4 upstream/v11-next-step-4\n```\n\n\n\n**Note:** This builds on top of step 3, but be sure to check out the upstream\nstep 4 branch because it includes the static assets required to get through this\nstep.\n\n\n\n### Build and start app\n\nInstall the app's dependencies (in case you're starting fresh in your current\ndirectory and not continuing from the previous step):\n\n```bash\nyarn\n```\n\nThen, start the app:\n\n```bash\nyarn dev\n```\n\nYou should see something similar to where the\n[previous step](/developing/react-tutorial/step-3) left off.\n\n## Review design\n\nHere's what we're building – an informational section that has a heading and\nthree subheadings. Each subheading has accompanying copy and a pictogram. We'll\nassume that this informational section is used elsewhere on the site, meaning\nit's a great opportunity to build it as a reusable component. As for naming,\nwe'll call it an `InfoSection` with three `InfoCard`s as children.\n\n\n\n
Info section layout
\n\n## Create components\n\nFirst we need files for the components, so create an `Info` folder in\n`src/components`. Even though we're building multiple components, their names\nall start with `Info`, so it makes sense to have them share one folder in\ncomponents. Create these files:\n\n### Add files\n\n```bash\nsrc/components/Info\n├──_info.scss\n└──Info.js\n```\n\nImport `_info.scss` in `app.scss` after all of the `tutorial-header.scss`\nimport.\n\n```scss path=src/app/globals.scss\n@use '@/components/Info/info';\n```\n\n### InfoSection component\n\nLet's create the parent component that includes the \"The Principles\" heading.\nThat markup currently looks like this in `LandingPage`:\n\n```jsx path=src/app/home/page.js\n\n \n \n
The Principles
\n \n \n Carbon is Open\n \n \n Carbon is Modular\n \n \n Carbon is Consistent\n \n \n\n```\n\nWe want to do a few things when abstracting it to a component. First, we only\nwant this component's class names; we don't want to include `landing-page__r3`\nas that's specific to the landing page. For that we'll use React `props` so we\ncan pass in and use `props.className`.\n\nWe'll also:\n\n- Add component class names like `info-section`, `info-card`, and\n `info-section__heading`\n- We will be using the `Grid` and `Column` components\n- Replace `The Principles` with `{props.heading}`\n- Replace columns 2 - 4 with `{props.children}`\n\nUsing `props` we can render any heading and any number of children components\n(`InfoCard` that we'll build soon.)\n\n```javascript path=src/components/Info/Info.js\nimport { Grid, Column } from '@carbon/react';\n\nconst InfoSection = (props) => (\n \n \n
{props.heading}
\n \n {props.children}\n \n);\n```\n\nAt this point let's import our needed styles and add styling for the new class\nnames that we just added.\n\n```scss path=src/components/Info/_info.scss\n@use '@carbon/react/scss/type' as *;\n\n.info-section__heading {\n @include type-style('heading-01');\n padding-bottom: $spacing-08;\n}\n```\n\n### InfoCard component\n\nNext up we're going to build a component for columns 2 - 4, which currently\nlooks like `Carbon is Open`. At the bottom of\n`Info.js`, add:\n\n```javascript path=src/components/Info/Info.js\nconst InfoCard = (props) => {\n return (\n \n
\n
\n {`${splitHeading[0]} `}\n {splitHeading[1]}\n
\n
{props.body}
\n
\n {props.icon()}\n \n );\n};\n\nexport { InfoSection, InfoCard };\n```\n\n\n\n**Note:** Make sure to export the two components!\n\n\n\nIn doing so, we:\n\n- Added `info-card` classes\n- Used `props` to render the heading, body copy, and icon\n- Set columns to match the grid\n\n## Use components\n\nNothing is styled yet, but with our components built let's put them to use. In\n`LandingPage`, import the components towards the top of the file.\n\n```javascript path=src/app/home/page.js\nimport { InfoSection, InfoCard } from '@/components/Info/Info';\n```\n\nNext, we will install the pictograms we will use in the header.\n\n```bash\nyarn add @carbon/pictograms-react\n```\n\nWhile we're at the top of `LandingPage`, import the pictograms that we'll need\nas well.\n\n```javascript path=src/app/home/page.js\nimport {\n Advocate,\n Globe,\n AcceleratingTransformation,\n} from '@carbon/pictograms-react';\n```\n\nWith everything imported, replace the current:\n\n```jsx path=src/app/home/page.js\n\n \n \n \n
The Principles
\n \n \n Carbon is Open\n \n \n Carbon is Modular\n \n \n Carbon is Consistent\n \n \n \n\n```\n\nWith the new components:\n\n```javascript path=src/app/home/page.js\n\n }\n />\n }\n />\n }\n />\n\n```\n\n\n\n**Note:** Now is a good time to resize your browser from phone to large viewport\nwidths to see how the responsive grid is working before we add further styling.\n\n\n\n## Add styling\n\nHere's our design showing the spacing tokens that we need to add. We also need\nto set type style and borders.\n\n\n\n### Layout\n\nStarting with layout, import the following carbon styles to\n`src/components/Info/_info.scss`. Make sure to import the needed carbon styles.\n\n```scss path=src/components/Info/_info.scss\n@use '@carbon/react/scss/spacing' as *;\n@use '@carbon/react/scss/breakpoint' as *;\n@use '@carbon/react/scss/theme' as *;\n```\n\nWe will then add the following styles to the same file to style our info cards.\n\n```scss path=src/components/Info/_info.scss\n.info-card {\n margin-top: $spacing-09;\n display: flex;\n flex-direction: column;\n padding-left: 1rem;\n\n svg {\n margin-top: $spacing-09;\n }\n\n @include breakpoint(sm) {\n padding-left: 0;\n }\n\n div {\n flex-grow: 1; // fill space so icons are bottom aligned\n }\n\n // top border in only small breakpoints to prevent overrides\n @include breakpoint-down(lg) {\n padding-left: 0;\n margin-top: 0;\n flex-direction: row-reverse;\n\n &:not(:nth-child(2)) {\n padding-top: $spacing-10;\n }\n\n svg {\n margin-top: -0.25rem;\n margin-right: 2rem;\n min-width: 48px;\n min-height: 48px;\n }\n }\n\n @include breakpoint(lg) {\n margin-top: 0;\n padding-left: 0;\n\n &:not(:nth-child(2)) {\n border-left: 1px solid $border-subtle-01;\n padding-left: 1rem;\n }\n\n svg {\n margin-top: $spacing-12;\n }\n }\n\n // left border in all items\n @include breakpoint(xlg) {\n margin-top: 0;\n border-left: 1px solid $border-subtle-01;\n padding-left: 1rem;\n\n svg {\n margin-top: $spacing-12;\n }\n }\n}\n```\n\nOnce you save, go ahead and resize your browser to see the responsive layout at\nthe different breakpoints. Make sure to review these color and spacing tokens.\nThere are also a few breakpoint mixins that may be new to you.\n\n### Type\n\nOur `InfoCard` headings look to be too small. We need to increase their font\nsizes according to the design spec. Lets update the heading with the following\ntype style:\n\n```scss path=src/components/Info/_info.scss\n.info-card__heading {\n @include type-style('productive-heading-03');\n}\n```\n\nAlso, the design has the last word in each subheading as bold. To accomplish\nthat, add this helper function after the import in `Info.js`.\n\n```javascript path=src/components/Info/Info.js\n// Take in a phrase and separate the third word in an array\nfunction createArrayFromPhrase(phrase) {\n const splitPhrase = phrase.split(' ');\n const thirdWord = splitPhrase.pop();\n return [splitPhrase.join(' '), thirdWord];\n}\n```\n\nThen, update `InfoCard` to use `createArrayFromPhrase`.\n\n```javascript path=src/components/Info/Info.js\nconst InfoCard = (props) => {\n const splitHeading = createArrayFromPhrase(props.heading);\n\n return (\n \n
\n {`${splitHeading[0]} `}\n {splitHeading[1]}\n
\n
{props.body}
\n {props.icon()}\n \n );\n};\n```\n\nFinally, add the declaration block in `_info.scss` to set `InfoCard` body copy\nstyles and to bottom-align the pictograms.\n\n```scss path=src/components/Info/_info.scss\n.info-card__body {\n margin-top: $spacing-06;\n flex-grow: 1; // fill space so pictograms are bottom aligned\n @include type-style('body-long-01');\n\n // prevent large line lengths between small and medium viewports\n @include breakpoint-between(321px, md) {\n max-width: 75%;\n }\n}\n```\n\n## Check accessibility\n\nWe've added new markup and styles, so it's a good practice to check\n[Equal Access Checker](https://www.ibm.com/able/toolkit/tools/) and make sure\nour rendered markup is on the right track for accessibility.\n\nWith the browser extension installed, Chrome in this example, open Dev Tools and\nrun Accessibility Assessment.\n\n## Submit pull request\n\nWe're going to submit a pull request to verify completion of this tutorial step.\n\n### Continuous integration (CI) check\n\nRun the CI check to make sure we're all set to submit a pull request.\n\n```bash\nyarn ci-check\n```\n\n\n\n**Note:** Having issues running the CI check?\n[Step 1]()\nhas troubleshooting notes that may help.\n\n\n\n### Git commit and push\n\nBefore we can create a pull request, format your code, then stage and commit all\nof your changes:\n\n```bash\nyarn format\ngit add --all && git commit -m \"feat(tutorial): complete step 4\"\n```\n\nThen, push to your repository:\n\n```bash\ngit push origin v11-next-step-4\n```\n\n\n\n**Note:** Having issues pushing your changes?\n[Step 1](/developing/react-tutorial/step-1#git-commit-and-push) has\ntroubleshooting notes that may help.\n\n\n\n### Pull request (PR)\n\nFinally, visit\n[carbon-tutorial-nextjs](https://github.com/carbon-design-system/carbon-tutorial-nextjs)\nto \"Compare & pull request\". In doing so, make sure that you are comparing to\n`v11-next-step-4` into `base: v11-next-step-4`.\n\n\n\n**Note:** Expect your tutorial step PRs to be reviewed by the Carbon team but\nnot merged. We'll close your PR so we can keep the repository's remote branches\npristine and ready for the next person!\n\n\n\n\n\n**Note:** If your PR fails the CircleCI test with the error\n`Can't make a request in offline mode`, try running the following command:\n`rm -rf .yarn-offline-mirror node_modules && yarn cache clean && yarn install`.\nAdd and commit the changes once this completes, and try pushing again.\n\n\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/developing/react-tutorial/step-4.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-developing-react-tutorial-step-4-mdx","path":"/developing/react-tutorial/step-4/","result":{"pageContext":{"frontmatter":{"title":"4. Creating components","description":"Welcome to Carbon! This tutorial will guide you in creating a React app using Next.js with the Carbon Design System.","tabs":["Overview","Step 1","Step 2","Step 3","Step 4","Step 5","Wrapping up","FAQ"]},"relativePagePath":"/developing/react-tutorial/step-4.mdx","titleType":"prepend","MdxNode":{"id":"5a012e6e-1914-5138-8c7f-fa672debbfb4","children":[],"parent":"c63627a7-f18c-55ae-98d5-929c1520b851","internal":{"content":"---\ntitle: 4. Creating components\ndescription:\n Welcome to Carbon! This tutorial will guide you in creating a React app using\n Next.js with the Carbon Design System.\ntabs:\n [\n 'Overview',\n 'Step 1',\n 'Step 2',\n 'Step 3',\n 'Step 4',\n 'Step 5',\n 'Wrapping up',\n 'FAQ',\n ]\n---\n\nimport Preview from 'components/Preview';\n\n\n\nWith two pages comprised entirely of Carbon components, let's revisit the\nlanding page and build a couple components of our own by using Carbon pictograms\nand tokens.\n\n\n\n\n\nFork, clone and branch\nReview design\nCreate components\nUse components\nAdd styling\nCheck accessibility\nSubmit pull request\n\n\n\n## Preview\n\nCarbon provides a solid foundation for building web applications through its\ncolor palette, layout, spacing, type, as well as common building blocks in the\nform of components. So far, we've only used Carbon components to build out two\npages.\n\nNext, we're going to use Carbon assets to build application-specific components.\nWe'll do so by including accessibility and responsive considerations all\nthroughout.\n\nA\n[preview](https://carbon-tutorial-nextjs-git-v11-next-step-5-carbon-design-system.vercel.app/)\nof what you'll build (see bottom of page):\n\n\n\n## Fork, clone and branch\n\nThis tutorial has an accompanying GitHub repository called\n[carbon-tutorial-nextjs](https://github.com/carbon-design-system/carbon-tutorial-nextjs)\nthat we'll use as a starting point for each step. If you haven't forked and\ncloned that repository yet, and haven't added the upstream remote, go ahead and\ndo so by following the\n[step 1 instructions](/developing/react-tutorial/step-1#fork-clone-and-branch).\n\n### Branch\n\nWith your repository all set up, let's check out the branch for this tutorial\nstep's starting point.\n\n```bash\ngit fetch upstream\ngit checkout -b v11-next-step-4 upstream/v11-next-step-4\n```\n\n\n\n**Note:** This builds on top of step 3, but be sure to check out the upstream\nstep 4 branch because it includes the static assets required to get through this\nstep.\n\n\n\n### Build and start app\n\nInstall the app's dependencies (in case you're starting fresh in your current\ndirectory and not continuing from the previous step):\n\n```bash\nyarn\n```\n\nThen, start the app:\n\n```bash\nyarn dev\n```\n\nYou should see something similar to where the\n[previous step](/developing/react-tutorial/step-3) left off.\n\n## Review design\n\nHere's what we're building – an informational section that has a heading and\nthree subheadings. Each subheading has accompanying copy and a pictogram. We'll\nassume that this informational section is used elsewhere on the site, meaning\nit's a great opportunity to build it as a reusable component. As for naming,\nwe'll call it an `InfoSection` with three `InfoCard`s as children.\n\n\n\n
Info section layout
\n\n## Create components\n\nFirst we need files for the components, so create an `Info` folder in\n`src/components`. Even though we're building multiple components, their names\nall start with `Info`, so it makes sense to have them share one folder in\ncomponents. Create these files:\n\n### Add files\n\n```bash\nsrc/components/Info\n├──_info.scss\n└──Info.js\n```\n\nImport `_info.scss` in `app.scss` after all of the `tutorial-header.scss`\nimport.\n\n```scss path=src/app/globals.scss\n@use '@/components/Info/info';\n```\n\n### InfoSection component\n\nLet's create the parent component that includes the \"The Principles\" heading.\nThat markup currently looks like this in `LandingPage`:\n\n```jsx path=src/app/home/page.js\n\n \n \n
The Principles
\n \n \n Carbon is Open\n \n \n Carbon is Modular\n \n \n Carbon is Consistent\n \n \n\n```\n\nWe want to do a few things when abstracting it to a component. First, we only\nwant this component's class names; we don't want to include `landing-page__r3`\nas that's specific to the landing page. For that we'll use React `props` so we\ncan pass in and use `props.className`.\n\nWe'll also:\n\n- Add component class names like `info-section`, `info-card`, and\n `info-section__heading`\n- We will be using the `Grid` and `Column` components\n- Replace `The Principles` with `{props.heading}`\n- Replace columns 2 - 4 with `{props.children}`\n\nUsing `props` we can render any heading and any number of children components\n(`InfoCard` that we'll build soon.)\n\n```javascript path=src/components/Info/Info.js\nimport { Grid, Column } from '@carbon/react';\n\nconst InfoSection = (props) => (\n \n \n
{props.heading}
\n \n {props.children}\n \n);\n```\n\nAt this point let's import our needed styles and add styling for the new class\nnames that we just added.\n\n```scss path=src/components/Info/_info.scss\n@use '@carbon/react/scss/type' as *;\n\n.info-section__heading {\n @include type-style('heading-01');\n padding-bottom: $spacing-08;\n}\n```\n\n### InfoCard component\n\nNext up we're going to build a component for columns 2 - 4, which currently\nlooks like `Carbon is Open`. At the bottom of\n`Info.js`, add:\n\n```javascript path=src/components/Info/Info.js\nconst InfoCard = (props) => {\n return (\n \n
\n
\n {`${splitHeading[0]} `}\n {splitHeading[1]}\n
\n
{props.body}
\n
\n {props.icon()}\n \n );\n};\n\nexport { InfoSection, InfoCard };\n```\n\n\n\n**Note:** Make sure to export the two components!\n\n\n\nIn doing so, we:\n\n- Added `info-card` classes\n- Used `props` to render the heading, body copy, and icon\n- Set columns to match the grid\n\n## Use components\n\nNothing is styled yet, but with our components built let's put them to use. In\n`LandingPage`, import the components towards the top of the file.\n\n```javascript path=src/app/home/page.js\nimport { InfoSection, InfoCard } from '@/components/Info/Info';\n```\n\nNext, we will install the pictograms we will use in the header.\n\n```bash\nyarn add @carbon/pictograms-react\n```\n\nWhile we're at the top of `LandingPage`, import the pictograms that we'll need\nas well.\n\n```javascript path=src/app/home/page.js\nimport {\n Advocate,\n Globe,\n AcceleratingTransformation,\n} from '@carbon/pictograms-react';\n```\n\nWith everything imported, replace the current:\n\n```jsx path=src/app/home/page.js\n\n \n \n \n
The Principles
\n \n \n Carbon is Open\n \n \n Carbon is Modular\n \n \n Carbon is Consistent\n \n \n \n\n```\n\nWith the new components:\n\n```javascript path=src/app/home/page.js\n\n }\n />\n }\n />\n }\n />\n\n```\n\n\n\n**Note:** Now is a good time to resize your browser from phone to large viewport\nwidths to see how the responsive grid is working before we add further styling.\n\n\n\n## Add styling\n\nHere's our design showing the spacing tokens that we need to add. We also need\nto set type style and borders.\n\n\n\n### Layout\n\nStarting with layout, import the following carbon styles to\n`src/components/Info/_info.scss`. Make sure to import the needed carbon styles.\n\n```scss path=src/components/Info/_info.scss\n@use '@carbon/react/scss/spacing' as *;\n@use '@carbon/react/scss/breakpoint' as *;\n@use '@carbon/react/scss/theme' as *;\n```\n\nWe will then add the following styles to the same file to style our info cards.\n\n```scss path=src/components/Info/_info.scss\n.info-card {\n margin-top: $spacing-09;\n display: flex;\n flex-direction: column;\n padding-left: 1rem;\n\n svg {\n margin-top: $spacing-09;\n }\n\n @include breakpoint(sm) {\n padding-left: 0;\n }\n\n div {\n flex-grow: 1; // fill space so icons are bottom aligned\n }\n\n // top border in only small breakpoints to prevent overrides\n @include breakpoint-down(lg) {\n padding-left: 0;\n margin-top: 0;\n flex-direction: row-reverse;\n\n &:not(:nth-child(2)) {\n padding-top: $spacing-10;\n }\n\n svg {\n margin-top: -0.25rem;\n margin-right: 2rem;\n min-width: 48px;\n min-height: 48px;\n }\n }\n\n @include breakpoint(lg) {\n margin-top: 0;\n padding-left: 0;\n\n &:not(:nth-child(2)) {\n border-left: 1px solid $border-subtle-01;\n padding-left: 1rem;\n }\n\n svg {\n margin-top: $spacing-12;\n }\n }\n\n // left border in all items\n @include breakpoint(xlg) {\n margin-top: 0;\n border-left: 1px solid $border-subtle-01;\n padding-left: 1rem;\n\n svg {\n margin-top: $spacing-12;\n }\n }\n}\n```\n\nOnce you save, go ahead and resize your browser to see the responsive layout at\nthe different breakpoints. Make sure to review these color and spacing tokens.\nThere are also a few breakpoint mixins that may be new to you.\n\n### Type\n\nOur `InfoCard` headings look to be too small. We need to increase their font\nsizes according to the design spec. Lets update the heading with the following\ntype style:\n\n```scss path=src/components/Info/_info.scss\n.info-card__heading {\n @include type-style('productive-heading-03');\n}\n```\n\nAlso, the design has the last word in each subheading as bold. To accomplish\nthat, add this helper function after the import in `Info.js`.\n\n```javascript path=src/components/Info/Info.js\n// Take in a phrase and separate the third word in an array\nfunction createArrayFromPhrase(phrase) {\n const splitPhrase = phrase.split(' ');\n const thirdWord = splitPhrase.pop();\n return [splitPhrase.join(' '), thirdWord];\n}\n```\n\nThen, update `InfoCard` to use `createArrayFromPhrase`.\n\n```javascript path=src/components/Info/Info.js\nconst InfoCard = (props) => {\n const splitHeading = createArrayFromPhrase(props.heading);\n\n return (\n \n
\n {`${splitHeading[0]} `}\n {splitHeading[1]}\n
\n
{props.body}
\n {props.icon()}\n \n );\n};\n```\n\nFinally, add the declaration block in `_info.scss` to set `InfoCard` body copy\nstyles and to bottom-align the pictograms.\n\n```scss path=src/components/Info/_info.scss\n.info-card__body {\n margin-top: $spacing-06;\n flex-grow: 1; // fill space so pictograms are bottom aligned\n @include type-style('body-long-01');\n\n // prevent large line lengths between small and medium viewports\n @include breakpoint-between(321px, md) {\n max-width: 75%;\n }\n}\n```\n\n## Check accessibility\n\nWe've added new markup and styles, so it's a good practice to check\n[Equal Access Checker](https://www.ibm.com/able/toolkit/tools/) and make sure\nour rendered markup is on the right track for accessibility.\n\nWith the browser extension installed, Chrome in this example, open Dev Tools and\nrun Accessibility Assessment.\n\n## Submit pull request\n\nWe're going to submit a pull request to verify completion of this tutorial step.\n\n### Continuous integration (CI) check\n\nRun the CI check to make sure we're all set to submit a pull request.\n\n```bash\nyarn ci-check\n```\n\n\n\n**Note:** Having issues running the CI check?\n[Step 1]()\nhas troubleshooting notes that may help.\n\n\n\n### Git commit and push\n\nBefore we can create a pull request, format your code, then stage and commit all\nof your changes:\n\n```bash\nyarn format\ngit add --all && git commit -m \"feat(tutorial): complete step 4\"\n```\n\nThen, push to your repository:\n\n```bash\ngit push origin v11-next-step-4\n```\n\n\n\n**Note:** Having issues pushing your changes?\n[Step 1](/developing/react-tutorial/step-1#git-commit-and-push) has\ntroubleshooting notes that may help.\n\n\n\n### Pull request (PR)\n\nFinally, visit\n[carbon-tutorial-nextjs](https://github.com/carbon-design-system/carbon-tutorial-nextjs)\nto \"Compare & pull request\". In doing so, make sure that you are comparing to\n`v11-next-step-4` into `base: v11-next-step-4`.\n\n\n\n**Note:** Expect your tutorial step PRs to be reviewed by the Carbon team but\nnot merged. We'll close your PR so we can keep the repository's remote branches\npristine and ready for the next person!\n\n\n\n\n\n**Note:** If your PR fails the CircleCI test with the error\n`Can't make a request in offline mode`, try running the following command:\n`rm -rf .yarn-offline-mirror node_modules && yarn cache clean && yarn install`.\nAdd and commit the changes once this completes, and try pushing again.\n\n\n","type":"Mdx","contentDigest":"7e616c2257a4cc2cf2272a48fa8ff6ed","owner":"gatsby-plugin-mdx","counter":5287},"frontmatter":{"title":"4. Creating components","description":"Welcome to Carbon! This tutorial will guide you in creating a React app using Next.js with the Carbon Design System.","tabs":["Overview","Step 1","Step 2","Step 3","Step 4","Step 5","Wrapping up","FAQ"]},"exports":{},"rawBody":"---\ntitle: 4. Creating components\ndescription:\n Welcome to Carbon! This tutorial will guide you in creating a React app using\n Next.js with the Carbon Design System.\ntabs:\n [\n 'Overview',\n 'Step 1',\n 'Step 2',\n 'Step 3',\n 'Step 4',\n 'Step 5',\n 'Wrapping up',\n 'FAQ',\n ]\n---\n\nimport Preview from 'components/Preview';\n\n\n\nWith two pages comprised entirely of Carbon components, let's revisit the\nlanding page and build a couple components of our own by using Carbon pictograms\nand tokens.\n\n\n\n\n\nFork, clone and branch\nReview design\nCreate components\nUse components\nAdd styling\nCheck accessibility\nSubmit pull request\n\n\n\n## Preview\n\nCarbon provides a solid foundation for building web applications through its\ncolor palette, layout, spacing, type, as well as common building blocks in the\nform of components. So far, we've only used Carbon components to build out two\npages.\n\nNext, we're going to use Carbon assets to build application-specific components.\nWe'll do so by including accessibility and responsive considerations all\nthroughout.\n\nA\n[preview](https://carbon-tutorial-nextjs-git-v11-next-step-5-carbon-design-system.vercel.app/)\nof what you'll build (see bottom of page):\n\n\n\n## Fork, clone and branch\n\nThis tutorial has an accompanying GitHub repository called\n[carbon-tutorial-nextjs](https://github.com/carbon-design-system/carbon-tutorial-nextjs)\nthat we'll use as a starting point for each step. If you haven't forked and\ncloned that repository yet, and haven't added the upstream remote, go ahead and\ndo so by following the\n[step 1 instructions](/developing/react-tutorial/step-1#fork-clone-and-branch).\n\n### Branch\n\nWith your repository all set up, let's check out the branch for this tutorial\nstep's starting point.\n\n```bash\ngit fetch upstream\ngit checkout -b v11-next-step-4 upstream/v11-next-step-4\n```\n\n\n\n**Note:** This builds on top of step 3, but be sure to check out the upstream\nstep 4 branch because it includes the static assets required to get through this\nstep.\n\n\n\n### Build and start app\n\nInstall the app's dependencies (in case you're starting fresh in your current\ndirectory and not continuing from the previous step):\n\n```bash\nyarn\n```\n\nThen, start the app:\n\n```bash\nyarn dev\n```\n\nYou should see something similar to where the\n[previous step](/developing/react-tutorial/step-3) left off.\n\n## Review design\n\nHere's what we're building – an informational section that has a heading and\nthree subheadings. Each subheading has accompanying copy and a pictogram. We'll\nassume that this informational section is used elsewhere on the site, meaning\nit's a great opportunity to build it as a reusable component. As for naming,\nwe'll call it an `InfoSection` with three `InfoCard`s as children.\n\n\n\n
Info section layout
\n\n## Create components\n\nFirst we need files for the components, so create an `Info` folder in\n`src/components`. Even though we're building multiple components, their names\nall start with `Info`, so it makes sense to have them share one folder in\ncomponents. Create these files:\n\n### Add files\n\n```bash\nsrc/components/Info\n├──_info.scss\n└──Info.js\n```\n\nImport `_info.scss` in `app.scss` after all of the `tutorial-header.scss`\nimport.\n\n```scss path=src/app/globals.scss\n@use '@/components/Info/info';\n```\n\n### InfoSection component\n\nLet's create the parent component that includes the \"The Principles\" heading.\nThat markup currently looks like this in `LandingPage`:\n\n```jsx path=src/app/home/page.js\n\n \n \n
The Principles
\n \n \n Carbon is Open\n \n \n Carbon is Modular\n \n \n Carbon is Consistent\n \n \n\n```\n\nWe want to do a few things when abstracting it to a component. First, we only\nwant this component's class names; we don't want to include `landing-page__r3`\nas that's specific to the landing page. For that we'll use React `props` so we\ncan pass in and use `props.className`.\n\nWe'll also:\n\n- Add component class names like `info-section`, `info-card`, and\n `info-section__heading`\n- We will be using the `Grid` and `Column` components\n- Replace `The Principles` with `{props.heading}`\n- Replace columns 2 - 4 with `{props.children}`\n\nUsing `props` we can render any heading and any number of children components\n(`InfoCard` that we'll build soon.)\n\n```javascript path=src/components/Info/Info.js\nimport { Grid, Column } from '@carbon/react';\n\nconst InfoSection = (props) => (\n \n \n
{props.heading}
\n \n {props.children}\n \n);\n```\n\nAt this point let's import our needed styles and add styling for the new class\nnames that we just added.\n\n```scss path=src/components/Info/_info.scss\n@use '@carbon/react/scss/type' as *;\n\n.info-section__heading {\n @include type-style('heading-01');\n padding-bottom: $spacing-08;\n}\n```\n\n### InfoCard component\n\nNext up we're going to build a component for columns 2 - 4, which currently\nlooks like `Carbon is Open`. At the bottom of\n`Info.js`, add:\n\n```javascript path=src/components/Info/Info.js\nconst InfoCard = (props) => {\n return (\n \n
\n
\n {`${splitHeading[0]} `}\n {splitHeading[1]}\n
\n
{props.body}
\n
\n {props.icon()}\n \n );\n};\n\nexport { InfoSection, InfoCard };\n```\n\n\n\n**Note:** Make sure to export the two components!\n\n\n\nIn doing so, we:\n\n- Added `info-card` classes\n- Used `props` to render the heading, body copy, and icon\n- Set columns to match the grid\n\n## Use components\n\nNothing is styled yet, but with our components built let's put them to use. In\n`LandingPage`, import the components towards the top of the file.\n\n```javascript path=src/app/home/page.js\nimport { InfoSection, InfoCard } from '@/components/Info/Info';\n```\n\nNext, we will install the pictograms we will use in the header.\n\n```bash\nyarn add @carbon/pictograms-react\n```\n\nWhile we're at the top of `LandingPage`, import the pictograms that we'll need\nas well.\n\n```javascript path=src/app/home/page.js\nimport {\n Advocate,\n Globe,\n AcceleratingTransformation,\n} from '@carbon/pictograms-react';\n```\n\nWith everything imported, replace the current:\n\n```jsx path=src/app/home/page.js\n\n \n \n \n
The Principles
\n \n \n Carbon is Open\n \n \n Carbon is Modular\n \n \n Carbon is Consistent\n \n \n \n\n```\n\nWith the new components:\n\n```javascript path=src/app/home/page.js\n\n }\n />\n }\n />\n }\n />\n\n```\n\n\n\n**Note:** Now is a good time to resize your browser from phone to large viewport\nwidths to see how the responsive grid is working before we add further styling.\n\n\n\n## Add styling\n\nHere's our design showing the spacing tokens that we need to add. We also need\nto set type style and borders.\n\n\n\n### Layout\n\nStarting with layout, import the following carbon styles to\n`src/components/Info/_info.scss`. Make sure to import the needed carbon styles.\n\n```scss path=src/components/Info/_info.scss\n@use '@carbon/react/scss/spacing' as *;\n@use '@carbon/react/scss/breakpoint' as *;\n@use '@carbon/react/scss/theme' as *;\n```\n\nWe will then add the following styles to the same file to style our info cards.\n\n```scss path=src/components/Info/_info.scss\n.info-card {\n margin-top: $spacing-09;\n display: flex;\n flex-direction: column;\n padding-left: 1rem;\n\n svg {\n margin-top: $spacing-09;\n }\n\n @include breakpoint(sm) {\n padding-left: 0;\n }\n\n div {\n flex-grow: 1; // fill space so icons are bottom aligned\n }\n\n // top border in only small breakpoints to prevent overrides\n @include breakpoint-down(lg) {\n padding-left: 0;\n margin-top: 0;\n flex-direction: row-reverse;\n\n &:not(:nth-child(2)) {\n padding-top: $spacing-10;\n }\n\n svg {\n margin-top: -0.25rem;\n margin-right: 2rem;\n min-width: 48px;\n min-height: 48px;\n }\n }\n\n @include breakpoint(lg) {\n margin-top: 0;\n padding-left: 0;\n\n &:not(:nth-child(2)) {\n border-left: 1px solid $border-subtle-01;\n padding-left: 1rem;\n }\n\n svg {\n margin-top: $spacing-12;\n }\n }\n\n // left border in all items\n @include breakpoint(xlg) {\n margin-top: 0;\n border-left: 1px solid $border-subtle-01;\n padding-left: 1rem;\n\n svg {\n margin-top: $spacing-12;\n }\n }\n}\n```\n\nOnce you save, go ahead and resize your browser to see the responsive layout at\nthe different breakpoints. Make sure to review these color and spacing tokens.\nThere are also a few breakpoint mixins that may be new to you.\n\n### Type\n\nOur `InfoCard` headings look to be too small. We need to increase their font\nsizes according to the design spec. Lets update the heading with the following\ntype style:\n\n```scss path=src/components/Info/_info.scss\n.info-card__heading {\n @include type-style('productive-heading-03');\n}\n```\n\nAlso, the design has the last word in each subheading as bold. To accomplish\nthat, add this helper function after the import in `Info.js`.\n\n```javascript path=src/components/Info/Info.js\n// Take in a phrase and separate the third word in an array\nfunction createArrayFromPhrase(phrase) {\n const splitPhrase = phrase.split(' ');\n const thirdWord = splitPhrase.pop();\n return [splitPhrase.join(' '), thirdWord];\n}\n```\n\nThen, update `InfoCard` to use `createArrayFromPhrase`.\n\n```javascript path=src/components/Info/Info.js\nconst InfoCard = (props) => {\n const splitHeading = createArrayFromPhrase(props.heading);\n\n return (\n \n
\n {`${splitHeading[0]} `}\n {splitHeading[1]}\n
\n
{props.body}
\n {props.icon()}\n \n );\n};\n```\n\nFinally, add the declaration block in `_info.scss` to set `InfoCard` body copy\nstyles and to bottom-align the pictograms.\n\n```scss path=src/components/Info/_info.scss\n.info-card__body {\n margin-top: $spacing-06;\n flex-grow: 1; // fill space so pictograms are bottom aligned\n @include type-style('body-long-01');\n\n // prevent large line lengths between small and medium viewports\n @include breakpoint-between(321px, md) {\n max-width: 75%;\n }\n}\n```\n\n## Check accessibility\n\nWe've added new markup and styles, so it's a good practice to check\n[Equal Access Checker](https://www.ibm.com/able/toolkit/tools/) and make sure\nour rendered markup is on the right track for accessibility.\n\nWith the browser extension installed, Chrome in this example, open Dev Tools and\nrun Accessibility Assessment.\n\n## Submit pull request\n\nWe're going to submit a pull request to verify completion of this tutorial step.\n\n### Continuous integration (CI) check\n\nRun the CI check to make sure we're all set to submit a pull request.\n\n```bash\nyarn ci-check\n```\n\n\n\n**Note:** Having issues running the CI check?\n[Step 1]()\nhas troubleshooting notes that may help.\n\n\n\n### Git commit and push\n\nBefore we can create a pull request, format your code, then stage and commit all\nof your changes:\n\n```bash\nyarn format\ngit add --all && git commit -m \"feat(tutorial): complete step 4\"\n```\n\nThen, push to your repository:\n\n```bash\ngit push origin v11-next-step-4\n```\n\n\n\n**Note:** Having issues pushing your changes?\n[Step 1](/developing/react-tutorial/step-1#git-commit-and-push) has\ntroubleshooting notes that may help.\n\n\n\n### Pull request (PR)\n\nFinally, visit\n[carbon-tutorial-nextjs](https://github.com/carbon-design-system/carbon-tutorial-nextjs)\nto \"Compare & pull request\". In doing so, make sure that you are comparing to\n`v11-next-step-4` into `base: v11-next-step-4`.\n\n\n\n**Note:** Expect your tutorial step PRs to be reviewed by the Carbon team but\nnot merged. We'll close your PR so we can keep the repository's remote branches\npristine and ready for the next person!\n\n\n\n\n\n**Note:** If your PR fails the CircleCI test with the error\n`Can't make a request in offline mode`, try running the following command:\n`rm -rf .yarn-offline-mirror node_modules && yarn cache clean && yarn install`.\nAdd and commit the changes once this completes, and try pushing again.\n\n\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/developing/react-tutorial/step-4.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/elements/themes/overview/page-data.json b/page-data/elements/themes/overview/page-data.json
index 2faff24eee8..3aeb84b4614 100644
--- a/page-data/elements/themes/overview/page-data.json
+++ b/page-data/elements/themes/overview/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-elements-themes-overview-mdx","path":"/elements/themes/overview/","result":{"pageContext":{"frontmatter":{"label":"Themes are used to customize component styles to fit the specific aesthetic of a brand or product.","title":"Themes","description":"Themes are used to customize component styles to fit the specific aesthetic of a brand or product.","tabs":["Overview","Code"]},"relativePagePath":"/elements/themes/overview.mdx","titleType":"prepend","MdxNode":{"id":"a1206f5e-f5f3-51ec-96ba-b101e55597d3","children":[],"parent":"a0da6a10-e000-54c5-bab9-cd7eaa42d583","internal":{"content":"---\nlabel:\n Themes are used to customize component styles to fit the specific aesthetic of\n a brand or product.\ntitle: Themes\ndescription:\n Themes are used to customize component styles to fit the specific aesthetic of\n a brand or product.\ntabs: ['Overview', 'Code']\n---\n\n\n\nThemes are used to customize component styles to fit the specific aesthetic of a\nbrand or product.\n\n\n\n\n\nTheming basics\nCustomizing a theme\nTokens\nTheming applied\nResources\n\n\n\n## Theming basics\n\nThemes are used to modify existing components to fit a specific visual style. By\nusing Carbon's tokens, developers can easily customize all of their components\nby changing a set of universal variables, eliminating the need to modify\nindividual components.\n\n### Theme terms\n\n| Term | Definition | |\n| ------- | ------------------------------------------------------------------------------------------------------------ | --- |\n| _Theme_ | A collection of visual attributes assigned to the tokens in order to create a specific aesthetic | |\n| _Token_ | A role-based identifier that assigns a value to a theme. Tokens are universal and never change across themes | |\n| _Role_ | The systematic usage(s) of a token. Roles cannot be changed between themes | |\n| _Value_ | The actual style (such as a hex code) assigned to a token | |\n\n### Default theme\n\nCarbon provides four themes as shown in the\n[color usage](/guidelines/color/usage) page. When `@carbon/react` is downloaded\nand installed, the components are preset to use the default (White) theme.\n\nTo use the Gray 10, Gray 90, or Gray 100 theme as your default instead of White,\nconfigure the sass module using `with`.\n\n```scss\n@use '@carbon/react/scss/themes';\n@use '@carbon/react/scss/theme' with (\n $theme: themes.$g100\n);\n```\n\n## Customizing a theme\n\nThe default theme acts as a starting point; from there designers and developers\ncan define how their own components and styles deviate from the default.\nAltering one, some, or all of the default token values will result in a new\ntheme. The developer configures these new values by configuring the sass module\nusing `with` which can replace the values of the default theme or add new custom\ntokens as well.\n\n```scss\n@use '@carbon/react/scss/theme' with (\n $theme: (\n background: #e2e2e2,\n text-primary: #ffffff,\n custom-token-01: #000000,\n )\n);\n```\n\n## Tokens\n\nWith tokens, the code only needs to be changed in one place to see the effect\nsystem-wide. Tokens are used across all components and help keep global patterns\nand styles consistent.\n\nAll tokens come pre-baked into the Carbon component source code. Tokens are\ndenoted by the prefix `$` (e.g. `$layer-01`). Tokens can also be nested within\nother tokens. For example, `$interactive` calls the IBM Design Language color\npalette token `$blue-60` for its value in the default theme.\n\nThere are several token categories:\n\n- Color\n- Spacing\n- Typography\n- Global\n\nThe full list of tokens available can be found in the source of the\n`@carbon/themes` package per theme for\n[white](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/white.js),\n[g10](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/g10.js),\n[g90](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/g90.js),\nand\n[g100](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/g100.js).\n\n### Color\n\nEach theme is assigned universal color variables, which are determined by common\nroles and usage. This allows for uniform color application across themes while\nmaintaining full styling flexibility. For more information, see the\n[color](/guidelines/color/overview) page.\n\n### Spacing\n\nUse the spacing scale when building individual components. It includes small\nincrements needed to create appropriate spatial relationships for detail-level\ndesigns. For more information, see the [spacing](/guidelines/spacing/overview/)\npage.\n\n### Typography\n\nTypography has four categories of type styles (universal, productive, editorial,\nand additional) that can be customized through tokens. These tokens are used\nboth within components and across layouts. Type tokens are determined by their\nrole across the system. For more information, see the\n[typography](/guidelines/typography/overview/) page.\n\n### Global\n\nThe other categories are global and component-specific variables. These control\nmore general styling of components, such as layer usage or border width. The\nfull list of tokens available can be found in\n[the source of the `@carbon/themes` package](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/white.js).\n\n## Theming applied\n\nThe following example demonstrates the relationship between the different\nthemes. Each theme shares the same variables and roles, with only the value\nchanging for each individual theme.\n\n\n\n\n\n\n\n\n\n| Key | Token | Role | White theme value | Gray 100 theme value |\n| --- | ----------------- | ------------------- | ----------------- | -------------------- |\n| 1 | `$text-secondary` | Label color | Gray 70 | Gray 30 |\n| 2 | `$text-primary` | Primary text color | Gray 100 | Gray 10 |\n| 3 | `$border-strong` | Border bottom color | Gray 50 | Gray 60 |\n| 4 | `$icon-primary` | Primary icon color | Gray 100 | Gray 10 |\n| 5 | `$field-01` | Field color | Gray 10 | Gray 90 |\n| 6 | `$background` | Page background | White | Gray 100 |\n\n## Resources\n\n\n \n\n\n\n \n\n","type":"Mdx","contentDigest":"46ed525eeb92298de9d33a36953cb8a6","owner":"gatsby-plugin-mdx","counter":5316},"frontmatter":{"label":"Themes are used to customize component styles to fit the specific aesthetic of a brand or product.","title":"Themes","description":"Themes are used to customize component styles to fit the specific aesthetic of a brand or product.","tabs":["Overview","Code"]},"exports":{},"rawBody":"---\nlabel:\n Themes are used to customize component styles to fit the specific aesthetic of\n a brand or product.\ntitle: Themes\ndescription:\n Themes are used to customize component styles to fit the specific aesthetic of\n a brand or product.\ntabs: ['Overview', 'Code']\n---\n\n\n\nThemes are used to customize component styles to fit the specific aesthetic of a\nbrand or product.\n\n\n\n\n\nTheming basics\nCustomizing a theme\nTokens\nTheming applied\nResources\n\n\n\n## Theming basics\n\nThemes are used to modify existing components to fit a specific visual style. By\nusing Carbon's tokens, developers can easily customize all of their components\nby changing a set of universal variables, eliminating the need to modify\nindividual components.\n\n### Theme terms\n\n| Term | Definition | |\n| ------- | ------------------------------------------------------------------------------------------------------------ | --- |\n| _Theme_ | A collection of visual attributes assigned to the tokens in order to create a specific aesthetic | |\n| _Token_ | A role-based identifier that assigns a value to a theme. Tokens are universal and never change across themes | |\n| _Role_ | The systematic usage(s) of a token. Roles cannot be changed between themes | |\n| _Value_ | The actual style (such as a hex code) assigned to a token | |\n\n### Default theme\n\nCarbon provides four themes as shown in the\n[color usage](/guidelines/color/usage) page. When `@carbon/react` is downloaded\nand installed, the components are preset to use the default (White) theme.\n\nTo use the Gray 10, Gray 90, or Gray 100 theme as your default instead of White,\nconfigure the sass module using `with`.\n\n```scss\n@use '@carbon/react/scss/themes';\n@use '@carbon/react/scss/theme' with (\n $theme: themes.$g100\n);\n```\n\n## Customizing a theme\n\nThe default theme acts as a starting point; from there designers and developers\ncan define how their own components and styles deviate from the default.\nAltering one, some, or all of the default token values will result in a new\ntheme. The developer configures these new values by configuring the sass module\nusing `with` which can replace the values of the default theme or add new custom\ntokens as well.\n\n```scss\n@use '@carbon/react/scss/theme' with (\n $theme: (\n background: #e2e2e2,\n text-primary: #ffffff,\n custom-token-01: #000000,\n )\n);\n```\n\n## Tokens\n\nWith tokens, the code only needs to be changed in one place to see the effect\nsystem-wide. Tokens are used across all components and help keep global patterns\nand styles consistent.\n\nAll tokens come pre-baked into the Carbon component source code. Tokens are\ndenoted by the prefix `$` (e.g. `$layer-01`). Tokens can also be nested within\nother tokens. For example, `$interactive` calls the IBM Design Language color\npalette token `$blue-60` for its value in the default theme.\n\nThere are several token categories:\n\n- Color\n- Spacing\n- Typography\n- Global\n\nThe full list of tokens available can be found in the source of the\n`@carbon/themes` package per theme for\n[white](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/white.js),\n[g10](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/g10.js),\n[g90](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/g90.js),\nand\n[g100](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/g100.js).\n\n### Color\n\nEach theme is assigned universal color variables, which are determined by common\nroles and usage. This allows for uniform color application across themes while\nmaintaining full styling flexibility. For more information, see the\n[color](/guidelines/color/overview) page.\n\n### Spacing\n\nUse the spacing scale when building individual components. It includes small\nincrements needed to create appropriate spatial relationships for detail-level\ndesigns. For more information, see the [spacing](/guidelines/spacing/overview/)\npage.\n\n### Typography\n\nTypography has four categories of type styles (universal, productive, editorial,\nand additional) that can be customized through tokens. These tokens are used\nboth within components and across layouts. Type tokens are determined by their\nrole across the system. For more information, see the\n[typography](/guidelines/typography/overview/) page.\n\n### Global\n\nThe other categories are global and component-specific variables. These control\nmore general styling of components, such as layer usage or border width. The\nfull list of tokens available can be found in\n[the source of the `@carbon/themes` package](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/white.js).\n\n## Theming applied\n\nThe following example demonstrates the relationship between the different\nthemes. Each theme shares the same variables and roles, with only the value\nchanging for each individual theme.\n\n\n\n\n\n\n\n\n\n| Key | Token | Role | White theme value | Gray 100 theme value |\n| --- | ----------------- | ------------------- | ----------------- | -------------------- |\n| 1 | `$text-secondary` | Label color | Gray 70 | Gray 30 |\n| 2 | `$text-primary` | Primary text color | Gray 100 | Gray 10 |\n| 3 | `$border-strong` | Border bottom color | Gray 50 | Gray 60 |\n| 4 | `$icon-primary` | Primary icon color | Gray 100 | Gray 10 |\n| 5 | `$field-01` | Field color | Gray 10 | Gray 90 |\n| 6 | `$background` | Page background | White | Gray 100 |\n\n## Resources\n\n\n \n\n\n\n \n\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/elements/themes/overview.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-elements-themes-overview-mdx","path":"/elements/themes/overview/","result":{"pageContext":{"frontmatter":{"label":"Themes are used to customize component styles to fit the specific aesthetic of a brand or product.","title":"Themes","description":"Themes are used to customize component styles to fit the specific aesthetic of a brand or product.","tabs":["Overview","Code"]},"relativePagePath":"/elements/themes/overview.mdx","titleType":"prepend","MdxNode":{"id":"a1206f5e-f5f3-51ec-96ba-b101e55597d3","children":[],"parent":"a0da6a10-e000-54c5-bab9-cd7eaa42d583","internal":{"content":"---\nlabel:\n Themes are used to customize component styles to fit the specific aesthetic of\n a brand or product.\ntitle: Themes\ndescription:\n Themes are used to customize component styles to fit the specific aesthetic of\n a brand or product.\ntabs: ['Overview', 'Code']\n---\n\n\n\nThemes are used to customize component styles to fit the specific aesthetic of a\nbrand or product.\n\n\n\n\n\nTheming basics\nCustomizing a theme\nTokens\nTheming applied\nResources\n\n\n\n## Theming basics\n\nThemes are used to modify existing components to fit a specific visual style. By\nusing Carbon's tokens, developers can easily customize all of their components\nby changing a set of universal variables, eliminating the need to modify\nindividual components.\n\n### Theme terms\n\n| Term | Definition | |\n| ------- | ------------------------------------------------------------------------------------------------------------ | --- |\n| _Theme_ | A collection of visual attributes assigned to the tokens in order to create a specific aesthetic | |\n| _Token_ | A role-based identifier that assigns a value to a theme. Tokens are universal and never change across themes | |\n| _Role_ | The systematic usage(s) of a token. Roles cannot be changed between themes | |\n| _Value_ | The actual style (such as a hex code) assigned to a token | |\n\n### Default theme\n\nCarbon provides four themes as shown in the\n[color usage](/guidelines/color/usage) page. When `@carbon/react` is downloaded\nand installed, the components are preset to use the default (White) theme.\n\nTo use the Gray 10, Gray 90, or Gray 100 theme as your default instead of White,\nconfigure the sass module using `with`.\n\n```scss\n@use '@carbon/react/scss/themes';\n@use '@carbon/react/scss/theme' with (\n $theme: themes.$g100\n);\n```\n\n## Customizing a theme\n\nThe default theme acts as a starting point; from there designers and developers\ncan define how their own components and styles deviate from the default.\nAltering one, some, or all of the default token values will result in a new\ntheme. The developer configures these new values by configuring the sass module\nusing `with` which can replace the values of the default theme or add new custom\ntokens as well.\n\n```scss\n@use '@carbon/react/scss/theme' with (\n $theme: (\n background: #e2e2e2,\n text-primary: #ffffff,\n custom-token-01: #000000,\n )\n);\n```\n\n## Tokens\n\nWith tokens, the code only needs to be changed in one place to see the effect\nsystem-wide. Tokens are used across all components and help keep global patterns\nand styles consistent.\n\nAll tokens come pre-baked into the Carbon component source code. Tokens are\ndenoted by the prefix `$` (e.g. `$layer-01`). Tokens can also be nested within\nother tokens. For example, `$interactive` calls the IBM Design Language color\npalette token `$blue-60` for its value in the default theme.\n\nThere are several token categories:\n\n- Color\n- Spacing\n- Typography\n- Global\n\nThe full list of tokens available can be found in the source of the\n`@carbon/themes` package per theme for\n[white](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/white.js),\n[g10](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/g10.js),\n[g90](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/g90.js),\nand\n[g100](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/g100.js).\n\n### Color\n\nEach theme is assigned universal color variables, which are determined by common\nroles and usage. This allows for uniform color application across themes while\nmaintaining full styling flexibility. For more information, see the\n[color](/guidelines/color/overview) page.\n\n### Spacing\n\nUse the spacing scale when building individual components. It includes small\nincrements needed to create appropriate spatial relationships for detail-level\ndesigns. For more information, see the [spacing](/guidelines/spacing/overview/)\npage.\n\n### Typography\n\nTypography has four categories of type styles (universal, productive, editorial,\nand additional) that can be customized through tokens. These tokens are used\nboth within components and across layouts. Type tokens are determined by their\nrole across the system. For more information, see the\n[typography](/guidelines/typography/overview/) page.\n\n### Global\n\nThe other categories are global and component-specific variables. These control\nmore general styling of components, such as layer usage or border width. The\nfull list of tokens available can be found in\n[the source of the `@carbon/themes` package](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/white.js).\n\n## Theming applied\n\nThe following example demonstrates the relationship between the different\nthemes. Each theme shares the same variables and roles, with only the value\nchanging for each individual theme.\n\n\n\n\n\n\n\n\n\n| Key | Token | Role | White theme value | Gray 100 theme value |\n| --- | ----------------- | ------------------- | ----------------- | -------------------- |\n| 1 | `$text-secondary` | Label color | Gray 70 | Gray 30 |\n| 2 | `$text-primary` | Primary text color | Gray 100 | Gray 10 |\n| 3 | `$border-strong` | Border bottom color | Gray 50 | Gray 60 |\n| 4 | `$icon-primary` | Primary icon color | Gray 100 | Gray 10 |\n| 5 | `$field-01` | Field color | Gray 10 | Gray 90 |\n| 6 | `$background` | Page background | White | Gray 100 |\n\n## Resources\n\n\n \n\n\n\n \n\n","type":"Mdx","contentDigest":"46ed525eeb92298de9d33a36953cb8a6","owner":"gatsby-plugin-mdx","counter":5315},"frontmatter":{"label":"Themes are used to customize component styles to fit the specific aesthetic of a brand or product.","title":"Themes","description":"Themes are used to customize component styles to fit the specific aesthetic of a brand or product.","tabs":["Overview","Code"]},"exports":{},"rawBody":"---\nlabel:\n Themes are used to customize component styles to fit the specific aesthetic of\n a brand or product.\ntitle: Themes\ndescription:\n Themes are used to customize component styles to fit the specific aesthetic of\n a brand or product.\ntabs: ['Overview', 'Code']\n---\n\n\n\nThemes are used to customize component styles to fit the specific aesthetic of a\nbrand or product.\n\n\n\n\n\nTheming basics\nCustomizing a theme\nTokens\nTheming applied\nResources\n\n\n\n## Theming basics\n\nThemes are used to modify existing components to fit a specific visual style. By\nusing Carbon's tokens, developers can easily customize all of their components\nby changing a set of universal variables, eliminating the need to modify\nindividual components.\n\n### Theme terms\n\n| Term | Definition | |\n| ------- | ------------------------------------------------------------------------------------------------------------ | --- |\n| _Theme_ | A collection of visual attributes assigned to the tokens in order to create a specific aesthetic | |\n| _Token_ | A role-based identifier that assigns a value to a theme. Tokens are universal and never change across themes | |\n| _Role_ | The systematic usage(s) of a token. Roles cannot be changed between themes | |\n| _Value_ | The actual style (such as a hex code) assigned to a token | |\n\n### Default theme\n\nCarbon provides four themes as shown in the\n[color usage](/guidelines/color/usage) page. When `@carbon/react` is downloaded\nand installed, the components are preset to use the default (White) theme.\n\nTo use the Gray 10, Gray 90, or Gray 100 theme as your default instead of White,\nconfigure the sass module using `with`.\n\n```scss\n@use '@carbon/react/scss/themes';\n@use '@carbon/react/scss/theme' with (\n $theme: themes.$g100\n);\n```\n\n## Customizing a theme\n\nThe default theme acts as a starting point; from there designers and developers\ncan define how their own components and styles deviate from the default.\nAltering one, some, or all of the default token values will result in a new\ntheme. The developer configures these new values by configuring the sass module\nusing `with` which can replace the values of the default theme or add new custom\ntokens as well.\n\n```scss\n@use '@carbon/react/scss/theme' with (\n $theme: (\n background: #e2e2e2,\n text-primary: #ffffff,\n custom-token-01: #000000,\n )\n);\n```\n\n## Tokens\n\nWith tokens, the code only needs to be changed in one place to see the effect\nsystem-wide. Tokens are used across all components and help keep global patterns\nand styles consistent.\n\nAll tokens come pre-baked into the Carbon component source code. Tokens are\ndenoted by the prefix `$` (e.g. `$layer-01`). Tokens can also be nested within\nother tokens. For example, `$interactive` calls the IBM Design Language color\npalette token `$blue-60` for its value in the default theme.\n\nThere are several token categories:\n\n- Color\n- Spacing\n- Typography\n- Global\n\nThe full list of tokens available can be found in the source of the\n`@carbon/themes` package per theme for\n[white](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/white.js),\n[g10](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/g10.js),\n[g90](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/g90.js),\nand\n[g100](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/g100.js).\n\n### Color\n\nEach theme is assigned universal color variables, which are determined by common\nroles and usage. This allows for uniform color application across themes while\nmaintaining full styling flexibility. For more information, see the\n[color](/guidelines/color/overview) page.\n\n### Spacing\n\nUse the spacing scale when building individual components. It includes small\nincrements needed to create appropriate spatial relationships for detail-level\ndesigns. For more information, see the [spacing](/guidelines/spacing/overview/)\npage.\n\n### Typography\n\nTypography has four categories of type styles (universal, productive, editorial,\nand additional) that can be customized through tokens. These tokens are used\nboth within components and across layouts. Type tokens are determined by their\nrole across the system. For more information, see the\n[typography](/guidelines/typography/overview/) page.\n\n### Global\n\nThe other categories are global and component-specific variables. These control\nmore general styling of components, such as layer usage or border width. The\nfull list of tokens available can be found in\n[the source of the `@carbon/themes` package](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/white.js).\n\n## Theming applied\n\nThe following example demonstrates the relationship between the different\nthemes. Each theme shares the same variables and roles, with only the value\nchanging for each individual theme.\n\n\n\n\n\n\n\n\n\n| Key | Token | Role | White theme value | Gray 100 theme value |\n| --- | ----------------- | ------------------- | ----------------- | -------------------- |\n| 1 | `$text-secondary` | Label color | Gray 70 | Gray 30 |\n| 2 | `$text-primary` | Primary text color | Gray 100 | Gray 10 |\n| 3 | `$border-strong` | Border bottom color | Gray 50 | Gray 60 |\n| 4 | `$icon-primary` | Primary icon color | Gray 100 | Gray 10 |\n| 5 | `$field-01` | Field color | Gray 10 | Gray 90 |\n| 6 | `$background` | Page background | White | Gray 100 |\n\n## Resources\n\n\n \n\n\n\n \n\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/elements/themes/overview.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/elements/typography/code/page-data.json b/page-data/elements/typography/code/page-data.json
index 3c308de677d..f1d408f3b1d 100644
--- a/page-data/elements/typography/code/page-data.json
+++ b/page-data/elements/typography/code/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-elements-typography-code-mdx","path":"/elements/typography/code/","result":{"pageContext":{"frontmatter":{"label":"Type is a core part of any offering and critical to how brands express and communicate throughout any experience. Use the Carbon type package to leverage IBM Plex and create effective typography across your products more easily.","title":"Typography","description":"Typography can help create clear hierarchies, organize information, and guide users through a product or experience.","tabs":["Overview","Style strategies","Type sets","Code"]},"relativePagePath":"/elements/typography/code.mdx","titleType":"prepend","MdxNode":{"id":"ec3b8b4f-96ad-5bef-b358-991601f2924a","children":[],"parent":"eec9b706-5e19-5e82-829f-adef903b26b6","internal":{"content":"---\nlabel:\n Type is a core part of any offering and critical to how brands express and\n communicate throughout any experience. Use the Carbon type package to leverage\n IBM Plex and create effective typography across your products more easily.\ntitle: Typography\ndescription:\n Typography can help create clear hierarchies, organize information, and guide\n users through a product or experience.\ntabs: ['Overview', 'Style strategies', 'Type sets', 'Code']\n---\n\n\n\nType is a core part of any offering and critical to how brands express and\ncommunicate throughout any experience. Use the Carbon type package to leverage\nIBM Plex and create effective typography across your products more easily.\n\n\n\n\n\nIf you're using `@carbon/react`, you probably don't need need to install the\ntype package separately. See our [Carbon React](/developing/frameworks/react/)\nguide to start building.\n\n\n\n## Usage\n\nThe `@carbon/type` package enables you to use typography from the IBM Design\nLanguage, including the type scale and fonts, along with typography design\ntokens from the Carbon Design System. It also comes with opinionated defaults\nfor type styles on common elements like `h1`, `h2`, `p`, etc.\n\nYou can use this package by writing the following:\n\n```scss\n@use '@carbon/type';\n// Include type reset\n@include type.reset();\n\n// Include default type styles, targets h1, h2, h3, etc\n@include type.default-type();\n\n// Include utility classes for type-related properties\n@include type.type-classes();\n\n.selector {\n // Include a type style\n @include type.style('productive-heading-01');\n}\n```\n\n### Type classes\n\nThe `type-classes` mixin will output a collection of utility CSS that you can\nuse to style a given HTML element with type-related styles.\n\n```scss\n@mixin type-classes;\n```\n\nIn particular, you can use the following classes:\n\n| Class | Description |\n| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `.cds--type-{font-family}` | Set the `font-family` property for the given font. This can include `mono`, `sans`, `sans-condensed`, `sans-arabic`, `sans-devanagari`, `sans-hebrew`, `sans-jp`, `sans-kr`, `sans-thai-looped`, `sans-thai`, `serif` |\n| `.cds--type-{font-weight}` | Set the `font-weight` property |\n| `.cds--type-italic` | Set the `font-style` property to `italic` |\n| `.cds--type-{token}` | Style the HTML element with the given type token |\n\n### Type styles\n\nInstead of using a type scale, `@carbon/type` provides tokens that represent\nwhat we call type styles. These tokens have a variety of properties for styling\nhow text is rendered on a page.\n\nYou can find a full reference of the type styles that are available on the\n[Carbon Design System website](https://carbondesignsystem.com/guidelines/typography/type-sets)\n.\n\nYou can include a token in your Sass file by writing:\n\n````scss\n@use '@carbon/type';\n\n@include type.type-style('productive-heading-01');\n``` |\n\n### Reset\n\nAn optional type reset is provided under the `type.reset()` mixin. You can\ninclude this mixin by writing the following in your Sass file:\n\n```scss\n@use '@carbon/type';\n\n@include type.reset();\n````\n\nThis reset sets some top-level properties on `html` and `body`, namely\n`font-size`, `font-family`, and some `text-rendering` options. We also map the\n`strong` tag to the semibold font weight.\n\n### Type scale\n\nA type scale is provided through the `$type-scale` variable and corresponding\n`type-scale` function and mixin. However, for specifying type styles, the\nrecommendation is to use [type styles](#type-styles) .\n\nIf you are looking to use the type scale, you can include all the scale-related\nutilities and variables by writing the following in your Sass file:\n\n```scss\n@use '@carbon/type';\n```\n\nYou can access a specific step in the type scale by using the `type-scale`\nfunction:\n\n```scss\n@use '@carbon/type';\n\n.my-selector {\n font-size: type.type-scale(1);\n}\n```\n\n## Resources\n\n\n \n \n\n\n\n \n \n \n \n\n\n\n \n \n\n","type":"Mdx","contentDigest":"c35164bd591d0d0501bd9f4d8fa78d3c","owner":"gatsby-plugin-mdx","counter":5315},"frontmatter":{"label":"Type is a core part of any offering and critical to how brands express and communicate throughout any experience. Use the Carbon type package to leverage IBM Plex and create effective typography across your products more easily.","title":"Typography","description":"Typography can help create clear hierarchies, organize information, and guide users through a product or experience.","tabs":["Overview","Style strategies","Type sets","Code"]},"exports":{},"rawBody":"---\nlabel:\n Type is a core part of any offering and critical to how brands express and\n communicate throughout any experience. Use the Carbon type package to leverage\n IBM Plex and create effective typography across your products more easily.\ntitle: Typography\ndescription:\n Typography can help create clear hierarchies, organize information, and guide\n users through a product or experience.\ntabs: ['Overview', 'Style strategies', 'Type sets', 'Code']\n---\n\n\n\nType is a core part of any offering and critical to how brands express and\ncommunicate throughout any experience. Use the Carbon type package to leverage\nIBM Plex and create effective typography across your products more easily.\n\n\n\n\n\nIf you're using `@carbon/react`, you probably don't need need to install the\ntype package separately. See our [Carbon React](/developing/frameworks/react/)\nguide to start building.\n\n\n\n## Usage\n\nThe `@carbon/type` package enables you to use typography from the IBM Design\nLanguage, including the type scale and fonts, along with typography design\ntokens from the Carbon Design System. It also comes with opinionated defaults\nfor type styles on common elements like `h1`, `h2`, `p`, etc.\n\nYou can use this package by writing the following:\n\n```scss\n@use '@carbon/type';\n// Include type reset\n@include type.reset();\n\n// Include default type styles, targets h1, h2, h3, etc\n@include type.default-type();\n\n// Include utility classes for type-related properties\n@include type.type-classes();\n\n.selector {\n // Include a type style\n @include type.style('productive-heading-01');\n}\n```\n\n### Type classes\n\nThe `type-classes` mixin will output a collection of utility CSS that you can\nuse to style a given HTML element with type-related styles.\n\n```scss\n@mixin type-classes;\n```\n\nIn particular, you can use the following classes:\n\n| Class | Description |\n| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `.cds--type-{font-family}` | Set the `font-family` property for the given font. This can include `mono`, `sans`, `sans-condensed`, `sans-arabic`, `sans-devanagari`, `sans-hebrew`, `sans-jp`, `sans-kr`, `sans-thai-looped`, `sans-thai`, `serif` |\n| `.cds--type-{font-weight}` | Set the `font-weight` property |\n| `.cds--type-italic` | Set the `font-style` property to `italic` |\n| `.cds--type-{token}` | Style the HTML element with the given type token |\n\n### Type styles\n\nInstead of using a type scale, `@carbon/type` provides tokens that represent\nwhat we call type styles. These tokens have a variety of properties for styling\nhow text is rendered on a page.\n\nYou can find a full reference of the type styles that are available on the\n[Carbon Design System website](https://carbondesignsystem.com/guidelines/typography/type-sets)\n.\n\nYou can include a token in your Sass file by writing:\n\n````scss\n@use '@carbon/type';\n\n@include type.type-style('productive-heading-01');\n``` |\n\n### Reset\n\nAn optional type reset is provided under the `type.reset()` mixin. You can\ninclude this mixin by writing the following in your Sass file:\n\n```scss\n@use '@carbon/type';\n\n@include type.reset();\n````\n\nThis reset sets some top-level properties on `html` and `body`, namely\n`font-size`, `font-family`, and some `text-rendering` options. We also map the\n`strong` tag to the semibold font weight.\n\n### Type scale\n\nA type scale is provided through the `$type-scale` variable and corresponding\n`type-scale` function and mixin. However, for specifying type styles, the\nrecommendation is to use [type styles](#type-styles) .\n\nIf you are looking to use the type scale, you can include all the scale-related\nutilities and variables by writing the following in your Sass file:\n\n```scss\n@use '@carbon/type';\n```\n\nYou can access a specific step in the type scale by using the `type-scale`\nfunction:\n\n```scss\n@use '@carbon/type';\n\n.my-selector {\n font-size: type.type-scale(1);\n}\n```\n\n## Resources\n\n\n \n \n\n\n\n \n \n \n \n\n\n\n \n \n\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/elements/typography/code.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-elements-typography-code-mdx","path":"/elements/typography/code/","result":{"pageContext":{"frontmatter":{"label":"Type is a core part of any offering and critical to how brands express and communicate throughout any experience. Use the Carbon type package to leverage IBM Plex and create effective typography across your products more easily.","title":"Typography","description":"Typography can help create clear hierarchies, organize information, and guide users through a product or experience.","tabs":["Overview","Style strategies","Type sets","Code"]},"relativePagePath":"/elements/typography/code.mdx","titleType":"prepend","MdxNode":{"id":"ec3b8b4f-96ad-5bef-b358-991601f2924a","children":[],"parent":"eec9b706-5e19-5e82-829f-adef903b26b6","internal":{"content":"---\nlabel:\n Type is a core part of any offering and critical to how brands express and\n communicate throughout any experience. Use the Carbon type package to leverage\n IBM Plex and create effective typography across your products more easily.\ntitle: Typography\ndescription:\n Typography can help create clear hierarchies, organize information, and guide\n users through a product or experience.\ntabs: ['Overview', 'Style strategies', 'Type sets', 'Code']\n---\n\n\n\nType is a core part of any offering and critical to how brands express and\ncommunicate throughout any experience. Use the Carbon type package to leverage\nIBM Plex and create effective typography across your products more easily.\n\n\n\n\n\nIf you're using `@carbon/react`, you probably don't need need to install the\ntype package separately. See our [Carbon React](/developing/frameworks/react/)\nguide to start building.\n\n\n\n## Usage\n\nThe `@carbon/type` package enables you to use typography from the IBM Design\nLanguage, including the type scale and fonts, along with typography design\ntokens from the Carbon Design System. It also comes with opinionated defaults\nfor type styles on common elements like `h1`, `h2`, `p`, etc.\n\nYou can use this package by writing the following:\n\n```scss\n@use '@carbon/type';\n// Include type reset\n@include type.reset();\n\n// Include default type styles, targets h1, h2, h3, etc\n@include type.default-type();\n\n// Include utility classes for type-related properties\n@include type.type-classes();\n\n.selector {\n // Include a type style\n @include type.style('productive-heading-01');\n}\n```\n\n### Type classes\n\nThe `type-classes` mixin will output a collection of utility CSS that you can\nuse to style a given HTML element with type-related styles.\n\n```scss\n@mixin type-classes;\n```\n\nIn particular, you can use the following classes:\n\n| Class | Description |\n| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `.cds--type-{font-family}` | Set the `font-family` property for the given font. This can include `mono`, `sans`, `sans-condensed`, `sans-arabic`, `sans-devanagari`, `sans-hebrew`, `sans-jp`, `sans-kr`, `sans-thai-looped`, `sans-thai`, `serif` |\n| `.cds--type-{font-weight}` | Set the `font-weight` property |\n| `.cds--type-italic` | Set the `font-style` property to `italic` |\n| `.cds--type-{token}` | Style the HTML element with the given type token |\n\n### Type styles\n\nInstead of using a type scale, `@carbon/type` provides tokens that represent\nwhat we call type styles. These tokens have a variety of properties for styling\nhow text is rendered on a page.\n\nYou can find a full reference of the type styles that are available on the\n[Carbon Design System website](https://carbondesignsystem.com/guidelines/typography/type-sets)\n.\n\nYou can include a token in your Sass file by writing:\n\n````scss\n@use '@carbon/type';\n\n@include type.type-style('productive-heading-01');\n``` |\n\n### Reset\n\nAn optional type reset is provided under the `type.reset()` mixin. You can\ninclude this mixin by writing the following in your Sass file:\n\n```scss\n@use '@carbon/type';\n\n@include type.reset();\n````\n\nThis reset sets some top-level properties on `html` and `body`, namely\n`font-size`, `font-family`, and some `text-rendering` options. We also map the\n`strong` tag to the semibold font weight.\n\n### Type scale\n\nA type scale is provided through the `$type-scale` variable and corresponding\n`type-scale` function and mixin. However, for specifying type styles, the\nrecommendation is to use [type styles](#type-styles) .\n\nIf you are looking to use the type scale, you can include all the scale-related\nutilities and variables by writing the following in your Sass file:\n\n```scss\n@use '@carbon/type';\n```\n\nYou can access a specific step in the type scale by using the `type-scale`\nfunction:\n\n```scss\n@use '@carbon/type';\n\n.my-selector {\n font-size: type.type-scale(1);\n}\n```\n\n## Resources\n\n\n \n \n\n\n\n \n \n \n \n\n\n\n \n \n\n","type":"Mdx","contentDigest":"c35164bd591d0d0501bd9f4d8fa78d3c","owner":"gatsby-plugin-mdx","counter":5316},"frontmatter":{"label":"Type is a core part of any offering and critical to how brands express and communicate throughout any experience. Use the Carbon type package to leverage IBM Plex and create effective typography across your products more easily.","title":"Typography","description":"Typography can help create clear hierarchies, organize information, and guide users through a product or experience.","tabs":["Overview","Style strategies","Type sets","Code"]},"exports":{},"rawBody":"---\nlabel:\n Type is a core part of any offering and critical to how brands express and\n communicate throughout any experience. Use the Carbon type package to leverage\n IBM Plex and create effective typography across your products more easily.\ntitle: Typography\ndescription:\n Typography can help create clear hierarchies, organize information, and guide\n users through a product or experience.\ntabs: ['Overview', 'Style strategies', 'Type sets', 'Code']\n---\n\n\n\nType is a core part of any offering and critical to how brands express and\ncommunicate throughout any experience. Use the Carbon type package to leverage\nIBM Plex and create effective typography across your products more easily.\n\n\n\n\n\nIf you're using `@carbon/react`, you probably don't need need to install the\ntype package separately. See our [Carbon React](/developing/frameworks/react/)\nguide to start building.\n\n\n\n## Usage\n\nThe `@carbon/type` package enables you to use typography from the IBM Design\nLanguage, including the type scale and fonts, along with typography design\ntokens from the Carbon Design System. It also comes with opinionated defaults\nfor type styles on common elements like `h1`, `h2`, `p`, etc.\n\nYou can use this package by writing the following:\n\n```scss\n@use '@carbon/type';\n// Include type reset\n@include type.reset();\n\n// Include default type styles, targets h1, h2, h3, etc\n@include type.default-type();\n\n// Include utility classes for type-related properties\n@include type.type-classes();\n\n.selector {\n // Include a type style\n @include type.style('productive-heading-01');\n}\n```\n\n### Type classes\n\nThe `type-classes` mixin will output a collection of utility CSS that you can\nuse to style a given HTML element with type-related styles.\n\n```scss\n@mixin type-classes;\n```\n\nIn particular, you can use the following classes:\n\n| Class | Description |\n| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `.cds--type-{font-family}` | Set the `font-family` property for the given font. This can include `mono`, `sans`, `sans-condensed`, `sans-arabic`, `sans-devanagari`, `sans-hebrew`, `sans-jp`, `sans-kr`, `sans-thai-looped`, `sans-thai`, `serif` |\n| `.cds--type-{font-weight}` | Set the `font-weight` property |\n| `.cds--type-italic` | Set the `font-style` property to `italic` |\n| `.cds--type-{token}` | Style the HTML element with the given type token |\n\n### Type styles\n\nInstead of using a type scale, `@carbon/type` provides tokens that represent\nwhat we call type styles. These tokens have a variety of properties for styling\nhow text is rendered on a page.\n\nYou can find a full reference of the type styles that are available on the\n[Carbon Design System website](https://carbondesignsystem.com/guidelines/typography/type-sets)\n.\n\nYou can include a token in your Sass file by writing:\n\n````scss\n@use '@carbon/type';\n\n@include type.type-style('productive-heading-01');\n``` |\n\n### Reset\n\nAn optional type reset is provided under the `type.reset()` mixin. You can\ninclude this mixin by writing the following in your Sass file:\n\n```scss\n@use '@carbon/type';\n\n@include type.reset();\n````\n\nThis reset sets some top-level properties on `html` and `body`, namely\n`font-size`, `font-family`, and some `text-rendering` options. We also map the\n`strong` tag to the semibold font weight.\n\n### Type scale\n\nA type scale is provided through the `$type-scale` variable and corresponding\n`type-scale` function and mixin. However, for specifying type styles, the\nrecommendation is to use [type styles](#type-styles) .\n\nIf you are looking to use the type scale, you can include all the scale-related\nutilities and variables by writing the following in your Sass file:\n\n```scss\n@use '@carbon/type';\n```\n\nYou can access a specific step in the type scale by using the `type-scale`\nfunction:\n\n```scss\n@use '@carbon/type';\n\n.my-selector {\n font-size: type.type-scale(1);\n}\n```\n\n## Resources\n\n\n \n \n\n\n\n \n \n \n \n\n\n\n \n \n\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/elements/typography/code.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/guidelines/content/writing-style/page-data.json b/page-data/guidelines/content/writing-style/page-data.json
index 60f77ecbe97..583d1486175 100644
--- a/page-data/guidelines/content/writing-style/page-data.json
+++ b/page-data/guidelines/content/writing-style/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-guidelines-content-writing-style-mdx","path":"/guidelines/content/writing-style/","result":{"pageContext":{"frontmatter":{"title":"Content","description":"Writing should always be simple, clear, and easy to understand. Using everyday language keeps the tone friendly, human, and inviting. And choose short words over long, impressive–sounding words. Put the thesaurus away!","tabs":["Overview","Writing style","Action labels"]},"relativePagePath":"/guidelines/content/writing-style.mdx","titleType":"prepend","MdxNode":{"id":"05827b79-4d2d-5c13-8eed-ee892e7a2faf","children":[],"parent":"7de25dd9-b57f-5e25-b37b-b84898fc3ced","internal":{"content":"---\ntitle: Content\ndescription:\n Writing should always be simple, clear, and easy to understand. Using everyday\n language keeps the tone friendly, human, and inviting. And choose short words\n over long, impressive–sounding words. Put the thesaurus away!\ntabs: ['Overview', 'Writing style', 'Action labels']\n---\n\n\n\nWriting should always be simple, clear, and easy to understand. Using everyday\nlanguage keeps the tone friendly, human, and inviting. And choose short words\nover long, impressive–sounding words. Put the thesaurus away!\n\n\n\n\n\nCapitalization\nSimple writing\nConversational style\nInclusive language\nPronouns\nActive and passive voice\n\n\n\n## Capitalization\n\n### Use sentence–case capitalization\n\nUse sentence–case capitalization for all UI text elements. This style is\npredominantly lowercase. Capitalize only the initial letter of the first word in\nthe text and other words that require capitalization, such as proper nouns. For\nexample, labels in a form would be written as “First name” and “Email address”.\n\nThe image below shows a page title, tabs, a module title, link text, button\ntext, table headers, and table content all following the sentence case rule.\n\n\n\n\n\n\n
Example of a product page using sentence–style capitalization
\n\n\n\n\nSentence–style capitalization makes it easy for readers to distinguish between\ncommon nouns and proper nouns, and is generally considered the quickest form to\nread.\n\n> Do not capitalize the names of features and components unless they are sold\n> separately or are trademarked.\n>\n> – The IBM Style Guide: Conventions for Writers and Editors\n\nCarbon does not consider UI elements within a product to be proper nouns. Nor\ndoes Carbon support a concept of “important words” or “specialness”. Determining\nwhether something is important or special is highly subjective and can result in\ninconsistencies across an organization.\n\nUnless the name is a product or service name, or is trademarked, always use\nsentence–style capitalization.\n\nIn the following examples, the capitalization shows that Padlock, Visual\nRecognition, and IBM Cloud are either products or services.\n\n\n \n \n\n\n### Do not use title case capitalization\n\n**Title (or headline) case capitalization** is where the first letter of most\nwords is capitalized, but not articles, conjunctions, or prepositions (except if\nany of these are the first or last word in the sentence or phrase).\n\nTitle case is difficult to implement consistently across an organization\nbecause:\n\n1. It requires everyone who writes any copy to understand and follow fairly\n complex grammatical rules about which words should and shouldn't be\n capitalized, and\n\n1. It relies on a subjective viewpoint of what is considered “important” or\n “special” and that viewpoint being communicated or understood somehow.\n\nTitle case can also slow reading and comprehension down as it is more difficult\nfor readers to distinguish between proper nouns and common nouns.\n\n\n \n \n\n\n### Do not use all caps capitalization\n\n**All caps (or uppercase) capitalization** is where every letter is capitalized.\n\nAll caps capitalization has been shown to be slower to read (especially when\ntext is more than a few words) as individual letter shapes are less\ndistinguishable from each other—they are the same height and have no ascenders\nor descenders. This style also typically requires more space in the UI per\nletter than sentence case does.\n\nIn addition, it can be difficult for the reader to distinguish between proper\nnouns and common nouns. In the first example below, it's easy to distinguish\nproduct names from features whereas it takes longer to make these distinctions\nwhen the text is in all caps.\n\n\n \n \n\n\n### When to use capital letters\n\nCapital letters are reserved for the following:\n\n- “Carbon” or the “Carbon Design System” (the name of IBM’s official design\n system)\n- “IBM” or any other company or organization name\n- Any official, trademarked product or service (whether from IBM or not) –\n unless they intentionally use a lowercase letter at the beginning, such as the\n iPhone\n- Any initialisms (for example, BBC, HTML) or acronyms (for example, NASA, NATO)\n- Any people\n- Any country / place names\n- When referring to any UI labels that are themselves capitalized\n- When the word begins a sentence or phrase\n\nIf it’s not in the list above, it should not be capitalized.\n\nSometimes official company and product names use non–standard capitalization. If\nyou refer to any of these, ensure you write them accurately. Here are some\nexamples (all written correctly):\n\n- developerWorks\n- GitHub\n- iTunes\n- JavaScript\n- WebSphere\n\n### How to refer to UI elements\n\nWhen writing about a UI element, use the same capitalization as used in the UI.\nFor example, if an input field is labeled “Name” then you refer to this as the\nName input field. Similarly, if a drop–down menu has the label “Country” next to\nit, then it is correct to refer to the Country drop–down menu. Where a product\npage is titled “My network”, you refer to this in writing as follows: “Enter\nyour network information in the My network page”.\n\n\n \n \n\n\n### Capitalizing proper nouns\n\nThe names of people, places, and products are proper nouns and therefore all\ntake initial capitals. Examples of proper nouns are:\n\n- Eliot Noyes\n- IBM Watson Studio\n- Paris, France\n- Porsche Boxster\n\nThere are many words that can act as either a common noun or a proper noun,\ndepending on the context. So, you always need to think about how the word is\nbeing used. Here are some examples:\n\n| Word | Used as a common noun | Used as a proper noun |\n| ------------------- | ------------------------------------------------ | -------------------------------------------------- |\n| agile | The group uses agile tools and processes | Debs referred her manager to the Agile Manifesto |\n| design | Jodi works in the design organization | Jodi works for IBM Design |\n| editor | Joe used a text editor to update the config file | Joe used IBM Flow Editor to define his data models |\n| front end developer | Jane is hoping to recruit a front end developer | Megan’s job title is Senior Front End Developer |\n\n### Capitalizing abbreviations\n\n**IBM product and service names**\n\nWhen referencing the name of any IBM product, use the official (full) name, not\nan abbreviation or just the product name initials, unless a shortened name has\nbeen specifically approved, as with IBM CICS.\n\n\n \n \n\n\nUse all uppercase letters for well–recognized abbreviations. This applies to\nboth initialisms, such as IBM, and to acronyms, such as GIF.\n\n- ASCII\n- CAPTCHA\n- FAQ\n- HTML\n- OK (not Ok or Okay)\n- WDSL\n\nIf there's a chance that an abbreviation might not be known to the target\naudience, it's good practice to spell it out in full the first time you use it.\nHowever, don't spell out commonly known abbreviations, for example PDF, CEO,\nAM/PM.\n\n### Capitalizing all other words\n\nUnless the word begins a sentence, phrase, or UI element name, don't give it a\ncapital letter.\n\nDon't give a word a capital letter to denote “specialness”. If you want to\nemphasize a particular word or phrase within a sentence, use italic or bold\nformatting (but not both).\n\n\n \n \n\n\n## Simple writing\n\n### Use simple words and sentences\n\nUse the simplest term that is appropriate for your audience. For example, use\nlarge instead of voluminous, and use small instead of diminutive.\n\nBe succinct, and keep sentences as short and simple as possible. Omit wordy or\nredundant phrases.\n\nTIP: Create a terminology list of words for your product that includes preferred\nwords and words not to use. This simple tool can help with consistency over\ntime, especially if multiple are writing copy.\n\nRespect a user's time and make things quick and easy to read. Always trim back\nto as few words as possible, although don't be terse.\n\nWe recommend avoiding terms of politeness such as _please_ and _thank you_ in a\nUI as they can be inappropriate or offensive in some cultural contexts.\n\n### Use simple present tense\n\nUse simple verbs and tenses, and keep sentences concise, simple, friendly, and\npunchy. Focus on the user's context and make content relevant. The more familiar\nyou are with their context, the better you can communicate without using a lot\nof words.\n\nIf you need to use past or future tense, avoid verb tenses with the words have,\nhas, had, been, should, would, and will.\n\n## Conversational style\n\nTo set the appropriate tone and conversation level, it helps to imagine the user\nengaging with the product as if in a conversation. The interplay between words,\nimagery, and interactions forms the conversation, a back–and–forth that takes\nplace on the glass, between the user and the product.\n\nThe conversational level is determined by where the user is in the journey, and\nthe task they are performing at that time. The most conversational content is\nusually found in the \"discover, try, and buy\" phases of the journey. Probably\nthe least conversational content can be found in error messages where an economy\nof words is desirable.\n\nWhatever the conversational level, the writing should always be simple, clear,\nand easy to understand. And keep the tone friendly, human, and inviting. Use\neveryday language, not jargon. And choose short words to make the reading\nfaster, rather than long, impressive–sounding words. Put the thesaurus away!\n\nIBM Style offers more guidelines on\n[conversational style](<[https://www-03preprod.ibm.com/support/knowledgecenter/ibm_style/conversational-style.html](https://ibmdocs-test.mybluemix.net/docs/en/ibm-style?topic=medium-conversational-style)>).\n\n### Formal versus casual tone\n\nWhile a more formal tone is often appropriate for technical and business\nwriting, a more casual tone is becoming increasingly accepted (and expected) in\nUI and supporting materials.\n\n- Don't be afraid to use **contractions** when they fit the context and improve\n the flow.\n- Beginning sentences with **and**, **but**, or **so** is not always forbidden.\n When it allows for shorter scannable sentences they can be used, but do not\n overuse these devices.\n- Use **exclamation marks** only positively, not negatively. Make sure you use\n no more than one exclamation mark in a context, such as a single window or a\n single Docs topic.\n\n\n \n \n\n\n#### Terms of politeness\n\nOften overused, these terms can convey the wrong tone for technical material,\nand are not regarded the same way in all cultures. Use terms such as “please”\nand “thank you” carefully.\n\n\n \n \n\n\n### Can, may, and might\n\n#### Terms of ability\n\nThese terms are often misused. Remember, “can” implies ability, and “may”\nimplies permission (and sometimes uncertainty).\n\n\n \n \n\n\n#### Terms of possibility\n\nThese terms can also be confusing. Remember, when either “may” or “might” will\nwork, generally go with “might” to avoid confusion with the multiple meanings of\n“may”.\n\n\n \n \n\n\n## Inclusive language\n\nIBM is committed to eliminating language that supports racial, cultural, or\ngender bias. It is critical that all words used in any capacity in product\nofferings be inclusive in their language.\n\nIBMers who are unsure about a particular word can search the\n[IBM Terminology database](http://ibm.biz/termsearch), and can also\n[submit a term for review](https://w3.terminology.g11n.ibm.com/standards/terminology/feedback).\n\nFor more information about this important work, see the\n[Inclusive IT Terminology](https://w3.ibm.com/w3publisher/inclusive-it-terminology/take-action)\nsite.\n\n## Pronouns\n\nUse the second person (you, your) as often as possible.\n\n\n \n \n\n\nYou can use first person in headings or labels that are very specific to the\nuser or customer data, for example “My account” or “My usage.” However, in\nexplanatory text for the heading or label, switch to second person. For example,\n“Your usage is calculated from the first day of the month.”\n\nWhere appropriate, use first person (we, our) to refer to IBM. For example, in\nrequests for personal information, such as name and email address, where the\nuser will benefit from knowing why IBM is asking for this information. Example:\n“Why do we need your email address?”\n\nAvoid third–person pronouns that are gender specific.\n\nFor more detailed guidance about pronouns, refer to the\n[Pronouns](https://ibmdocs-test.mybluemix.net/docs/en/ibm-style?topic=grammar-pronouns)\ntopic in IBM Style.\n\n## Active and passive voice\n\nThe _active voice_ is direct and emphasizes the subject of the sentence. The\nsubject clearly “acts upon” the verb (hence, “active”). For example, “John ate\nthe apple”. In situations where either voice will work, generally choose the\nactive voice for more directness.\n\n\n \n \n\n\nThe _passive voice_, on the other hand, flips the construction so that the\nsubject is secondary to the verb and object (hence, “passive”). Often, the\nsubject is not even included in the sentence. For example, “_The apple was eaten\nby John_” or just “_The apple was eaten_”. Only sentences that contain direct\nobjects can be constructed in the passive voice. Thus, “_John ate_” cannot be\nconstructed passively.\n\nThe passive voice makes for a more natural tone in certain use cases. For\nexample, if the true subject of the sentence is a system, and the human is\nsecondary, passive voice can be acceptable.\n\n\n \n \n\n","type":"Mdx","contentDigest":"c196691a985a9635b719c1cd95728ab2","owner":"gatsby-plugin-mdx","counter":5327},"frontmatter":{"title":"Content","description":"Writing should always be simple, clear, and easy to understand. Using everyday language keeps the tone friendly, human, and inviting. And choose short words over long, impressive–sounding words. Put the thesaurus away!","tabs":["Overview","Writing style","Action labels"]},"exports":{},"rawBody":"---\ntitle: Content\ndescription:\n Writing should always be simple, clear, and easy to understand. Using everyday\n language keeps the tone friendly, human, and inviting. And choose short words\n over long, impressive–sounding words. Put the thesaurus away!\ntabs: ['Overview', 'Writing style', 'Action labels']\n---\n\n\n\nWriting should always be simple, clear, and easy to understand. Using everyday\nlanguage keeps the tone friendly, human, and inviting. And choose short words\nover long, impressive–sounding words. Put the thesaurus away!\n\n\n\n\n\nCapitalization\nSimple writing\nConversational style\nInclusive language\nPronouns\nActive and passive voice\n\n\n\n## Capitalization\n\n### Use sentence–case capitalization\n\nUse sentence–case capitalization for all UI text elements. This style is\npredominantly lowercase. Capitalize only the initial letter of the first word in\nthe text and other words that require capitalization, such as proper nouns. For\nexample, labels in a form would be written as “First name” and “Email address”.\n\nThe image below shows a page title, tabs, a module title, link text, button\ntext, table headers, and table content all following the sentence case rule.\n\n\n\n\n\n\n
Example of a product page using sentence–style capitalization
\n\n\n\n\nSentence–style capitalization makes it easy for readers to distinguish between\ncommon nouns and proper nouns, and is generally considered the quickest form to\nread.\n\n> Do not capitalize the names of features and components unless they are sold\n> separately or are trademarked.\n>\n> – The IBM Style Guide: Conventions for Writers and Editors\n\nCarbon does not consider UI elements within a product to be proper nouns. Nor\ndoes Carbon support a concept of “important words” or “specialness”. Determining\nwhether something is important or special is highly subjective and can result in\ninconsistencies across an organization.\n\nUnless the name is a product or service name, or is trademarked, always use\nsentence–style capitalization.\n\nIn the following examples, the capitalization shows that Padlock, Visual\nRecognition, and IBM Cloud are either products or services.\n\n\n \n \n\n\n### Do not use title case capitalization\n\n**Title (or headline) case capitalization** is where the first letter of most\nwords is capitalized, but not articles, conjunctions, or prepositions (except if\nany of these are the first or last word in the sentence or phrase).\n\nTitle case is difficult to implement consistently across an organization\nbecause:\n\n1. It requires everyone who writes any copy to understand and follow fairly\n complex grammatical rules about which words should and shouldn't be\n capitalized, and\n\n1. It relies on a subjective viewpoint of what is considered “important” or\n “special” and that viewpoint being communicated or understood somehow.\n\nTitle case can also slow reading and comprehension down as it is more difficult\nfor readers to distinguish between proper nouns and common nouns.\n\n\n \n \n\n\n### Do not use all caps capitalization\n\n**All caps (or uppercase) capitalization** is where every letter is capitalized.\n\nAll caps capitalization has been shown to be slower to read (especially when\ntext is more than a few words) as individual letter shapes are less\ndistinguishable from each other—they are the same height and have no ascenders\nor descenders. This style also typically requires more space in the UI per\nletter than sentence case does.\n\nIn addition, it can be difficult for the reader to distinguish between proper\nnouns and common nouns. In the first example below, it's easy to distinguish\nproduct names from features whereas it takes longer to make these distinctions\nwhen the text is in all caps.\n\n\n \n \n\n\n### When to use capital letters\n\nCapital letters are reserved for the following:\n\n- “Carbon” or the “Carbon Design System” (the name of IBM’s official design\n system)\n- “IBM” or any other company or organization name\n- Any official, trademarked product or service (whether from IBM or not) –\n unless they intentionally use a lowercase letter at the beginning, such as the\n iPhone\n- Any initialisms (for example, BBC, HTML) or acronyms (for example, NASA, NATO)\n- Any people\n- Any country / place names\n- When referring to any UI labels that are themselves capitalized\n- When the word begins a sentence or phrase\n\nIf it’s not in the list above, it should not be capitalized.\n\nSometimes official company and product names use non–standard capitalization. If\nyou refer to any of these, ensure you write them accurately. Here are some\nexamples (all written correctly):\n\n- developerWorks\n- GitHub\n- iTunes\n- JavaScript\n- WebSphere\n\n### How to refer to UI elements\n\nWhen writing about a UI element, use the same capitalization as used in the UI.\nFor example, if an input field is labeled “Name” then you refer to this as the\nName input field. Similarly, if a drop–down menu has the label “Country” next to\nit, then it is correct to refer to the Country drop–down menu. Where a product\npage is titled “My network”, you refer to this in writing as follows: “Enter\nyour network information in the My network page”.\n\n\n \n \n\n\n### Capitalizing proper nouns\n\nThe names of people, places, and products are proper nouns and therefore all\ntake initial capitals. Examples of proper nouns are:\n\n- Eliot Noyes\n- IBM Watson Studio\n- Paris, France\n- Porsche Boxster\n\nThere are many words that can act as either a common noun or a proper noun,\ndepending on the context. So, you always need to think about how the word is\nbeing used. Here are some examples:\n\n| Word | Used as a common noun | Used as a proper noun |\n| ------------------- | ------------------------------------------------ | -------------------------------------------------- |\n| agile | The group uses agile tools and processes | Debs referred her manager to the Agile Manifesto |\n| design | Jodi works in the design organization | Jodi works for IBM Design |\n| editor | Joe used a text editor to update the config file | Joe used IBM Flow Editor to define his data models |\n| front end developer | Jane is hoping to recruit a front end developer | Megan’s job title is Senior Front End Developer |\n\n### Capitalizing abbreviations\n\n**IBM product and service names**\n\nWhen referencing the name of any IBM product, use the official (full) name, not\nan abbreviation or just the product name initials, unless a shortened name has\nbeen specifically approved, as with IBM CICS.\n\n\n \n \n\n\nUse all uppercase letters for well–recognized abbreviations. This applies to\nboth initialisms, such as IBM, and to acronyms, such as GIF.\n\n- ASCII\n- CAPTCHA\n- FAQ\n- HTML\n- OK (not Ok or Okay)\n- WDSL\n\nIf there's a chance that an abbreviation might not be known to the target\naudience, it's good practice to spell it out in full the first time you use it.\nHowever, don't spell out commonly known abbreviations, for example PDF, CEO,\nAM/PM.\n\n### Capitalizing all other words\n\nUnless the word begins a sentence, phrase, or UI element name, don't give it a\ncapital letter.\n\nDon't give a word a capital letter to denote “specialness”. If you want to\nemphasize a particular word or phrase within a sentence, use italic or bold\nformatting (but not both).\n\n\n \n \n\n\n## Simple writing\n\n### Use simple words and sentences\n\nUse the simplest term that is appropriate for your audience. For example, use\nlarge instead of voluminous, and use small instead of diminutive.\n\nBe succinct, and keep sentences as short and simple as possible. Omit wordy or\nredundant phrases.\n\nTIP: Create a terminology list of words for your product that includes preferred\nwords and words not to use. This simple tool can help with consistency over\ntime, especially if multiple are writing copy.\n\nRespect a user's time and make things quick and easy to read. Always trim back\nto as few words as possible, although don't be terse.\n\nWe recommend avoiding terms of politeness such as _please_ and _thank you_ in a\nUI as they can be inappropriate or offensive in some cultural contexts.\n\n### Use simple present tense\n\nUse simple verbs and tenses, and keep sentences concise, simple, friendly, and\npunchy. Focus on the user's context and make content relevant. The more familiar\nyou are with their context, the better you can communicate without using a lot\nof words.\n\nIf you need to use past or future tense, avoid verb tenses with the words have,\nhas, had, been, should, would, and will.\n\n## Conversational style\n\nTo set the appropriate tone and conversation level, it helps to imagine the user\nengaging with the product as if in a conversation. The interplay between words,\nimagery, and interactions forms the conversation, a back–and–forth that takes\nplace on the glass, between the user and the product.\n\nThe conversational level is determined by where the user is in the journey, and\nthe task they are performing at that time. The most conversational content is\nusually found in the \"discover, try, and buy\" phases of the journey. Probably\nthe least conversational content can be found in error messages where an economy\nof words is desirable.\n\nWhatever the conversational level, the writing should always be simple, clear,\nand easy to understand. And keep the tone friendly, human, and inviting. Use\neveryday language, not jargon. And choose short words to make the reading\nfaster, rather than long, impressive–sounding words. Put the thesaurus away!\n\nIBM Style offers more guidelines on\n[conversational style](<[https://www-03preprod.ibm.com/support/knowledgecenter/ibm_style/conversational-style.html](https://ibmdocs-test.mybluemix.net/docs/en/ibm-style?topic=medium-conversational-style)>).\n\n### Formal versus casual tone\n\nWhile a more formal tone is often appropriate for technical and business\nwriting, a more casual tone is becoming increasingly accepted (and expected) in\nUI and supporting materials.\n\n- Don't be afraid to use **contractions** when they fit the context and improve\n the flow.\n- Beginning sentences with **and**, **but**, or **so** is not always forbidden.\n When it allows for shorter scannable sentences they can be used, but do not\n overuse these devices.\n- Use **exclamation marks** only positively, not negatively. Make sure you use\n no more than one exclamation mark in a context, such as a single window or a\n single Docs topic.\n\n\n \n \n\n\n#### Terms of politeness\n\nOften overused, these terms can convey the wrong tone for technical material,\nand are not regarded the same way in all cultures. Use terms such as “please”\nand “thank you” carefully.\n\n\n \n \n\n\n### Can, may, and might\n\n#### Terms of ability\n\nThese terms are often misused. Remember, “can” implies ability, and “may”\nimplies permission (and sometimes uncertainty).\n\n\n \n \n\n\n#### Terms of possibility\n\nThese terms can also be confusing. Remember, when either “may” or “might” will\nwork, generally go with “might” to avoid confusion with the multiple meanings of\n“may”.\n\n\n \n \n\n\n## Inclusive language\n\nIBM is committed to eliminating language that supports racial, cultural, or\ngender bias. It is critical that all words used in any capacity in product\nofferings be inclusive in their language.\n\nIBMers who are unsure about a particular word can search the\n[IBM Terminology database](http://ibm.biz/termsearch), and can also\n[submit a term for review](https://w3.terminology.g11n.ibm.com/standards/terminology/feedback).\n\nFor more information about this important work, see the\n[Inclusive IT Terminology](https://w3.ibm.com/w3publisher/inclusive-it-terminology/take-action)\nsite.\n\n## Pronouns\n\nUse the second person (you, your) as often as possible.\n\n\n \n \n\n\nYou can use first person in headings or labels that are very specific to the\nuser or customer data, for example “My account” or “My usage.” However, in\nexplanatory text for the heading or label, switch to second person. For example,\n“Your usage is calculated from the first day of the month.”\n\nWhere appropriate, use first person (we, our) to refer to IBM. For example, in\nrequests for personal information, such as name and email address, where the\nuser will benefit from knowing why IBM is asking for this information. Example:\n“Why do we need your email address?”\n\nAvoid third–person pronouns that are gender specific.\n\nFor more detailed guidance about pronouns, refer to the\n[Pronouns](https://ibmdocs-test.mybluemix.net/docs/en/ibm-style?topic=grammar-pronouns)\ntopic in IBM Style.\n\n## Active and passive voice\n\nThe _active voice_ is direct and emphasizes the subject of the sentence. The\nsubject clearly “acts upon” the verb (hence, “active”). For example, “John ate\nthe apple”. In situations where either voice will work, generally choose the\nactive voice for more directness.\n\n\n \n \n\n\nThe _passive voice_, on the other hand, flips the construction so that the\nsubject is secondary to the verb and object (hence, “passive”). Often, the\nsubject is not even included in the sentence. For example, “_The apple was eaten\nby John_” or just “_The apple was eaten_”. Only sentences that contain direct\nobjects can be constructed in the passive voice. Thus, “_John ate_” cannot be\nconstructed passively.\n\nThe passive voice makes for a more natural tone in certain use cases. For\nexample, if the true subject of the sentence is a system, and the human is\nsecondary, passive voice can be acceptable.\n\n\n \n \n\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/guidelines/content/writing-style.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-guidelines-content-writing-style-mdx","path":"/guidelines/content/writing-style/","result":{"pageContext":{"frontmatter":{"title":"Content","description":"Writing should always be simple, clear, and easy to understand. Using everyday language keeps the tone friendly, human, and inviting. And choose short words over long, impressive–sounding words. Put the thesaurus away!","tabs":["Overview","Writing style","Action labels"]},"relativePagePath":"/guidelines/content/writing-style.mdx","titleType":"prepend","MdxNode":{"id":"05827b79-4d2d-5c13-8eed-ee892e7a2faf","children":[],"parent":"7de25dd9-b57f-5e25-b37b-b84898fc3ced","internal":{"content":"---\ntitle: Content\ndescription:\n Writing should always be simple, clear, and easy to understand. Using everyday\n language keeps the tone friendly, human, and inviting. And choose short words\n over long, impressive–sounding words. Put the thesaurus away!\ntabs: ['Overview', 'Writing style', 'Action labels']\n---\n\n\n\nWriting should always be simple, clear, and easy to understand. Using everyday\nlanguage keeps the tone friendly, human, and inviting. And choose short words\nover long, impressive–sounding words. Put the thesaurus away!\n\n\n\n\n\nCapitalization\nSimple writing\nConversational style\nInclusive language\nPronouns\nActive and passive voice\n\n\n\n## Capitalization\n\n### Use sentence–case capitalization\n\nUse sentence–case capitalization for all UI text elements. This style is\npredominantly lowercase. Capitalize only the initial letter of the first word in\nthe text and other words that require capitalization, such as proper nouns. For\nexample, labels in a form would be written as “First name” and “Email address”.\n\nThe image below shows a page title, tabs, a module title, link text, button\ntext, table headers, and table content all following the sentence case rule.\n\n\n\n\n\n\n
Example of a product page using sentence–style capitalization
\n\n\n\n\nSentence–style capitalization makes it easy for readers to distinguish between\ncommon nouns and proper nouns, and is generally considered the quickest form to\nread.\n\n> Do not capitalize the names of features and components unless they are sold\n> separately or are trademarked.\n>\n> – The IBM Style Guide: Conventions for Writers and Editors\n\nCarbon does not consider UI elements within a product to be proper nouns. Nor\ndoes Carbon support a concept of “important words” or “specialness”. Determining\nwhether something is important or special is highly subjective and can result in\ninconsistencies across an organization.\n\nUnless the name is a product or service name, or is trademarked, always use\nsentence–style capitalization.\n\nIn the following examples, the capitalization shows that Padlock, Visual\nRecognition, and IBM Cloud are either products or services.\n\n\n \n \n\n\n### Do not use title case capitalization\n\n**Title (or headline) case capitalization** is where the first letter of most\nwords is capitalized, but not articles, conjunctions, or prepositions (except if\nany of these are the first or last word in the sentence or phrase).\n\nTitle case is difficult to implement consistently across an organization\nbecause:\n\n1. It requires everyone who writes any copy to understand and follow fairly\n complex grammatical rules about which words should and shouldn't be\n capitalized, and\n\n1. It relies on a subjective viewpoint of what is considered “important” or\n “special” and that viewpoint being communicated or understood somehow.\n\nTitle case can also slow reading and comprehension down as it is more difficult\nfor readers to distinguish between proper nouns and common nouns.\n\n\n \n \n\n\n### Do not use all caps capitalization\n\n**All caps (or uppercase) capitalization** is where every letter is capitalized.\n\nAll caps capitalization has been shown to be slower to read (especially when\ntext is more than a few words) as individual letter shapes are less\ndistinguishable from each other—they are the same height and have no ascenders\nor descenders. This style also typically requires more space in the UI per\nletter than sentence case does.\n\nIn addition, it can be difficult for the reader to distinguish between proper\nnouns and common nouns. In the first example below, it's easy to distinguish\nproduct names from features whereas it takes longer to make these distinctions\nwhen the text is in all caps.\n\n\n \n \n\n\n### When to use capital letters\n\nCapital letters are reserved for the following:\n\n- “Carbon” or the “Carbon Design System” (the name of IBM’s official design\n system)\n- “IBM” or any other company or organization name\n- Any official, trademarked product or service (whether from IBM or not) –\n unless they intentionally use a lowercase letter at the beginning, such as the\n iPhone\n- Any initialisms (for example, BBC, HTML) or acronyms (for example, NASA, NATO)\n- Any people\n- Any country / place names\n- When referring to any UI labels that are themselves capitalized\n- When the word begins a sentence or phrase\n\nIf it’s not in the list above, it should not be capitalized.\n\nSometimes official company and product names use non–standard capitalization. If\nyou refer to any of these, ensure you write them accurately. Here are some\nexamples (all written correctly):\n\n- developerWorks\n- GitHub\n- iTunes\n- JavaScript\n- WebSphere\n\n### How to refer to UI elements\n\nWhen writing about a UI element, use the same capitalization as used in the UI.\nFor example, if an input field is labeled “Name” then you refer to this as the\nName input field. Similarly, if a drop–down menu has the label “Country” next to\nit, then it is correct to refer to the Country drop–down menu. Where a product\npage is titled “My network”, you refer to this in writing as follows: “Enter\nyour network information in the My network page”.\n\n\n \n \n\n\n### Capitalizing proper nouns\n\nThe names of people, places, and products are proper nouns and therefore all\ntake initial capitals. Examples of proper nouns are:\n\n- Eliot Noyes\n- IBM Watson Studio\n- Paris, France\n- Porsche Boxster\n\nThere are many words that can act as either a common noun or a proper noun,\ndepending on the context. So, you always need to think about how the word is\nbeing used. Here are some examples:\n\n| Word | Used as a common noun | Used as a proper noun |\n| ------------------- | ------------------------------------------------ | -------------------------------------------------- |\n| agile | The group uses agile tools and processes | Debs referred her manager to the Agile Manifesto |\n| design | Jodi works in the design organization | Jodi works for IBM Design |\n| editor | Joe used a text editor to update the config file | Joe used IBM Flow Editor to define his data models |\n| front end developer | Jane is hoping to recruit a front end developer | Megan’s job title is Senior Front End Developer |\n\n### Capitalizing abbreviations\n\n**IBM product and service names**\n\nWhen referencing the name of any IBM product, use the official (full) name, not\nan abbreviation or just the product name initials, unless a shortened name has\nbeen specifically approved, as with IBM CICS.\n\n\n \n \n\n\nUse all uppercase letters for well–recognized abbreviations. This applies to\nboth initialisms, such as IBM, and to acronyms, such as GIF.\n\n- ASCII\n- CAPTCHA\n- FAQ\n- HTML\n- OK (not Ok or Okay)\n- WDSL\n\nIf there's a chance that an abbreviation might not be known to the target\naudience, it's good practice to spell it out in full the first time you use it.\nHowever, don't spell out commonly known abbreviations, for example PDF, CEO,\nAM/PM.\n\n### Capitalizing all other words\n\nUnless the word begins a sentence, phrase, or UI element name, don't give it a\ncapital letter.\n\nDon't give a word a capital letter to denote “specialness”. If you want to\nemphasize a particular word or phrase within a sentence, use italic or bold\nformatting (but not both).\n\n\n \n \n\n\n## Simple writing\n\n### Use simple words and sentences\n\nUse the simplest term that is appropriate for your audience. For example, use\nlarge instead of voluminous, and use small instead of diminutive.\n\nBe succinct, and keep sentences as short and simple as possible. Omit wordy or\nredundant phrases.\n\nTIP: Create a terminology list of words for your product that includes preferred\nwords and words not to use. This simple tool can help with consistency over\ntime, especially if multiple are writing copy.\n\nRespect a user's time and make things quick and easy to read. Always trim back\nto as few words as possible, although don't be terse.\n\nWe recommend avoiding terms of politeness such as _please_ and _thank you_ in a\nUI as they can be inappropriate or offensive in some cultural contexts.\n\n### Use simple present tense\n\nUse simple verbs and tenses, and keep sentences concise, simple, friendly, and\npunchy. Focus on the user's context and make content relevant. The more familiar\nyou are with their context, the better you can communicate without using a lot\nof words.\n\nIf you need to use past or future tense, avoid verb tenses with the words have,\nhas, had, been, should, would, and will.\n\n## Conversational style\n\nTo set the appropriate tone and conversation level, it helps to imagine the user\nengaging with the product as if in a conversation. The interplay between words,\nimagery, and interactions forms the conversation, a back–and–forth that takes\nplace on the glass, between the user and the product.\n\nThe conversational level is determined by where the user is in the journey, and\nthe task they are performing at that time. The most conversational content is\nusually found in the \"discover, try, and buy\" phases of the journey. Probably\nthe least conversational content can be found in error messages where an economy\nof words is desirable.\n\nWhatever the conversational level, the writing should always be simple, clear,\nand easy to understand. And keep the tone friendly, human, and inviting. Use\neveryday language, not jargon. And choose short words to make the reading\nfaster, rather than long, impressive–sounding words. Put the thesaurus away!\n\nIBM Style offers more guidelines on\n[conversational style](<[https://www-03preprod.ibm.com/support/knowledgecenter/ibm_style/conversational-style.html](https://ibmdocs-test.mybluemix.net/docs/en/ibm-style?topic=medium-conversational-style)>).\n\n### Formal versus casual tone\n\nWhile a more formal tone is often appropriate for technical and business\nwriting, a more casual tone is becoming increasingly accepted (and expected) in\nUI and supporting materials.\n\n- Don't be afraid to use **contractions** when they fit the context and improve\n the flow.\n- Beginning sentences with **and**, **but**, or **so** is not always forbidden.\n When it allows for shorter scannable sentences they can be used, but do not\n overuse these devices.\n- Use **exclamation marks** only positively, not negatively. Make sure you use\n no more than one exclamation mark in a context, such as a single window or a\n single Docs topic.\n\n\n \n \n\n\n#### Terms of politeness\n\nOften overused, these terms can convey the wrong tone for technical material,\nand are not regarded the same way in all cultures. Use terms such as “please”\nand “thank you” carefully.\n\n\n \n \n\n\n### Can, may, and might\n\n#### Terms of ability\n\nThese terms are often misused. Remember, “can” implies ability, and “may”\nimplies permission (and sometimes uncertainty).\n\n\n \n \n\n\n#### Terms of possibility\n\nThese terms can also be confusing. Remember, when either “may” or “might” will\nwork, generally go with “might” to avoid confusion with the multiple meanings of\n“may”.\n\n\n \n \n\n\n## Inclusive language\n\nIBM is committed to eliminating language that supports racial, cultural, or\ngender bias. It is critical that all words used in any capacity in product\nofferings be inclusive in their language.\n\nIBMers who are unsure about a particular word can search the\n[IBM Terminology database](http://ibm.biz/termsearch), and can also\n[submit a term for review](https://w3.terminology.g11n.ibm.com/standards/terminology/feedback).\n\nFor more information about this important work, see the\n[Inclusive IT Terminology](https://w3.ibm.com/w3publisher/inclusive-it-terminology/take-action)\nsite.\n\n## Pronouns\n\nUse the second person (you, your) as often as possible.\n\n\n \n \n\n\nYou can use first person in headings or labels that are very specific to the\nuser or customer data, for example “My account” or “My usage.” However, in\nexplanatory text for the heading or label, switch to second person. For example,\n“Your usage is calculated from the first day of the month.”\n\nWhere appropriate, use first person (we, our) to refer to IBM. For example, in\nrequests for personal information, such as name and email address, where the\nuser will benefit from knowing why IBM is asking for this information. Example:\n“Why do we need your email address?”\n\nAvoid third–person pronouns that are gender specific.\n\nFor more detailed guidance about pronouns, refer to the\n[Pronouns](https://ibmdocs-test.mybluemix.net/docs/en/ibm-style?topic=grammar-pronouns)\ntopic in IBM Style.\n\n## Active and passive voice\n\nThe _active voice_ is direct and emphasizes the subject of the sentence. The\nsubject clearly “acts upon” the verb (hence, “active”). For example, “John ate\nthe apple”. In situations where either voice will work, generally choose the\nactive voice for more directness.\n\n\n \n \n\n\nThe _passive voice_, on the other hand, flips the construction so that the\nsubject is secondary to the verb and object (hence, “passive”). Often, the\nsubject is not even included in the sentence. For example, “_The apple was eaten\nby John_” or just “_The apple was eaten_”. Only sentences that contain direct\nobjects can be constructed in the passive voice. Thus, “_John ate_” cannot be\nconstructed passively.\n\nThe passive voice makes for a more natural tone in certain use cases. For\nexample, if the true subject of the sentence is a system, and the human is\nsecondary, passive voice can be acceptable.\n\n\n \n \n\n","type":"Mdx","contentDigest":"c196691a985a9635b719c1cd95728ab2","owner":"gatsby-plugin-mdx","counter":5326},"frontmatter":{"title":"Content","description":"Writing should always be simple, clear, and easy to understand. Using everyday language keeps the tone friendly, human, and inviting. And choose short words over long, impressive–sounding words. Put the thesaurus away!","tabs":["Overview","Writing style","Action labels"]},"exports":{},"rawBody":"---\ntitle: Content\ndescription:\n Writing should always be simple, clear, and easy to understand. Using everyday\n language keeps the tone friendly, human, and inviting. And choose short words\n over long, impressive–sounding words. Put the thesaurus away!\ntabs: ['Overview', 'Writing style', 'Action labels']\n---\n\n\n\nWriting should always be simple, clear, and easy to understand. Using everyday\nlanguage keeps the tone friendly, human, and inviting. And choose short words\nover long, impressive–sounding words. Put the thesaurus away!\n\n\n\n\n\nCapitalization\nSimple writing\nConversational style\nInclusive language\nPronouns\nActive and passive voice\n\n\n\n## Capitalization\n\n### Use sentence–case capitalization\n\nUse sentence–case capitalization for all UI text elements. This style is\npredominantly lowercase. Capitalize only the initial letter of the first word in\nthe text and other words that require capitalization, such as proper nouns. For\nexample, labels in a form would be written as “First name” and “Email address”.\n\nThe image below shows a page title, tabs, a module title, link text, button\ntext, table headers, and table content all following the sentence case rule.\n\n\n\n\n\n\n
Example of a product page using sentence–style capitalization
\n\n\n\n\nSentence–style capitalization makes it easy for readers to distinguish between\ncommon nouns and proper nouns, and is generally considered the quickest form to\nread.\n\n> Do not capitalize the names of features and components unless they are sold\n> separately or are trademarked.\n>\n> – The IBM Style Guide: Conventions for Writers and Editors\n\nCarbon does not consider UI elements within a product to be proper nouns. Nor\ndoes Carbon support a concept of “important words” or “specialness”. Determining\nwhether something is important or special is highly subjective and can result in\ninconsistencies across an organization.\n\nUnless the name is a product or service name, or is trademarked, always use\nsentence–style capitalization.\n\nIn the following examples, the capitalization shows that Padlock, Visual\nRecognition, and IBM Cloud are either products or services.\n\n\n \n \n\n\n### Do not use title case capitalization\n\n**Title (or headline) case capitalization** is where the first letter of most\nwords is capitalized, but not articles, conjunctions, or prepositions (except if\nany of these are the first or last word in the sentence or phrase).\n\nTitle case is difficult to implement consistently across an organization\nbecause:\n\n1. It requires everyone who writes any copy to understand and follow fairly\n complex grammatical rules about which words should and shouldn't be\n capitalized, and\n\n1. It relies on a subjective viewpoint of what is considered “important” or\n “special” and that viewpoint being communicated or understood somehow.\n\nTitle case can also slow reading and comprehension down as it is more difficult\nfor readers to distinguish between proper nouns and common nouns.\n\n\n \n \n\n\n### Do not use all caps capitalization\n\n**All caps (or uppercase) capitalization** is where every letter is capitalized.\n\nAll caps capitalization has been shown to be slower to read (especially when\ntext is more than a few words) as individual letter shapes are less\ndistinguishable from each other—they are the same height and have no ascenders\nor descenders. This style also typically requires more space in the UI per\nletter than sentence case does.\n\nIn addition, it can be difficult for the reader to distinguish between proper\nnouns and common nouns. In the first example below, it's easy to distinguish\nproduct names from features whereas it takes longer to make these distinctions\nwhen the text is in all caps.\n\n\n \n \n\n\n### When to use capital letters\n\nCapital letters are reserved for the following:\n\n- “Carbon” or the “Carbon Design System” (the name of IBM’s official design\n system)\n- “IBM” or any other company or organization name\n- Any official, trademarked product or service (whether from IBM or not) –\n unless they intentionally use a lowercase letter at the beginning, such as the\n iPhone\n- Any initialisms (for example, BBC, HTML) or acronyms (for example, NASA, NATO)\n- Any people\n- Any country / place names\n- When referring to any UI labels that are themselves capitalized\n- When the word begins a sentence or phrase\n\nIf it’s not in the list above, it should not be capitalized.\n\nSometimes official company and product names use non–standard capitalization. If\nyou refer to any of these, ensure you write them accurately. Here are some\nexamples (all written correctly):\n\n- developerWorks\n- GitHub\n- iTunes\n- JavaScript\n- WebSphere\n\n### How to refer to UI elements\n\nWhen writing about a UI element, use the same capitalization as used in the UI.\nFor example, if an input field is labeled “Name” then you refer to this as the\nName input field. Similarly, if a drop–down menu has the label “Country” next to\nit, then it is correct to refer to the Country drop–down menu. Where a product\npage is titled “My network”, you refer to this in writing as follows: “Enter\nyour network information in the My network page”.\n\n\n \n \n\n\n### Capitalizing proper nouns\n\nThe names of people, places, and products are proper nouns and therefore all\ntake initial capitals. Examples of proper nouns are:\n\n- Eliot Noyes\n- IBM Watson Studio\n- Paris, France\n- Porsche Boxster\n\nThere are many words that can act as either a common noun or a proper noun,\ndepending on the context. So, you always need to think about how the word is\nbeing used. Here are some examples:\n\n| Word | Used as a common noun | Used as a proper noun |\n| ------------------- | ------------------------------------------------ | -------------------------------------------------- |\n| agile | The group uses agile tools and processes | Debs referred her manager to the Agile Manifesto |\n| design | Jodi works in the design organization | Jodi works for IBM Design |\n| editor | Joe used a text editor to update the config file | Joe used IBM Flow Editor to define his data models |\n| front end developer | Jane is hoping to recruit a front end developer | Megan’s job title is Senior Front End Developer |\n\n### Capitalizing abbreviations\n\n**IBM product and service names**\n\nWhen referencing the name of any IBM product, use the official (full) name, not\nan abbreviation or just the product name initials, unless a shortened name has\nbeen specifically approved, as with IBM CICS.\n\n\n \n \n\n\nUse all uppercase letters for well–recognized abbreviations. This applies to\nboth initialisms, such as IBM, and to acronyms, such as GIF.\n\n- ASCII\n- CAPTCHA\n- FAQ\n- HTML\n- OK (not Ok or Okay)\n- WDSL\n\nIf there's a chance that an abbreviation might not be known to the target\naudience, it's good practice to spell it out in full the first time you use it.\nHowever, don't spell out commonly known abbreviations, for example PDF, CEO,\nAM/PM.\n\n### Capitalizing all other words\n\nUnless the word begins a sentence, phrase, or UI element name, don't give it a\ncapital letter.\n\nDon't give a word a capital letter to denote “specialness”. If you want to\nemphasize a particular word or phrase within a sentence, use italic or bold\nformatting (but not both).\n\n\n \n \n\n\n## Simple writing\n\n### Use simple words and sentences\n\nUse the simplest term that is appropriate for your audience. For example, use\nlarge instead of voluminous, and use small instead of diminutive.\n\nBe succinct, and keep sentences as short and simple as possible. Omit wordy or\nredundant phrases.\n\nTIP: Create a terminology list of words for your product that includes preferred\nwords and words not to use. This simple tool can help with consistency over\ntime, especially if multiple are writing copy.\n\nRespect a user's time and make things quick and easy to read. Always trim back\nto as few words as possible, although don't be terse.\n\nWe recommend avoiding terms of politeness such as _please_ and _thank you_ in a\nUI as they can be inappropriate or offensive in some cultural contexts.\n\n### Use simple present tense\n\nUse simple verbs and tenses, and keep sentences concise, simple, friendly, and\npunchy. Focus on the user's context and make content relevant. The more familiar\nyou are with their context, the better you can communicate without using a lot\nof words.\n\nIf you need to use past or future tense, avoid verb tenses with the words have,\nhas, had, been, should, would, and will.\n\n## Conversational style\n\nTo set the appropriate tone and conversation level, it helps to imagine the user\nengaging with the product as if in a conversation. The interplay between words,\nimagery, and interactions forms the conversation, a back–and–forth that takes\nplace on the glass, between the user and the product.\n\nThe conversational level is determined by where the user is in the journey, and\nthe task they are performing at that time. The most conversational content is\nusually found in the \"discover, try, and buy\" phases of the journey. Probably\nthe least conversational content can be found in error messages where an economy\nof words is desirable.\n\nWhatever the conversational level, the writing should always be simple, clear,\nand easy to understand. And keep the tone friendly, human, and inviting. Use\neveryday language, not jargon. And choose short words to make the reading\nfaster, rather than long, impressive–sounding words. Put the thesaurus away!\n\nIBM Style offers more guidelines on\n[conversational style](<[https://www-03preprod.ibm.com/support/knowledgecenter/ibm_style/conversational-style.html](https://ibmdocs-test.mybluemix.net/docs/en/ibm-style?topic=medium-conversational-style)>).\n\n### Formal versus casual tone\n\nWhile a more formal tone is often appropriate for technical and business\nwriting, a more casual tone is becoming increasingly accepted (and expected) in\nUI and supporting materials.\n\n- Don't be afraid to use **contractions** when they fit the context and improve\n the flow.\n- Beginning sentences with **and**, **but**, or **so** is not always forbidden.\n When it allows for shorter scannable sentences they can be used, but do not\n overuse these devices.\n- Use **exclamation marks** only positively, not negatively. Make sure you use\n no more than one exclamation mark in a context, such as a single window or a\n single Docs topic.\n\n\n \n \n\n\n#### Terms of politeness\n\nOften overused, these terms can convey the wrong tone for technical material,\nand are not regarded the same way in all cultures. Use terms such as “please”\nand “thank you” carefully.\n\n\n \n \n\n\n### Can, may, and might\n\n#### Terms of ability\n\nThese terms are often misused. Remember, “can” implies ability, and “may”\nimplies permission (and sometimes uncertainty).\n\n\n \n \n\n\n#### Terms of possibility\n\nThese terms can also be confusing. Remember, when either “may” or “might” will\nwork, generally go with “might” to avoid confusion with the multiple meanings of\n“may”.\n\n\n \n \n\n\n## Inclusive language\n\nIBM is committed to eliminating language that supports racial, cultural, or\ngender bias. It is critical that all words used in any capacity in product\nofferings be inclusive in their language.\n\nIBMers who are unsure about a particular word can search the\n[IBM Terminology database](http://ibm.biz/termsearch), and can also\n[submit a term for review](https://w3.terminology.g11n.ibm.com/standards/terminology/feedback).\n\nFor more information about this important work, see the\n[Inclusive IT Terminology](https://w3.ibm.com/w3publisher/inclusive-it-terminology/take-action)\nsite.\n\n## Pronouns\n\nUse the second person (you, your) as often as possible.\n\n\n \n \n\n\nYou can use first person in headings or labels that are very specific to the\nuser or customer data, for example “My account” or “My usage.” However, in\nexplanatory text for the heading or label, switch to second person. For example,\n“Your usage is calculated from the first day of the month.”\n\nWhere appropriate, use first person (we, our) to refer to IBM. For example, in\nrequests for personal information, such as name and email address, where the\nuser will benefit from knowing why IBM is asking for this information. Example:\n“Why do we need your email address?”\n\nAvoid third–person pronouns that are gender specific.\n\nFor more detailed guidance about pronouns, refer to the\n[Pronouns](https://ibmdocs-test.mybluemix.net/docs/en/ibm-style?topic=grammar-pronouns)\ntopic in IBM Style.\n\n## Active and passive voice\n\nThe _active voice_ is direct and emphasizes the subject of the sentence. The\nsubject clearly “acts upon” the verb (hence, “active”). For example, “John ate\nthe apple”. In situations where either voice will work, generally choose the\nactive voice for more directness.\n\n\n \n \n\n\nThe _passive voice_, on the other hand, flips the construction so that the\nsubject is secondary to the verb and object (hence, “passive”). Often, the\nsubject is not even included in the sentence. For example, “_The apple was eaten\nby John_” or just “_The apple was eaten_”. Only sentences that contain direct\nobjects can be constructed in the passive voice. Thus, “_John ate_” cannot be\nconstructed passively.\n\nThe passive voice makes for a more natural tone in certain use cases. For\nexample, if the true subject of the sentence is a system, and the human is\nsecondary, passive voice can be acceptable.\n\n\n \n \n\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/guidelines/content/writing-style.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/help/contact-us/page-data.json b/page-data/help/contact-us/page-data.json
index 1214d01a8b7..949be266937 100644
--- a/page-data/help/contact-us/page-data.json
+++ b/page-data/help/contact-us/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-help-contact-us-index-mdx","path":"/help/contact-us/","result":{"pageContext":{"frontmatter":{"title":"Contact us","description":"Have a question about our design system? The Carbon team is here to help you. Before you start, be sure to check out the following resources to see if we've already got your topic covered."},"relativePagePath":"/help/contact-us/index.mdx","titleType":"prepend","MdxNode":{"id":"9fa1d57a-3c99-512c-b75c-fadf7534a1c2","children":[],"parent":"ef6986f3-4583-5951-91e7-2d100bdc8975","internal":{"content":"---\ntitle: Contact us\ndescription:\n Have a question about our design system? The Carbon team is here to help you.\n Before you start, be sure to check out the following resources to see if we've\n already got your topic covered.\n---\n\n\n\nHave a question about our design system? The Carbon team is here to help you.\nBefore you start, be sure to check out the following resources to see if we've\nalready got your topic covered.\n\n\n\n\n\nCheck existing resources\nProvide a suggestion or contribution\nStart a new discussion\n\n\n\n## Check existing resources\n\n### Carbon website\n\nAs a first step, it's always good to explore the content on this website. The\nsite is comprehensive and most of the guidelines and components are well\ndocumented.\n\n### Frequently asked questions\n\nAnswers to the most common questions about the design system can be found in the\n[Carbon FAQs](/help/faq).\n\n## Provide a suggestion or contribution\n\nThe Carbon core team provides support for users of the design system. Find the\nuse case below that most closely matches your own for the quickest response.\n\n### GitHub issues\n\nIf you have a bug report, suggestion, or general feedback, please create a\nGitHub issue.\n\n#### Design issues\n\n- [Design kit](https://github.com/carbon-design-system/carbon-design-kit/issues/new)\n- [Icons](https://github.com/carbon-design-system/carbon-icons/issues/new)\n- [Website](https://github.com/carbon-design-system/carbon-website/issues/new/choose)\n- [Components](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [Elements](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [Charts](https://github.com/carbon-design-system/carbon-charts/issues/new)\n- [Everything else](https://github.com/carbon-design-system/issue-tracking/issues/new)\n\n#### Code issues\n\n- [@carbon/react](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [@carbon/web-components](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues/new/choose)\n- [carbon-components-angular](https://github.com/IBM/carbon-components-angular/issues/new)\n- [carbon-components-vanilla](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [carbon-components-vue](https://github.com/carbon-design-system/carbon-components-vue/issues/new)\n- [carbon-charts](https://github.com/carbon-design-system/carbon-charts/issues/new)\n\n### GitHub pull requests\n\nIf you have a specific fix or a contribution, you can generate a pull request in\nthe appropriate Carbon repo.\n\n## Start a new discussion\n\n### Discord\n\nCome chat and get support from Carbon maintainers and fellow community members\non our [Discord server](https://discord.gg/SYjvP8epkM).\n\n### Slack channels\n\n_For internal IBM users only._ The Carbon core team maintains the following\nchannels and will provide support as time permits.\n\nTry searching the Slack channel for your topic first. Slack’s filtering feature\nwill return more targeted and relevant results. For instance, if you have a\ntechnical question about the `DataTable` component, you could search “DataTable”\nin Slack and then filter by the #carbon-components channel.\n\n_Tip: You can start a new search directly from the message box using the `/s`\nslash command._\n\nFor designer questions:\n[#carbon-design-system](https://ibm-studios.slack.com/messages/C0M053VPT/)\n\nFor developer questions:\n[#carbon-react](https://ibm-studios.slack.com/messages/C2K6RFJ1G/),\n[#carbon-web-components](https://ibm-studios.slack.com/archives/CL83LMKSA)\n\n### Email\n\nMessages to will be addressed by the Carbon technical team\nas quickly as possible.\n\n### Twitter\n\nThe Carbon team can also be reached on Twitter:\n[@\\_carbondesign](https://twitter.com/_carbondesign?lang=en)\n","type":"Mdx","contentDigest":"371e29bd10a1019089e9ebd6cc4a1148","owner":"gatsby-plugin-mdx","counter":5326},"frontmatter":{"title":"Contact us","description":"Have a question about our design system? The Carbon team is here to help you. Before you start, be sure to check out the following resources to see if we've already got your topic covered."},"exports":{},"rawBody":"---\ntitle: Contact us\ndescription:\n Have a question about our design system? The Carbon team is here to help you.\n Before you start, be sure to check out the following resources to see if we've\n already got your topic covered.\n---\n\n\n\nHave a question about our design system? The Carbon team is here to help you.\nBefore you start, be sure to check out the following resources to see if we've\nalready got your topic covered.\n\n\n\n\n\nCheck existing resources\nProvide a suggestion or contribution\nStart a new discussion\n\n\n\n## Check existing resources\n\n### Carbon website\n\nAs a first step, it's always good to explore the content on this website. The\nsite is comprehensive and most of the guidelines and components are well\ndocumented.\n\n### Frequently asked questions\n\nAnswers to the most common questions about the design system can be found in the\n[Carbon FAQs](/help/faq).\n\n## Provide a suggestion or contribution\n\nThe Carbon core team provides support for users of the design system. Find the\nuse case below that most closely matches your own for the quickest response.\n\n### GitHub issues\n\nIf you have a bug report, suggestion, or general feedback, please create a\nGitHub issue.\n\n#### Design issues\n\n- [Design kit](https://github.com/carbon-design-system/carbon-design-kit/issues/new)\n- [Icons](https://github.com/carbon-design-system/carbon-icons/issues/new)\n- [Website](https://github.com/carbon-design-system/carbon-website/issues/new/choose)\n- [Components](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [Elements](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [Charts](https://github.com/carbon-design-system/carbon-charts/issues/new)\n- [Everything else](https://github.com/carbon-design-system/issue-tracking/issues/new)\n\n#### Code issues\n\n- [@carbon/react](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [@carbon/web-components](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues/new/choose)\n- [carbon-components-angular](https://github.com/IBM/carbon-components-angular/issues/new)\n- [carbon-components-vanilla](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [carbon-components-vue](https://github.com/carbon-design-system/carbon-components-vue/issues/new)\n- [carbon-charts](https://github.com/carbon-design-system/carbon-charts/issues/new)\n\n### GitHub pull requests\n\nIf you have a specific fix or a contribution, you can generate a pull request in\nthe appropriate Carbon repo.\n\n## Start a new discussion\n\n### Discord\n\nCome chat and get support from Carbon maintainers and fellow community members\non our [Discord server](https://discord.gg/SYjvP8epkM).\n\n### Slack channels\n\n_For internal IBM users only._ The Carbon core team maintains the following\nchannels and will provide support as time permits.\n\nTry searching the Slack channel for your topic first. Slack’s filtering feature\nwill return more targeted and relevant results. For instance, if you have a\ntechnical question about the `DataTable` component, you could search “DataTable”\nin Slack and then filter by the #carbon-components channel.\n\n_Tip: You can start a new search directly from the message box using the `/s`\nslash command._\n\nFor designer questions:\n[#carbon-design-system](https://ibm-studios.slack.com/messages/C0M053VPT/)\n\nFor developer questions:\n[#carbon-react](https://ibm-studios.slack.com/messages/C2K6RFJ1G/),\n[#carbon-web-components](https://ibm-studios.slack.com/archives/CL83LMKSA)\n\n### Email\n\nMessages to will be addressed by the Carbon technical team\nas quickly as possible.\n\n### Twitter\n\nThe Carbon team can also be reached on Twitter:\n[@\\_carbondesign](https://twitter.com/_carbondesign?lang=en)\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/help/contact-us/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-help-contact-us-index-mdx","path":"/help/contact-us/","result":{"pageContext":{"frontmatter":{"title":"Contact us","description":"Have a question about our design system? The Carbon team is here to help you. Before you start, be sure to check out the following resources to see if we've already got your topic covered."},"relativePagePath":"/help/contact-us/index.mdx","titleType":"prepend","MdxNode":{"id":"9fa1d57a-3c99-512c-b75c-fadf7534a1c2","children":[],"parent":"ef6986f3-4583-5951-91e7-2d100bdc8975","internal":{"content":"---\ntitle: Contact us\ndescription:\n Have a question about our design system? The Carbon team is here to help you.\n Before you start, be sure to check out the following resources to see if we've\n already got your topic covered.\n---\n\n\n\nHave a question about our design system? The Carbon team is here to help you.\nBefore you start, be sure to check out the following resources to see if we've\nalready got your topic covered.\n\n\n\n\n\nCheck existing resources\nProvide a suggestion or contribution\nStart a new discussion\n\n\n\n## Check existing resources\n\n### Carbon website\n\nAs a first step, it's always good to explore the content on this website. The\nsite is comprehensive and most of the guidelines and components are well\ndocumented.\n\n### Frequently asked questions\n\nAnswers to the most common questions about the design system can be found in the\n[Carbon FAQs](/help/faq).\n\n## Provide a suggestion or contribution\n\nThe Carbon core team provides support for users of the design system. Find the\nuse case below that most closely matches your own for the quickest response.\n\n### GitHub issues\n\nIf you have a bug report, suggestion, or general feedback, please create a\nGitHub issue.\n\n#### Design issues\n\n- [Design kit](https://github.com/carbon-design-system/carbon-design-kit/issues/new)\n- [Icons](https://github.com/carbon-design-system/carbon-icons/issues/new)\n- [Website](https://github.com/carbon-design-system/carbon-website/issues/new/choose)\n- [Components](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [Elements](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [Charts](https://github.com/carbon-design-system/carbon-charts/issues/new)\n- [Everything else](https://github.com/carbon-design-system/issue-tracking/issues/new)\n\n#### Code issues\n\n- [@carbon/react](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [@carbon/web-components](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues/new/choose)\n- [carbon-components-angular](https://github.com/IBM/carbon-components-angular/issues/new)\n- [carbon-components-vanilla](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [carbon-components-vue](https://github.com/carbon-design-system/carbon-components-vue/issues/new)\n- [carbon-charts](https://github.com/carbon-design-system/carbon-charts/issues/new)\n\n### GitHub pull requests\n\nIf you have a specific fix or a contribution, you can generate a pull request in\nthe appropriate Carbon repo.\n\n## Start a new discussion\n\n### Discord\n\nCome chat and get support from Carbon maintainers and fellow community members\non our [Discord server](https://discord.gg/SYjvP8epkM).\n\n### Slack channels\n\n_For internal IBM users only._ The Carbon core team maintains the following\nchannels and will provide support as time permits.\n\nTry searching the Slack channel for your topic first. Slack’s filtering feature\nwill return more targeted and relevant results. For instance, if you have a\ntechnical question about the `DataTable` component, you could search “DataTable”\nin Slack and then filter by the #carbon-components channel.\n\n_Tip: You can start a new search directly from the message box using the `/s`\nslash command._\n\nFor designer questions:\n[#carbon-design-system](https://ibm-studios.slack.com/messages/C0M053VPT/)\n\nFor developer questions:\n[#carbon-react](https://ibm-studios.slack.com/messages/C2K6RFJ1G/),\n[#carbon-web-components](https://ibm-studios.slack.com/archives/CL83LMKSA)\n\n### Email\n\nMessages to will be addressed by the Carbon technical team\nas quickly as possible.\n\n### Twitter\n\nThe Carbon team can also be reached on Twitter:\n[@\\_carbondesign](https://twitter.com/_carbondesign?lang=en)\n","type":"Mdx","contentDigest":"371e29bd10a1019089e9ebd6cc4a1148","owner":"gatsby-plugin-mdx","counter":5327},"frontmatter":{"title":"Contact us","description":"Have a question about our design system? The Carbon team is here to help you. Before you start, be sure to check out the following resources to see if we've already got your topic covered."},"exports":{},"rawBody":"---\ntitle: Contact us\ndescription:\n Have a question about our design system? The Carbon team is here to help you.\n Before you start, be sure to check out the following resources to see if we've\n already got your topic covered.\n---\n\n\n\nHave a question about our design system? The Carbon team is here to help you.\nBefore you start, be sure to check out the following resources to see if we've\nalready got your topic covered.\n\n\n\n\n\nCheck existing resources\nProvide a suggestion or contribution\nStart a new discussion\n\n\n\n## Check existing resources\n\n### Carbon website\n\nAs a first step, it's always good to explore the content on this website. The\nsite is comprehensive and most of the guidelines and components are well\ndocumented.\n\n### Frequently asked questions\n\nAnswers to the most common questions about the design system can be found in the\n[Carbon FAQs](/help/faq).\n\n## Provide a suggestion or contribution\n\nThe Carbon core team provides support for users of the design system. Find the\nuse case below that most closely matches your own for the quickest response.\n\n### GitHub issues\n\nIf you have a bug report, suggestion, or general feedback, please create a\nGitHub issue.\n\n#### Design issues\n\n- [Design kit](https://github.com/carbon-design-system/carbon-design-kit/issues/new)\n- [Icons](https://github.com/carbon-design-system/carbon-icons/issues/new)\n- [Website](https://github.com/carbon-design-system/carbon-website/issues/new/choose)\n- [Components](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [Elements](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [Charts](https://github.com/carbon-design-system/carbon-charts/issues/new)\n- [Everything else](https://github.com/carbon-design-system/issue-tracking/issues/new)\n\n#### Code issues\n\n- [@carbon/react](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [@carbon/web-components](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues/new/choose)\n- [carbon-components-angular](https://github.com/IBM/carbon-components-angular/issues/new)\n- [carbon-components-vanilla](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [carbon-components-vue](https://github.com/carbon-design-system/carbon-components-vue/issues/new)\n- [carbon-charts](https://github.com/carbon-design-system/carbon-charts/issues/new)\n\n### GitHub pull requests\n\nIf you have a specific fix or a contribution, you can generate a pull request in\nthe appropriate Carbon repo.\n\n## Start a new discussion\n\n### Discord\n\nCome chat and get support from Carbon maintainers and fellow community members\non our [Discord server](https://discord.gg/SYjvP8epkM).\n\n### Slack channels\n\n_For internal IBM users only._ The Carbon core team maintains the following\nchannels and will provide support as time permits.\n\nTry searching the Slack channel for your topic first. Slack’s filtering feature\nwill return more targeted and relevant results. For instance, if you have a\ntechnical question about the `DataTable` component, you could search “DataTable”\nin Slack and then filter by the #carbon-components channel.\n\n_Tip: You can start a new search directly from the message box using the `/s`\nslash command._\n\nFor designer questions:\n[#carbon-design-system](https://ibm-studios.slack.com/messages/C0M053VPT/)\n\nFor developer questions:\n[#carbon-react](https://ibm-studios.slack.com/messages/C2K6RFJ1G/),\n[#carbon-web-components](https://ibm-studios.slack.com/archives/CL83LMKSA)\n\n### Email\n\nMessages to will be addressed by the Carbon technical team\nas quickly as possible.\n\n### Twitter\n\nThe Carbon team can also be reached on Twitter:\n[@\\_carbondesign](https://twitter.com/_carbondesign?lang=en)\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/help/contact-us/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/help/faq/page-data.json b/page-data/help/faq/page-data.json
index e4b355f6e6c..44561913ddc 100644
--- a/page-data/help/faq/page-data.json
+++ b/page-data/help/faq/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-help-faq-index-mdx","path":"/help/faq/","result":{"pageContext":{"frontmatter":{"title":"FAQs","description":"What is the Carbon Design System? Who works on Carbon? How can I contribute? Here, we answer some of our frequently asked questions."},"relativePagePath":"/help/faq/index.mdx","titleType":"prepend","MdxNode":{"id":"1140a300-e6e1-544e-b7a8-0bff20590823","children":[],"parent":"70d00f9b-5a64-5370-8f21-b62995ce3daf","internal":{"content":"---\ntitle: FAQs\ndescription:\n What is the Carbon Design System? Who works on Carbon? How can I contribute?\n Here, we answer some of our frequently asked questions.\n---\n\n\n\nAbout Carbon\nContributing\nCreating with Carbon\nTelemetry\n\n\n\n## About Carbon\n\n### What is the Carbon Design System?\n\nCarbon is the open-source design system for all IBM software products. It is a\nseries of individual styles, components, and guidelines used for creating\nunified product experiences.\n\nTo learn more about how we work check out\n[What is Carbon](/all-about-carbon/what-is-carbon).\n\n### Who works on Carbon?\n\nCarbon has a core team of designers and front-end developers dedicated to\ndeveloping and supporting the system. There are also countless other designers\nand developers who contribute back to\n[carbon-react](https://github.com/carbon-design-system/carbon#contributors).\n\n## Contributing\n\n### How can I contribute and/or propose new components or ideas?\n\nCheck out our [contribution get started](/contributing/get-started) page to\nlearn all about the different ways to contribute. Thanks for the help!\n\n### I see a bug. How do I report it?\n\nFirst, make sure the problem is reproducible. Once confirmed, open an issue in\nthe appropriate GitHub repo from the following list. We will address the bug as\nsoon as we can. If you have a fix for the bug, please feel free to submit a PR\nfor it.\n\nFor larger changes, please see our\n[contribution get started](/contributing/get-started) page.\n\n#### Design issue repos\n\n- [Design kit](https://github.com/carbon-design-system/carbon-design-kit/issues/new)\n- [Icons](https://github.com/carbon-design-system/carbon-icons/issues/new)\n- [Website](https://github.com/carbon-design-system/carbon-website/issues/new/choose)\n- [Components](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [Elements](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [Charts](https://github.com/carbon-design-system/carbon-charts/issues/new)\n- [Everything else](https://github.com/carbon-design-system/carbon/issues/new/choose)\n\n#### Code repos\n\n- [@carbon/react](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [@carbon/web-components](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues/new/choose)\n- [carbon-components-angular](https://github.com/IBM/carbon-components-angular/issues/new)\n- [carbon-components-vanilla](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [carbon-components-vue](https://github.com/carbon-design-system/carbon-components-vue/issues/new)\n- [carbon-charts](https://github.com/carbon-design-system/carbon-charts/issues/new)\n\n### What can I expect for a response to my bug report?\n\nIf you have a pressing bug or change it is best to make a PR for the issue\nyourself. Our team works in sprints and will try to address your bug as soon as\npossible; sometimes within two or three days, but usually by the following\nsprint. Issues that are out of scope will be closed until they become a higher\npriority.\n\nTypical responses to bug reports will include:\n\n- Need more info, can't reproduce the problem\n- Won't fix, this isn't something we intend to support\n- Confirmed, will add to our roadmap (Carbon team will fix)\n- Confirmed, will accept PRs (need external member to fix)\n- Need to include design to verify this behavior is supported\n\n### What should I do if I find a component that isn't accessible?\n\nFirst, refer to the\n[Carbon accessibility guidelines](/guidelines/accessibility/overview) to confirm\nthat the component fails accessibility standards. If confirmed,\n[create a GitHub issue](https://github.com/carbon-design-system/carbon/issues/new/choose)\nin the Components repo and describe the steps to reproduce the problem. If the\ncore Carbon team confirms the problem, we will work to fix it as quickly as\npossible.\n\n## Creating with Carbon\n\n### Which browsers are supported?\n\nCarbon components are supported in the following browsers:\n\n- Microsoft Edge latest\n- Firefox latest\n- Chrome latest\n- Safari latest\n\nFor IBM teams, see\n[browser support standards here](https://w3.ibm.com/w3publisher/ibm-web-standards-external/standards-mandatory/browser-standards).\n\n### What languages are the components written in?\n\nCarbon is built React first, with official support for Web Components. There is\ncommunity support for vanilla JS, Angular, Vue, and Svelte implementations.\nCheck out [Frameworks](/developing/frameworks/react) to learn more about what\nyou need to get started with Carbon implementations.\n\n### Where do I find mobile components?\n\nThe Carbon Native mobile Figma kit is available on the\n[Other resources](https://carbondesignsystem.com/designing/design-resources/#native-mobile)\npage.\n\n### Where do I find the Experimental components and patterns?\n\nThe patterns and components that were in Experimental are now in the\n[Community assets](/community/overview) section. Community assets include work\ndeveloped and maintained by the individuals and teams who use Carbon. You can\nhelp elevate these resources by contributing feedback, code, and design.\n\nNote that some of the content in Community assets is hosted on internal IBM\nsites and is only accessible to IBMers.\n\n### Where do I find charts and data visualization?\n\nCarbon charts and their corresponding assets and documentation are now in the\n[Data visualization](/data-visualization/getting-started) section.\n\n### Where can I find documentation for earlier versions of Carbon?\n\nYou can find earlier versions of Carbon documentation here:\n**[V6](http://v6.carbondesignsystem.com/)**,\n**[V7](http://v7.carbondesignsystem.com/)**,\n**[V8](http://v8.carbondesignsystem.com/)**,\n**[V9](http://v9.carbondesignsystem.com/)**, and\n**[V10](http://v10.carbondesignsystem.com/).**\n\n## Telemetry\n\nCarbon contains a telemetry feature that collects usage information for IBM and\nCarbon Design System properties.\n\n### Why is telemetry collected?\n\nCarbon collects telemetry information to influence Carbon's roadmap and\nprioritize bug fixes.\n\n### When is data collected?\n\nData is only collected when Carbon packages are installed on a Continuous\nIntegration (CI) server, when the installation is not part of a Pull Request\n(PR), and for Git repositories with the origin remotes:\n\n- `github.ibm.com`\n- `github.com/ibm`\n- `github.com/carbon-design-system`\n\nAs the information collected is not anonymous, telemetry data collection is\nlimited to IBM GitHub Enterprise repositories, as well as open source\nrepositories in the IBM and Carbon Design System GitHub organizations.\n\n### What is being collected?\n\nThe following is collected through a postinstall script:\n\n- Git repository remote origin URLs and commit hashes\n- Packages and package versions used in the repository\n- Components being used including file paths and their packages\n- Component props being used (the prop value is only collected when it is\n serializable to a string)\n\n### How do I opt out?\n\nParticipation in Carbon's telemetry is optional. To opt-out, set the environment\nvariable `CARBON_TELEMETRY_DISABLED` to `1`.\n","type":"Mdx","contentDigest":"9b5756a60bbab8f80833d7d37b451f17","owner":"gatsby-plugin-mdx","counter":5329},"frontmatter":{"title":"FAQs","description":"What is the Carbon Design System? Who works on Carbon? How can I contribute? Here, we answer some of our frequently asked questions."},"exports":{},"rawBody":"---\ntitle: FAQs\ndescription:\n What is the Carbon Design System? Who works on Carbon? How can I contribute?\n Here, we answer some of our frequently asked questions.\n---\n\n\n\nAbout Carbon\nContributing\nCreating with Carbon\nTelemetry\n\n\n\n## About Carbon\n\n### What is the Carbon Design System?\n\nCarbon is the open-source design system for all IBM software products. It is a\nseries of individual styles, components, and guidelines used for creating\nunified product experiences.\n\nTo learn more about how we work check out\n[What is Carbon](/all-about-carbon/what-is-carbon).\n\n### Who works on Carbon?\n\nCarbon has a core team of designers and front-end developers dedicated to\ndeveloping and supporting the system. There are also countless other designers\nand developers who contribute back to\n[carbon-react](https://github.com/carbon-design-system/carbon#contributors).\n\n## Contributing\n\n### How can I contribute and/or propose new components or ideas?\n\nCheck out our [contribution get started](/contributing/get-started) page to\nlearn all about the different ways to contribute. Thanks for the help!\n\n### I see a bug. How do I report it?\n\nFirst, make sure the problem is reproducible. Once confirmed, open an issue in\nthe appropriate GitHub repo from the following list. We will address the bug as\nsoon as we can. If you have a fix for the bug, please feel free to submit a PR\nfor it.\n\nFor larger changes, please see our\n[contribution get started](/contributing/get-started) page.\n\n#### Design issue repos\n\n- [Design kit](https://github.com/carbon-design-system/carbon-design-kit/issues/new)\n- [Icons](https://github.com/carbon-design-system/carbon-icons/issues/new)\n- [Website](https://github.com/carbon-design-system/carbon-website/issues/new/choose)\n- [Components](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [Elements](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [Charts](https://github.com/carbon-design-system/carbon-charts/issues/new)\n- [Everything else](https://github.com/carbon-design-system/carbon/issues/new/choose)\n\n#### Code repos\n\n- [@carbon/react](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [@carbon/web-components](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues/new/choose)\n- [carbon-components-angular](https://github.com/IBM/carbon-components-angular/issues/new)\n- [carbon-components-vanilla](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [carbon-components-vue](https://github.com/carbon-design-system/carbon-components-vue/issues/new)\n- [carbon-charts](https://github.com/carbon-design-system/carbon-charts/issues/new)\n\n### What can I expect for a response to my bug report?\n\nIf you have a pressing bug or change it is best to make a PR for the issue\nyourself. Our team works in sprints and will try to address your bug as soon as\npossible; sometimes within two or three days, but usually by the following\nsprint. Issues that are out of scope will be closed until they become a higher\npriority.\n\nTypical responses to bug reports will include:\n\n- Need more info, can't reproduce the problem\n- Won't fix, this isn't something we intend to support\n- Confirmed, will add to our roadmap (Carbon team will fix)\n- Confirmed, will accept PRs (need external member to fix)\n- Need to include design to verify this behavior is supported\n\n### What should I do if I find a component that isn't accessible?\n\nFirst, refer to the\n[Carbon accessibility guidelines](/guidelines/accessibility/overview) to confirm\nthat the component fails accessibility standards. If confirmed,\n[create a GitHub issue](https://github.com/carbon-design-system/carbon/issues/new/choose)\nin the Components repo and describe the steps to reproduce the problem. If the\ncore Carbon team confirms the problem, we will work to fix it as quickly as\npossible.\n\n## Creating with Carbon\n\n### Which browsers are supported?\n\nCarbon components are supported in the following browsers:\n\n- Microsoft Edge latest\n- Firefox latest\n- Chrome latest\n- Safari latest\n\nFor IBM teams, see\n[browser support standards here](https://w3.ibm.com/w3publisher/ibm-web-standards-external/standards-mandatory/browser-standards).\n\n### What languages are the components written in?\n\nCarbon is built React first, with official support for Web Components. There is\ncommunity support for vanilla JS, Angular, Vue, and Svelte implementations.\nCheck out [Frameworks](/developing/frameworks/react) to learn more about what\nyou need to get started with Carbon implementations.\n\n### Where do I find mobile components?\n\nThe Carbon Native mobile Figma kit is available on the\n[Other resources](https://carbondesignsystem.com/designing/design-resources/#native-mobile)\npage.\n\n### Where do I find the Experimental components and patterns?\n\nThe patterns and components that were in Experimental are now in the\n[Community assets](/community/overview) section. Community assets include work\ndeveloped and maintained by the individuals and teams who use Carbon. You can\nhelp elevate these resources by contributing feedback, code, and design.\n\nNote that some of the content in Community assets is hosted on internal IBM\nsites and is only accessible to IBMers.\n\n### Where do I find charts and data visualization?\n\nCarbon charts and their corresponding assets and documentation are now in the\n[Data visualization](/data-visualization/getting-started) section.\n\n### Where can I find documentation for earlier versions of Carbon?\n\nYou can find earlier versions of Carbon documentation here:\n**[V6](http://v6.carbondesignsystem.com/)**,\n**[V7](http://v7.carbondesignsystem.com/)**,\n**[V8](http://v8.carbondesignsystem.com/)**,\n**[V9](http://v9.carbondesignsystem.com/)**, and\n**[V10](http://v10.carbondesignsystem.com/).**\n\n## Telemetry\n\nCarbon contains a telemetry feature that collects usage information for IBM and\nCarbon Design System properties.\n\n### Why is telemetry collected?\n\nCarbon collects telemetry information to influence Carbon's roadmap and\nprioritize bug fixes.\n\n### When is data collected?\n\nData is only collected when Carbon packages are installed on a Continuous\nIntegration (CI) server, when the installation is not part of a Pull Request\n(PR), and for Git repositories with the origin remotes:\n\n- `github.ibm.com`\n- `github.com/ibm`\n- `github.com/carbon-design-system`\n\nAs the information collected is not anonymous, telemetry data collection is\nlimited to IBM GitHub Enterprise repositories, as well as open source\nrepositories in the IBM and Carbon Design System GitHub organizations.\n\n### What is being collected?\n\nThe following is collected through a postinstall script:\n\n- Git repository remote origin URLs and commit hashes\n- Packages and package versions used in the repository\n- Components being used including file paths and their packages\n- Component props being used (the prop value is only collected when it is\n serializable to a string)\n\n### How do I opt out?\n\nParticipation in Carbon's telemetry is optional. To opt-out, set the environment\nvariable `CARBON_TELEMETRY_DISABLED` to `1`.\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/help/faq/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-help-faq-index-mdx","path":"/help/faq/","result":{"pageContext":{"frontmatter":{"title":"FAQs","description":"What is the Carbon Design System? Who works on Carbon? How can I contribute? Here, we answer some of our frequently asked questions."},"relativePagePath":"/help/faq/index.mdx","titleType":"prepend","MdxNode":{"id":"1140a300-e6e1-544e-b7a8-0bff20590823","children":[],"parent":"70d00f9b-5a64-5370-8f21-b62995ce3daf","internal":{"content":"---\ntitle: FAQs\ndescription:\n What is the Carbon Design System? Who works on Carbon? How can I contribute?\n Here, we answer some of our frequently asked questions.\n---\n\n\n\nAbout Carbon\nContributing\nCreating with Carbon\nTelemetry\n\n\n\n## About Carbon\n\n### What is the Carbon Design System?\n\nCarbon is the open-source design system for all IBM software products. It is a\nseries of individual styles, components, and guidelines used for creating\nunified product experiences.\n\nTo learn more about how we work check out\n[What is Carbon](/all-about-carbon/what-is-carbon).\n\n### Who works on Carbon?\n\nCarbon has a core team of designers and front-end developers dedicated to\ndeveloping and supporting the system. There are also countless other designers\nand developers who contribute back to\n[carbon-react](https://github.com/carbon-design-system/carbon#contributors).\n\n## Contributing\n\n### How can I contribute and/or propose new components or ideas?\n\nCheck out our [contribution get started](/contributing/get-started) page to\nlearn all about the different ways to contribute. Thanks for the help!\n\n### I see a bug. How do I report it?\n\nFirst, make sure the problem is reproducible. Once confirmed, open an issue in\nthe appropriate GitHub repo from the following list. We will address the bug as\nsoon as we can. If you have a fix for the bug, please feel free to submit a PR\nfor it.\n\nFor larger changes, please see our\n[contribution get started](/contributing/get-started) page.\n\n#### Design issue repos\n\n- [Design kit](https://github.com/carbon-design-system/carbon-design-kit/issues/new)\n- [Icons](https://github.com/carbon-design-system/carbon-icons/issues/new)\n- [Website](https://github.com/carbon-design-system/carbon-website/issues/new/choose)\n- [Components](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [Elements](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [Charts](https://github.com/carbon-design-system/carbon-charts/issues/new)\n- [Everything else](https://github.com/carbon-design-system/carbon/issues/new/choose)\n\n#### Code repos\n\n- [@carbon/react](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [@carbon/web-components](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues/new/choose)\n- [carbon-components-angular](https://github.com/IBM/carbon-components-angular/issues/new)\n- [carbon-components-vanilla](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [carbon-components-vue](https://github.com/carbon-design-system/carbon-components-vue/issues/new)\n- [carbon-charts](https://github.com/carbon-design-system/carbon-charts/issues/new)\n\n### What can I expect for a response to my bug report?\n\nIf you have a pressing bug or change it is best to make a PR for the issue\nyourself. Our team works in sprints and will try to address your bug as soon as\npossible; sometimes within two or three days, but usually by the following\nsprint. Issues that are out of scope will be closed until they become a higher\npriority.\n\nTypical responses to bug reports will include:\n\n- Need more info, can't reproduce the problem\n- Won't fix, this isn't something we intend to support\n- Confirmed, will add to our roadmap (Carbon team will fix)\n- Confirmed, will accept PRs (need external member to fix)\n- Need to include design to verify this behavior is supported\n\n### What should I do if I find a component that isn't accessible?\n\nFirst, refer to the\n[Carbon accessibility guidelines](/guidelines/accessibility/overview) to confirm\nthat the component fails accessibility standards. If confirmed,\n[create a GitHub issue](https://github.com/carbon-design-system/carbon/issues/new/choose)\nin the Components repo and describe the steps to reproduce the problem. If the\ncore Carbon team confirms the problem, we will work to fix it as quickly as\npossible.\n\n## Creating with Carbon\n\n### Which browsers are supported?\n\nCarbon components are supported in the following browsers:\n\n- Microsoft Edge latest\n- Firefox latest\n- Chrome latest\n- Safari latest\n\nFor IBM teams, see\n[browser support standards here](https://w3.ibm.com/w3publisher/ibm-web-standards-external/standards-mandatory/browser-standards).\n\n### What languages are the components written in?\n\nCarbon is built React first, with official support for Web Components. There is\ncommunity support for vanilla JS, Angular, Vue, and Svelte implementations.\nCheck out [Frameworks](/developing/frameworks/react) to learn more about what\nyou need to get started with Carbon implementations.\n\n### Where do I find mobile components?\n\nThe Carbon Native mobile Figma kit is available on the\n[Other resources](https://carbondesignsystem.com/designing/design-resources/#native-mobile)\npage.\n\n### Where do I find the Experimental components and patterns?\n\nThe patterns and components that were in Experimental are now in the\n[Community assets](/community/overview) section. Community assets include work\ndeveloped and maintained by the individuals and teams who use Carbon. You can\nhelp elevate these resources by contributing feedback, code, and design.\n\nNote that some of the content in Community assets is hosted on internal IBM\nsites and is only accessible to IBMers.\n\n### Where do I find charts and data visualization?\n\nCarbon charts and their corresponding assets and documentation are now in the\n[Data visualization](/data-visualization/getting-started) section.\n\n### Where can I find documentation for earlier versions of Carbon?\n\nYou can find earlier versions of Carbon documentation here:\n**[V6](http://v6.carbondesignsystem.com/)**,\n**[V7](http://v7.carbondesignsystem.com/)**,\n**[V8](http://v8.carbondesignsystem.com/)**,\n**[V9](http://v9.carbondesignsystem.com/)**, and\n**[V10](http://v10.carbondesignsystem.com/).**\n\n## Telemetry\n\nCarbon contains a telemetry feature that collects usage information for IBM and\nCarbon Design System properties.\n\n### Why is telemetry collected?\n\nCarbon collects telemetry information to influence Carbon's roadmap and\nprioritize bug fixes.\n\n### When is data collected?\n\nData is only collected when Carbon packages are installed on a Continuous\nIntegration (CI) server, when the installation is not part of a Pull Request\n(PR), and for Git repositories with the origin remotes:\n\n- `github.ibm.com`\n- `github.com/ibm`\n- `github.com/carbon-design-system`\n\nAs the information collected is not anonymous, telemetry data collection is\nlimited to IBM GitHub Enterprise repositories, as well as open source\nrepositories in the IBM and Carbon Design System GitHub organizations.\n\n### What is being collected?\n\nThe following is collected through a postinstall script:\n\n- Git repository remote origin URLs and commit hashes\n- Packages and package versions used in the repository\n- Components being used including file paths and their packages\n- Component props being used (the prop value is only collected when it is\n serializable to a string)\n\n### How do I opt out?\n\nParticipation in Carbon's telemetry is optional. To opt-out, set the environment\nvariable `CARBON_TELEMETRY_DISABLED` to `1`.\n","type":"Mdx","contentDigest":"9b5756a60bbab8f80833d7d37b451f17","owner":"gatsby-plugin-mdx","counter":5328},"frontmatter":{"title":"FAQs","description":"What is the Carbon Design System? Who works on Carbon? How can I contribute? Here, we answer some of our frequently asked questions."},"exports":{},"rawBody":"---\ntitle: FAQs\ndescription:\n What is the Carbon Design System? Who works on Carbon? How can I contribute?\n Here, we answer some of our frequently asked questions.\n---\n\n\n\nAbout Carbon\nContributing\nCreating with Carbon\nTelemetry\n\n\n\n## About Carbon\n\n### What is the Carbon Design System?\n\nCarbon is the open-source design system for all IBM software products. It is a\nseries of individual styles, components, and guidelines used for creating\nunified product experiences.\n\nTo learn more about how we work check out\n[What is Carbon](/all-about-carbon/what-is-carbon).\n\n### Who works on Carbon?\n\nCarbon has a core team of designers and front-end developers dedicated to\ndeveloping and supporting the system. There are also countless other designers\nand developers who contribute back to\n[carbon-react](https://github.com/carbon-design-system/carbon#contributors).\n\n## Contributing\n\n### How can I contribute and/or propose new components or ideas?\n\nCheck out our [contribution get started](/contributing/get-started) page to\nlearn all about the different ways to contribute. Thanks for the help!\n\n### I see a bug. How do I report it?\n\nFirst, make sure the problem is reproducible. Once confirmed, open an issue in\nthe appropriate GitHub repo from the following list. We will address the bug as\nsoon as we can. If you have a fix for the bug, please feel free to submit a PR\nfor it.\n\nFor larger changes, please see our\n[contribution get started](/contributing/get-started) page.\n\n#### Design issue repos\n\n- [Design kit](https://github.com/carbon-design-system/carbon-design-kit/issues/new)\n- [Icons](https://github.com/carbon-design-system/carbon-icons/issues/new)\n- [Website](https://github.com/carbon-design-system/carbon-website/issues/new/choose)\n- [Components](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [Elements](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [Charts](https://github.com/carbon-design-system/carbon-charts/issues/new)\n- [Everything else](https://github.com/carbon-design-system/carbon/issues/new/choose)\n\n#### Code repos\n\n- [@carbon/react](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [@carbon/web-components](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues/new/choose)\n- [carbon-components-angular](https://github.com/IBM/carbon-components-angular/issues/new)\n- [carbon-components-vanilla](https://github.com/carbon-design-system/carbon/issues/new/choose)\n- [carbon-components-vue](https://github.com/carbon-design-system/carbon-components-vue/issues/new)\n- [carbon-charts](https://github.com/carbon-design-system/carbon-charts/issues/new)\n\n### What can I expect for a response to my bug report?\n\nIf you have a pressing bug or change it is best to make a PR for the issue\nyourself. Our team works in sprints and will try to address your bug as soon as\npossible; sometimes within two or three days, but usually by the following\nsprint. Issues that are out of scope will be closed until they become a higher\npriority.\n\nTypical responses to bug reports will include:\n\n- Need more info, can't reproduce the problem\n- Won't fix, this isn't something we intend to support\n- Confirmed, will add to our roadmap (Carbon team will fix)\n- Confirmed, will accept PRs (need external member to fix)\n- Need to include design to verify this behavior is supported\n\n### What should I do if I find a component that isn't accessible?\n\nFirst, refer to the\n[Carbon accessibility guidelines](/guidelines/accessibility/overview) to confirm\nthat the component fails accessibility standards. If confirmed,\n[create a GitHub issue](https://github.com/carbon-design-system/carbon/issues/new/choose)\nin the Components repo and describe the steps to reproduce the problem. If the\ncore Carbon team confirms the problem, we will work to fix it as quickly as\npossible.\n\n## Creating with Carbon\n\n### Which browsers are supported?\n\nCarbon components are supported in the following browsers:\n\n- Microsoft Edge latest\n- Firefox latest\n- Chrome latest\n- Safari latest\n\nFor IBM teams, see\n[browser support standards here](https://w3.ibm.com/w3publisher/ibm-web-standards-external/standards-mandatory/browser-standards).\n\n### What languages are the components written in?\n\nCarbon is built React first, with official support for Web Components. There is\ncommunity support for vanilla JS, Angular, Vue, and Svelte implementations.\nCheck out [Frameworks](/developing/frameworks/react) to learn more about what\nyou need to get started with Carbon implementations.\n\n### Where do I find mobile components?\n\nThe Carbon Native mobile Figma kit is available on the\n[Other resources](https://carbondesignsystem.com/designing/design-resources/#native-mobile)\npage.\n\n### Where do I find the Experimental components and patterns?\n\nThe patterns and components that were in Experimental are now in the\n[Community assets](/community/overview) section. Community assets include work\ndeveloped and maintained by the individuals and teams who use Carbon. You can\nhelp elevate these resources by contributing feedback, code, and design.\n\nNote that some of the content in Community assets is hosted on internal IBM\nsites and is only accessible to IBMers.\n\n### Where do I find charts and data visualization?\n\nCarbon charts and their corresponding assets and documentation are now in the\n[Data visualization](/data-visualization/getting-started) section.\n\n### Where can I find documentation for earlier versions of Carbon?\n\nYou can find earlier versions of Carbon documentation here:\n**[V6](http://v6.carbondesignsystem.com/)**,\n**[V7](http://v7.carbondesignsystem.com/)**,\n**[V8](http://v8.carbondesignsystem.com/)**,\n**[V9](http://v9.carbondesignsystem.com/)**, and\n**[V10](http://v10.carbondesignsystem.com/).**\n\n## Telemetry\n\nCarbon contains a telemetry feature that collects usage information for IBM and\nCarbon Design System properties.\n\n### Why is telemetry collected?\n\nCarbon collects telemetry information to influence Carbon's roadmap and\nprioritize bug fixes.\n\n### When is data collected?\n\nData is only collected when Carbon packages are installed on a Continuous\nIntegration (CI) server, when the installation is not part of a Pull Request\n(PR), and for Git repositories with the origin remotes:\n\n- `github.ibm.com`\n- `github.com/ibm`\n- `github.com/carbon-design-system`\n\nAs the information collected is not anonymous, telemetry data collection is\nlimited to IBM GitHub Enterprise repositories, as well as open source\nrepositories in the IBM and Carbon Design System GitHub organizations.\n\n### What is being collected?\n\nThe following is collected through a postinstall script:\n\n- Git repository remote origin URLs and commit hashes\n- Packages and package versions used in the repository\n- Components being used including file paths and their packages\n- Component props being used (the prop value is only collected when it is\n serializable to a string)\n\n### How do I opt out?\n\nParticipation in Carbon's telemetry is optional. To opt-out, set the environment\nvariable `CARBON_TELEMETRY_DISABLED` to `1`.\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/help/faq/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/migrating/guide/design/page-data.json b/page-data/migrating/guide/design/page-data.json
index 6073b5b08f4..d64a9608ffd 100644
--- a/page-data/migrating/guide/design/page-data.json
+++ b/page-data/migrating/guide/design/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-migrating-guide-design-mdx","path":"/migrating/guide/design/","result":{"pageContext":{"frontmatter":{"title":"Guide","description":"The transition from v10 to v11 includes significant updates and additions to color tokens, theming, size naming, with new components providing better accessibility, collaboration, and efficiency for users.","tabs":["Overview","Design","Develop"]},"relativePagePath":"/migrating/guide/design.mdx","titleType":"prepend","MdxNode":{"id":"a8363807-0a74-55f9-96b1-05ecbbc0b62c","children":[],"parent":"b9f9080b-3981-58d2-b870-38c705a9ff83","internal":{"content":"---\ntitle: Guide\ndescription:\n The transition from v10 to v11 includes significant updates and additions to\n color tokens, theming, size naming, with new components providing better\n accessibility, collaboration, and efficiency for users.\ntabs: ['Overview', 'Design', 'Develop']\n---\n\nimport { Tag } from '@carbon/react';\n\n\n\nThe transition from v10 to v11 includes significant updates and additions to\ncolor tokens, theming, size naming, with new components providing better\naccessibility, collaboration, and efficiency for users.\n\n\n\n\n Design kit\n Components\n Sizing\n Type tokens\n Color tokens\n Theming\n\n\n## Design kit\n\n### What's new\n\n- Added new color tokens.\n- Introduced layering models: layer set tokens and contextual layer tokens.\n\n### What's changed\n\n- Updated existing color token names to better reflect their usage.\n- Updated layer styles with new color tokens.\n- Updated text styles with new token names.\n- Removal of `light` variants (in favor of new layer and contextual token sets).\n\n### Kit migration\n\n| Design tool | v11 | Migration strategy |\n| -------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [Figma](/designing/kits/figma) | Update available | The v11 Figma update is available as a new library with all themes in one file. See the [Design Kit Figma tab](https://carbondesignsystem.com/designing/kits/figma/) for more information. Teams need to swap out assets from v10 to v11 assets to migrate. The v10 Figma files will not receive continuous updates and will remain permanently on v10. |\n| [Sketch](/designing/kits/sketch) | Update available | The same Sketch Cloud libraries that were used in v10 have been updated to include the v11 changes. Do not accept the library update until you are ready to work in v11. There are new [v10](https://v10.carbondesignsystem.com/designing/kits/sketch#get-the-kit) libraries available for teams that still need them. Note that Sketch kits will not be prioritized or maintained in the future. |\n| [Adobe XD](https://github.com/IBM/design-kit/tree/master/Adobe%20XD) | Partial update available | Some of the v11 changes have been made in the XD files, available in GitHub. Note that Adobe XD kits will no longer be prioritized or maintained. |\n\n#### Figma\n\nMigration to the new v11 Carbon libraries will be a manual process from v10.\nHere are some steps of how to migrate your Text and Color styles from v10 to\nv11.\n\n1. Swap the library from v10 to v11.\n2. Open the library panel and select the `v10` library.\n3. Click the `Swap library` button.\n4. Take a screenshot of the styles that didn't swap.\n5. Visit the `v11` Text or Color styles file in `IBM Design Systems`.\n6. Duplicate the file and move it to your team's space.\n7. Rename the duplicate file to a temporary name.\n8. Change the names of the text or color styles that didn't swap in Step 5 to\n match the name and organization of v10.\n9. Swap to this temporary library.\n10. Update the names back to v11 and swap to the actual v11 library.\n11. Check nested components for text style overrides.\n\n## Components\n\n### Notifications Breaking\n\nAn actionable variant has been added to the notification component. Actionable\nnotifications allow for interactive elements within a notification, like\nbuttons. Actionable notifications can be styled like an inline or toast\nnotification.\n\nSee Carbon's\n[actionable notification](/components/notification/usage/#actionable-notifications)\nusage guidance for more information.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n### Popover New\n\nPopover is a new component we have added to our system. A popover is a layer\nthat appears above all other content on the page and is used to display\nadditional details for specific elements whether it be text or interactive\nelements.\n\nSee Carbon's [popover](/components/popover/usage/) usage guidance for more\ninformation.\n\n\n\n\n\n\n\n\n\n### Tooltip Breaking\n\nThe tooltip component has been refactored to use the popover component under the\nhood to improve accessibility.\n\nSee Carbon's [tooltip](/components/tooltip/usage/) usage guidance for more\ninformation.\n\n\n\n\n\n\n\n\n\n### Toggletip New\n\nDefinition and interactive tootips now use the toggletip component to achieve\naccessibility standards. Toggletip uses the disclosure pattern to toggle the\nvisibility of a popover. This popover may contain a variety of information, from\ndescriptive text to interactive elements. Further guidance on the toggletip\ncomponent is coming soon.\n\nSee Carbon's [toggletip](/components/toggletip/usage/) usage guidance for more\ninformation.\n\n### Tabs Breaking\n\nThe tab component variant names are changing. Default tabs will become _Line\ntabs_ and Container tabs will become _Contained tabs_. There are three new\nmodifiers—tabs with icons, icon-only tabs, and secondary labels. Additionally,\nthere is a new third alignment option for tab that allows for auto-widths where\neach tab size is determined by the label length.\n\nSee Carbon's [tab](/components/tabs/usage/) usage guidance for more information.\n\n\n\n\n\n\n\n\n\n### UI shell Updated\n\nThe UI shell is now themeable and has been updated to use inline theming. The UI\nshell uses Carbon theme tokens instead of component specific tokens and the\ncolor will follow each themes styles.\n\n\n\n\n\n\n\n\n\n## Sizing Breaking\n\nAll size properties for components have been renamed to be more consistent with\nthe pixel/rem value that it is paired with.\n\n| Size | Height (px / rem) |\n| ------------------------ | ----------------- |\n| Extra small (xs) | 24 / 1.5 |\n| Small (sm) | 32 / 2 |\n| Medium (md) | 40 / 2.5 |\n| Large (lg) | 48 / 3 |\n| Extra large (xl) | 64 / 4 |\n| Double extra large (2xl) | 80 / 5 |\n\n## Type tokens Breaking\n\nThe two v10 type sets—Productive and Expressive—have been blended together to\nwork as a unified collection in v11. As a result of this convergence, type token\nnames have been renamed to better define their relationship to one another and\nreflect its styling.\n\nSee Carbon's [typography](/guidelines/typography/styling-strategies) guidance\nfor more information.\n\n### Compact styles\n\nSome tokens now have a compact designation, meaning the only difference it has\nwith the token of a similar name is a variation in line height.\n\n### Body styles\n\nThe four body styles stay the same but their names have been updated. The `long`\nstyles are now simply just `body`, while the `short` styles are now\n`body-compact`.\n\n- `$body-long-01` → `$body-01`\n- `$body-short-02` → `$body-compact-02`\n\n### Heading styles\n\nProductive and expressive while still a concept used to express different\n“moments” are no longer used in the type token header names. There are two new\nclassifications—Fixed and Fluid.\n\n#### Fixed headings\n\nFixed headings, for the most part take the place of what were the v10 productive\nheadings. The first two v10 expressive headings are also now included in the\nfixed type set. They are called “fixed” because they do not change sizes across\nbreakpoints and always remain a single fixed size. However, the term fixed is\nnot included in the token name but simply named `heading`.\n\n- `$productive-heading-03` → `$heading-03`\n\n#### Fluid headings\n\nFluid headings take the place of the v10 expressive heading. These headings are\nresponsive and the type styles change size at different breakpoints.\n\n- `$expressive-heading-05` → `$fluid-heading-05`\n\n### Resources\n\n\n \n \n \n \n \n\n\n## Color tokens Breaking\n\nExisting color tokens have been renamed to better reflect their usage. In\naddition to renaming existing tokens, new tokens have been added to fill gaps in\nthe color token system and fix complex layering logic.\n\n### Color token names\n\nPreviously, in v10 many color tokens had numeral endings, now in v11 only\nlayering tokens will have this distinction. All other tokens have been given an\nadjective descriptor in place of the number ending to help users better\nunderstand how a token should be used. The new naming convention is as follows:\n`[element] - [role] - [order] - [state]`\n\nSee Carbon's [color overview](/guidelines/color/overview/) guidance for more\ninformation.\n\n\n\n\n\n\n\n\n\n
\n Examples showing v10 tokens on the left and v11 tokens on the right\n
\n\n### Layer model tokens New\n\nWe have introduced two new types of color token for the layering models—Layering\ntokens and Contextual layer tokens. The two types of tokens will produce the\nsame visual effect. The difference between them is a technical one and largely a\ndeveloper concern. **In Sketch, and other design tools, designer will only use\nthe layering tokens to design.** The layering tokens replace what were the `ui`\ncolor tokens in v10 and are used in a similar way.\n\nSee Carbon's [color implementation](/guidelines/color/implementation) guidance\nfor more information.\n\n\n\n\n\n\n\n\n\n
\n Examples showing layering tokens on the left and contextual tokens on the\n right\n
\n\n### Resources\n\n\n \n \n \n \n \n\n\n## Theming\n\n### Inline theming\n\nInline theming is available to use in your product. Inline theming is used when\na section of a UI needs to have a different theme from the rest of the page and\nallows themes to be nested within each other without needing custom styles or\noverrides. In product, a common use-case for inline theming is applying a\ncontrasting theme to a UI shell and side panels.\n\nSee Carbon's [inline theming](/guidelines/color/implementation#inline-theming)\nguidance for more information.\n\n\n\n\n\n\n\n\n\n### Light or dark mode\n\nLight or dark mode has been newly introduced and is a theme setting that allows\nthe end user to choose a UI that is either predominately light or dark in color.\nThe UI will automatically switch from using light color backgrounds with dark\ncolor text to using dark color backgrounds with light color text.\n\nSee Carbon's\n[light or dark mode](/guidelines/color/implementation#light-or-dark-mode)\nguidance for more information.\n\n\n\n\n\n\n\n\n\n\n\n\n\n","type":"Mdx","contentDigest":"381f2fd70396b511409c5c77fc1f4f25","owner":"gatsby-plugin-mdx","counter":5328},"frontmatter":{"title":"Guide","description":"The transition from v10 to v11 includes significant updates and additions to color tokens, theming, size naming, with new components providing better accessibility, collaboration, and efficiency for users.","tabs":["Overview","Design","Develop"]},"exports":{},"rawBody":"---\ntitle: Guide\ndescription:\n The transition from v10 to v11 includes significant updates and additions to\n color tokens, theming, size naming, with new components providing better\n accessibility, collaboration, and efficiency for users.\ntabs: ['Overview', 'Design', 'Develop']\n---\n\nimport { Tag } from '@carbon/react';\n\n\n\nThe transition from v10 to v11 includes significant updates and additions to\ncolor tokens, theming, size naming, with new components providing better\naccessibility, collaboration, and efficiency for users.\n\n\n\n\n Design kit\n Components\n Sizing\n Type tokens\n Color tokens\n Theming\n\n\n## Design kit\n\n### What's new\n\n- Added new color tokens.\n- Introduced layering models: layer set tokens and contextual layer tokens.\n\n### What's changed\n\n- Updated existing color token names to better reflect their usage.\n- Updated layer styles with new color tokens.\n- Updated text styles with new token names.\n- Removal of `light` variants (in favor of new layer and contextual token sets).\n\n### Kit migration\n\n| Design tool | v11 | Migration strategy |\n| -------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [Figma](/designing/kits/figma) | Update available | The v11 Figma update is available as a new library with all themes in one file. See the [Design Kit Figma tab](https://carbondesignsystem.com/designing/kits/figma/) for more information. Teams need to swap out assets from v10 to v11 assets to migrate. The v10 Figma files will not receive continuous updates and will remain permanently on v10. |\n| [Sketch](/designing/kits/sketch) | Update available | The same Sketch Cloud libraries that were used in v10 have been updated to include the v11 changes. Do not accept the library update until you are ready to work in v11. There are new [v10](https://v10.carbondesignsystem.com/designing/kits/sketch#get-the-kit) libraries available for teams that still need them. Note that Sketch kits will not be prioritized or maintained in the future. |\n| [Adobe XD](https://github.com/IBM/design-kit/tree/master/Adobe%20XD) | Partial update available | Some of the v11 changes have been made in the XD files, available in GitHub. Note that Adobe XD kits will no longer be prioritized or maintained. |\n\n#### Figma\n\nMigration to the new v11 Carbon libraries will be a manual process from v10.\nHere are some steps of how to migrate your Text and Color styles from v10 to\nv11.\n\n1. Swap the library from v10 to v11.\n2. Open the library panel and select the `v10` library.\n3. Click the `Swap library` button.\n4. Take a screenshot of the styles that didn't swap.\n5. Visit the `v11` Text or Color styles file in `IBM Design Systems`.\n6. Duplicate the file and move it to your team's space.\n7. Rename the duplicate file to a temporary name.\n8. Change the names of the text or color styles that didn't swap in Step 5 to\n match the name and organization of v10.\n9. Swap to this temporary library.\n10. Update the names back to v11 and swap to the actual v11 library.\n11. Check nested components for text style overrides.\n\n## Components\n\n### Notifications Breaking\n\nAn actionable variant has been added to the notification component. Actionable\nnotifications allow for interactive elements within a notification, like\nbuttons. Actionable notifications can be styled like an inline or toast\nnotification.\n\nSee Carbon's\n[actionable notification](/components/notification/usage/#actionable-notifications)\nusage guidance for more information.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n### Popover New\n\nPopover is a new component we have added to our system. A popover is a layer\nthat appears above all other content on the page and is used to display\nadditional details for specific elements whether it be text or interactive\nelements.\n\nSee Carbon's [popover](/components/popover/usage/) usage guidance for more\ninformation.\n\n\n\n\n\n\n\n\n\n### Tooltip Breaking\n\nThe tooltip component has been refactored to use the popover component under the\nhood to improve accessibility.\n\nSee Carbon's [tooltip](/components/tooltip/usage/) usage guidance for more\ninformation.\n\n\n\n\n\n\n\n\n\n### Toggletip New\n\nDefinition and interactive tootips now use the toggletip component to achieve\naccessibility standards. Toggletip uses the disclosure pattern to toggle the\nvisibility of a popover. This popover may contain a variety of information, from\ndescriptive text to interactive elements. Further guidance on the toggletip\ncomponent is coming soon.\n\nSee Carbon's [toggletip](/components/toggletip/usage/) usage guidance for more\ninformation.\n\n### Tabs Breaking\n\nThe tab component variant names are changing. Default tabs will become _Line\ntabs_ and Container tabs will become _Contained tabs_. There are three new\nmodifiers—tabs with icons, icon-only tabs, and secondary labels. Additionally,\nthere is a new third alignment option for tab that allows for auto-widths where\neach tab size is determined by the label length.\n\nSee Carbon's [tab](/components/tabs/usage/) usage guidance for more information.\n\n\n\n\n\n\n\n\n\n### UI shell Updated\n\nThe UI shell is now themeable and has been updated to use inline theming. The UI\nshell uses Carbon theme tokens instead of component specific tokens and the\ncolor will follow each themes styles.\n\n\n\n\n\n\n\n\n\n## Sizing Breaking\n\nAll size properties for components have been renamed to be more consistent with\nthe pixel/rem value that it is paired with.\n\n| Size | Height (px / rem) |\n| ------------------------ | ----------------- |\n| Extra small (xs) | 24 / 1.5 |\n| Small (sm) | 32 / 2 |\n| Medium (md) | 40 / 2.5 |\n| Large (lg) | 48 / 3 |\n| Extra large (xl) | 64 / 4 |\n| Double extra large (2xl) | 80 / 5 |\n\n## Type tokens Breaking\n\nThe two v10 type sets—Productive and Expressive—have been blended together to\nwork as a unified collection in v11. As a result of this convergence, type token\nnames have been renamed to better define their relationship to one another and\nreflect its styling.\n\nSee Carbon's [typography](/guidelines/typography/styling-strategies) guidance\nfor more information.\n\n### Compact styles\n\nSome tokens now have a compact designation, meaning the only difference it has\nwith the token of a similar name is a variation in line height.\n\n### Body styles\n\nThe four body styles stay the same but their names have been updated. The `long`\nstyles are now simply just `body`, while the `short` styles are now\n`body-compact`.\n\n- `$body-long-01` → `$body-01`\n- `$body-short-02` → `$body-compact-02`\n\n### Heading styles\n\nProductive and expressive while still a concept used to express different\n“moments” are no longer used in the type token header names. There are two new\nclassifications—Fixed and Fluid.\n\n#### Fixed headings\n\nFixed headings, for the most part take the place of what were the v10 productive\nheadings. The first two v10 expressive headings are also now included in the\nfixed type set. They are called “fixed” because they do not change sizes across\nbreakpoints and always remain a single fixed size. However, the term fixed is\nnot included in the token name but simply named `heading`.\n\n- `$productive-heading-03` → `$heading-03`\n\n#### Fluid headings\n\nFluid headings take the place of the v10 expressive heading. These headings are\nresponsive and the type styles change size at different breakpoints.\n\n- `$expressive-heading-05` → `$fluid-heading-05`\n\n### Resources\n\n\n \n \n \n \n \n\n\n## Color tokens Breaking\n\nExisting color tokens have been renamed to better reflect their usage. In\naddition to renaming existing tokens, new tokens have been added to fill gaps in\nthe color token system and fix complex layering logic.\n\n### Color token names\n\nPreviously, in v10 many color tokens had numeral endings, now in v11 only\nlayering tokens will have this distinction. All other tokens have been given an\nadjective descriptor in place of the number ending to help users better\nunderstand how a token should be used. The new naming convention is as follows:\n`[element] - [role] - [order] - [state]`\n\nSee Carbon's [color overview](/guidelines/color/overview/) guidance for more\ninformation.\n\n\n\n\n\n\n\n\n\n
\n Examples showing v10 tokens on the left and v11 tokens on the right\n
\n\n### Layer model tokens New\n\nWe have introduced two new types of color token for the layering models—Layering\ntokens and Contextual layer tokens. The two types of tokens will produce the\nsame visual effect. The difference between them is a technical one and largely a\ndeveloper concern. **In Sketch, and other design tools, designer will only use\nthe layering tokens to design.** The layering tokens replace what were the `ui`\ncolor tokens in v10 and are used in a similar way.\n\nSee Carbon's [color implementation](/guidelines/color/implementation) guidance\nfor more information.\n\n\n\n\n\n\n\n\n\n
\n Examples showing layering tokens on the left and contextual tokens on the\n right\n
\n\n### Resources\n\n\n \n \n \n \n \n\n\n## Theming\n\n### Inline theming\n\nInline theming is available to use in your product. Inline theming is used when\na section of a UI needs to have a different theme from the rest of the page and\nallows themes to be nested within each other without needing custom styles or\noverrides. In product, a common use-case for inline theming is applying a\ncontrasting theme to a UI shell and side panels.\n\nSee Carbon's [inline theming](/guidelines/color/implementation#inline-theming)\nguidance for more information.\n\n\n\n\n\n\n\n\n\n### Light or dark mode\n\nLight or dark mode has been newly introduced and is a theme setting that allows\nthe end user to choose a UI that is either predominately light or dark in color.\nThe UI will automatically switch from using light color backgrounds with dark\ncolor text to using dark color backgrounds with light color text.\n\nSee Carbon's\n[light or dark mode](/guidelines/color/implementation#light-or-dark-mode)\nguidance for more information.\n\n\n\n\n\n\n\n\n\n\n\n\n\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/migrating/guide/design.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-migrating-guide-design-mdx","path":"/migrating/guide/design/","result":{"pageContext":{"frontmatter":{"title":"Guide","description":"The transition from v10 to v11 includes significant updates and additions to color tokens, theming, size naming, with new components providing better accessibility, collaboration, and efficiency for users.","tabs":["Overview","Design","Develop"]},"relativePagePath":"/migrating/guide/design.mdx","titleType":"prepend","MdxNode":{"id":"a8363807-0a74-55f9-96b1-05ecbbc0b62c","children":[],"parent":"b9f9080b-3981-58d2-b870-38c705a9ff83","internal":{"content":"---\ntitle: Guide\ndescription:\n The transition from v10 to v11 includes significant updates and additions to\n color tokens, theming, size naming, with new components providing better\n accessibility, collaboration, and efficiency for users.\ntabs: ['Overview', 'Design', 'Develop']\n---\n\nimport { Tag } from '@carbon/react';\n\n\n\nThe transition from v10 to v11 includes significant updates and additions to\ncolor tokens, theming, size naming, with new components providing better\naccessibility, collaboration, and efficiency for users.\n\n\n\n\n Design kit\n Components\n Sizing\n Type tokens\n Color tokens\n Theming\n\n\n## Design kit\n\n### What's new\n\n- Added new color tokens.\n- Introduced layering models: layer set tokens and contextual layer tokens.\n\n### What's changed\n\n- Updated existing color token names to better reflect their usage.\n- Updated layer styles with new color tokens.\n- Updated text styles with new token names.\n- Removal of `light` variants (in favor of new layer and contextual token sets).\n\n### Kit migration\n\n| Design tool | v11 | Migration strategy |\n| -------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [Figma](/designing/kits/figma) | Update available | The v11 Figma update is available as a new library with all themes in one file. See the [Design Kit Figma tab](https://carbondesignsystem.com/designing/kits/figma/) for more information. Teams need to swap out assets from v10 to v11 assets to migrate. The v10 Figma files will not receive continuous updates and will remain permanently on v10. |\n| [Sketch](/designing/kits/sketch) | Update available | The same Sketch Cloud libraries that were used in v10 have been updated to include the v11 changes. Do not accept the library update until you are ready to work in v11. There are new [v10](https://v10.carbondesignsystem.com/designing/kits/sketch#get-the-kit) libraries available for teams that still need them. Note that Sketch kits will not be prioritized or maintained in the future. |\n| [Adobe XD](https://github.com/IBM/design-kit/tree/master/Adobe%20XD) | Partial update available | Some of the v11 changes have been made in the XD files, available in GitHub. Note that Adobe XD kits will no longer be prioritized or maintained. |\n\n#### Figma\n\nMigration to the new v11 Carbon libraries will be a manual process from v10.\nHere are some steps of how to migrate your Text and Color styles from v10 to\nv11.\n\n1. Swap the library from v10 to v11.\n2. Open the library panel and select the `v10` library.\n3. Click the `Swap library` button.\n4. Take a screenshot of the styles that didn't swap.\n5. Visit the `v11` Text or Color styles file in `IBM Design Systems`.\n6. Duplicate the file and move it to your team's space.\n7. Rename the duplicate file to a temporary name.\n8. Change the names of the text or color styles that didn't swap in Step 5 to\n match the name and organization of v10.\n9. Swap to this temporary library.\n10. Update the names back to v11 and swap to the actual v11 library.\n11. Check nested components for text style overrides.\n\n## Components\n\n### Notifications Breaking\n\nAn actionable variant has been added to the notification component. Actionable\nnotifications allow for interactive elements within a notification, like\nbuttons. Actionable notifications can be styled like an inline or toast\nnotification.\n\nSee Carbon's\n[actionable notification](/components/notification/usage/#actionable-notifications)\nusage guidance for more information.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n### Popover New\n\nPopover is a new component we have added to our system. A popover is a layer\nthat appears above all other content on the page and is used to display\nadditional details for specific elements whether it be text or interactive\nelements.\n\nSee Carbon's [popover](/components/popover/usage/) usage guidance for more\ninformation.\n\n\n\n\n\n\n\n\n\n### Tooltip Breaking\n\nThe tooltip component has been refactored to use the popover component under the\nhood to improve accessibility.\n\nSee Carbon's [tooltip](/components/tooltip/usage/) usage guidance for more\ninformation.\n\n\n\n\n\n\n\n\n\n### Toggletip New\n\nDefinition and interactive tootips now use the toggletip component to achieve\naccessibility standards. Toggletip uses the disclosure pattern to toggle the\nvisibility of a popover. This popover may contain a variety of information, from\ndescriptive text to interactive elements. Further guidance on the toggletip\ncomponent is coming soon.\n\nSee Carbon's [toggletip](/components/toggletip/usage/) usage guidance for more\ninformation.\n\n### Tabs Breaking\n\nThe tab component variant names are changing. Default tabs will become _Line\ntabs_ and Container tabs will become _Contained tabs_. There are three new\nmodifiers—tabs with icons, icon-only tabs, and secondary labels. Additionally,\nthere is a new third alignment option for tab that allows for auto-widths where\neach tab size is determined by the label length.\n\nSee Carbon's [tab](/components/tabs/usage/) usage guidance for more information.\n\n\n\n\n\n\n\n\n\n### UI shell Updated\n\nThe UI shell is now themeable and has been updated to use inline theming. The UI\nshell uses Carbon theme tokens instead of component specific tokens and the\ncolor will follow each themes styles.\n\n\n\n\n\n\n\n\n\n## Sizing Breaking\n\nAll size properties for components have been renamed to be more consistent with\nthe pixel/rem value that it is paired with.\n\n| Size | Height (px / rem) |\n| ------------------------ | ----------------- |\n| Extra small (xs) | 24 / 1.5 |\n| Small (sm) | 32 / 2 |\n| Medium (md) | 40 / 2.5 |\n| Large (lg) | 48 / 3 |\n| Extra large (xl) | 64 / 4 |\n| Double extra large (2xl) | 80 / 5 |\n\n## Type tokens Breaking\n\nThe two v10 type sets—Productive and Expressive—have been blended together to\nwork as a unified collection in v11. As a result of this convergence, type token\nnames have been renamed to better define their relationship to one another and\nreflect its styling.\n\nSee Carbon's [typography](/guidelines/typography/styling-strategies) guidance\nfor more information.\n\n### Compact styles\n\nSome tokens now have a compact designation, meaning the only difference it has\nwith the token of a similar name is a variation in line height.\n\n### Body styles\n\nThe four body styles stay the same but their names have been updated. The `long`\nstyles are now simply just `body`, while the `short` styles are now\n`body-compact`.\n\n- `$body-long-01` → `$body-01`\n- `$body-short-02` → `$body-compact-02`\n\n### Heading styles\n\nProductive and expressive while still a concept used to express different\n“moments” are no longer used in the type token header names. There are two new\nclassifications—Fixed and Fluid.\n\n#### Fixed headings\n\nFixed headings, for the most part take the place of what were the v10 productive\nheadings. The first two v10 expressive headings are also now included in the\nfixed type set. They are called “fixed” because they do not change sizes across\nbreakpoints and always remain a single fixed size. However, the term fixed is\nnot included in the token name but simply named `heading`.\n\n- `$productive-heading-03` → `$heading-03`\n\n#### Fluid headings\n\nFluid headings take the place of the v10 expressive heading. These headings are\nresponsive and the type styles change size at different breakpoints.\n\n- `$expressive-heading-05` → `$fluid-heading-05`\n\n### Resources\n\n\n \n \n \n \n \n\n\n## Color tokens Breaking\n\nExisting color tokens have been renamed to better reflect their usage. In\naddition to renaming existing tokens, new tokens have been added to fill gaps in\nthe color token system and fix complex layering logic.\n\n### Color token names\n\nPreviously, in v10 many color tokens had numeral endings, now in v11 only\nlayering tokens will have this distinction. All other tokens have been given an\nadjective descriptor in place of the number ending to help users better\nunderstand how a token should be used. The new naming convention is as follows:\n`[element] - [role] - [order] - [state]`\n\nSee Carbon's [color overview](/guidelines/color/overview/) guidance for more\ninformation.\n\n\n\n\n\n\n\n\n\n
\n Examples showing v10 tokens on the left and v11 tokens on the right\n
\n\n### Layer model tokens New\n\nWe have introduced two new types of color token for the layering models—Layering\ntokens and Contextual layer tokens. The two types of tokens will produce the\nsame visual effect. The difference between them is a technical one and largely a\ndeveloper concern. **In Sketch, and other design tools, designer will only use\nthe layering tokens to design.** The layering tokens replace what were the `ui`\ncolor tokens in v10 and are used in a similar way.\n\nSee Carbon's [color implementation](/guidelines/color/implementation) guidance\nfor more information.\n\n\n\n\n\n\n\n\n\n
\n Examples showing layering tokens on the left and contextual tokens on the\n right\n
\n\n### Resources\n\n\n \n \n \n \n \n\n\n## Theming\n\n### Inline theming\n\nInline theming is available to use in your product. Inline theming is used when\na section of a UI needs to have a different theme from the rest of the page and\nallows themes to be nested within each other without needing custom styles or\noverrides. In product, a common use-case for inline theming is applying a\ncontrasting theme to a UI shell and side panels.\n\nSee Carbon's [inline theming](/guidelines/color/implementation#inline-theming)\nguidance for more information.\n\n\n\n\n\n\n\n\n\n### Light or dark mode\n\nLight or dark mode has been newly introduced and is a theme setting that allows\nthe end user to choose a UI that is either predominately light or dark in color.\nThe UI will automatically switch from using light color backgrounds with dark\ncolor text to using dark color backgrounds with light color text.\n\nSee Carbon's\n[light or dark mode](/guidelines/color/implementation#light-or-dark-mode)\nguidance for more information.\n\n\n\n\n\n\n\n\n\n\n\n\n\n","type":"Mdx","contentDigest":"381f2fd70396b511409c5c77fc1f4f25","owner":"gatsby-plugin-mdx","counter":5329},"frontmatter":{"title":"Guide","description":"The transition from v10 to v11 includes significant updates and additions to color tokens, theming, size naming, with new components providing better accessibility, collaboration, and efficiency for users.","tabs":["Overview","Design","Develop"]},"exports":{},"rawBody":"---\ntitle: Guide\ndescription:\n The transition from v10 to v11 includes significant updates and additions to\n color tokens, theming, size naming, with new components providing better\n accessibility, collaboration, and efficiency for users.\ntabs: ['Overview', 'Design', 'Develop']\n---\n\nimport { Tag } from '@carbon/react';\n\n\n\nThe transition from v10 to v11 includes significant updates and additions to\ncolor tokens, theming, size naming, with new components providing better\naccessibility, collaboration, and efficiency for users.\n\n\n\n\n Design kit\n Components\n Sizing\n Type tokens\n Color tokens\n Theming\n\n\n## Design kit\n\n### What's new\n\n- Added new color tokens.\n- Introduced layering models: layer set tokens and contextual layer tokens.\n\n### What's changed\n\n- Updated existing color token names to better reflect their usage.\n- Updated layer styles with new color tokens.\n- Updated text styles with new token names.\n- Removal of `light` variants (in favor of new layer and contextual token sets).\n\n### Kit migration\n\n| Design tool | v11 | Migration strategy |\n| -------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [Figma](/designing/kits/figma) | Update available | The v11 Figma update is available as a new library with all themes in one file. See the [Design Kit Figma tab](https://carbondesignsystem.com/designing/kits/figma/) for more information. Teams need to swap out assets from v10 to v11 assets to migrate. The v10 Figma files will not receive continuous updates and will remain permanently on v10. |\n| [Sketch](/designing/kits/sketch) | Update available | The same Sketch Cloud libraries that were used in v10 have been updated to include the v11 changes. Do not accept the library update until you are ready to work in v11. There are new [v10](https://v10.carbondesignsystem.com/designing/kits/sketch#get-the-kit) libraries available for teams that still need them. Note that Sketch kits will not be prioritized or maintained in the future. |\n| [Adobe XD](https://github.com/IBM/design-kit/tree/master/Adobe%20XD) | Partial update available | Some of the v11 changes have been made in the XD files, available in GitHub. Note that Adobe XD kits will no longer be prioritized or maintained. |\n\n#### Figma\n\nMigration to the new v11 Carbon libraries will be a manual process from v10.\nHere are some steps of how to migrate your Text and Color styles from v10 to\nv11.\n\n1. Swap the library from v10 to v11.\n2. Open the library panel and select the `v10` library.\n3. Click the `Swap library` button.\n4. Take a screenshot of the styles that didn't swap.\n5. Visit the `v11` Text or Color styles file in `IBM Design Systems`.\n6. Duplicate the file and move it to your team's space.\n7. Rename the duplicate file to a temporary name.\n8. Change the names of the text or color styles that didn't swap in Step 5 to\n match the name and organization of v10.\n9. Swap to this temporary library.\n10. Update the names back to v11 and swap to the actual v11 library.\n11. Check nested components for text style overrides.\n\n## Components\n\n### Notifications Breaking\n\nAn actionable variant has been added to the notification component. Actionable\nnotifications allow for interactive elements within a notification, like\nbuttons. Actionable notifications can be styled like an inline or toast\nnotification.\n\nSee Carbon's\n[actionable notification](/components/notification/usage/#actionable-notifications)\nusage guidance for more information.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n### Popover New\n\nPopover is a new component we have added to our system. A popover is a layer\nthat appears above all other content on the page and is used to display\nadditional details for specific elements whether it be text or interactive\nelements.\n\nSee Carbon's [popover](/components/popover/usage/) usage guidance for more\ninformation.\n\n\n\n\n\n\n\n\n\n### Tooltip Breaking\n\nThe tooltip component has been refactored to use the popover component under the\nhood to improve accessibility.\n\nSee Carbon's [tooltip](/components/tooltip/usage/) usage guidance for more\ninformation.\n\n\n\n\n\n\n\n\n\n### Toggletip New\n\nDefinition and interactive tootips now use the toggletip component to achieve\naccessibility standards. Toggletip uses the disclosure pattern to toggle the\nvisibility of a popover. This popover may contain a variety of information, from\ndescriptive text to interactive elements. Further guidance on the toggletip\ncomponent is coming soon.\n\nSee Carbon's [toggletip](/components/toggletip/usage/) usage guidance for more\ninformation.\n\n### Tabs Breaking\n\nThe tab component variant names are changing. Default tabs will become _Line\ntabs_ and Container tabs will become _Contained tabs_. There are three new\nmodifiers—tabs with icons, icon-only tabs, and secondary labels. Additionally,\nthere is a new third alignment option for tab that allows for auto-widths where\neach tab size is determined by the label length.\n\nSee Carbon's [tab](/components/tabs/usage/) usage guidance for more information.\n\n\n\n\n\n\n\n\n\n### UI shell Updated\n\nThe UI shell is now themeable and has been updated to use inline theming. The UI\nshell uses Carbon theme tokens instead of component specific tokens and the\ncolor will follow each themes styles.\n\n\n\n\n\n\n\n\n\n## Sizing Breaking\n\nAll size properties for components have been renamed to be more consistent with\nthe pixel/rem value that it is paired with.\n\n| Size | Height (px / rem) |\n| ------------------------ | ----------------- |\n| Extra small (xs) | 24 / 1.5 |\n| Small (sm) | 32 / 2 |\n| Medium (md) | 40 / 2.5 |\n| Large (lg) | 48 / 3 |\n| Extra large (xl) | 64 / 4 |\n| Double extra large (2xl) | 80 / 5 |\n\n## Type tokens Breaking\n\nThe two v10 type sets—Productive and Expressive—have been blended together to\nwork as a unified collection in v11. As a result of this convergence, type token\nnames have been renamed to better define their relationship to one another and\nreflect its styling.\n\nSee Carbon's [typography](/guidelines/typography/styling-strategies) guidance\nfor more information.\n\n### Compact styles\n\nSome tokens now have a compact designation, meaning the only difference it has\nwith the token of a similar name is a variation in line height.\n\n### Body styles\n\nThe four body styles stay the same but their names have been updated. The `long`\nstyles are now simply just `body`, while the `short` styles are now\n`body-compact`.\n\n- `$body-long-01` → `$body-01`\n- `$body-short-02` → `$body-compact-02`\n\n### Heading styles\n\nProductive and expressive while still a concept used to express different\n“moments” are no longer used in the type token header names. There are two new\nclassifications—Fixed and Fluid.\n\n#### Fixed headings\n\nFixed headings, for the most part take the place of what were the v10 productive\nheadings. The first two v10 expressive headings are also now included in the\nfixed type set. They are called “fixed” because they do not change sizes across\nbreakpoints and always remain a single fixed size. However, the term fixed is\nnot included in the token name but simply named `heading`.\n\n- `$productive-heading-03` → `$heading-03`\n\n#### Fluid headings\n\nFluid headings take the place of the v10 expressive heading. These headings are\nresponsive and the type styles change size at different breakpoints.\n\n- `$expressive-heading-05` → `$fluid-heading-05`\n\n### Resources\n\n\n \n \n \n \n \n\n\n## Color tokens Breaking\n\nExisting color tokens have been renamed to better reflect their usage. In\naddition to renaming existing tokens, new tokens have been added to fill gaps in\nthe color token system and fix complex layering logic.\n\n### Color token names\n\nPreviously, in v10 many color tokens had numeral endings, now in v11 only\nlayering tokens will have this distinction. All other tokens have been given an\nadjective descriptor in place of the number ending to help users better\nunderstand how a token should be used. The new naming convention is as follows:\n`[element] - [role] - [order] - [state]`\n\nSee Carbon's [color overview](/guidelines/color/overview/) guidance for more\ninformation.\n\n\n\n\n\n\n\n\n\n
\n Examples showing v10 tokens on the left and v11 tokens on the right\n
\n\n### Layer model tokens New\n\nWe have introduced two new types of color token for the layering models—Layering\ntokens and Contextual layer tokens. The two types of tokens will produce the\nsame visual effect. The difference between them is a technical one and largely a\ndeveloper concern. **In Sketch, and other design tools, designer will only use\nthe layering tokens to design.** The layering tokens replace what were the `ui`\ncolor tokens in v10 and are used in a similar way.\n\nSee Carbon's [color implementation](/guidelines/color/implementation) guidance\nfor more information.\n\n\n\n\n\n\n\n\n\n
\n Examples showing layering tokens on the left and contextual tokens on the\n right\n
\n\n### Resources\n\n\n \n \n \n \n \n\n\n## Theming\n\n### Inline theming\n\nInline theming is available to use in your product. Inline theming is used when\na section of a UI needs to have a different theme from the rest of the page and\nallows themes to be nested within each other without needing custom styles or\noverrides. In product, a common use-case for inline theming is applying a\ncontrasting theme to a UI shell and side panels.\n\nSee Carbon's [inline theming](/guidelines/color/implementation#inline-theming)\nguidance for more information.\n\n\n\n\n\n\n\n\n\n### Light or dark mode\n\nLight or dark mode has been newly introduced and is a theme setting that allows\nthe end user to choose a UI that is either predominately light or dark in color.\nThe UI will automatically switch from using light color backgrounds with dark\ncolor text to using dark color backgrounds with light color text.\n\nSee Carbon's\n[light or dark mode](/guidelines/color/implementation#light-or-dark-mode)\nguidance for more information.\n\n\n\n\n\n\n\n\n\n\n\n\n\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/migrating/guide/design.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/migrating/guide/develop/page-data.json b/page-data/migrating/guide/develop/page-data.json
index c3bd48cd56b..b7aaa521df6 100644
--- a/page-data/migrating/guide/develop/page-data.json
+++ b/page-data/migrating/guide/develop/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-migrating-guide-develop-mdx","path":"/migrating/guide/develop/","result":{"pageContext":{"frontmatter":{"title":"Guide","description":"This guide includes everything you need to migrate your offering from v10 to v11 of Carbon.","tabs":["Overview","Design","Develop"]},"relativePagePath":"/migrating/guide/develop.mdx","titleType":"prepend","MdxNode":{"id":"62679931-0962-5f96-9e11-3480f242b214","children":[],"parent":"3e1035a9-69dd-5afc-90b3-4cc516ca5e43","internal":{"content":"---\ntitle: Guide\ndescription:\n This guide includes everything you need to migrate your offering from v10 to\n v11 of Carbon.\ntabs: ['Overview', 'Design', 'Develop']\n---\n\nimport { Tag } from '@carbon/react';\n\n\n\nStep-by-step guide to updating your code from Carbon v10 to v11.\n\n\n\n\n\nOverview\nMigrating a React app or library\nMigrating an app or library using just styles\nMigrating carbon-icons\nMigrating Carbon elements\n\n\n\n## Overview\n\nThis guide helps you update your project to Carbon v11. It is broken into\nsections based on how you are using Carbon in your project today. For most teams\nusing Carbon, you'll want to use the\n[Migrating a React app](#migrating-a-react-app) section.\n\nOne of the biggest changes to Carbon in v11 is that we moved to dedicated\npackages under the `@carbon` scope. What this means for you is that if you were\npreviously using the following packages:\n\n- `carbon-components`\n- `carbon-components-react`\n- `carbon-icons`\n- `@carbon/icons-react`\n\nYou can access all of this work under one single package: `@carbon/react`. This\npackage will re-export all of the styles and icons for Carbon all in one\ndependency.\n\nIf you were previously using `carbon-components`, the styles from this package\nare available under `@carbon/styles`. They are also re-exported through\n`@carbon/react`\n\nBoth the `carbon-components` and `carbon-components-react` packages will stick\naround in v11 but they are only re-exports of `@carbon/styles` and\n`@carbon/react` respectively.\n\n## Migrating a React app or library\n\nStarting in v11, the React components for Carbon live in the `@carbon/react`\npackage.\n\nThe `@carbon/react` package also includes the styles for Carbon along with\nicons.\n\n### Step 1: Install @carbon/react\n\nTo get started, uninstall the following packages if they exist in your project:\n\n- `carbon-components`\n- `carbon-components-react`\n- `carbon-icons`\n- `@carbon/icons-react`\n\n```bash\nnpm uninstall carbon-components carbon-components-react carbon-icons @carbon/icons-react\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn remove carbon-components carbon-components-react carbon-icons @carbon/icons-react\n```\n\nNext, install the `@carbon/react` package:\n\n```bash\nnpm install @carbon/react\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn add @carbon/react\n```\n\nNow that you've removed the old packages and brought in the new ones, run the\ncodemod below to fix your pathing.\n\n```bash\nnpx @carbon/upgrade migrate update-carbon-components-react-import-to-scoped --write\n```\n\nAfter running the command, your code should start looking like this:\n\n```jsx\n// Before\nimport { Accordion, AccordionItem } from 'carbon-components-react';\n// After\nimport { Accordion, AccordionItem } from '@carbon/react';\n```\n\n\n\nFor full details, including options and commands availabe when using the\n`@carbon/upgrade` CLI, see the\n[package documentation](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade).\n\n\n\n### Step 2: Install Dart Sass\n\nIf you were previously importing styles from `carbon-components`, you can now\nimport styles directly from `@carbon/react` or the `@carbon/react/scss` folder.\n\nBefore you're able to bring in these styles, you'll need to make sure your\nproject is setup to use Dart Sass. Starting in v11, Carbon styles requires Dart\nSass through the `sass` package in order to compile. This change comes from our\nmigration to Sass Modules in order to improve our compilation times and overall\nproject structure.\n\nFirst, let's remove `node-sass` from your project. If you don't have\n`node-sass`, no worries, just skip down and begin adding `sass`.\n\n```bash\nnpm uninstall node-sass\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn remove node-sass\n```\n\nNow, let's install `sass`:\n\n```bash\nnpm install sass --save-dev\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn add sass --dev\n```\n\nOnce you have Dart Sass installed, it's important that you configure your\nproject to support resolving imports in Sass from `node_modules`. Typically,\nthis means adding `node_modules` to your `includePaths` config for Sass in your\nbundler or toolchain of choice.\n\nTo learn more about how to configure your specific toolchain to support this,\nread the documentation for configuration\n[here](https://github.com/carbon-design-system/carbon/blob/main/packages/styles/docs/sass.md#configuration).\nWe also have published a guide over on\n[Medium](https://medium.com/carbondesign/migrating-from-node-sass-to-sass-eba9db004a3a)\nto help out with common problems that come from this migration.\n\n\n\n \n \n\n \n\n\n \n \n\n \n\n\n\n### Step 3: Update style import paths\n\nNow, open your project's root stylesheet to make the following changes:\n\n```diff\n- @import 'carbon-components/scss/globals/scss/styles.scss';\n+ @use '@carbon/react';\n```\n\nIf you were providing any configuration options before you imported Carbon you\ncan now provide them using the `with` syntax:\n\n```scss\n@use '@carbon/react' with (\n $css--default-type: true,\n $css--reset: true\n);\n```\n\nIf you were using any feature flags in v10, you can safely remove them in v11.\n\nYou can also use @import to bring in Carbon, if you prefer, although @use is\nrecommended.\n\nFor cases where your projects does't need to include everything via\n`@use '@carbon/react'`; and just want to do individual component styles.\n\n```scss\n// Configure feature flags if needed, if not these\n// lines can be removed\n@use '@carbon/react/scss/config' with (\n $font-path: '@ibm/plex',\n $use-flexbox-grid: 'true'\n);\n\n// Emit the css reset\n@use '@carbon/react/scss/reset';\n\n// Emit the Plex font-face declarations\n@use '@carbon/react/scss/fonts';\n\n// Optional: emit the grid styles if using the grid.\n// This will emit the flex-grid styles if\n// $use-flexbox-grid is configured to 'true'\n@use '@carbon/react/scss/grid';\n\n// Emit the layer styles\n@use '@carbon/react/scss/layer';\n\n// Emit individual component styles\n@use '@carbon/react/scss/components/button';\n@use '@carbon/react/scss/components/tile';\n\n// Use additional local stylesheets\n@use 'sample-grid';\n```\n\nWhen migrating your custom components, some of our most used sass assets are\nincluded below, along with what you would need to have at the top of your file\nto use it. Essentially, all we are doing is including the path where we would\n[find these styles](https://github.com/carbon-design-system/carbon/tree/main/packages/react/scss)\nin our package.\n\n| Carbon sass I'm using | Sass modules to include |\n| ------------------------------- | -------------------------------------------------------- |\n| Type tokens | `@use '@carbon/react/scss/type' as *;` |\n| Theme tokens | `@use '@carbon/react/scss/theme' as *` |\n| Theme mixins | `@use '@carbon/react/scss/themes' as *` |\n| Design language color tokens | `@use '@carbon/react/scss/colors' as *` |\n| Spacing tokens | `@use '@carbon/react/scss/spacing' as *` |\n| Breakpoint mixins | `@use '@carbon/react/scss/breakpoint' as *` |\n| Motion tokens and functions | `@use '@carbon/react/scss/motion' as *` |\n| Rem and other convert functions | `@use '@carbon/react/scss/utilities/convert' as *` |\n| Z-index helper | `@use '@carbon/react/scss/utilities/z-index' as *` |\n| Focus outline helper | `@use '@carbon/react/scss/utilities/focus-outline' as *` |\n| Transform rotate helper | `@use '@carbon/react/scss/utilities/rotate' as *` |\n| Skeleton animation helper | `@use '@carbon/react/scss/utilities/skeleton' as *` |\n\nNow that you've migrated all of your imports, do a find/replace using your\nfavorite code editor. The prefix `carbon--` is no longer necessary. You can do a\nfind for `carbon--` and replace it with nothing to remove across all your files\nlike the example below. The full list of changes are available in our\n[Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#changing-import-paths-from-scssglobalsscss-to-scss).\n\n```diff\n- @include carbon--breakpoint(lg) {\n+ @include breakpoint(lg) {\n width: 42%;\n }\n```\n\nOnce you've removed the prefix, your styles should all be set using the old, v10\ntokens. We recommend teams install the community supported\n[stylelint-plugin-carbon-tokens](https://github.com/carbon-design-system/stylelint-plugin-carbon-tokens)\nto further assist in migrating your tokens to v11 tokens as the old v10 tokens\nwill be removed in our next major release.\n\n\n\n \n \n\n \n\n\n \n \n\n \n\n\n\n### Step 4: Updating component size props\n\nComponents with size variants have been updated to use the same API options.\nPreviously, the size options were inconsistent: `field`, `medium`, `short`. Now,\nsize options fall under the following values:\n\n| Prop value | Size |\n| ---------- | ---- |\n| `xs` | 24px |\n| `sm` | 32px |\n| `md` | 40px |\n| `lg` | 48px |\n| `xl` | 64px |\n| `2xl` | 80px |\n\n**Note:** the default size in v11 is `md` (`40px`).\n\nRun the following codemods to update the size prop across the effected\ncomponents in your project.\n\n```bash\nnpx @carbon/upgrade migrate small-to-size-prop --write\nnpx @carbon/upgrade migrate size-prop-update --write\n```\n\nBy running the series of codemods, they will do the following, in order:\n\n1. Removes the deprecated `small` boolean prop and replaces it with `size=\"sm\"`.\n2. Removes v10 size props and replaces them with v11 sizes props.\n\nIt's important to run the npx commands in the order that they are presented\nabove. Doing them out of order might result in the codemod not working as\nintended.\n\n\n\nFor full details, including options and commands availabe when using the\n`@carbon/upgrade` CLI, see the\n[package documentation](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade).\n\n\n\nThe following components all have size variants that may be affected in your\ncode. To update, you will need to switch to one of the size options listed\nabove. The codemod will make short work of these changes.\n\n- Accordion\n- Button\n- ComboBox\n- Dropdown\n- Multiselect\n- Filterable multiselect\n- ContentSwitcher\n- DataTable\n- DatePicker\n- FileUploader\n- FileUploaderItem\n- FileUploaderDropContainer\n- FileUploaderButton\n- Link\n- Modal\n- ComposedModal\n- NumberInput\n- OverflowMenu\n- Search\n- Select\n- Tag\n- TextInput\n- TimePicker\n- Toggle\n\n### Step 5: Update icon sizes and imports\n\nThe `@carbon/icons-react` package has been updated to minimize the number of\nexports from the package to help reduce build and compile times. This package is\navailable under `@carbon/react/icons`.\n\nThis update includes a change to the API of the icon components that come from\nthis package. Previously, we would export icons that included the size of the\nasset. This update allows you to bring the icon directly and specify the size\nusing the `size` prop.\n\nRun the following codemods to update your project's icons.\n\n```bash\nnpx @carbon/upgrade migrate icons-react-size-prop --write\nnpx @carbon/upgrade migrate update-carbon-icons-react-import-to-carbon-react --write\n```\n\nBy running the series of codemods, they will do the following, in order:\n\n1. Removes the size from the import and places it on the icon directly.\n2. Remove the `@carbon/icons-react` pathing and replace it with\n `@carbon/react/icons`.\n\nIt's important to run the npx commands in the order that they are presented\nabove. Doing them out of order might result in the codemod not working as\nintended.\n\n\n\nFor full details, including options and commands availabe when using the\n`@carbon/upgrade` CLI, see the\n[package documentation](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade).\n\n\n\nAfter running the command, instead of your icons imports looking like this:\n\n**Before**\n\n```jsx\nimport { Add32, Add24, Add20, Add16 } from '@carbon/icons-react';\n\nfunction MyComponent() {\n return (\n <>\n \n \n \n \n \n );\n}\n```\n\nThey should start looking like this:\n\n**After**\n\n```jsx\nimport { Add } from '@carbon/react/icons';\n\nfunction MyComponent() {\n return (\n <>\n \n \n \n \n \n );\n}\n```\n\n#### Removed icons\n\nThe following deprecated icons have been removed. Use the table below to find\ntheir replacement, if available, in v11.\n\n| Asset | v10 | v11 |\n| :------------------------------ | :-------------------------- | :-------------------------- |\n| app-switcher | AppSwitcher | Switcher |\n| arrows | Arrows | ArrowsVertical |\n| back-to-top | BackToTop | UpToTop |\n| checkbox--undeterminate | CheckboxUndeterminate | CheckboxIndeterminate |\n| checkbox--undeterminate--filled | CheckboxUndeterminateFilled | CheckboxIndeterminateFilled |\n| cloud--lightning | CloudLightning | Removed |\n| cloud--rain | CloudRain | Removed |\n| cloud--snow | CloudSnow | Removed |\n| delete | Delete | TrashCan |\n| edit-filter | EditFilter | FilterEdit |\n| sunny | Sunny | Removed |\n| research--bloch-sphere | ResearchBlockSphere | BlochSphere |\n| research--hinton-plot | ResearchHintonPlot | HintonPlot |\n| research--matrix | ResearchMatrix | Matrix |\n| misuse--alt | MisuseAlt | MisuseOutline |\n| logo--google | LogoGoogle | Removed |\n| mammogram--stacked | MammogramStacked | Removed |\n| logo--delicious | LogoDelicious | Removed |\n| logo--stumbleupon | LogoStumbleUpon | Removed |\n| letter--Aa--large | LetterAaLarge | TextFont |\n| glyph--caution-inverted | GlyphCautionInverted | CautionInverted |\n| glyph--caution | GlyphCaution | Caution |\n| glyph--circle-fill | GlyphCircleFill | CircleFill |\n| glyph--circle-stroke | GlyphCircleStroke | CircleStroke |\n| glyph--critical | GlyphCritical | Critical |\n| glyph--incomplete | GlyphIncomplete | Incomplete |\n| glyph--square-fill | GlyphSquareFill | SquareFill |\n| glyph--undefined | GlyphUndefined | Undefined |\n\nHowever, in certain situations, we will be unable to infer what the correct\nupdate should be for a certain usage of the icon component. We have written the\ncodemod to work for most situations, but you will see console warnings for files\nthat will require you to manually review them to make sure the transforms were\napplied correctly.\n\nThe most common manual update that teams will need to make is if a `prop` where\nthe icon is passed to places a `ref` on the icon. For example,\n\n```jsx\nfunction MyComponent({ renderIcon: Icon }) {\n const ref = useRef(null);\n return ;\n}\n\n// Before\n\n\n// After the codemod\n} />\n```\n\nIn this situation, you will need to update your code to use `React.forwardRef`:\n\n```jsx\n (\n \n ))}\n/>;\n\n// Or, alternatively:\nconst Search16 = React.forwardRef((props, ref) => {\n return ;\n});\n\n;\n```\n\n#### Manual migration\n\nIn addition to the automated codemods above, there are several patterns in your\ncodebase that you will need to update manually:\n\n- If you use the name `ForwardRef(IconName16)` in a test you will need to\n manually change this. Prefer to use the component directly if using enzyme\n- If you use snapshot tests, the structure will change and include a `size`\n prop. Make sure that the `size` prop value matches what your icon name used to\n be. For example, `` should become ``\n\n### Step 6: Update components that have changed\n\nIn v11, we have updated the APIs of certain components in one of the following\nways:\n\n- Update `className` usage to be applied to the outermost element of a component\n- Remove props that have been deprecated in v10\n- Refactor the API to ship an accessible component\n\nFor a full list of changes to components, check out our\n[Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbon-components-react).\nBelow are some common changes that may impact you and your usage of Carbon.\n\n#### Changes to `className`\n\nThe usage of `className` prop has been updated so that the class is passed to\nthe outermost element of a component's inner markup. This was already the case\nfor most components and this change brings along the remaining components in the\nlibrary to this convention.\n\nThe following components previously were not applying the `className` prop to\nthe outermost element. If you were using a custom `className` to target an inner\nelement for any of these components, you will have to update your selectors to\nnow account for the `className` being placed on the outermost element.\n\n- Checkbox\n- ComboBox\n- Table\n- TableToolbar\n- DataTableSkeleton\n- DatePicker\n- DatePickerSkeleton\n- DatePickerInput\n- Dropdown\n- FileUploaderDropContainer\n- FileUploaderItem\n- FormGroup\n- FilterableMultiSelect\n- MultiSelect\n- NotificationTextDetails\n- NotificationIcon\n- NumberInput\n- OverflowMenuItem\n- RadioButtonGroup\n- RadioTile\n- Select\n- Slider\n- Switch\n- TextArea\n- ControlledPasswordInput\n- PasswordInput\n- TextInput\n- TimePicker\n- Tooltip\n- HeaderContainer\n\n#### Notification\n\nWe have updated the notification components to be more accessible out of the\nbox. `ToastNotification` and `InlineNotification` now have `role=\"status\"` by\ndefault with additional `role` options of `log` and `alert`. These components do\nnot receive focus and should be used for information-only use cases. These\ncomponents no longer accept actions or interactive children.\n\nFor notifications requiring an action, a new `ActionableNotifiation` component\nis available. It has a `role=\"alertdialog\"` and recieves focus by default.\nAutomatic placement of focus can be turned off via the new `hasFocus` prop.\n\nAll notifications have a new optional `closeOnEscape` prop, it enables\nnotifications to closed by pressing the `escape` key. For more details, see the\n[notification components accessibility page](https://www.carbondesignsystem.com/components/notification/accessibility).\n\n#### Update `ToastNotification` usage\n\n- `children` can no longer contain interactive elements. A `ToastNotification`\n containing an action or interactive children should be replaced with\n `ActionableNotification`.\n- The `notificationType` prop is no longer needed and can be removed.\n- The default `role` is now `status`. `log` and `alert` can also be used.\n- The `closeOnEscape` prop toggles the closing of notifications via the `escape`\n key.\n\n#### Update `InlineNotification` usage\n\n- The `actions` prop has been removed. An `InlineNotification` containing an\n action or interactive children should be replaced with\n `ActionableNotification` configured with the `inline` prop.\n- `children` can no longer contain interactive elements.\n- The `notificationType` prop is no longer needed and can be removed.\n- The default `role` is now `status`. `log` and `alert` can also be used.\n- The `closeOnEscape` prop toggles the closing of notifications via the `escape`\n key.\n\n#### When using `ActionableNotification`:\n\n- The `inline` prop enables a styling variation resulting in a similar visual\n design to `InlineNotification`.\n- The `actionButtonLabel` prop configures the action button text.\n- The `hasFocus` prop toggles the automatic placement of focus.\n- The `closeOnEscape` prop toggles the closing of notifications via the `escape`\n key.\n\n#### Tabs\n\nTabs have been updated to be more composable so that you have the flexibity and\ncontrol to make them look and act how you want.\n\nIn v10, you may have code that looks like the following:\n\n```js\n\n \n
Content for first tab goes here.
\n \n \n
Content for second tab goes here.
\n \n \n
Content for third tab goes here.
\n \n \n
Content for fourth tab goes here.
\n \n\n```\n\nThose same Tabs, migrated to v11:\n\n```js\n\n \n Tab Label 1\n Tab Label 2\n Tab Label 3\n Tab Label 4 shows truncation\n \n \n Content for first tab goes here.\n Content for second tab goes here.\n Content for third tab goes here.\n Content for fourth tab goes here.\n \n\n```\n\n#### Update `Tabs` and `Tab` usage\n\nAll the same functionality for Tabs is available in v11 and more! However, some\nprops have been deprecated because they have either been renamed or are no\nlonger needed. Below are the minor tweaks in naming or implementation.\n\n- the `type` prop is deprecated. Both \"contained\" and \"default\" tabs still exist\n but now can be called by adding the prop `contained` to the `TabList`.\n- Default tabs are now referred to as line tabs in our documentation here and in\n our storybook.\n- `hidden` prop is no longer needed with the new composable Tabs. You have\n control over tab content and when it is hidden through the `TabPanel` and\n `TabPanels` components.\n- `selected` prop is now named `selectedIndex`.\n- `tabContentClassName` is no longer needed. `TabPanel` (equivalent to tab\n content) takes in a className prop on its outermost node.\n- For `Tab`, `label` is no longer needed. `children` of `Tab` are now the label.\n- Due to its composability, `renderAnchor`, `renderButton`, `renderContent` are\n no longer needed on `Tab`. You now have full control over what is rendered\n inside of `Tab` and `TabPanel`.\n- Because `renderButton` is no longer needed, the associated `tabIndex` prop has\n also been deprecated.\n- `selected` on `Tab` is deprecated in favor or `selectedIndex`, now placed on\n `Tabs` instead.\n\nFor more details about the changes to Tabs, see our storybook documentation\n[here](https://react.carbondesignsystem.com/?path=/docs/components-tabs--default).\n\n### Step 7: Done with @carbon/react!\n\nAnd that's it! You're done. At this point you have migrated to use Carbon v11\nusing the `@carbon/react` package.\n\nIf you run into any problems after this point, please feel free to reach out to\nus over on Slack or open up a discussion on\n[GitHub](https://github.com/carbon-design-system/carbon/discussions/categories/help).\nWe want to make this migration experience as seamless as possible and will be\nmonitoring both areas to help out.\n\n## Migrating an app or library using just styles\n\nStarting in v11, the styles for Carbon live in the `@carbon/styles` package.\nAlternatively, you can continue to use `carbon-components` as it re-exports\nstyles from this package directly.\n\nFor teams using Svelte, Angular, Vue, LWC, or Web Components, please\n[review the documention](https://carbondesignsystem.com/developing/frameworks/web-components),\nfor those respective frameworks before making the migration to v11.\n\n### Step 1: Install @carbon/styles\n\nTo get started, uninstall `carbon-components` from your project:\n\n```bash\nnpm uninstall carbon-components\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn remove carbon-components\n```\n\nNext, install the `@carbon/styles` package:\n\n```bash\nnpm install @carbon/styles\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn add @carbon/styles\n```\n\n### Step 2: Install and configure Dart Sass\n\nPreviously, `carbon-components` supported being compiled by different Sass\nlibraries. Starting in v11, the `@carbon/styles` package requires Dart Sass\nthrough the `sass` package in order to compile. This change comes from our\nmigration to Sass Modules in order to improve our compilation times and overall\nproject structure.\n\nIf you don't have this dependency already in your project, you can install it:\n\n```bash\nnpm install sass\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn add sass\n```\n\nSimilarly, if you currently use `node-sass` now is a good time to remove that\ndependency from your project. In most situations, Dart Sass is a drop-in\nreplacement for `node-sass` and should require no changes on your end in order\nto use it once you install the dependency.\n\nOne you have Dart Sass installed, it's important that you configure your project\nto support resolving imports in Sass from `node_modules`. Typically, this means\nadding `node_modules` to your `includePaths` config for Sass in your bundler or\ntoolchain of choice.\n\nTo learn more about how to configure your specific toolchain to support this,\nread the documentation for configuration\n[here](https://github.com/carbon-design-system/carbon/blob/main/packages/styles/docs/sass.md#configuration).\nWe also have published a guide over on\n[Medium](https://medium.com/carbondesign/migrating-from-node-sass-to-sass-eba9db004a3a)\nto help out with common problems that come from this migration.\n\n\n\n \n \n\n \n\n\n \n \n\n \n\n\n\n### Step 3: Update import paths and tokens\n\nNow, open your project's root stylesheet to make the following changes:\n\n```diff\n- @import 'carbon-components/scss/globals/scss/styles.scss';\n+ @use '@carbon/styles';\n```\n\nIf you were providing any configuration options before you imported Carbon you\ncan now provide them using the `with` syntax:\n\n```scss\n@use '@carbon/styles' with (\n $css--default-type: true,\n $css--reset: true\n);\n```\n\nFor cases where your projects does't need to include everything via\n`@use '@carbon/styles'`; and just want to do individual component styles.\n\n```scss\n// configure feature flags if needed, if not this line can be removed\n@use '@carbon/styles/scss/config' with (\n $font-path: '@ibm/plex'\n);\n\n// ensure the css reset is included\n@use '@carbon/styles/scss/reset';\n\n// add styles for components individually\n@use '@carbon/styles/scss/components/button';\n```\n\nWhen migrating your custom components, some of our most used sass assets are\nincluded below, along with what you would need to have at the top of your file\nto use it. Essentially, all we are doing is including the path where we would\n[find these styles](https://github.com/carbon-design-system/carbon/tree/main/packages/styles/scss)\nin our package.\n\n| Carbon sass I'm using | Sass modules to include |\n| ------------------------------- | --------------------------------------------------------- |\n| Theme tokens | `@use '@carbon/styles/scss/theme' as *` |\n| Theme mixins | `@use '@carbon/styles/scss/themes' as *` |\n| Design language color tokens | `@use '@carbon/styles/scss/colors' as *` |\n| Spacing tokens | `@use '@carbon/styles/scss/spacing' as *` |\n| Breakpoint mixins | `@use '@carbon/styles/scss/breakpoint' as *` |\n| Motion tokens and functions | `@use '@carbon/styles/scss/motion' as *` |\n| Rem and other convert functions | `@use '@carbon/styles/scss/utilities/convert' as *` |\n| Z-index helper | `@use '@carbon/styles/scss/utilities/z-index' as *` |\n| Focus outline helper | `@use '@carbon/styles/scss/utilities/focus-outline' as *` |\n| Transform rotate helper | `@use '@carbon/styles/scss/utilities/rotate' as *` |\n| Skeleton animation helper | `@use '@carbon/styles/scss/utilities/skeleton' as *` |\n\nNow that you've migrated all of your imports, do a find/replace using your\nfavorite code editor. The prefix`carbon--` is no longer necessary. You can do a\nfind for `carbon--` and replace it with nothing to remove across all your files\nlike the example below. The full list of changes are available in our\n[Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#changing-import-paths-from-scssglobalsscss-to-scss).\n\n```diff\n- @include carbon--breakpoint(lg) {\n+ @include breakpoint(lg) {\n width: 42%;\n }\n```\n\nOnce you've removed the prefix, your styles should all be set using the old, v10\ntokens. We recommend teams install the community supported\n[stylelint-plugin-carbon-tokens](https://github.com/carbon-design-system/stylelint-plugin-carbon-tokens)\nto further assist in migrating your tokens to v11 tokens as the old v10 tokens\nwill be removed in our next major release.\n\n\n\n \n \n\n \n\n\n \n \n\n \n\n\n\n### Step 4: Update bx to cds\n\nIf you are targeting specific selectors that use the `bx` prefix, you will need\nto update your code to either target the `cds` prefix for selectors or update\nCarbon's configuration to use `bx` as the prefix by writing the following:\n\n```scss\n// Option A\n@use '@carbon/styles' with (\n $prefix: 'bx'\n);\n// Option B\n@use '@carbon/styles/scss/config' with (\n $prefix: 'bx'\n);\n```\n\n### Step 5: Enable flexbox grid\n\nIf you are using the flexbox-based grid in your project, you can continue to use\nthis feature in v11 by importing the following:\n\n```scss\n@use '@carbon/styles/scss/grid/flexbox';\n```\n\nThis is important due to the fact that the CSS Grid implementation is used by\ndefault in v11. However, bringing in the flexbox grid styles in this way means\nthat your layouts will continue to work the same as in v10.\n\n### Step 6: Done with @carbon/styles!\n\nAnd that's it! You're done. At this point you have migrated to use Carbon v11\nusing the `@carbon/styles` package.\n\nIf you run into any problems after this point, please feel free to reach out to\nus over on Slack or open up a discussion on\n[GitHub](https://github.com/carbon-design-system/carbon/discussions/categories/help).\nWe want to make this migration experience as seamless as possible and will be\nmonitoring both areas to help out.\n\n## Migrating carbon-icons\n\nThe `carbon-icons` package has been deprecated and is no longer supported. To\nuse icons from the Carbon Design System, you should install the appropriate\nlibrary to use with your framework:\n\n| Package | Framework | Link |\n| :---------------------- | :----------------- | :------------------------------------------------------ |\n| `@carbon/icons-react` | React | [Link](https://npmjs.com/package/@carbon/icons-react) |\n| `@carbon/icons-angular` | Angular | [Link](https://npmjs.com/package/@carbon/icons-angular) |\n| `@carbon/icons-vue` | Vue | [Link](https://npmjs.com/package/@carbon/icons-vue) |\n| `carbon-icons-svelte` | Svelte | [Link](https://npmjs.com/package/carbon-icons-svelte) |\n| `@carbon/icons` | Vanilla JavaScript | [Link](https://npmjs.com/package/@carbon/icons) |\n\nIf you are using `@carbon/react`, you can directly import icons from\n`@carbon/react/icons`.\n\n## Migrating Carbon elements\n\nThe packages that we ship for the IBM Design Language have been updated in v11.\nThe most notable change is that these packages now require Dart Sass in order to\ncompile as they now use Sass Modules to improve compilation times.\n\nIf you were directly importing from one of these element packages, consider\nimporting from either `@carbon/styles` or `@carbon/react` instead. Both of these\npackages provide entrypoints for elements packages on top of the styles for\nCarbon itself.\n\nFor teams using these packages directly, you will need to update each of the\nelements packages you're using to the latest version.\n\n```bash\nnpm install @carbon/@latest\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn upgrade @carbon/@latest\n```\n\nAfterwards, you will need to update the import paths and import names themselves\nthat you bring in. In general, each package now supports importing from the\npackage directly and all `carbon--` prefixed variables, mixins, and functions\nhave been renamed to remove the prefix.\n\nFor full details fo the changes to each elements package, check out the links\nbelow.\n\n| Package | Migration Docs |\n| :----------------- | :---------------------------------------------------------------------------------------------------- |\n| `@carbon/colors` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carboncolors) |\n| `@carbon/elements` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbonelements) |\n| `@carbon/grid` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbongrid) |\n| `@carbon/layout` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbonlayout) |\n| `@carbon/motion` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbonmotion) |\n| `@carbon/themes` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbonthemes) |\n| `@carbon/type` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbontype) |\n\nIf you were previously using the `@carbon/import-once` package, you can continue\nto use this in v11. However, this package will receive no further updates after\nCarbon switched to using Sass Modules.\n","type":"Mdx","contentDigest":"179a69c16a51c4f022f75ae4b43e443a","owner":"gatsby-plugin-mdx","counter":5331},"frontmatter":{"title":"Guide","description":"This guide includes everything you need to migrate your offering from v10 to v11 of Carbon.","tabs":["Overview","Design","Develop"]},"exports":{},"rawBody":"---\ntitle: Guide\ndescription:\n This guide includes everything you need to migrate your offering from v10 to\n v11 of Carbon.\ntabs: ['Overview', 'Design', 'Develop']\n---\n\nimport { Tag } from '@carbon/react';\n\n\n\nStep-by-step guide to updating your code from Carbon v10 to v11.\n\n\n\n\n\nOverview\nMigrating a React app or library\nMigrating an app or library using just styles\nMigrating carbon-icons\nMigrating Carbon elements\n\n\n\n## Overview\n\nThis guide helps you update your project to Carbon v11. It is broken into\nsections based on how you are using Carbon in your project today. For most teams\nusing Carbon, you'll want to use the\n[Migrating a React app](#migrating-a-react-app) section.\n\nOne of the biggest changes to Carbon in v11 is that we moved to dedicated\npackages under the `@carbon` scope. What this means for you is that if you were\npreviously using the following packages:\n\n- `carbon-components`\n- `carbon-components-react`\n- `carbon-icons`\n- `@carbon/icons-react`\n\nYou can access all of this work under one single package: `@carbon/react`. This\npackage will re-export all of the styles and icons for Carbon all in one\ndependency.\n\nIf you were previously using `carbon-components`, the styles from this package\nare available under `@carbon/styles`. They are also re-exported through\n`@carbon/react`\n\nBoth the `carbon-components` and `carbon-components-react` packages will stick\naround in v11 but they are only re-exports of `@carbon/styles` and\n`@carbon/react` respectively.\n\n## Migrating a React app or library\n\nStarting in v11, the React components for Carbon live in the `@carbon/react`\npackage.\n\nThe `@carbon/react` package also includes the styles for Carbon along with\nicons.\n\n### Step 1: Install @carbon/react\n\nTo get started, uninstall the following packages if they exist in your project:\n\n- `carbon-components`\n- `carbon-components-react`\n- `carbon-icons`\n- `@carbon/icons-react`\n\n```bash\nnpm uninstall carbon-components carbon-components-react carbon-icons @carbon/icons-react\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn remove carbon-components carbon-components-react carbon-icons @carbon/icons-react\n```\n\nNext, install the `@carbon/react` package:\n\n```bash\nnpm install @carbon/react\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn add @carbon/react\n```\n\nNow that you've removed the old packages and brought in the new ones, run the\ncodemod below to fix your pathing.\n\n```bash\nnpx @carbon/upgrade migrate update-carbon-components-react-import-to-scoped --write\n```\n\nAfter running the command, your code should start looking like this:\n\n```jsx\n// Before\nimport { Accordion, AccordionItem } from 'carbon-components-react';\n// After\nimport { Accordion, AccordionItem } from '@carbon/react';\n```\n\n\n\nFor full details, including options and commands availabe when using the\n`@carbon/upgrade` CLI, see the\n[package documentation](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade).\n\n\n\n### Step 2: Install Dart Sass\n\nIf you were previously importing styles from `carbon-components`, you can now\nimport styles directly from `@carbon/react` or the `@carbon/react/scss` folder.\n\nBefore you're able to bring in these styles, you'll need to make sure your\nproject is setup to use Dart Sass. Starting in v11, Carbon styles requires Dart\nSass through the `sass` package in order to compile. This change comes from our\nmigration to Sass Modules in order to improve our compilation times and overall\nproject structure.\n\nFirst, let's remove `node-sass` from your project. If you don't have\n`node-sass`, no worries, just skip down and begin adding `sass`.\n\n```bash\nnpm uninstall node-sass\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn remove node-sass\n```\n\nNow, let's install `sass`:\n\n```bash\nnpm install sass --save-dev\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn add sass --dev\n```\n\nOnce you have Dart Sass installed, it's important that you configure your\nproject to support resolving imports in Sass from `node_modules`. Typically,\nthis means adding `node_modules` to your `includePaths` config for Sass in your\nbundler or toolchain of choice.\n\nTo learn more about how to configure your specific toolchain to support this,\nread the documentation for configuration\n[here](https://github.com/carbon-design-system/carbon/blob/main/packages/styles/docs/sass.md#configuration).\nWe also have published a guide over on\n[Medium](https://medium.com/carbondesign/migrating-from-node-sass-to-sass-eba9db004a3a)\nto help out with common problems that come from this migration.\n\n\n\n \n \n\n \n\n\n \n \n\n \n\n\n\n### Step 3: Update style import paths\n\nNow, open your project's root stylesheet to make the following changes:\n\n```diff\n- @import 'carbon-components/scss/globals/scss/styles.scss';\n+ @use '@carbon/react';\n```\n\nIf you were providing any configuration options before you imported Carbon you\ncan now provide them using the `with` syntax:\n\n```scss\n@use '@carbon/react' with (\n $css--default-type: true,\n $css--reset: true\n);\n```\n\nIf you were using any feature flags in v10, you can safely remove them in v11.\n\nYou can also use @import to bring in Carbon, if you prefer, although @use is\nrecommended.\n\nFor cases where your projects does't need to include everything via\n`@use '@carbon/react'`; and just want to do individual component styles.\n\n```scss\n// Configure feature flags if needed, if not these\n// lines can be removed\n@use '@carbon/react/scss/config' with (\n $font-path: '@ibm/plex',\n $use-flexbox-grid: 'true'\n);\n\n// Emit the css reset\n@use '@carbon/react/scss/reset';\n\n// Emit the Plex font-face declarations\n@use '@carbon/react/scss/fonts';\n\n// Optional: emit the grid styles if using the grid.\n// This will emit the flex-grid styles if\n// $use-flexbox-grid is configured to 'true'\n@use '@carbon/react/scss/grid';\n\n// Emit the layer styles\n@use '@carbon/react/scss/layer';\n\n// Emit individual component styles\n@use '@carbon/react/scss/components/button';\n@use '@carbon/react/scss/components/tile';\n\n// Use additional local stylesheets\n@use 'sample-grid';\n```\n\nWhen migrating your custom components, some of our most used sass assets are\nincluded below, along with what you would need to have at the top of your file\nto use it. Essentially, all we are doing is including the path where we would\n[find these styles](https://github.com/carbon-design-system/carbon/tree/main/packages/react/scss)\nin our package.\n\n| Carbon sass I'm using | Sass modules to include |\n| ------------------------------- | -------------------------------------------------------- |\n| Type tokens | `@use '@carbon/react/scss/type' as *;` |\n| Theme tokens | `@use '@carbon/react/scss/theme' as *` |\n| Theme mixins | `@use '@carbon/react/scss/themes' as *` |\n| Design language color tokens | `@use '@carbon/react/scss/colors' as *` |\n| Spacing tokens | `@use '@carbon/react/scss/spacing' as *` |\n| Breakpoint mixins | `@use '@carbon/react/scss/breakpoint' as *` |\n| Motion tokens and functions | `@use '@carbon/react/scss/motion' as *` |\n| Rem and other convert functions | `@use '@carbon/react/scss/utilities/convert' as *` |\n| Z-index helper | `@use '@carbon/react/scss/utilities/z-index' as *` |\n| Focus outline helper | `@use '@carbon/react/scss/utilities/focus-outline' as *` |\n| Transform rotate helper | `@use '@carbon/react/scss/utilities/rotate' as *` |\n| Skeleton animation helper | `@use '@carbon/react/scss/utilities/skeleton' as *` |\n\nNow that you've migrated all of your imports, do a find/replace using your\nfavorite code editor. The prefix `carbon--` is no longer necessary. You can do a\nfind for `carbon--` and replace it with nothing to remove across all your files\nlike the example below. The full list of changes are available in our\n[Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#changing-import-paths-from-scssglobalsscss-to-scss).\n\n```diff\n- @include carbon--breakpoint(lg) {\n+ @include breakpoint(lg) {\n width: 42%;\n }\n```\n\nOnce you've removed the prefix, your styles should all be set using the old, v10\ntokens. We recommend teams install the community supported\n[stylelint-plugin-carbon-tokens](https://github.com/carbon-design-system/stylelint-plugin-carbon-tokens)\nto further assist in migrating your tokens to v11 tokens as the old v10 tokens\nwill be removed in our next major release.\n\n\n\n \n \n\n \n\n\n \n \n\n \n\n\n\n### Step 4: Updating component size props\n\nComponents with size variants have been updated to use the same API options.\nPreviously, the size options were inconsistent: `field`, `medium`, `short`. Now,\nsize options fall under the following values:\n\n| Prop value | Size |\n| ---------- | ---- |\n| `xs` | 24px |\n| `sm` | 32px |\n| `md` | 40px |\n| `lg` | 48px |\n| `xl` | 64px |\n| `2xl` | 80px |\n\n**Note:** the default size in v11 is `md` (`40px`).\n\nRun the following codemods to update the size prop across the effected\ncomponents in your project.\n\n```bash\nnpx @carbon/upgrade migrate small-to-size-prop --write\nnpx @carbon/upgrade migrate size-prop-update --write\n```\n\nBy running the series of codemods, they will do the following, in order:\n\n1. Removes the deprecated `small` boolean prop and replaces it with `size=\"sm\"`.\n2. Removes v10 size props and replaces them with v11 sizes props.\n\nIt's important to run the npx commands in the order that they are presented\nabove. Doing them out of order might result in the codemod not working as\nintended.\n\n\n\nFor full details, including options and commands availabe when using the\n`@carbon/upgrade` CLI, see the\n[package documentation](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade).\n\n\n\nThe following components all have size variants that may be affected in your\ncode. To update, you will need to switch to one of the size options listed\nabove. The codemod will make short work of these changes.\n\n- Accordion\n- Button\n- ComboBox\n- Dropdown\n- Multiselect\n- Filterable multiselect\n- ContentSwitcher\n- DataTable\n- DatePicker\n- FileUploader\n- FileUploaderItem\n- FileUploaderDropContainer\n- FileUploaderButton\n- Link\n- Modal\n- ComposedModal\n- NumberInput\n- OverflowMenu\n- Search\n- Select\n- Tag\n- TextInput\n- TimePicker\n- Toggle\n\n### Step 5: Update icon sizes and imports\n\nThe `@carbon/icons-react` package has been updated to minimize the number of\nexports from the package to help reduce build and compile times. This package is\navailable under `@carbon/react/icons`.\n\nThis update includes a change to the API of the icon components that come from\nthis package. Previously, we would export icons that included the size of the\nasset. This update allows you to bring the icon directly and specify the size\nusing the `size` prop.\n\nRun the following codemods to update your project's icons.\n\n```bash\nnpx @carbon/upgrade migrate icons-react-size-prop --write\nnpx @carbon/upgrade migrate update-carbon-icons-react-import-to-carbon-react --write\n```\n\nBy running the series of codemods, they will do the following, in order:\n\n1. Removes the size from the import and places it on the icon directly.\n2. Remove the `@carbon/icons-react` pathing and replace it with\n `@carbon/react/icons`.\n\nIt's important to run the npx commands in the order that they are presented\nabove. Doing them out of order might result in the codemod not working as\nintended.\n\n\n\nFor full details, including options and commands availabe when using the\n`@carbon/upgrade` CLI, see the\n[package documentation](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade).\n\n\n\nAfter running the command, instead of your icons imports looking like this:\n\n**Before**\n\n```jsx\nimport { Add32, Add24, Add20, Add16 } from '@carbon/icons-react';\n\nfunction MyComponent() {\n return (\n <>\n \n \n \n \n \n );\n}\n```\n\nThey should start looking like this:\n\n**After**\n\n```jsx\nimport { Add } from '@carbon/react/icons';\n\nfunction MyComponent() {\n return (\n <>\n \n \n \n \n \n );\n}\n```\n\n#### Removed icons\n\nThe following deprecated icons have been removed. Use the table below to find\ntheir replacement, if available, in v11.\n\n| Asset | v10 | v11 |\n| :------------------------------ | :-------------------------- | :-------------------------- |\n| app-switcher | AppSwitcher | Switcher |\n| arrows | Arrows | ArrowsVertical |\n| back-to-top | BackToTop | UpToTop |\n| checkbox--undeterminate | CheckboxUndeterminate | CheckboxIndeterminate |\n| checkbox--undeterminate--filled | CheckboxUndeterminateFilled | CheckboxIndeterminateFilled |\n| cloud--lightning | CloudLightning | Removed |\n| cloud--rain | CloudRain | Removed |\n| cloud--snow | CloudSnow | Removed |\n| delete | Delete | TrashCan |\n| edit-filter | EditFilter | FilterEdit |\n| sunny | Sunny | Removed |\n| research--bloch-sphere | ResearchBlockSphere | BlochSphere |\n| research--hinton-plot | ResearchHintonPlot | HintonPlot |\n| research--matrix | ResearchMatrix | Matrix |\n| misuse--alt | MisuseAlt | MisuseOutline |\n| logo--google | LogoGoogle | Removed |\n| mammogram--stacked | MammogramStacked | Removed |\n| logo--delicious | LogoDelicious | Removed |\n| logo--stumbleupon | LogoStumbleUpon | Removed |\n| letter--Aa--large | LetterAaLarge | TextFont |\n| glyph--caution-inverted | GlyphCautionInverted | CautionInverted |\n| glyph--caution | GlyphCaution | Caution |\n| glyph--circle-fill | GlyphCircleFill | CircleFill |\n| glyph--circle-stroke | GlyphCircleStroke | CircleStroke |\n| glyph--critical | GlyphCritical | Critical |\n| glyph--incomplete | GlyphIncomplete | Incomplete |\n| glyph--square-fill | GlyphSquareFill | SquareFill |\n| glyph--undefined | GlyphUndefined | Undefined |\n\nHowever, in certain situations, we will be unable to infer what the correct\nupdate should be for a certain usage of the icon component. We have written the\ncodemod to work for most situations, but you will see console warnings for files\nthat will require you to manually review them to make sure the transforms were\napplied correctly.\n\nThe most common manual update that teams will need to make is if a `prop` where\nthe icon is passed to places a `ref` on the icon. For example,\n\n```jsx\nfunction MyComponent({ renderIcon: Icon }) {\n const ref = useRef(null);\n return ;\n}\n\n// Before\n\n\n// After the codemod\n} />\n```\n\nIn this situation, you will need to update your code to use `React.forwardRef`:\n\n```jsx\n (\n \n ))}\n/>;\n\n// Or, alternatively:\nconst Search16 = React.forwardRef((props, ref) => {\n return ;\n});\n\n;\n```\n\n#### Manual migration\n\nIn addition to the automated codemods above, there are several patterns in your\ncodebase that you will need to update manually:\n\n- If you use the name `ForwardRef(IconName16)` in a test you will need to\n manually change this. Prefer to use the component directly if using enzyme\n- If you use snapshot tests, the structure will change and include a `size`\n prop. Make sure that the `size` prop value matches what your icon name used to\n be. For example, `` should become ``\n\n### Step 6: Update components that have changed\n\nIn v11, we have updated the APIs of certain components in one of the following\nways:\n\n- Update `className` usage to be applied to the outermost element of a component\n- Remove props that have been deprecated in v10\n- Refactor the API to ship an accessible component\n\nFor a full list of changes to components, check out our\n[Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbon-components-react).\nBelow are some common changes that may impact you and your usage of Carbon.\n\n#### Changes to `className`\n\nThe usage of `className` prop has been updated so that the class is passed to\nthe outermost element of a component's inner markup. This was already the case\nfor most components and this change brings along the remaining components in the\nlibrary to this convention.\n\nThe following components previously were not applying the `className` prop to\nthe outermost element. If you were using a custom `className` to target an inner\nelement for any of these components, you will have to update your selectors to\nnow account for the `className` being placed on the outermost element.\n\n- Checkbox\n- ComboBox\n- Table\n- TableToolbar\n- DataTableSkeleton\n- DatePicker\n- DatePickerSkeleton\n- DatePickerInput\n- Dropdown\n- FileUploaderDropContainer\n- FileUploaderItem\n- FormGroup\n- FilterableMultiSelect\n- MultiSelect\n- NotificationTextDetails\n- NotificationIcon\n- NumberInput\n- OverflowMenuItem\n- RadioButtonGroup\n- RadioTile\n- Select\n- Slider\n- Switch\n- TextArea\n- ControlledPasswordInput\n- PasswordInput\n- TextInput\n- TimePicker\n- Tooltip\n- HeaderContainer\n\n#### Notification\n\nWe have updated the notification components to be more accessible out of the\nbox. `ToastNotification` and `InlineNotification` now have `role=\"status\"` by\ndefault with additional `role` options of `log` and `alert`. These components do\nnot receive focus and should be used for information-only use cases. These\ncomponents no longer accept actions or interactive children.\n\nFor notifications requiring an action, a new `ActionableNotifiation` component\nis available. It has a `role=\"alertdialog\"` and recieves focus by default.\nAutomatic placement of focus can be turned off via the new `hasFocus` prop.\n\nAll notifications have a new optional `closeOnEscape` prop, it enables\nnotifications to closed by pressing the `escape` key. For more details, see the\n[notification components accessibility page](https://www.carbondesignsystem.com/components/notification/accessibility).\n\n#### Update `ToastNotification` usage\n\n- `children` can no longer contain interactive elements. A `ToastNotification`\n containing an action or interactive children should be replaced with\n `ActionableNotification`.\n- The `notificationType` prop is no longer needed and can be removed.\n- The default `role` is now `status`. `log` and `alert` can also be used.\n- The `closeOnEscape` prop toggles the closing of notifications via the `escape`\n key.\n\n#### Update `InlineNotification` usage\n\n- The `actions` prop has been removed. An `InlineNotification` containing an\n action or interactive children should be replaced with\n `ActionableNotification` configured with the `inline` prop.\n- `children` can no longer contain interactive elements.\n- The `notificationType` prop is no longer needed and can be removed.\n- The default `role` is now `status`. `log` and `alert` can also be used.\n- The `closeOnEscape` prop toggles the closing of notifications via the `escape`\n key.\n\n#### When using `ActionableNotification`:\n\n- The `inline` prop enables a styling variation resulting in a similar visual\n design to `InlineNotification`.\n- The `actionButtonLabel` prop configures the action button text.\n- The `hasFocus` prop toggles the automatic placement of focus.\n- The `closeOnEscape` prop toggles the closing of notifications via the `escape`\n key.\n\n#### Tabs\n\nTabs have been updated to be more composable so that you have the flexibity and\ncontrol to make them look and act how you want.\n\nIn v10, you may have code that looks like the following:\n\n```js\n\n \n
Content for first tab goes here.
\n \n \n
Content for second tab goes here.
\n \n \n
Content for third tab goes here.
\n \n \n
Content for fourth tab goes here.
\n \n\n```\n\nThose same Tabs, migrated to v11:\n\n```js\n\n \n Tab Label 1\n Tab Label 2\n Tab Label 3\n Tab Label 4 shows truncation\n \n \n Content for first tab goes here.\n Content for second tab goes here.\n Content for third tab goes here.\n Content for fourth tab goes here.\n \n\n```\n\n#### Update `Tabs` and `Tab` usage\n\nAll the same functionality for Tabs is available in v11 and more! However, some\nprops have been deprecated because they have either been renamed or are no\nlonger needed. Below are the minor tweaks in naming or implementation.\n\n- the `type` prop is deprecated. Both \"contained\" and \"default\" tabs still exist\n but now can be called by adding the prop `contained` to the `TabList`.\n- Default tabs are now referred to as line tabs in our documentation here and in\n our storybook.\n- `hidden` prop is no longer needed with the new composable Tabs. You have\n control over tab content and when it is hidden through the `TabPanel` and\n `TabPanels` components.\n- `selected` prop is now named `selectedIndex`.\n- `tabContentClassName` is no longer needed. `TabPanel` (equivalent to tab\n content) takes in a className prop on its outermost node.\n- For `Tab`, `label` is no longer needed. `children` of `Tab` are now the label.\n- Due to its composability, `renderAnchor`, `renderButton`, `renderContent` are\n no longer needed on `Tab`. You now have full control over what is rendered\n inside of `Tab` and `TabPanel`.\n- Because `renderButton` is no longer needed, the associated `tabIndex` prop has\n also been deprecated.\n- `selected` on `Tab` is deprecated in favor or `selectedIndex`, now placed on\n `Tabs` instead.\n\nFor more details about the changes to Tabs, see our storybook documentation\n[here](https://react.carbondesignsystem.com/?path=/docs/components-tabs--default).\n\n### Step 7: Done with @carbon/react!\n\nAnd that's it! You're done. At this point you have migrated to use Carbon v11\nusing the `@carbon/react` package.\n\nIf you run into any problems after this point, please feel free to reach out to\nus over on Slack or open up a discussion on\n[GitHub](https://github.com/carbon-design-system/carbon/discussions/categories/help).\nWe want to make this migration experience as seamless as possible and will be\nmonitoring both areas to help out.\n\n## Migrating an app or library using just styles\n\nStarting in v11, the styles for Carbon live in the `@carbon/styles` package.\nAlternatively, you can continue to use `carbon-components` as it re-exports\nstyles from this package directly.\n\nFor teams using Svelte, Angular, Vue, LWC, or Web Components, please\n[review the documention](https://carbondesignsystem.com/developing/frameworks/web-components),\nfor those respective frameworks before making the migration to v11.\n\n### Step 1: Install @carbon/styles\n\nTo get started, uninstall `carbon-components` from your project:\n\n```bash\nnpm uninstall carbon-components\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn remove carbon-components\n```\n\nNext, install the `@carbon/styles` package:\n\n```bash\nnpm install @carbon/styles\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn add @carbon/styles\n```\n\n### Step 2: Install and configure Dart Sass\n\nPreviously, `carbon-components` supported being compiled by different Sass\nlibraries. Starting in v11, the `@carbon/styles` package requires Dart Sass\nthrough the `sass` package in order to compile. This change comes from our\nmigration to Sass Modules in order to improve our compilation times and overall\nproject structure.\n\nIf you don't have this dependency already in your project, you can install it:\n\n```bash\nnpm install sass\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn add sass\n```\n\nSimilarly, if you currently use `node-sass` now is a good time to remove that\ndependency from your project. In most situations, Dart Sass is a drop-in\nreplacement for `node-sass` and should require no changes on your end in order\nto use it once you install the dependency.\n\nOne you have Dart Sass installed, it's important that you configure your project\nto support resolving imports in Sass from `node_modules`. Typically, this means\nadding `node_modules` to your `includePaths` config for Sass in your bundler or\ntoolchain of choice.\n\nTo learn more about how to configure your specific toolchain to support this,\nread the documentation for configuration\n[here](https://github.com/carbon-design-system/carbon/blob/main/packages/styles/docs/sass.md#configuration).\nWe also have published a guide over on\n[Medium](https://medium.com/carbondesign/migrating-from-node-sass-to-sass-eba9db004a3a)\nto help out with common problems that come from this migration.\n\n\n\n \n \n\n \n\n\n \n \n\n \n\n\n\n### Step 3: Update import paths and tokens\n\nNow, open your project's root stylesheet to make the following changes:\n\n```diff\n- @import 'carbon-components/scss/globals/scss/styles.scss';\n+ @use '@carbon/styles';\n```\n\nIf you were providing any configuration options before you imported Carbon you\ncan now provide them using the `with` syntax:\n\n```scss\n@use '@carbon/styles' with (\n $css--default-type: true,\n $css--reset: true\n);\n```\n\nFor cases where your projects does't need to include everything via\n`@use '@carbon/styles'`; and just want to do individual component styles.\n\n```scss\n// configure feature flags if needed, if not this line can be removed\n@use '@carbon/styles/scss/config' with (\n $font-path: '@ibm/plex'\n);\n\n// ensure the css reset is included\n@use '@carbon/styles/scss/reset';\n\n// add styles for components individually\n@use '@carbon/styles/scss/components/button';\n```\n\nWhen migrating your custom components, some of our most used sass assets are\nincluded below, along with what you would need to have at the top of your file\nto use it. Essentially, all we are doing is including the path where we would\n[find these styles](https://github.com/carbon-design-system/carbon/tree/main/packages/styles/scss)\nin our package.\n\n| Carbon sass I'm using | Sass modules to include |\n| ------------------------------- | --------------------------------------------------------- |\n| Theme tokens | `@use '@carbon/styles/scss/theme' as *` |\n| Theme mixins | `@use '@carbon/styles/scss/themes' as *` |\n| Design language color tokens | `@use '@carbon/styles/scss/colors' as *` |\n| Spacing tokens | `@use '@carbon/styles/scss/spacing' as *` |\n| Breakpoint mixins | `@use '@carbon/styles/scss/breakpoint' as *` |\n| Motion tokens and functions | `@use '@carbon/styles/scss/motion' as *` |\n| Rem and other convert functions | `@use '@carbon/styles/scss/utilities/convert' as *` |\n| Z-index helper | `@use '@carbon/styles/scss/utilities/z-index' as *` |\n| Focus outline helper | `@use '@carbon/styles/scss/utilities/focus-outline' as *` |\n| Transform rotate helper | `@use '@carbon/styles/scss/utilities/rotate' as *` |\n| Skeleton animation helper | `@use '@carbon/styles/scss/utilities/skeleton' as *` |\n\nNow that you've migrated all of your imports, do a find/replace using your\nfavorite code editor. The prefix`carbon--` is no longer necessary. You can do a\nfind for `carbon--` and replace it with nothing to remove across all your files\nlike the example below. The full list of changes are available in our\n[Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#changing-import-paths-from-scssglobalsscss-to-scss).\n\n```diff\n- @include carbon--breakpoint(lg) {\n+ @include breakpoint(lg) {\n width: 42%;\n }\n```\n\nOnce you've removed the prefix, your styles should all be set using the old, v10\ntokens. We recommend teams install the community supported\n[stylelint-plugin-carbon-tokens](https://github.com/carbon-design-system/stylelint-plugin-carbon-tokens)\nto further assist in migrating your tokens to v11 tokens as the old v10 tokens\nwill be removed in our next major release.\n\n\n\n \n \n\n \n\n\n \n \n\n \n\n\n\n### Step 4: Update bx to cds\n\nIf you are targeting specific selectors that use the `bx` prefix, you will need\nto update your code to either target the `cds` prefix for selectors or update\nCarbon's configuration to use `bx` as the prefix by writing the following:\n\n```scss\n// Option A\n@use '@carbon/styles' with (\n $prefix: 'bx'\n);\n// Option B\n@use '@carbon/styles/scss/config' with (\n $prefix: 'bx'\n);\n```\n\n### Step 5: Enable flexbox grid\n\nIf you are using the flexbox-based grid in your project, you can continue to use\nthis feature in v11 by importing the following:\n\n```scss\n@use '@carbon/styles/scss/grid/flexbox';\n```\n\nThis is important due to the fact that the CSS Grid implementation is used by\ndefault in v11. However, bringing in the flexbox grid styles in this way means\nthat your layouts will continue to work the same as in v10.\n\n### Step 6: Done with @carbon/styles!\n\nAnd that's it! You're done. At this point you have migrated to use Carbon v11\nusing the `@carbon/styles` package.\n\nIf you run into any problems after this point, please feel free to reach out to\nus over on Slack or open up a discussion on\n[GitHub](https://github.com/carbon-design-system/carbon/discussions/categories/help).\nWe want to make this migration experience as seamless as possible and will be\nmonitoring both areas to help out.\n\n## Migrating carbon-icons\n\nThe `carbon-icons` package has been deprecated and is no longer supported. To\nuse icons from the Carbon Design System, you should install the appropriate\nlibrary to use with your framework:\n\n| Package | Framework | Link |\n| :---------------------- | :----------------- | :------------------------------------------------------ |\n| `@carbon/icons-react` | React | [Link](https://npmjs.com/package/@carbon/icons-react) |\n| `@carbon/icons-angular` | Angular | [Link](https://npmjs.com/package/@carbon/icons-angular) |\n| `@carbon/icons-vue` | Vue | [Link](https://npmjs.com/package/@carbon/icons-vue) |\n| `carbon-icons-svelte` | Svelte | [Link](https://npmjs.com/package/carbon-icons-svelte) |\n| `@carbon/icons` | Vanilla JavaScript | [Link](https://npmjs.com/package/@carbon/icons) |\n\nIf you are using `@carbon/react`, you can directly import icons from\n`@carbon/react/icons`.\n\n## Migrating Carbon elements\n\nThe packages that we ship for the IBM Design Language have been updated in v11.\nThe most notable change is that these packages now require Dart Sass in order to\ncompile as they now use Sass Modules to improve compilation times.\n\nIf you were directly importing from one of these element packages, consider\nimporting from either `@carbon/styles` or `@carbon/react` instead. Both of these\npackages provide entrypoints for elements packages on top of the styles for\nCarbon itself.\n\nFor teams using these packages directly, you will need to update each of the\nelements packages you're using to the latest version.\n\n```bash\nnpm install @carbon/@latest\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn upgrade @carbon/@latest\n```\n\nAfterwards, you will need to update the import paths and import names themselves\nthat you bring in. In general, each package now supports importing from the\npackage directly and all `carbon--` prefixed variables, mixins, and functions\nhave been renamed to remove the prefix.\n\nFor full details fo the changes to each elements package, check out the links\nbelow.\n\n| Package | Migration Docs |\n| :----------------- | :---------------------------------------------------------------------------------------------------- |\n| `@carbon/colors` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carboncolors) |\n| `@carbon/elements` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbonelements) |\n| `@carbon/grid` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbongrid) |\n| `@carbon/layout` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbonlayout) |\n| `@carbon/motion` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbonmotion) |\n| `@carbon/themes` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbonthemes) |\n| `@carbon/type` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbontype) |\n\nIf you were previously using the `@carbon/import-once` package, you can continue\nto use this in v11. However, this package will receive no further updates after\nCarbon switched to using Sass Modules.\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/migrating/guide/develop.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-migrating-guide-develop-mdx","path":"/migrating/guide/develop/","result":{"pageContext":{"frontmatter":{"title":"Guide","description":"This guide includes everything you need to migrate your offering from v10 to v11 of Carbon.","tabs":["Overview","Design","Develop"]},"relativePagePath":"/migrating/guide/develop.mdx","titleType":"prepend","MdxNode":{"id":"62679931-0962-5f96-9e11-3480f242b214","children":[],"parent":"3e1035a9-69dd-5afc-90b3-4cc516ca5e43","internal":{"content":"---\ntitle: Guide\ndescription:\n This guide includes everything you need to migrate your offering from v10 to\n v11 of Carbon.\ntabs: ['Overview', 'Design', 'Develop']\n---\n\nimport { Tag } from '@carbon/react';\n\n\n\nStep-by-step guide to updating your code from Carbon v10 to v11.\n\n\n\n\n\nOverview\nMigrating a React app or library\nMigrating an app or library using just styles\nMigrating carbon-icons\nMigrating Carbon elements\n\n\n\n## Overview\n\nThis guide helps you update your project to Carbon v11. It is broken into\nsections based on how you are using Carbon in your project today. For most teams\nusing Carbon, you'll want to use the\n[Migrating a React app](#migrating-a-react-app) section.\n\nOne of the biggest changes to Carbon in v11 is that we moved to dedicated\npackages under the `@carbon` scope. What this means for you is that if you were\npreviously using the following packages:\n\n- `carbon-components`\n- `carbon-components-react`\n- `carbon-icons`\n- `@carbon/icons-react`\n\nYou can access all of this work under one single package: `@carbon/react`. This\npackage will re-export all of the styles and icons for Carbon all in one\ndependency.\n\nIf you were previously using `carbon-components`, the styles from this package\nare available under `@carbon/styles`. They are also re-exported through\n`@carbon/react`\n\nBoth the `carbon-components` and `carbon-components-react` packages will stick\naround in v11 but they are only re-exports of `@carbon/styles` and\n`@carbon/react` respectively.\n\n## Migrating a React app or library\n\nStarting in v11, the React components for Carbon live in the `@carbon/react`\npackage.\n\nThe `@carbon/react` package also includes the styles for Carbon along with\nicons.\n\n### Step 1: Install @carbon/react\n\nTo get started, uninstall the following packages if they exist in your project:\n\n- `carbon-components`\n- `carbon-components-react`\n- `carbon-icons`\n- `@carbon/icons-react`\n\n```bash\nnpm uninstall carbon-components carbon-components-react carbon-icons @carbon/icons-react\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn remove carbon-components carbon-components-react carbon-icons @carbon/icons-react\n```\n\nNext, install the `@carbon/react` package:\n\n```bash\nnpm install @carbon/react\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn add @carbon/react\n```\n\nNow that you've removed the old packages and brought in the new ones, run the\ncodemod below to fix your pathing.\n\n```bash\nnpx @carbon/upgrade migrate update-carbon-components-react-import-to-scoped --write\n```\n\nAfter running the command, your code should start looking like this:\n\n```jsx\n// Before\nimport { Accordion, AccordionItem } from 'carbon-components-react';\n// After\nimport { Accordion, AccordionItem } from '@carbon/react';\n```\n\n\n\nFor full details, including options and commands availabe when using the\n`@carbon/upgrade` CLI, see the\n[package documentation](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade).\n\n\n\n### Step 2: Install Dart Sass\n\nIf you were previously importing styles from `carbon-components`, you can now\nimport styles directly from `@carbon/react` or the `@carbon/react/scss` folder.\n\nBefore you're able to bring in these styles, you'll need to make sure your\nproject is setup to use Dart Sass. Starting in v11, Carbon styles requires Dart\nSass through the `sass` package in order to compile. This change comes from our\nmigration to Sass Modules in order to improve our compilation times and overall\nproject structure.\n\nFirst, let's remove `node-sass` from your project. If you don't have\n`node-sass`, no worries, just skip down and begin adding `sass`.\n\n```bash\nnpm uninstall node-sass\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn remove node-sass\n```\n\nNow, let's install `sass`:\n\n```bash\nnpm install sass --save-dev\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn add sass --dev\n```\n\nOnce you have Dart Sass installed, it's important that you configure your\nproject to support resolving imports in Sass from `node_modules`. Typically,\nthis means adding `node_modules` to your `includePaths` config for Sass in your\nbundler or toolchain of choice.\n\nTo learn more about how to configure your specific toolchain to support this,\nread the documentation for configuration\n[here](https://github.com/carbon-design-system/carbon/blob/main/packages/styles/docs/sass.md#configuration).\nWe also have published a guide over on\n[Medium](https://medium.com/carbondesign/migrating-from-node-sass-to-sass-eba9db004a3a)\nto help out with common problems that come from this migration.\n\n\n\n \n \n\n \n\n\n \n \n\n \n\n\n\n### Step 3: Update style import paths\n\nNow, open your project's root stylesheet to make the following changes:\n\n```diff\n- @import 'carbon-components/scss/globals/scss/styles.scss';\n+ @use '@carbon/react';\n```\n\nIf you were providing any configuration options before you imported Carbon you\ncan now provide them using the `with` syntax:\n\n```scss\n@use '@carbon/react' with (\n $css--default-type: true,\n $css--reset: true\n);\n```\n\nIf you were using any feature flags in v10, you can safely remove them in v11.\n\nYou can also use @import to bring in Carbon, if you prefer, although @use is\nrecommended.\n\nFor cases where your projects does't need to include everything via\n`@use '@carbon/react'`; and just want to do individual component styles.\n\n```scss\n// Configure feature flags if needed, if not these\n// lines can be removed\n@use '@carbon/react/scss/config' with (\n $font-path: '@ibm/plex',\n $use-flexbox-grid: 'true'\n);\n\n// Emit the css reset\n@use '@carbon/react/scss/reset';\n\n// Emit the Plex font-face declarations\n@use '@carbon/react/scss/fonts';\n\n// Optional: emit the grid styles if using the grid.\n// This will emit the flex-grid styles if\n// $use-flexbox-grid is configured to 'true'\n@use '@carbon/react/scss/grid';\n\n// Emit the layer styles\n@use '@carbon/react/scss/layer';\n\n// Emit individual component styles\n@use '@carbon/react/scss/components/button';\n@use '@carbon/react/scss/components/tile';\n\n// Use additional local stylesheets\n@use 'sample-grid';\n```\n\nWhen migrating your custom components, some of our most used sass assets are\nincluded below, along with what you would need to have at the top of your file\nto use it. Essentially, all we are doing is including the path where we would\n[find these styles](https://github.com/carbon-design-system/carbon/tree/main/packages/react/scss)\nin our package.\n\n| Carbon sass I'm using | Sass modules to include |\n| ------------------------------- | -------------------------------------------------------- |\n| Type tokens | `@use '@carbon/react/scss/type' as *;` |\n| Theme tokens | `@use '@carbon/react/scss/theme' as *` |\n| Theme mixins | `@use '@carbon/react/scss/themes' as *` |\n| Design language color tokens | `@use '@carbon/react/scss/colors' as *` |\n| Spacing tokens | `@use '@carbon/react/scss/spacing' as *` |\n| Breakpoint mixins | `@use '@carbon/react/scss/breakpoint' as *` |\n| Motion tokens and functions | `@use '@carbon/react/scss/motion' as *` |\n| Rem and other convert functions | `@use '@carbon/react/scss/utilities/convert' as *` |\n| Z-index helper | `@use '@carbon/react/scss/utilities/z-index' as *` |\n| Focus outline helper | `@use '@carbon/react/scss/utilities/focus-outline' as *` |\n| Transform rotate helper | `@use '@carbon/react/scss/utilities/rotate' as *` |\n| Skeleton animation helper | `@use '@carbon/react/scss/utilities/skeleton' as *` |\n\nNow that you've migrated all of your imports, do a find/replace using your\nfavorite code editor. The prefix `carbon--` is no longer necessary. You can do a\nfind for `carbon--` and replace it with nothing to remove across all your files\nlike the example below. The full list of changes are available in our\n[Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#changing-import-paths-from-scssglobalsscss-to-scss).\n\n```diff\n- @include carbon--breakpoint(lg) {\n+ @include breakpoint(lg) {\n width: 42%;\n }\n```\n\nOnce you've removed the prefix, your styles should all be set using the old, v10\ntokens. We recommend teams install the community supported\n[stylelint-plugin-carbon-tokens](https://github.com/carbon-design-system/stylelint-plugin-carbon-tokens)\nto further assist in migrating your tokens to v11 tokens as the old v10 tokens\nwill be removed in our next major release.\n\n\n\n \n \n\n \n\n\n \n \n\n \n\n\n\n### Step 4: Updating component size props\n\nComponents with size variants have been updated to use the same API options.\nPreviously, the size options were inconsistent: `field`, `medium`, `short`. Now,\nsize options fall under the following values:\n\n| Prop value | Size |\n| ---------- | ---- |\n| `xs` | 24px |\n| `sm` | 32px |\n| `md` | 40px |\n| `lg` | 48px |\n| `xl` | 64px |\n| `2xl` | 80px |\n\n**Note:** the default size in v11 is `md` (`40px`).\n\nRun the following codemods to update the size prop across the effected\ncomponents in your project.\n\n```bash\nnpx @carbon/upgrade migrate small-to-size-prop --write\nnpx @carbon/upgrade migrate size-prop-update --write\n```\n\nBy running the series of codemods, they will do the following, in order:\n\n1. Removes the deprecated `small` boolean prop and replaces it with `size=\"sm\"`.\n2. Removes v10 size props and replaces them with v11 sizes props.\n\nIt's important to run the npx commands in the order that they are presented\nabove. Doing them out of order might result in the codemod not working as\nintended.\n\n\n\nFor full details, including options and commands availabe when using the\n`@carbon/upgrade` CLI, see the\n[package documentation](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade).\n\n\n\nThe following components all have size variants that may be affected in your\ncode. To update, you will need to switch to one of the size options listed\nabove. The codemod will make short work of these changes.\n\n- Accordion\n- Button\n- ComboBox\n- Dropdown\n- Multiselect\n- Filterable multiselect\n- ContentSwitcher\n- DataTable\n- DatePicker\n- FileUploader\n- FileUploaderItem\n- FileUploaderDropContainer\n- FileUploaderButton\n- Link\n- Modal\n- ComposedModal\n- NumberInput\n- OverflowMenu\n- Search\n- Select\n- Tag\n- TextInput\n- TimePicker\n- Toggle\n\n### Step 5: Update icon sizes and imports\n\nThe `@carbon/icons-react` package has been updated to minimize the number of\nexports from the package to help reduce build and compile times. This package is\navailable under `@carbon/react/icons`.\n\nThis update includes a change to the API of the icon components that come from\nthis package. Previously, we would export icons that included the size of the\nasset. This update allows you to bring the icon directly and specify the size\nusing the `size` prop.\n\nRun the following codemods to update your project's icons.\n\n```bash\nnpx @carbon/upgrade migrate icons-react-size-prop --write\nnpx @carbon/upgrade migrate update-carbon-icons-react-import-to-carbon-react --write\n```\n\nBy running the series of codemods, they will do the following, in order:\n\n1. Removes the size from the import and places it on the icon directly.\n2. Remove the `@carbon/icons-react` pathing and replace it with\n `@carbon/react/icons`.\n\nIt's important to run the npx commands in the order that they are presented\nabove. Doing them out of order might result in the codemod not working as\nintended.\n\n\n\nFor full details, including options and commands availabe when using the\n`@carbon/upgrade` CLI, see the\n[package documentation](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade).\n\n\n\nAfter running the command, instead of your icons imports looking like this:\n\n**Before**\n\n```jsx\nimport { Add32, Add24, Add20, Add16 } from '@carbon/icons-react';\n\nfunction MyComponent() {\n return (\n <>\n \n \n \n \n \n );\n}\n```\n\nThey should start looking like this:\n\n**After**\n\n```jsx\nimport { Add } from '@carbon/react/icons';\n\nfunction MyComponent() {\n return (\n <>\n \n \n \n \n \n );\n}\n```\n\n#### Removed icons\n\nThe following deprecated icons have been removed. Use the table below to find\ntheir replacement, if available, in v11.\n\n| Asset | v10 | v11 |\n| :------------------------------ | :-------------------------- | :-------------------------- |\n| app-switcher | AppSwitcher | Switcher |\n| arrows | Arrows | ArrowsVertical |\n| back-to-top | BackToTop | UpToTop |\n| checkbox--undeterminate | CheckboxUndeterminate | CheckboxIndeterminate |\n| checkbox--undeterminate--filled | CheckboxUndeterminateFilled | CheckboxIndeterminateFilled |\n| cloud--lightning | CloudLightning | Removed |\n| cloud--rain | CloudRain | Removed |\n| cloud--snow | CloudSnow | Removed |\n| delete | Delete | TrashCan |\n| edit-filter | EditFilter | FilterEdit |\n| sunny | Sunny | Removed |\n| research--bloch-sphere | ResearchBlockSphere | BlochSphere |\n| research--hinton-plot | ResearchHintonPlot | HintonPlot |\n| research--matrix | ResearchMatrix | Matrix |\n| misuse--alt | MisuseAlt | MisuseOutline |\n| logo--google | LogoGoogle | Removed |\n| mammogram--stacked | MammogramStacked | Removed |\n| logo--delicious | LogoDelicious | Removed |\n| logo--stumbleupon | LogoStumbleUpon | Removed |\n| letter--Aa--large | LetterAaLarge | TextFont |\n| glyph--caution-inverted | GlyphCautionInverted | CautionInverted |\n| glyph--caution | GlyphCaution | Caution |\n| glyph--circle-fill | GlyphCircleFill | CircleFill |\n| glyph--circle-stroke | GlyphCircleStroke | CircleStroke |\n| glyph--critical | GlyphCritical | Critical |\n| glyph--incomplete | GlyphIncomplete | Incomplete |\n| glyph--square-fill | GlyphSquareFill | SquareFill |\n| glyph--undefined | GlyphUndefined | Undefined |\n\nHowever, in certain situations, we will be unable to infer what the correct\nupdate should be for a certain usage of the icon component. We have written the\ncodemod to work for most situations, but you will see console warnings for files\nthat will require you to manually review them to make sure the transforms were\napplied correctly.\n\nThe most common manual update that teams will need to make is if a `prop` where\nthe icon is passed to places a `ref` on the icon. For example,\n\n```jsx\nfunction MyComponent({ renderIcon: Icon }) {\n const ref = useRef(null);\n return ;\n}\n\n// Before\n\n\n// After the codemod\n} />\n```\n\nIn this situation, you will need to update your code to use `React.forwardRef`:\n\n```jsx\n (\n \n ))}\n/>;\n\n// Or, alternatively:\nconst Search16 = React.forwardRef((props, ref) => {\n return ;\n});\n\n;\n```\n\n#### Manual migration\n\nIn addition to the automated codemods above, there are several patterns in your\ncodebase that you will need to update manually:\n\n- If you use the name `ForwardRef(IconName16)` in a test you will need to\n manually change this. Prefer to use the component directly if using enzyme\n- If you use snapshot tests, the structure will change and include a `size`\n prop. Make sure that the `size` prop value matches what your icon name used to\n be. For example, `` should become ``\n\n### Step 6: Update components that have changed\n\nIn v11, we have updated the APIs of certain components in one of the following\nways:\n\n- Update `className` usage to be applied to the outermost element of a component\n- Remove props that have been deprecated in v10\n- Refactor the API to ship an accessible component\n\nFor a full list of changes to components, check out our\n[Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbon-components-react).\nBelow are some common changes that may impact you and your usage of Carbon.\n\n#### Changes to `className`\n\nThe usage of `className` prop has been updated so that the class is passed to\nthe outermost element of a component's inner markup. This was already the case\nfor most components and this change brings along the remaining components in the\nlibrary to this convention.\n\nThe following components previously were not applying the `className` prop to\nthe outermost element. If you were using a custom `className` to target an inner\nelement for any of these components, you will have to update your selectors to\nnow account for the `className` being placed on the outermost element.\n\n- Checkbox\n- ComboBox\n- Table\n- TableToolbar\n- DataTableSkeleton\n- DatePicker\n- DatePickerSkeleton\n- DatePickerInput\n- Dropdown\n- FileUploaderDropContainer\n- FileUploaderItem\n- FormGroup\n- FilterableMultiSelect\n- MultiSelect\n- NotificationTextDetails\n- NotificationIcon\n- NumberInput\n- OverflowMenuItem\n- RadioButtonGroup\n- RadioTile\n- Select\n- Slider\n- Switch\n- TextArea\n- ControlledPasswordInput\n- PasswordInput\n- TextInput\n- TimePicker\n- Tooltip\n- HeaderContainer\n\n#### Notification\n\nWe have updated the notification components to be more accessible out of the\nbox. `ToastNotification` and `InlineNotification` now have `role=\"status\"` by\ndefault with additional `role` options of `log` and `alert`. These components do\nnot receive focus and should be used for information-only use cases. These\ncomponents no longer accept actions or interactive children.\n\nFor notifications requiring an action, a new `ActionableNotifiation` component\nis available. It has a `role=\"alertdialog\"` and recieves focus by default.\nAutomatic placement of focus can be turned off via the new `hasFocus` prop.\n\nAll notifications have a new optional `closeOnEscape` prop, it enables\nnotifications to closed by pressing the `escape` key. For more details, see the\n[notification components accessibility page](https://www.carbondesignsystem.com/components/notification/accessibility).\n\n#### Update `ToastNotification` usage\n\n- `children` can no longer contain interactive elements. A `ToastNotification`\n containing an action or interactive children should be replaced with\n `ActionableNotification`.\n- The `notificationType` prop is no longer needed and can be removed.\n- The default `role` is now `status`. `log` and `alert` can also be used.\n- The `closeOnEscape` prop toggles the closing of notifications via the `escape`\n key.\n\n#### Update `InlineNotification` usage\n\n- The `actions` prop has been removed. An `InlineNotification` containing an\n action or interactive children should be replaced with\n `ActionableNotification` configured with the `inline` prop.\n- `children` can no longer contain interactive elements.\n- The `notificationType` prop is no longer needed and can be removed.\n- The default `role` is now `status`. `log` and `alert` can also be used.\n- The `closeOnEscape` prop toggles the closing of notifications via the `escape`\n key.\n\n#### When using `ActionableNotification`:\n\n- The `inline` prop enables a styling variation resulting in a similar visual\n design to `InlineNotification`.\n- The `actionButtonLabel` prop configures the action button text.\n- The `hasFocus` prop toggles the automatic placement of focus.\n- The `closeOnEscape` prop toggles the closing of notifications via the `escape`\n key.\n\n#### Tabs\n\nTabs have been updated to be more composable so that you have the flexibity and\ncontrol to make them look and act how you want.\n\nIn v10, you may have code that looks like the following:\n\n```js\n\n \n
Content for first tab goes here.
\n \n \n
Content for second tab goes here.
\n \n \n
Content for third tab goes here.
\n \n \n
Content for fourth tab goes here.
\n \n\n```\n\nThose same Tabs, migrated to v11:\n\n```js\n\n \n Tab Label 1\n Tab Label 2\n Tab Label 3\n Tab Label 4 shows truncation\n \n \n Content for first tab goes here.\n Content for second tab goes here.\n Content for third tab goes here.\n Content for fourth tab goes here.\n \n\n```\n\n#### Update `Tabs` and `Tab` usage\n\nAll the same functionality for Tabs is available in v11 and more! However, some\nprops have been deprecated because they have either been renamed or are no\nlonger needed. Below are the minor tweaks in naming or implementation.\n\n- the `type` prop is deprecated. Both \"contained\" and \"default\" tabs still exist\n but now can be called by adding the prop `contained` to the `TabList`.\n- Default tabs are now referred to as line tabs in our documentation here and in\n our storybook.\n- `hidden` prop is no longer needed with the new composable Tabs. You have\n control over tab content and when it is hidden through the `TabPanel` and\n `TabPanels` components.\n- `selected` prop is now named `selectedIndex`.\n- `tabContentClassName` is no longer needed. `TabPanel` (equivalent to tab\n content) takes in a className prop on its outermost node.\n- For `Tab`, `label` is no longer needed. `children` of `Tab` are now the label.\n- Due to its composability, `renderAnchor`, `renderButton`, `renderContent` are\n no longer needed on `Tab`. You now have full control over what is rendered\n inside of `Tab` and `TabPanel`.\n- Because `renderButton` is no longer needed, the associated `tabIndex` prop has\n also been deprecated.\n- `selected` on `Tab` is deprecated in favor or `selectedIndex`, now placed on\n `Tabs` instead.\n\nFor more details about the changes to Tabs, see our storybook documentation\n[here](https://react.carbondesignsystem.com/?path=/docs/components-tabs--default).\n\n### Step 7: Done with @carbon/react!\n\nAnd that's it! You're done. At this point you have migrated to use Carbon v11\nusing the `@carbon/react` package.\n\nIf you run into any problems after this point, please feel free to reach out to\nus over on Slack or open up a discussion on\n[GitHub](https://github.com/carbon-design-system/carbon/discussions/categories/help).\nWe want to make this migration experience as seamless as possible and will be\nmonitoring both areas to help out.\n\n## Migrating an app or library using just styles\n\nStarting in v11, the styles for Carbon live in the `@carbon/styles` package.\nAlternatively, you can continue to use `carbon-components` as it re-exports\nstyles from this package directly.\n\nFor teams using Svelte, Angular, Vue, LWC, or Web Components, please\n[review the documention](https://carbondesignsystem.com/developing/frameworks/web-components),\nfor those respective frameworks before making the migration to v11.\n\n### Step 1: Install @carbon/styles\n\nTo get started, uninstall `carbon-components` from your project:\n\n```bash\nnpm uninstall carbon-components\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn remove carbon-components\n```\n\nNext, install the `@carbon/styles` package:\n\n```bash\nnpm install @carbon/styles\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn add @carbon/styles\n```\n\n### Step 2: Install and configure Dart Sass\n\nPreviously, `carbon-components` supported being compiled by different Sass\nlibraries. Starting in v11, the `@carbon/styles` package requires Dart Sass\nthrough the `sass` package in order to compile. This change comes from our\nmigration to Sass Modules in order to improve our compilation times and overall\nproject structure.\n\nIf you don't have this dependency already in your project, you can install it:\n\n```bash\nnpm install sass\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn add sass\n```\n\nSimilarly, if you currently use `node-sass` now is a good time to remove that\ndependency from your project. In most situations, Dart Sass is a drop-in\nreplacement for `node-sass` and should require no changes on your end in order\nto use it once you install the dependency.\n\nOne you have Dart Sass installed, it's important that you configure your project\nto support resolving imports in Sass from `node_modules`. Typically, this means\nadding `node_modules` to your `includePaths` config for Sass in your bundler or\ntoolchain of choice.\n\nTo learn more about how to configure your specific toolchain to support this,\nread the documentation for configuration\n[here](https://github.com/carbon-design-system/carbon/blob/main/packages/styles/docs/sass.md#configuration).\nWe also have published a guide over on\n[Medium](https://medium.com/carbondesign/migrating-from-node-sass-to-sass-eba9db004a3a)\nto help out with common problems that come from this migration.\n\n\n\n \n \n\n \n\n\n \n \n\n \n\n\n\n### Step 3: Update import paths and tokens\n\nNow, open your project's root stylesheet to make the following changes:\n\n```diff\n- @import 'carbon-components/scss/globals/scss/styles.scss';\n+ @use '@carbon/styles';\n```\n\nIf you were providing any configuration options before you imported Carbon you\ncan now provide them using the `with` syntax:\n\n```scss\n@use '@carbon/styles' with (\n $css--default-type: true,\n $css--reset: true\n);\n```\n\nFor cases where your projects does't need to include everything via\n`@use '@carbon/styles'`; and just want to do individual component styles.\n\n```scss\n// configure feature flags if needed, if not this line can be removed\n@use '@carbon/styles/scss/config' with (\n $font-path: '@ibm/plex'\n);\n\n// ensure the css reset is included\n@use '@carbon/styles/scss/reset';\n\n// add styles for components individually\n@use '@carbon/styles/scss/components/button';\n```\n\nWhen migrating your custom components, some of our most used sass assets are\nincluded below, along with what you would need to have at the top of your file\nto use it. Essentially, all we are doing is including the path where we would\n[find these styles](https://github.com/carbon-design-system/carbon/tree/main/packages/styles/scss)\nin our package.\n\n| Carbon sass I'm using | Sass modules to include |\n| ------------------------------- | --------------------------------------------------------- |\n| Theme tokens | `@use '@carbon/styles/scss/theme' as *` |\n| Theme mixins | `@use '@carbon/styles/scss/themes' as *` |\n| Design language color tokens | `@use '@carbon/styles/scss/colors' as *` |\n| Spacing tokens | `@use '@carbon/styles/scss/spacing' as *` |\n| Breakpoint mixins | `@use '@carbon/styles/scss/breakpoint' as *` |\n| Motion tokens and functions | `@use '@carbon/styles/scss/motion' as *` |\n| Rem and other convert functions | `@use '@carbon/styles/scss/utilities/convert' as *` |\n| Z-index helper | `@use '@carbon/styles/scss/utilities/z-index' as *` |\n| Focus outline helper | `@use '@carbon/styles/scss/utilities/focus-outline' as *` |\n| Transform rotate helper | `@use '@carbon/styles/scss/utilities/rotate' as *` |\n| Skeleton animation helper | `@use '@carbon/styles/scss/utilities/skeleton' as *` |\n\nNow that you've migrated all of your imports, do a find/replace using your\nfavorite code editor. The prefix`carbon--` is no longer necessary. You can do a\nfind for `carbon--` and replace it with nothing to remove across all your files\nlike the example below. The full list of changes are available in our\n[Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#changing-import-paths-from-scssglobalsscss-to-scss).\n\n```diff\n- @include carbon--breakpoint(lg) {\n+ @include breakpoint(lg) {\n width: 42%;\n }\n```\n\nOnce you've removed the prefix, your styles should all be set using the old, v10\ntokens. We recommend teams install the community supported\n[stylelint-plugin-carbon-tokens](https://github.com/carbon-design-system/stylelint-plugin-carbon-tokens)\nto further assist in migrating your tokens to v11 tokens as the old v10 tokens\nwill be removed in our next major release.\n\n\n\n \n \n\n \n\n\n \n \n\n \n\n\n\n### Step 4: Update bx to cds\n\nIf you are targeting specific selectors that use the `bx` prefix, you will need\nto update your code to either target the `cds` prefix for selectors or update\nCarbon's configuration to use `bx` as the prefix by writing the following:\n\n```scss\n// Option A\n@use '@carbon/styles' with (\n $prefix: 'bx'\n);\n// Option B\n@use '@carbon/styles/scss/config' with (\n $prefix: 'bx'\n);\n```\n\n### Step 5: Enable flexbox grid\n\nIf you are using the flexbox-based grid in your project, you can continue to use\nthis feature in v11 by importing the following:\n\n```scss\n@use '@carbon/styles/scss/grid/flexbox';\n```\n\nThis is important due to the fact that the CSS Grid implementation is used by\ndefault in v11. However, bringing in the flexbox grid styles in this way means\nthat your layouts will continue to work the same as in v10.\n\n### Step 6: Done with @carbon/styles!\n\nAnd that's it! You're done. At this point you have migrated to use Carbon v11\nusing the `@carbon/styles` package.\n\nIf you run into any problems after this point, please feel free to reach out to\nus over on Slack or open up a discussion on\n[GitHub](https://github.com/carbon-design-system/carbon/discussions/categories/help).\nWe want to make this migration experience as seamless as possible and will be\nmonitoring both areas to help out.\n\n## Migrating carbon-icons\n\nThe `carbon-icons` package has been deprecated and is no longer supported. To\nuse icons from the Carbon Design System, you should install the appropriate\nlibrary to use with your framework:\n\n| Package | Framework | Link |\n| :---------------------- | :----------------- | :------------------------------------------------------ |\n| `@carbon/icons-react` | React | [Link](https://npmjs.com/package/@carbon/icons-react) |\n| `@carbon/icons-angular` | Angular | [Link](https://npmjs.com/package/@carbon/icons-angular) |\n| `@carbon/icons-vue` | Vue | [Link](https://npmjs.com/package/@carbon/icons-vue) |\n| `carbon-icons-svelte` | Svelte | [Link](https://npmjs.com/package/carbon-icons-svelte) |\n| `@carbon/icons` | Vanilla JavaScript | [Link](https://npmjs.com/package/@carbon/icons) |\n\nIf you are using `@carbon/react`, you can directly import icons from\n`@carbon/react/icons`.\n\n## Migrating Carbon elements\n\nThe packages that we ship for the IBM Design Language have been updated in v11.\nThe most notable change is that these packages now require Dart Sass in order to\ncompile as they now use Sass Modules to improve compilation times.\n\nIf you were directly importing from one of these element packages, consider\nimporting from either `@carbon/styles` or `@carbon/react` instead. Both of these\npackages provide entrypoints for elements packages on top of the styles for\nCarbon itself.\n\nFor teams using these packages directly, you will need to update each of the\nelements packages you're using to the latest version.\n\n```bash\nnpm install @carbon/@latest\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn upgrade @carbon/@latest\n```\n\nAfterwards, you will need to update the import paths and import names themselves\nthat you bring in. In general, each package now supports importing from the\npackage directly and all `carbon--` prefixed variables, mixins, and functions\nhave been renamed to remove the prefix.\n\nFor full details fo the changes to each elements package, check out the links\nbelow.\n\n| Package | Migration Docs |\n| :----------------- | :---------------------------------------------------------------------------------------------------- |\n| `@carbon/colors` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carboncolors) |\n| `@carbon/elements` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbonelements) |\n| `@carbon/grid` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbongrid) |\n| `@carbon/layout` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbonlayout) |\n| `@carbon/motion` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbonmotion) |\n| `@carbon/themes` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbonthemes) |\n| `@carbon/type` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbontype) |\n\nIf you were previously using the `@carbon/import-once` package, you can continue\nto use this in v11. However, this package will receive no further updates after\nCarbon switched to using Sass Modules.\n","type":"Mdx","contentDigest":"179a69c16a51c4f022f75ae4b43e443a","owner":"gatsby-plugin-mdx","counter":5330},"frontmatter":{"title":"Guide","description":"This guide includes everything you need to migrate your offering from v10 to v11 of Carbon.","tabs":["Overview","Design","Develop"]},"exports":{},"rawBody":"---\ntitle: Guide\ndescription:\n This guide includes everything you need to migrate your offering from v10 to\n v11 of Carbon.\ntabs: ['Overview', 'Design', 'Develop']\n---\n\nimport { Tag } from '@carbon/react';\n\n\n\nStep-by-step guide to updating your code from Carbon v10 to v11.\n\n\n\n\n\nOverview\nMigrating a React app or library\nMigrating an app or library using just styles\nMigrating carbon-icons\nMigrating Carbon elements\n\n\n\n## Overview\n\nThis guide helps you update your project to Carbon v11. It is broken into\nsections based on how you are using Carbon in your project today. For most teams\nusing Carbon, you'll want to use the\n[Migrating a React app](#migrating-a-react-app) section.\n\nOne of the biggest changes to Carbon in v11 is that we moved to dedicated\npackages under the `@carbon` scope. What this means for you is that if you were\npreviously using the following packages:\n\n- `carbon-components`\n- `carbon-components-react`\n- `carbon-icons`\n- `@carbon/icons-react`\n\nYou can access all of this work under one single package: `@carbon/react`. This\npackage will re-export all of the styles and icons for Carbon all in one\ndependency.\n\nIf you were previously using `carbon-components`, the styles from this package\nare available under `@carbon/styles`. They are also re-exported through\n`@carbon/react`\n\nBoth the `carbon-components` and `carbon-components-react` packages will stick\naround in v11 but they are only re-exports of `@carbon/styles` and\n`@carbon/react` respectively.\n\n## Migrating a React app or library\n\nStarting in v11, the React components for Carbon live in the `@carbon/react`\npackage.\n\nThe `@carbon/react` package also includes the styles for Carbon along with\nicons.\n\n### Step 1: Install @carbon/react\n\nTo get started, uninstall the following packages if they exist in your project:\n\n- `carbon-components`\n- `carbon-components-react`\n- `carbon-icons`\n- `@carbon/icons-react`\n\n```bash\nnpm uninstall carbon-components carbon-components-react carbon-icons @carbon/icons-react\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn remove carbon-components carbon-components-react carbon-icons @carbon/icons-react\n```\n\nNext, install the `@carbon/react` package:\n\n```bash\nnpm install @carbon/react\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn add @carbon/react\n```\n\nNow that you've removed the old packages and brought in the new ones, run the\ncodemod below to fix your pathing.\n\n```bash\nnpx @carbon/upgrade migrate update-carbon-components-react-import-to-scoped --write\n```\n\nAfter running the command, your code should start looking like this:\n\n```jsx\n// Before\nimport { Accordion, AccordionItem } from 'carbon-components-react';\n// After\nimport { Accordion, AccordionItem } from '@carbon/react';\n```\n\n\n\nFor full details, including options and commands availabe when using the\n`@carbon/upgrade` CLI, see the\n[package documentation](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade).\n\n\n\n### Step 2: Install Dart Sass\n\nIf you were previously importing styles from `carbon-components`, you can now\nimport styles directly from `@carbon/react` or the `@carbon/react/scss` folder.\n\nBefore you're able to bring in these styles, you'll need to make sure your\nproject is setup to use Dart Sass. Starting in v11, Carbon styles requires Dart\nSass through the `sass` package in order to compile. This change comes from our\nmigration to Sass Modules in order to improve our compilation times and overall\nproject structure.\n\nFirst, let's remove `node-sass` from your project. If you don't have\n`node-sass`, no worries, just skip down and begin adding `sass`.\n\n```bash\nnpm uninstall node-sass\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn remove node-sass\n```\n\nNow, let's install `sass`:\n\n```bash\nnpm install sass --save-dev\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn add sass --dev\n```\n\nOnce you have Dart Sass installed, it's important that you configure your\nproject to support resolving imports in Sass from `node_modules`. Typically,\nthis means adding `node_modules` to your `includePaths` config for Sass in your\nbundler or toolchain of choice.\n\nTo learn more about how to configure your specific toolchain to support this,\nread the documentation for configuration\n[here](https://github.com/carbon-design-system/carbon/blob/main/packages/styles/docs/sass.md#configuration).\nWe also have published a guide over on\n[Medium](https://medium.com/carbondesign/migrating-from-node-sass-to-sass-eba9db004a3a)\nto help out with common problems that come from this migration.\n\n\n\n \n \n\n \n\n\n \n \n\n \n\n\n\n### Step 3: Update style import paths\n\nNow, open your project's root stylesheet to make the following changes:\n\n```diff\n- @import 'carbon-components/scss/globals/scss/styles.scss';\n+ @use '@carbon/react';\n```\n\nIf you were providing any configuration options before you imported Carbon you\ncan now provide them using the `with` syntax:\n\n```scss\n@use '@carbon/react' with (\n $css--default-type: true,\n $css--reset: true\n);\n```\n\nIf you were using any feature flags in v10, you can safely remove them in v11.\n\nYou can also use @import to bring in Carbon, if you prefer, although @use is\nrecommended.\n\nFor cases where your projects does't need to include everything via\n`@use '@carbon/react'`; and just want to do individual component styles.\n\n```scss\n// Configure feature flags if needed, if not these\n// lines can be removed\n@use '@carbon/react/scss/config' with (\n $font-path: '@ibm/plex',\n $use-flexbox-grid: 'true'\n);\n\n// Emit the css reset\n@use '@carbon/react/scss/reset';\n\n// Emit the Plex font-face declarations\n@use '@carbon/react/scss/fonts';\n\n// Optional: emit the grid styles if using the grid.\n// This will emit the flex-grid styles if\n// $use-flexbox-grid is configured to 'true'\n@use '@carbon/react/scss/grid';\n\n// Emit the layer styles\n@use '@carbon/react/scss/layer';\n\n// Emit individual component styles\n@use '@carbon/react/scss/components/button';\n@use '@carbon/react/scss/components/tile';\n\n// Use additional local stylesheets\n@use 'sample-grid';\n```\n\nWhen migrating your custom components, some of our most used sass assets are\nincluded below, along with what you would need to have at the top of your file\nto use it. Essentially, all we are doing is including the path where we would\n[find these styles](https://github.com/carbon-design-system/carbon/tree/main/packages/react/scss)\nin our package.\n\n| Carbon sass I'm using | Sass modules to include |\n| ------------------------------- | -------------------------------------------------------- |\n| Type tokens | `@use '@carbon/react/scss/type' as *;` |\n| Theme tokens | `@use '@carbon/react/scss/theme' as *` |\n| Theme mixins | `@use '@carbon/react/scss/themes' as *` |\n| Design language color tokens | `@use '@carbon/react/scss/colors' as *` |\n| Spacing tokens | `@use '@carbon/react/scss/spacing' as *` |\n| Breakpoint mixins | `@use '@carbon/react/scss/breakpoint' as *` |\n| Motion tokens and functions | `@use '@carbon/react/scss/motion' as *` |\n| Rem and other convert functions | `@use '@carbon/react/scss/utilities/convert' as *` |\n| Z-index helper | `@use '@carbon/react/scss/utilities/z-index' as *` |\n| Focus outline helper | `@use '@carbon/react/scss/utilities/focus-outline' as *` |\n| Transform rotate helper | `@use '@carbon/react/scss/utilities/rotate' as *` |\n| Skeleton animation helper | `@use '@carbon/react/scss/utilities/skeleton' as *` |\n\nNow that you've migrated all of your imports, do a find/replace using your\nfavorite code editor. The prefix `carbon--` is no longer necessary. You can do a\nfind for `carbon--` and replace it with nothing to remove across all your files\nlike the example below. The full list of changes are available in our\n[Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#changing-import-paths-from-scssglobalsscss-to-scss).\n\n```diff\n- @include carbon--breakpoint(lg) {\n+ @include breakpoint(lg) {\n width: 42%;\n }\n```\n\nOnce you've removed the prefix, your styles should all be set using the old, v10\ntokens. We recommend teams install the community supported\n[stylelint-plugin-carbon-tokens](https://github.com/carbon-design-system/stylelint-plugin-carbon-tokens)\nto further assist in migrating your tokens to v11 tokens as the old v10 tokens\nwill be removed in our next major release.\n\n\n\n \n \n\n \n\n\n \n \n\n \n\n\n\n### Step 4: Updating component size props\n\nComponents with size variants have been updated to use the same API options.\nPreviously, the size options were inconsistent: `field`, `medium`, `short`. Now,\nsize options fall under the following values:\n\n| Prop value | Size |\n| ---------- | ---- |\n| `xs` | 24px |\n| `sm` | 32px |\n| `md` | 40px |\n| `lg` | 48px |\n| `xl` | 64px |\n| `2xl` | 80px |\n\n**Note:** the default size in v11 is `md` (`40px`).\n\nRun the following codemods to update the size prop across the effected\ncomponents in your project.\n\n```bash\nnpx @carbon/upgrade migrate small-to-size-prop --write\nnpx @carbon/upgrade migrate size-prop-update --write\n```\n\nBy running the series of codemods, they will do the following, in order:\n\n1. Removes the deprecated `small` boolean prop and replaces it with `size=\"sm\"`.\n2. Removes v10 size props and replaces them with v11 sizes props.\n\nIt's important to run the npx commands in the order that they are presented\nabove. Doing them out of order might result in the codemod not working as\nintended.\n\n\n\nFor full details, including options and commands availabe when using the\n`@carbon/upgrade` CLI, see the\n[package documentation](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade).\n\n\n\nThe following components all have size variants that may be affected in your\ncode. To update, you will need to switch to one of the size options listed\nabove. The codemod will make short work of these changes.\n\n- Accordion\n- Button\n- ComboBox\n- Dropdown\n- Multiselect\n- Filterable multiselect\n- ContentSwitcher\n- DataTable\n- DatePicker\n- FileUploader\n- FileUploaderItem\n- FileUploaderDropContainer\n- FileUploaderButton\n- Link\n- Modal\n- ComposedModal\n- NumberInput\n- OverflowMenu\n- Search\n- Select\n- Tag\n- TextInput\n- TimePicker\n- Toggle\n\n### Step 5: Update icon sizes and imports\n\nThe `@carbon/icons-react` package has been updated to minimize the number of\nexports from the package to help reduce build and compile times. This package is\navailable under `@carbon/react/icons`.\n\nThis update includes a change to the API of the icon components that come from\nthis package. Previously, we would export icons that included the size of the\nasset. This update allows you to bring the icon directly and specify the size\nusing the `size` prop.\n\nRun the following codemods to update your project's icons.\n\n```bash\nnpx @carbon/upgrade migrate icons-react-size-prop --write\nnpx @carbon/upgrade migrate update-carbon-icons-react-import-to-carbon-react --write\n```\n\nBy running the series of codemods, they will do the following, in order:\n\n1. Removes the size from the import and places it on the icon directly.\n2. Remove the `@carbon/icons-react` pathing and replace it with\n `@carbon/react/icons`.\n\nIt's important to run the npx commands in the order that they are presented\nabove. Doing them out of order might result in the codemod not working as\nintended.\n\n\n\nFor full details, including options and commands availabe when using the\n`@carbon/upgrade` CLI, see the\n[package documentation](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade).\n\n\n\nAfter running the command, instead of your icons imports looking like this:\n\n**Before**\n\n```jsx\nimport { Add32, Add24, Add20, Add16 } from '@carbon/icons-react';\n\nfunction MyComponent() {\n return (\n <>\n \n \n \n \n \n );\n}\n```\n\nThey should start looking like this:\n\n**After**\n\n```jsx\nimport { Add } from '@carbon/react/icons';\n\nfunction MyComponent() {\n return (\n <>\n \n \n \n \n \n );\n}\n```\n\n#### Removed icons\n\nThe following deprecated icons have been removed. Use the table below to find\ntheir replacement, if available, in v11.\n\n| Asset | v10 | v11 |\n| :------------------------------ | :-------------------------- | :-------------------------- |\n| app-switcher | AppSwitcher | Switcher |\n| arrows | Arrows | ArrowsVertical |\n| back-to-top | BackToTop | UpToTop |\n| checkbox--undeterminate | CheckboxUndeterminate | CheckboxIndeterminate |\n| checkbox--undeterminate--filled | CheckboxUndeterminateFilled | CheckboxIndeterminateFilled |\n| cloud--lightning | CloudLightning | Removed |\n| cloud--rain | CloudRain | Removed |\n| cloud--snow | CloudSnow | Removed |\n| delete | Delete | TrashCan |\n| edit-filter | EditFilter | FilterEdit |\n| sunny | Sunny | Removed |\n| research--bloch-sphere | ResearchBlockSphere | BlochSphere |\n| research--hinton-plot | ResearchHintonPlot | HintonPlot |\n| research--matrix | ResearchMatrix | Matrix |\n| misuse--alt | MisuseAlt | MisuseOutline |\n| logo--google | LogoGoogle | Removed |\n| mammogram--stacked | MammogramStacked | Removed |\n| logo--delicious | LogoDelicious | Removed |\n| logo--stumbleupon | LogoStumbleUpon | Removed |\n| letter--Aa--large | LetterAaLarge | TextFont |\n| glyph--caution-inverted | GlyphCautionInverted | CautionInverted |\n| glyph--caution | GlyphCaution | Caution |\n| glyph--circle-fill | GlyphCircleFill | CircleFill |\n| glyph--circle-stroke | GlyphCircleStroke | CircleStroke |\n| glyph--critical | GlyphCritical | Critical |\n| glyph--incomplete | GlyphIncomplete | Incomplete |\n| glyph--square-fill | GlyphSquareFill | SquareFill |\n| glyph--undefined | GlyphUndefined | Undefined |\n\nHowever, in certain situations, we will be unable to infer what the correct\nupdate should be for a certain usage of the icon component. We have written the\ncodemod to work for most situations, but you will see console warnings for files\nthat will require you to manually review them to make sure the transforms were\napplied correctly.\n\nThe most common manual update that teams will need to make is if a `prop` where\nthe icon is passed to places a `ref` on the icon. For example,\n\n```jsx\nfunction MyComponent({ renderIcon: Icon }) {\n const ref = useRef(null);\n return ;\n}\n\n// Before\n\n\n// After the codemod\n} />\n```\n\nIn this situation, you will need to update your code to use `React.forwardRef`:\n\n```jsx\n (\n \n ))}\n/>;\n\n// Or, alternatively:\nconst Search16 = React.forwardRef((props, ref) => {\n return ;\n});\n\n;\n```\n\n#### Manual migration\n\nIn addition to the automated codemods above, there are several patterns in your\ncodebase that you will need to update manually:\n\n- If you use the name `ForwardRef(IconName16)` in a test you will need to\n manually change this. Prefer to use the component directly if using enzyme\n- If you use snapshot tests, the structure will change and include a `size`\n prop. Make sure that the `size` prop value matches what your icon name used to\n be. For example, `` should become ``\n\n### Step 6: Update components that have changed\n\nIn v11, we have updated the APIs of certain components in one of the following\nways:\n\n- Update `className` usage to be applied to the outermost element of a component\n- Remove props that have been deprecated in v10\n- Refactor the API to ship an accessible component\n\nFor a full list of changes to components, check out our\n[Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbon-components-react).\nBelow are some common changes that may impact you and your usage of Carbon.\n\n#### Changes to `className`\n\nThe usage of `className` prop has been updated so that the class is passed to\nthe outermost element of a component's inner markup. This was already the case\nfor most components and this change brings along the remaining components in the\nlibrary to this convention.\n\nThe following components previously were not applying the `className` prop to\nthe outermost element. If you were using a custom `className` to target an inner\nelement for any of these components, you will have to update your selectors to\nnow account for the `className` being placed on the outermost element.\n\n- Checkbox\n- ComboBox\n- Table\n- TableToolbar\n- DataTableSkeleton\n- DatePicker\n- DatePickerSkeleton\n- DatePickerInput\n- Dropdown\n- FileUploaderDropContainer\n- FileUploaderItem\n- FormGroup\n- FilterableMultiSelect\n- MultiSelect\n- NotificationTextDetails\n- NotificationIcon\n- NumberInput\n- OverflowMenuItem\n- RadioButtonGroup\n- RadioTile\n- Select\n- Slider\n- Switch\n- TextArea\n- ControlledPasswordInput\n- PasswordInput\n- TextInput\n- TimePicker\n- Tooltip\n- HeaderContainer\n\n#### Notification\n\nWe have updated the notification components to be more accessible out of the\nbox. `ToastNotification` and `InlineNotification` now have `role=\"status\"` by\ndefault with additional `role` options of `log` and `alert`. These components do\nnot receive focus and should be used for information-only use cases. These\ncomponents no longer accept actions or interactive children.\n\nFor notifications requiring an action, a new `ActionableNotifiation` component\nis available. It has a `role=\"alertdialog\"` and recieves focus by default.\nAutomatic placement of focus can be turned off via the new `hasFocus` prop.\n\nAll notifications have a new optional `closeOnEscape` prop, it enables\nnotifications to closed by pressing the `escape` key. For more details, see the\n[notification components accessibility page](https://www.carbondesignsystem.com/components/notification/accessibility).\n\n#### Update `ToastNotification` usage\n\n- `children` can no longer contain interactive elements. A `ToastNotification`\n containing an action or interactive children should be replaced with\n `ActionableNotification`.\n- The `notificationType` prop is no longer needed and can be removed.\n- The default `role` is now `status`. `log` and `alert` can also be used.\n- The `closeOnEscape` prop toggles the closing of notifications via the `escape`\n key.\n\n#### Update `InlineNotification` usage\n\n- The `actions` prop has been removed. An `InlineNotification` containing an\n action or interactive children should be replaced with\n `ActionableNotification` configured with the `inline` prop.\n- `children` can no longer contain interactive elements.\n- The `notificationType` prop is no longer needed and can be removed.\n- The default `role` is now `status`. `log` and `alert` can also be used.\n- The `closeOnEscape` prop toggles the closing of notifications via the `escape`\n key.\n\n#### When using `ActionableNotification`:\n\n- The `inline` prop enables a styling variation resulting in a similar visual\n design to `InlineNotification`.\n- The `actionButtonLabel` prop configures the action button text.\n- The `hasFocus` prop toggles the automatic placement of focus.\n- The `closeOnEscape` prop toggles the closing of notifications via the `escape`\n key.\n\n#### Tabs\n\nTabs have been updated to be more composable so that you have the flexibity and\ncontrol to make them look and act how you want.\n\nIn v10, you may have code that looks like the following:\n\n```js\n\n \n
Content for first tab goes here.
\n \n \n
Content for second tab goes here.
\n \n \n
Content for third tab goes here.
\n \n \n
Content for fourth tab goes here.
\n \n\n```\n\nThose same Tabs, migrated to v11:\n\n```js\n\n \n Tab Label 1\n Tab Label 2\n Tab Label 3\n Tab Label 4 shows truncation\n \n \n Content for first tab goes here.\n Content for second tab goes here.\n Content for third tab goes here.\n Content for fourth tab goes here.\n \n\n```\n\n#### Update `Tabs` and `Tab` usage\n\nAll the same functionality for Tabs is available in v11 and more! However, some\nprops have been deprecated because they have either been renamed or are no\nlonger needed. Below are the minor tweaks in naming or implementation.\n\n- the `type` prop is deprecated. Both \"contained\" and \"default\" tabs still exist\n but now can be called by adding the prop `contained` to the `TabList`.\n- Default tabs are now referred to as line tabs in our documentation here and in\n our storybook.\n- `hidden` prop is no longer needed with the new composable Tabs. You have\n control over tab content and when it is hidden through the `TabPanel` and\n `TabPanels` components.\n- `selected` prop is now named `selectedIndex`.\n- `tabContentClassName` is no longer needed. `TabPanel` (equivalent to tab\n content) takes in a className prop on its outermost node.\n- For `Tab`, `label` is no longer needed. `children` of `Tab` are now the label.\n- Due to its composability, `renderAnchor`, `renderButton`, `renderContent` are\n no longer needed on `Tab`. You now have full control over what is rendered\n inside of `Tab` and `TabPanel`.\n- Because `renderButton` is no longer needed, the associated `tabIndex` prop has\n also been deprecated.\n- `selected` on `Tab` is deprecated in favor or `selectedIndex`, now placed on\n `Tabs` instead.\n\nFor more details about the changes to Tabs, see our storybook documentation\n[here](https://react.carbondesignsystem.com/?path=/docs/components-tabs--default).\n\n### Step 7: Done with @carbon/react!\n\nAnd that's it! You're done. At this point you have migrated to use Carbon v11\nusing the `@carbon/react` package.\n\nIf you run into any problems after this point, please feel free to reach out to\nus over on Slack or open up a discussion on\n[GitHub](https://github.com/carbon-design-system/carbon/discussions/categories/help).\nWe want to make this migration experience as seamless as possible and will be\nmonitoring both areas to help out.\n\n## Migrating an app or library using just styles\n\nStarting in v11, the styles for Carbon live in the `@carbon/styles` package.\nAlternatively, you can continue to use `carbon-components` as it re-exports\nstyles from this package directly.\n\nFor teams using Svelte, Angular, Vue, LWC, or Web Components, please\n[review the documention](https://carbondesignsystem.com/developing/frameworks/web-components),\nfor those respective frameworks before making the migration to v11.\n\n### Step 1: Install @carbon/styles\n\nTo get started, uninstall `carbon-components` from your project:\n\n```bash\nnpm uninstall carbon-components\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn remove carbon-components\n```\n\nNext, install the `@carbon/styles` package:\n\n```bash\nnpm install @carbon/styles\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn add @carbon/styles\n```\n\n### Step 2: Install and configure Dart Sass\n\nPreviously, `carbon-components` supported being compiled by different Sass\nlibraries. Starting in v11, the `@carbon/styles` package requires Dart Sass\nthrough the `sass` package in order to compile. This change comes from our\nmigration to Sass Modules in order to improve our compilation times and overall\nproject structure.\n\nIf you don't have this dependency already in your project, you can install it:\n\n```bash\nnpm install sass\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn add sass\n```\n\nSimilarly, if you currently use `node-sass` now is a good time to remove that\ndependency from your project. In most situations, Dart Sass is a drop-in\nreplacement for `node-sass` and should require no changes on your end in order\nto use it once you install the dependency.\n\nOne you have Dart Sass installed, it's important that you configure your project\nto support resolving imports in Sass from `node_modules`. Typically, this means\nadding `node_modules` to your `includePaths` config for Sass in your bundler or\ntoolchain of choice.\n\nTo learn more about how to configure your specific toolchain to support this,\nread the documentation for configuration\n[here](https://github.com/carbon-design-system/carbon/blob/main/packages/styles/docs/sass.md#configuration).\nWe also have published a guide over on\n[Medium](https://medium.com/carbondesign/migrating-from-node-sass-to-sass-eba9db004a3a)\nto help out with common problems that come from this migration.\n\n\n\n \n \n\n \n\n\n \n \n\n \n\n\n\n### Step 3: Update import paths and tokens\n\nNow, open your project's root stylesheet to make the following changes:\n\n```diff\n- @import 'carbon-components/scss/globals/scss/styles.scss';\n+ @use '@carbon/styles';\n```\n\nIf you were providing any configuration options before you imported Carbon you\ncan now provide them using the `with` syntax:\n\n```scss\n@use '@carbon/styles' with (\n $css--default-type: true,\n $css--reset: true\n);\n```\n\nFor cases where your projects does't need to include everything via\n`@use '@carbon/styles'`; and just want to do individual component styles.\n\n```scss\n// configure feature flags if needed, if not this line can be removed\n@use '@carbon/styles/scss/config' with (\n $font-path: '@ibm/plex'\n);\n\n// ensure the css reset is included\n@use '@carbon/styles/scss/reset';\n\n// add styles for components individually\n@use '@carbon/styles/scss/components/button';\n```\n\nWhen migrating your custom components, some of our most used sass assets are\nincluded below, along with what you would need to have at the top of your file\nto use it. Essentially, all we are doing is including the path where we would\n[find these styles](https://github.com/carbon-design-system/carbon/tree/main/packages/styles/scss)\nin our package.\n\n| Carbon sass I'm using | Sass modules to include |\n| ------------------------------- | --------------------------------------------------------- |\n| Theme tokens | `@use '@carbon/styles/scss/theme' as *` |\n| Theme mixins | `@use '@carbon/styles/scss/themes' as *` |\n| Design language color tokens | `@use '@carbon/styles/scss/colors' as *` |\n| Spacing tokens | `@use '@carbon/styles/scss/spacing' as *` |\n| Breakpoint mixins | `@use '@carbon/styles/scss/breakpoint' as *` |\n| Motion tokens and functions | `@use '@carbon/styles/scss/motion' as *` |\n| Rem and other convert functions | `@use '@carbon/styles/scss/utilities/convert' as *` |\n| Z-index helper | `@use '@carbon/styles/scss/utilities/z-index' as *` |\n| Focus outline helper | `@use '@carbon/styles/scss/utilities/focus-outline' as *` |\n| Transform rotate helper | `@use '@carbon/styles/scss/utilities/rotate' as *` |\n| Skeleton animation helper | `@use '@carbon/styles/scss/utilities/skeleton' as *` |\n\nNow that you've migrated all of your imports, do a find/replace using your\nfavorite code editor. The prefix`carbon--` is no longer necessary. You can do a\nfind for `carbon--` and replace it with nothing to remove across all your files\nlike the example below. The full list of changes are available in our\n[Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#changing-import-paths-from-scssglobalsscss-to-scss).\n\n```diff\n- @include carbon--breakpoint(lg) {\n+ @include breakpoint(lg) {\n width: 42%;\n }\n```\n\nOnce you've removed the prefix, your styles should all be set using the old, v10\ntokens. We recommend teams install the community supported\n[stylelint-plugin-carbon-tokens](https://github.com/carbon-design-system/stylelint-plugin-carbon-tokens)\nto further assist in migrating your tokens to v11 tokens as the old v10 tokens\nwill be removed in our next major release.\n\n\n\n \n \n\n \n\n\n \n \n\n \n\n\n\n### Step 4: Update bx to cds\n\nIf you are targeting specific selectors that use the `bx` prefix, you will need\nto update your code to either target the `cds` prefix for selectors or update\nCarbon's configuration to use `bx` as the prefix by writing the following:\n\n```scss\n// Option A\n@use '@carbon/styles' with (\n $prefix: 'bx'\n);\n// Option B\n@use '@carbon/styles/scss/config' with (\n $prefix: 'bx'\n);\n```\n\n### Step 5: Enable flexbox grid\n\nIf you are using the flexbox-based grid in your project, you can continue to use\nthis feature in v11 by importing the following:\n\n```scss\n@use '@carbon/styles/scss/grid/flexbox';\n```\n\nThis is important due to the fact that the CSS Grid implementation is used by\ndefault in v11. However, bringing in the flexbox grid styles in this way means\nthat your layouts will continue to work the same as in v10.\n\n### Step 6: Done with @carbon/styles!\n\nAnd that's it! You're done. At this point you have migrated to use Carbon v11\nusing the `@carbon/styles` package.\n\nIf you run into any problems after this point, please feel free to reach out to\nus over on Slack or open up a discussion on\n[GitHub](https://github.com/carbon-design-system/carbon/discussions/categories/help).\nWe want to make this migration experience as seamless as possible and will be\nmonitoring both areas to help out.\n\n## Migrating carbon-icons\n\nThe `carbon-icons` package has been deprecated and is no longer supported. To\nuse icons from the Carbon Design System, you should install the appropriate\nlibrary to use with your framework:\n\n| Package | Framework | Link |\n| :---------------------- | :----------------- | :------------------------------------------------------ |\n| `@carbon/icons-react` | React | [Link](https://npmjs.com/package/@carbon/icons-react) |\n| `@carbon/icons-angular` | Angular | [Link](https://npmjs.com/package/@carbon/icons-angular) |\n| `@carbon/icons-vue` | Vue | [Link](https://npmjs.com/package/@carbon/icons-vue) |\n| `carbon-icons-svelte` | Svelte | [Link](https://npmjs.com/package/carbon-icons-svelte) |\n| `@carbon/icons` | Vanilla JavaScript | [Link](https://npmjs.com/package/@carbon/icons) |\n\nIf you are using `@carbon/react`, you can directly import icons from\n`@carbon/react/icons`.\n\n## Migrating Carbon elements\n\nThe packages that we ship for the IBM Design Language have been updated in v11.\nThe most notable change is that these packages now require Dart Sass in order to\ncompile as they now use Sass Modules to improve compilation times.\n\nIf you were directly importing from one of these element packages, consider\nimporting from either `@carbon/styles` or `@carbon/react` instead. Both of these\npackages provide entrypoints for elements packages on top of the styles for\nCarbon itself.\n\nFor teams using these packages directly, you will need to update each of the\nelements packages you're using to the latest version.\n\n```bash\nnpm install @carbon/@latest\n```\n\nOr, with [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn upgrade @carbon/@latest\n```\n\nAfterwards, you will need to update the import paths and import names themselves\nthat you bring in. In general, each package now supports importing from the\npackage directly and all `carbon--` prefixed variables, mixins, and functions\nhave been renamed to remove the prefix.\n\nFor full details fo the changes to each elements package, check out the links\nbelow.\n\n| Package | Migration Docs |\n| :----------------- | :---------------------------------------------------------------------------------------------------- |\n| `@carbon/colors` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carboncolors) |\n| `@carbon/elements` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbonelements) |\n| `@carbon/grid` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbongrid) |\n| `@carbon/layout` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbonlayout) |\n| `@carbon/motion` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbonmotion) |\n| `@carbon/themes` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbonthemes) |\n| `@carbon/type` | [Link](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbontype) |\n\nIf you were previously using the `@carbon/import-once` package, you can continue\nto use this in v11. However, this package will receive no further updates after\nCarbon switched to using Sass Modules.\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/migrating/guide/develop.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/migrating/guide/overview/page-data.json b/page-data/migrating/guide/overview/page-data.json
index 09432bede9b..87b8b08f87e 100644
--- a/page-data/migrating/guide/overview/page-data.json
+++ b/page-data/migrating/guide/overview/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-migrating-guide-overview-mdx","path":"/migrating/guide/overview/","result":{"pageContext":{"frontmatter":{"title":"Guide","description":"This guide includes everything you need to migrate your product from v10 to v11 of Carbon.","tabs":["Overview","Design","Develop"]},"relativePagePath":"/migrating/guide/overview.mdx","titleType":"prepend","MdxNode":{"id":"e39f8010-e918-5b6d-a656-6a6a7073d793","children":[],"parent":"5976fddf-d5ed-5fe2-8701-25b57b7c72d2","internal":{"content":"---\ntitle: Guide\ndescription:\n This guide includes everything you need to migrate your product from v10 to\n v11 of Carbon.\ntabs: ['Overview', 'Design', 'Develop']\n---\n\n\n\nReady to make the move to Carbon v11? Our Migration Guide helps designers and\ndevelopers learn more about this release and get started migrating to v11\n\n\n\n\n Overview\n Getting started\n YourLearning\n Updates\n\n\n## Overview\n\nCarbon v11 focuses on quality of life updates for designers and developers. The\nhighlights of this release include:\n\n- Changes to how we name our tokens to make them easier to use\n- Improved theming to enable light and dark mode support in product\n- The introduction of CSS Grid to build robust layouts on top of the 2x grid\n- A 90% decrease in compilation for Styles from Carbon\n- Updates to the accessibility of our components\n\nWith no changes to the IBM Design Language, v11 will not require any\nbrand-driven product redesigns.\n\nTo learn more about everything included in this release, check out our\n[Updates](#changelog) section. To get started migrating, visit out our\n[Getting started](#getting-started) section below.\n\n## Getting started\n\nWhether you are a designer or a developer, we have curated guidance ready for\nyou as your team makes their migration. Dive in using one of the looks below to\nget started.\n\n\n\n \n\n\n\n \n\n\n \n\n\n\n \n\n\n\n## YourLearning\n\nWatch Carbon developers Abbey Hart and Josh Black showcase some of the latest\nfeatures and enhancements in v11, including theming and CSS Grid by catching the\nCarbon and IDL weekly design playback. In a collaboration with IBM Bluetalks,\nwatch Josefina Mancilla show off layering and storybook among many other\nexciting new things that come with our latest version in her talk, Carbon v11:\nThe One with the Cool Stuff.\n\n\n\n \n \n\n \n\n\n \n\n \n\n\n\n## Updates\n\nThis section covers the new features and updates that are introduced in Carbon\nv11. If you're looking for how to migrate a project from v10 to v11, check out\nour [Getting started](#getting-started) section above.\n\nYou are not required to use any of the new features introduced in this release.\nInstead, they are meant to be gradually adopted over time when the use case\ncomes up in your product. Each section will given an overview of the changes and\nwill help you understand how to learn more about the feature in v11.\n\nFor an overview of all the changes in this release, check out our\n[Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md)\n\n### Theming\n\nOne of the first areas we revisited in v11 was our color tokens. We heard from\nyou all that the names of tokens can be confusing and hard to understand, making\nit difficult to accurately apply them without constantly referencing our site.\n\nTo address this, we investigated several ways to represent usage directly in the\ntoken name in order to make them more intuitive to use. After discussing these\nvarious options and going through rounds of feedback on GitHub, we decided on an\napproach that makes it easier to understand and apply tokens based on their\nusage.\n\nTo learn more about the new color tokens, check out our\n[Color Guidelines](https://carbondesignsystem.com/guidelines/color/usage). You\ncan also learn more about concepts like layering\n[here](https://carbondesignsystem.com/guidelines/color/implementation).\n\n#### Light & Dark mode\n\nAll of these updated color tokens are now shipped as CSS Custom Properties in\nv11. This technique makes it incredibly simple and performant to customize the\ntheme of your product. We're most excited about using this for Light & Dark Mode\nsupport in products.\n\nThis technique also can allow teams to customize a specific area of the page, a\nspecific component, or other models within their product. The best part is that\nany component using our color tokens just works, regardless of the page or\ninline theme.\n\n#### Typography\n\nType tokens are being updated in v11 along with the changes to color tokens.\nThese changes involve mostly name changes. The values and roles of these tokens\nremain the same between v10 and v11.\n\nTo learn more about the new type tokens in v11, check out our\n[Typography Guidelines](https://www.carbondesignsystem.com/guidelines/typography/productive/).\nIf you're curious about specific changes to tokens, take a look at our\n[v11 Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#type-tokens).\n\n### Design kits\n\n#### Figma\n\nAll v11 themes are now available in a library in Figma. Head to the\n[get started page](https://carbondesignsystem.com/designing/get-started/#core-design-kits)\nto see the full list of available core libraries. We have leveraged Figma's\nlatest features in this release, which may result in breaking changes to some of\nour components. To meet team's migration preferences, we have separate v11 and\nv10 libraries. If you are still on v10, migrate to the v11 libraries when you\nare ready to do so.\n\n### New packages\n\nCarbon v11 introduces new code packages to simplify how you bring Carbon into\nyour project. For many teams, you may be installing several packages in order to\nuse Carbon, including:\n\n- carbon-components\n- carbon-components-react\n- carbon-icons\n- @carbon/icons-react\n\nStarting in v11, the styles, React components, and icons are all available under\nthe @carbon/react package. Each of the packages above can still be downloaded\nindividually but we brought them together to simplify bringing Carbon into your\nproject.\n\nThe @carbon/styles package is also being introduced in v11. This package\ncontains all of the Sass styles for our components and is being re-exported by\n@carbon/react. The Sass styles in this package have gone through a number of\nupdates as we've shifted over to Dart Sass in order to improve our compile times\nby over 90%.\n\n### Dart Sass\n\nSass files in Carbon now require Dart Sass in order to compile. The decision to\nmove towards Dart Sass was made after the announcement in the blog post, LibSass\nis deprecated. Like many of you who use Sass, we've relied heavily on LibSass\nthrough projects like node-sass. We would not be where we are today without all\nthe hard work and effort that went into these projects.\n\n#### Sass Modules\n\nWith the transition to using sass, Carbon has updated its Sass files to leverage\nSass Modules. This new module system was introduced in 2019 and we knew that it\nwould be a great fit for the way Carbon authors and ships Sass files.\n\nThis new module system created an opportunity to simplify how you bring styles\ninto your project from Carbon, while drastically reducing compile times. The\nbest part is that you can still `@import` any of the files from Carbon if you\nwould like, there is no requirement for you and your project to move to Sass\nModules in order to benefit from these changes.\n\n#### Compile time improvements\n\nOne of the most common and frustrating challenges team can run into when using\nCarbon are long Sass compilation times. Parts of this were related to how Carbon\nwas structured, other parts were related to toolchains, but overall we are\nincredibly excited to announce that we drastically improved the performance of\ncompiling Carbon Sass files in v11.\n\nThrough moving to Dart Sass, migrating to Sass Modules, and changing our overall\nfile structure we were able to achieve a 90% in average recompilation times when\nusing `sass-loader` along with a 60% reduction in initial build times.\n\n### CSS Grid\n\nWe're shipping a brand new way to incorporate the 2x Grid in code using a\ntechnique in CSS called CSS Grid. This implementation ships alongside our\nFlexbox-based grid that currently exists in v10 and we will continue to support\nboth in v11.\n\nCSS Grid, along with CSS Custom Properties, makes it easier to build more\nresilient products on the Grid through CSS Grid-specific techniques or through\nnew features that we're able to bring like sub-grid for more complex products.\n\nIf you're building on any of our Grid components in v10, every one of these will\ncontinue to be supported in v11. If you would like to learn more about how to\nuse CSS Grid in your project, you can check out our documentation in\n[React](https://react.carbondesignsystem.com/?path=/docs/elements-grid--default).\n\n### React Components\n\nWe're shipping several new components in v11 to accompany the changes that we're\nmaking to styles. Theming, layering, CSS Grid, and more are all available as\ncomponents in our React library.\n\nWe're also using this release to address some of the outstanding accessibility\nissues for components like Notification and Tooltip along with consistently\napplying how we name and define certain prop types in v11.\n\n#### Theming and Layering\n\nIn order to support the new theming features coming to v11, we're shipping\ncomponents like GlobalTheme and Theme to make it as easy as possible to change\nthe theme of an entire page or a sub-section of a page. These components are\npaired alongside the useTheme hook to allow component authors to access the\ncurrent theme for a given context.\n\nWe're also introducing a new Layer component to simplify how layering is\naccomplished in v11. Previously, we used the light prop to address the layering\nneeds for the white and g10 themes. Now, the Layer component can be used along\nwith contextual tokens to implement layering across themes.\n\n#### Grid\n\nThe default grid in v11 is now implemented using CSS Grid. As a result, you'll\nonly need to use two components to build layouts on top of the 2x grid: Grid and\nColumn. For teams that already have layouts built on the flexbox version of our\ngrid components, rest assured you can update your code to use FlexGrid along\nwith the existing Row and Column components and your layouts will continue to\nwork as expected.\n\n#### Accessibility updates\n\nIn order to ship accessible versions of some of our components, we've made\nupdates or breaking changes to either change or remove inaccessible behavior.\n\nFor example, our Notification component no longer accepts interactive content as\nthe semantics of this context would be stripped from users of Screen Readers. To\nbetter support common use cases of components where interactive content was\nneeded, we are also shipping new components like Actionable Notification to\noffer a better, accessible experience for these use cases.\n\nTooltip, TooltipIcon, and TooltipDefinition are also receiving updates in v11\nand mirror some of the changes seen in Notification. For example, Tooltips can\nnow only contain interactive content. For situations that require interactive\ncontent, we are shipping a new component: Toggletip.\n\n#### Changes to icons\n\nOne of the largest changes that came to Carbon in v10 was the set of icons that\nwe supported. This set grew tremendously due to the hard work of the brand team\nat IBM, and we went from supporting around 150 icons to over 1600 as a result.\n\nThe package size for these icons quickly ballooned as we shipped an export for\neach icon size. In v11, we decided to reduce the complexity of managing a\npackage that large by shipping the icon as a component and customizing its size\nwith the size prop.\n\nThis approach lead to a 75% decrease in the number of exports and files shipped\nthrough our @carbon/icons-react package and will make it easier to bring this\npackage into your toolchain.\n\n#### Changes to component size\n\nSpeaking of size changes, we have updated the size prop for components in order\nto make sizing consistent across all of our components. Before, this prop would\naccept a variety of values like field, medium, and short. Now, this prop has the\nsame names across components to make sizing clearer.\n","type":"Mdx","contentDigest":"c9223687bb8a2f1e9564a450d5c42ad4","owner":"gatsby-plugin-mdx","counter":5334},"frontmatter":{"title":"Guide","description":"This guide includes everything you need to migrate your product from v10 to v11 of Carbon.","tabs":["Overview","Design","Develop"]},"exports":{},"rawBody":"---\ntitle: Guide\ndescription:\n This guide includes everything you need to migrate your product from v10 to\n v11 of Carbon.\ntabs: ['Overview', 'Design', 'Develop']\n---\n\n\n\nReady to make the move to Carbon v11? Our Migration Guide helps designers and\ndevelopers learn more about this release and get started migrating to v11\n\n\n\n\n Overview\n Getting started\n YourLearning\n Updates\n\n\n## Overview\n\nCarbon v11 focuses on quality of life updates for designers and developers. The\nhighlights of this release include:\n\n- Changes to how we name our tokens to make them easier to use\n- Improved theming to enable light and dark mode support in product\n- The introduction of CSS Grid to build robust layouts on top of the 2x grid\n- A 90% decrease in compilation for Styles from Carbon\n- Updates to the accessibility of our components\n\nWith no changes to the IBM Design Language, v11 will not require any\nbrand-driven product redesigns.\n\nTo learn more about everything included in this release, check out our\n[Updates](#changelog) section. To get started migrating, visit out our\n[Getting started](#getting-started) section below.\n\n## Getting started\n\nWhether you are a designer or a developer, we have curated guidance ready for\nyou as your team makes their migration. Dive in using one of the looks below to\nget started.\n\n\n\n \n\n\n\n \n\n\n \n\n\n\n \n\n\n\n## YourLearning\n\nWatch Carbon developers Abbey Hart and Josh Black showcase some of the latest\nfeatures and enhancements in v11, including theming and CSS Grid by catching the\nCarbon and IDL weekly design playback. In a collaboration with IBM Bluetalks,\nwatch Josefina Mancilla show off layering and storybook among many other\nexciting new things that come with our latest version in her talk, Carbon v11:\nThe One with the Cool Stuff.\n\n\n\n \n \n\n \n\n\n \n\n \n\n\n\n## Updates\n\nThis section covers the new features and updates that are introduced in Carbon\nv11. If you're looking for how to migrate a project from v10 to v11, check out\nour [Getting started](#getting-started) section above.\n\nYou are not required to use any of the new features introduced in this release.\nInstead, they are meant to be gradually adopted over time when the use case\ncomes up in your product. Each section will given an overview of the changes and\nwill help you understand how to learn more about the feature in v11.\n\nFor an overview of all the changes in this release, check out our\n[Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md)\n\n### Theming\n\nOne of the first areas we revisited in v11 was our color tokens. We heard from\nyou all that the names of tokens can be confusing and hard to understand, making\nit difficult to accurately apply them without constantly referencing our site.\n\nTo address this, we investigated several ways to represent usage directly in the\ntoken name in order to make them more intuitive to use. After discussing these\nvarious options and going through rounds of feedback on GitHub, we decided on an\napproach that makes it easier to understand and apply tokens based on their\nusage.\n\nTo learn more about the new color tokens, check out our\n[Color Guidelines](https://carbondesignsystem.com/guidelines/color/usage). You\ncan also learn more about concepts like layering\n[here](https://carbondesignsystem.com/guidelines/color/implementation).\n\n#### Light & Dark mode\n\nAll of these updated color tokens are now shipped as CSS Custom Properties in\nv11. This technique makes it incredibly simple and performant to customize the\ntheme of your product. We're most excited about using this for Light & Dark Mode\nsupport in products.\n\nThis technique also can allow teams to customize a specific area of the page, a\nspecific component, or other models within their product. The best part is that\nany component using our color tokens just works, regardless of the page or\ninline theme.\n\n#### Typography\n\nType tokens are being updated in v11 along with the changes to color tokens.\nThese changes involve mostly name changes. The values and roles of these tokens\nremain the same between v10 and v11.\n\nTo learn more about the new type tokens in v11, check out our\n[Typography Guidelines](https://www.carbondesignsystem.com/guidelines/typography/productive/).\nIf you're curious about specific changes to tokens, take a look at our\n[v11 Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#type-tokens).\n\n### Design kits\n\n#### Figma\n\nAll v11 themes are now available in a library in Figma. Head to the\n[get started page](https://carbondesignsystem.com/designing/get-started/#core-design-kits)\nto see the full list of available core libraries. We have leveraged Figma's\nlatest features in this release, which may result in breaking changes to some of\nour components. To meet team's migration preferences, we have separate v11 and\nv10 libraries. If you are still on v10, migrate to the v11 libraries when you\nare ready to do so.\n\n### New packages\n\nCarbon v11 introduces new code packages to simplify how you bring Carbon into\nyour project. For many teams, you may be installing several packages in order to\nuse Carbon, including:\n\n- carbon-components\n- carbon-components-react\n- carbon-icons\n- @carbon/icons-react\n\nStarting in v11, the styles, React components, and icons are all available under\nthe @carbon/react package. Each of the packages above can still be downloaded\nindividually but we brought them together to simplify bringing Carbon into your\nproject.\n\nThe @carbon/styles package is also being introduced in v11. This package\ncontains all of the Sass styles for our components and is being re-exported by\n@carbon/react. The Sass styles in this package have gone through a number of\nupdates as we've shifted over to Dart Sass in order to improve our compile times\nby over 90%.\n\n### Dart Sass\n\nSass files in Carbon now require Dart Sass in order to compile. The decision to\nmove towards Dart Sass was made after the announcement in the blog post, LibSass\nis deprecated. Like many of you who use Sass, we've relied heavily on LibSass\nthrough projects like node-sass. We would not be where we are today without all\nthe hard work and effort that went into these projects.\n\n#### Sass Modules\n\nWith the transition to using sass, Carbon has updated its Sass files to leverage\nSass Modules. This new module system was introduced in 2019 and we knew that it\nwould be a great fit for the way Carbon authors and ships Sass files.\n\nThis new module system created an opportunity to simplify how you bring styles\ninto your project from Carbon, while drastically reducing compile times. The\nbest part is that you can still `@import` any of the files from Carbon if you\nwould like, there is no requirement for you and your project to move to Sass\nModules in order to benefit from these changes.\n\n#### Compile time improvements\n\nOne of the most common and frustrating challenges team can run into when using\nCarbon are long Sass compilation times. Parts of this were related to how Carbon\nwas structured, other parts were related to toolchains, but overall we are\nincredibly excited to announce that we drastically improved the performance of\ncompiling Carbon Sass files in v11.\n\nThrough moving to Dart Sass, migrating to Sass Modules, and changing our overall\nfile structure we were able to achieve a 90% in average recompilation times when\nusing `sass-loader` along with a 60% reduction in initial build times.\n\n### CSS Grid\n\nWe're shipping a brand new way to incorporate the 2x Grid in code using a\ntechnique in CSS called CSS Grid. This implementation ships alongside our\nFlexbox-based grid that currently exists in v10 and we will continue to support\nboth in v11.\n\nCSS Grid, along with CSS Custom Properties, makes it easier to build more\nresilient products on the Grid through CSS Grid-specific techniques or through\nnew features that we're able to bring like sub-grid for more complex products.\n\nIf you're building on any of our Grid components in v10, every one of these will\ncontinue to be supported in v11. If you would like to learn more about how to\nuse CSS Grid in your project, you can check out our documentation in\n[React](https://react.carbondesignsystem.com/?path=/docs/elements-grid--default).\n\n### React Components\n\nWe're shipping several new components in v11 to accompany the changes that we're\nmaking to styles. Theming, layering, CSS Grid, and more are all available as\ncomponents in our React library.\n\nWe're also using this release to address some of the outstanding accessibility\nissues for components like Notification and Tooltip along with consistently\napplying how we name and define certain prop types in v11.\n\n#### Theming and Layering\n\nIn order to support the new theming features coming to v11, we're shipping\ncomponents like GlobalTheme and Theme to make it as easy as possible to change\nthe theme of an entire page or a sub-section of a page. These components are\npaired alongside the useTheme hook to allow component authors to access the\ncurrent theme for a given context.\n\nWe're also introducing a new Layer component to simplify how layering is\naccomplished in v11. Previously, we used the light prop to address the layering\nneeds for the white and g10 themes. Now, the Layer component can be used along\nwith contextual tokens to implement layering across themes.\n\n#### Grid\n\nThe default grid in v11 is now implemented using CSS Grid. As a result, you'll\nonly need to use two components to build layouts on top of the 2x grid: Grid and\nColumn. For teams that already have layouts built on the flexbox version of our\ngrid components, rest assured you can update your code to use FlexGrid along\nwith the existing Row and Column components and your layouts will continue to\nwork as expected.\n\n#### Accessibility updates\n\nIn order to ship accessible versions of some of our components, we've made\nupdates or breaking changes to either change or remove inaccessible behavior.\n\nFor example, our Notification component no longer accepts interactive content as\nthe semantics of this context would be stripped from users of Screen Readers. To\nbetter support common use cases of components where interactive content was\nneeded, we are also shipping new components like Actionable Notification to\noffer a better, accessible experience for these use cases.\n\nTooltip, TooltipIcon, and TooltipDefinition are also receiving updates in v11\nand mirror some of the changes seen in Notification. For example, Tooltips can\nnow only contain interactive content. For situations that require interactive\ncontent, we are shipping a new component: Toggletip.\n\n#### Changes to icons\n\nOne of the largest changes that came to Carbon in v10 was the set of icons that\nwe supported. This set grew tremendously due to the hard work of the brand team\nat IBM, and we went from supporting around 150 icons to over 1600 as a result.\n\nThe package size for these icons quickly ballooned as we shipped an export for\neach icon size. In v11, we decided to reduce the complexity of managing a\npackage that large by shipping the icon as a component and customizing its size\nwith the size prop.\n\nThis approach lead to a 75% decrease in the number of exports and files shipped\nthrough our @carbon/icons-react package and will make it easier to bring this\npackage into your toolchain.\n\n#### Changes to component size\n\nSpeaking of size changes, we have updated the size prop for components in order\nto make sizing consistent across all of our components. Before, this prop would\naccept a variety of values like field, medium, and short. Now, this prop has the\nsame names across components to make sizing clearer.\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/migrating/guide/overview.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-migrating-guide-overview-mdx","path":"/migrating/guide/overview/","result":{"pageContext":{"frontmatter":{"title":"Guide","description":"This guide includes everything you need to migrate your product from v10 to v11 of Carbon.","tabs":["Overview","Design","Develop"]},"relativePagePath":"/migrating/guide/overview.mdx","titleType":"prepend","MdxNode":{"id":"e39f8010-e918-5b6d-a656-6a6a7073d793","children":[],"parent":"5976fddf-d5ed-5fe2-8701-25b57b7c72d2","internal":{"content":"---\ntitle: Guide\ndescription:\n This guide includes everything you need to migrate your product from v10 to\n v11 of Carbon.\ntabs: ['Overview', 'Design', 'Develop']\n---\n\n\n\nReady to make the move to Carbon v11? Our Migration Guide helps designers and\ndevelopers learn more about this release and get started migrating to v11\n\n\n\n\n Overview\n Getting started\n YourLearning\n Updates\n\n\n## Overview\n\nCarbon v11 focuses on quality of life updates for designers and developers. The\nhighlights of this release include:\n\n- Changes to how we name our tokens to make them easier to use\n- Improved theming to enable light and dark mode support in product\n- The introduction of CSS Grid to build robust layouts on top of the 2x grid\n- A 90% decrease in compilation for Styles from Carbon\n- Updates to the accessibility of our components\n\nWith no changes to the IBM Design Language, v11 will not require any\nbrand-driven product redesigns.\n\nTo learn more about everything included in this release, check out our\n[Updates](#changelog) section. To get started migrating, visit out our\n[Getting started](#getting-started) section below.\n\n## Getting started\n\nWhether you are a designer or a developer, we have curated guidance ready for\nyou as your team makes their migration. Dive in using one of the looks below to\nget started.\n\n\n\n \n\n\n\n \n\n\n \n\n\n\n \n\n\n\n## YourLearning\n\nWatch Carbon developers Abbey Hart and Josh Black showcase some of the latest\nfeatures and enhancements in v11, including theming and CSS Grid by catching the\nCarbon and IDL weekly design playback. In a collaboration with IBM Bluetalks,\nwatch Josefina Mancilla show off layering and storybook among many other\nexciting new things that come with our latest version in her talk, Carbon v11:\nThe One with the Cool Stuff.\n\n\n\n \n \n\n \n\n\n \n\n \n\n\n\n## Updates\n\nThis section covers the new features and updates that are introduced in Carbon\nv11. If you're looking for how to migrate a project from v10 to v11, check out\nour [Getting started](#getting-started) section above.\n\nYou are not required to use any of the new features introduced in this release.\nInstead, they are meant to be gradually adopted over time when the use case\ncomes up in your product. Each section will given an overview of the changes and\nwill help you understand how to learn more about the feature in v11.\n\nFor an overview of all the changes in this release, check out our\n[Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md)\n\n### Theming\n\nOne of the first areas we revisited in v11 was our color tokens. We heard from\nyou all that the names of tokens can be confusing and hard to understand, making\nit difficult to accurately apply them without constantly referencing our site.\n\nTo address this, we investigated several ways to represent usage directly in the\ntoken name in order to make them more intuitive to use. After discussing these\nvarious options and going through rounds of feedback on GitHub, we decided on an\napproach that makes it easier to understand and apply tokens based on their\nusage.\n\nTo learn more about the new color tokens, check out our\n[Color Guidelines](https://carbondesignsystem.com/guidelines/color/usage). You\ncan also learn more about concepts like layering\n[here](https://carbondesignsystem.com/guidelines/color/implementation).\n\n#### Light & Dark mode\n\nAll of these updated color tokens are now shipped as CSS Custom Properties in\nv11. This technique makes it incredibly simple and performant to customize the\ntheme of your product. We're most excited about using this for Light & Dark Mode\nsupport in products.\n\nThis technique also can allow teams to customize a specific area of the page, a\nspecific component, or other models within their product. The best part is that\nany component using our color tokens just works, regardless of the page or\ninline theme.\n\n#### Typography\n\nType tokens are being updated in v11 along with the changes to color tokens.\nThese changes involve mostly name changes. The values and roles of these tokens\nremain the same between v10 and v11.\n\nTo learn more about the new type tokens in v11, check out our\n[Typography Guidelines](https://www.carbondesignsystem.com/guidelines/typography/productive/).\nIf you're curious about specific changes to tokens, take a look at our\n[v11 Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#type-tokens).\n\n### Design kits\n\n#### Figma\n\nAll v11 themes are now available in a library in Figma. Head to the\n[get started page](https://carbondesignsystem.com/designing/get-started/#core-design-kits)\nto see the full list of available core libraries. We have leveraged Figma's\nlatest features in this release, which may result in breaking changes to some of\nour components. To meet team's migration preferences, we have separate v11 and\nv10 libraries. If you are still on v10, migrate to the v11 libraries when you\nare ready to do so.\n\n### New packages\n\nCarbon v11 introduces new code packages to simplify how you bring Carbon into\nyour project. For many teams, you may be installing several packages in order to\nuse Carbon, including:\n\n- carbon-components\n- carbon-components-react\n- carbon-icons\n- @carbon/icons-react\n\nStarting in v11, the styles, React components, and icons are all available under\nthe @carbon/react package. Each of the packages above can still be downloaded\nindividually but we brought them together to simplify bringing Carbon into your\nproject.\n\nThe @carbon/styles package is also being introduced in v11. This package\ncontains all of the Sass styles for our components and is being re-exported by\n@carbon/react. The Sass styles in this package have gone through a number of\nupdates as we've shifted over to Dart Sass in order to improve our compile times\nby over 90%.\n\n### Dart Sass\n\nSass files in Carbon now require Dart Sass in order to compile. The decision to\nmove towards Dart Sass was made after the announcement in the blog post, LibSass\nis deprecated. Like many of you who use Sass, we've relied heavily on LibSass\nthrough projects like node-sass. We would not be where we are today without all\nthe hard work and effort that went into these projects.\n\n#### Sass Modules\n\nWith the transition to using sass, Carbon has updated its Sass files to leverage\nSass Modules. This new module system was introduced in 2019 and we knew that it\nwould be a great fit for the way Carbon authors and ships Sass files.\n\nThis new module system created an opportunity to simplify how you bring styles\ninto your project from Carbon, while drastically reducing compile times. The\nbest part is that you can still `@import` any of the files from Carbon if you\nwould like, there is no requirement for you and your project to move to Sass\nModules in order to benefit from these changes.\n\n#### Compile time improvements\n\nOne of the most common and frustrating challenges team can run into when using\nCarbon are long Sass compilation times. Parts of this were related to how Carbon\nwas structured, other parts were related to toolchains, but overall we are\nincredibly excited to announce that we drastically improved the performance of\ncompiling Carbon Sass files in v11.\n\nThrough moving to Dart Sass, migrating to Sass Modules, and changing our overall\nfile structure we were able to achieve a 90% in average recompilation times when\nusing `sass-loader` along with a 60% reduction in initial build times.\n\n### CSS Grid\n\nWe're shipping a brand new way to incorporate the 2x Grid in code using a\ntechnique in CSS called CSS Grid. This implementation ships alongside our\nFlexbox-based grid that currently exists in v10 and we will continue to support\nboth in v11.\n\nCSS Grid, along with CSS Custom Properties, makes it easier to build more\nresilient products on the Grid through CSS Grid-specific techniques or through\nnew features that we're able to bring like sub-grid for more complex products.\n\nIf you're building on any of our Grid components in v10, every one of these will\ncontinue to be supported in v11. If you would like to learn more about how to\nuse CSS Grid in your project, you can check out our documentation in\n[React](https://react.carbondesignsystem.com/?path=/docs/elements-grid--default).\n\n### React Components\n\nWe're shipping several new components in v11 to accompany the changes that we're\nmaking to styles. Theming, layering, CSS Grid, and more are all available as\ncomponents in our React library.\n\nWe're also using this release to address some of the outstanding accessibility\nissues for components like Notification and Tooltip along with consistently\napplying how we name and define certain prop types in v11.\n\n#### Theming and Layering\n\nIn order to support the new theming features coming to v11, we're shipping\ncomponents like GlobalTheme and Theme to make it as easy as possible to change\nthe theme of an entire page or a sub-section of a page. These components are\npaired alongside the useTheme hook to allow component authors to access the\ncurrent theme for a given context.\n\nWe're also introducing a new Layer component to simplify how layering is\naccomplished in v11. Previously, we used the light prop to address the layering\nneeds for the white and g10 themes. Now, the Layer component can be used along\nwith contextual tokens to implement layering across themes.\n\n#### Grid\n\nThe default grid in v11 is now implemented using CSS Grid. As a result, you'll\nonly need to use two components to build layouts on top of the 2x grid: Grid and\nColumn. For teams that already have layouts built on the flexbox version of our\ngrid components, rest assured you can update your code to use FlexGrid along\nwith the existing Row and Column components and your layouts will continue to\nwork as expected.\n\n#### Accessibility updates\n\nIn order to ship accessible versions of some of our components, we've made\nupdates or breaking changes to either change or remove inaccessible behavior.\n\nFor example, our Notification component no longer accepts interactive content as\nthe semantics of this context would be stripped from users of Screen Readers. To\nbetter support common use cases of components where interactive content was\nneeded, we are also shipping new components like Actionable Notification to\noffer a better, accessible experience for these use cases.\n\nTooltip, TooltipIcon, and TooltipDefinition are also receiving updates in v11\nand mirror some of the changes seen in Notification. For example, Tooltips can\nnow only contain interactive content. For situations that require interactive\ncontent, we are shipping a new component: Toggletip.\n\n#### Changes to icons\n\nOne of the largest changes that came to Carbon in v10 was the set of icons that\nwe supported. This set grew tremendously due to the hard work of the brand team\nat IBM, and we went from supporting around 150 icons to over 1600 as a result.\n\nThe package size for these icons quickly ballooned as we shipped an export for\neach icon size. In v11, we decided to reduce the complexity of managing a\npackage that large by shipping the icon as a component and customizing its size\nwith the size prop.\n\nThis approach lead to a 75% decrease in the number of exports and files shipped\nthrough our @carbon/icons-react package and will make it easier to bring this\npackage into your toolchain.\n\n#### Changes to component size\n\nSpeaking of size changes, we have updated the size prop for components in order\nto make sizing consistent across all of our components. Before, this prop would\naccept a variety of values like field, medium, and short. Now, this prop has the\nsame names across components to make sizing clearer.\n","type":"Mdx","contentDigest":"c9223687bb8a2f1e9564a450d5c42ad4","owner":"gatsby-plugin-mdx","counter":5331},"frontmatter":{"title":"Guide","description":"This guide includes everything you need to migrate your product from v10 to v11 of Carbon.","tabs":["Overview","Design","Develop"]},"exports":{},"rawBody":"---\ntitle: Guide\ndescription:\n This guide includes everything you need to migrate your product from v10 to\n v11 of Carbon.\ntabs: ['Overview', 'Design', 'Develop']\n---\n\n\n\nReady to make the move to Carbon v11? Our Migration Guide helps designers and\ndevelopers learn more about this release and get started migrating to v11\n\n\n\n\n Overview\n Getting started\n YourLearning\n Updates\n\n\n## Overview\n\nCarbon v11 focuses on quality of life updates for designers and developers. The\nhighlights of this release include:\n\n- Changes to how we name our tokens to make them easier to use\n- Improved theming to enable light and dark mode support in product\n- The introduction of CSS Grid to build robust layouts on top of the 2x grid\n- A 90% decrease in compilation for Styles from Carbon\n- Updates to the accessibility of our components\n\nWith no changes to the IBM Design Language, v11 will not require any\nbrand-driven product redesigns.\n\nTo learn more about everything included in this release, check out our\n[Updates](#changelog) section. To get started migrating, visit out our\n[Getting started](#getting-started) section below.\n\n## Getting started\n\nWhether you are a designer or a developer, we have curated guidance ready for\nyou as your team makes their migration. Dive in using one of the looks below to\nget started.\n\n\n\n \n\n\n\n \n\n\n \n\n\n\n \n\n\n\n## YourLearning\n\nWatch Carbon developers Abbey Hart and Josh Black showcase some of the latest\nfeatures and enhancements in v11, including theming and CSS Grid by catching the\nCarbon and IDL weekly design playback. In a collaboration with IBM Bluetalks,\nwatch Josefina Mancilla show off layering and storybook among many other\nexciting new things that come with our latest version in her talk, Carbon v11:\nThe One with the Cool Stuff.\n\n\n\n \n \n\n \n\n\n \n\n \n\n\n\n## Updates\n\nThis section covers the new features and updates that are introduced in Carbon\nv11. If you're looking for how to migrate a project from v10 to v11, check out\nour [Getting started](#getting-started) section above.\n\nYou are not required to use any of the new features introduced in this release.\nInstead, they are meant to be gradually adopted over time when the use case\ncomes up in your product. Each section will given an overview of the changes and\nwill help you understand how to learn more about the feature in v11.\n\nFor an overview of all the changes in this release, check out our\n[Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md)\n\n### Theming\n\nOne of the first areas we revisited in v11 was our color tokens. We heard from\nyou all that the names of tokens can be confusing and hard to understand, making\nit difficult to accurately apply them without constantly referencing our site.\n\nTo address this, we investigated several ways to represent usage directly in the\ntoken name in order to make them more intuitive to use. After discussing these\nvarious options and going through rounds of feedback on GitHub, we decided on an\napproach that makes it easier to understand and apply tokens based on their\nusage.\n\nTo learn more about the new color tokens, check out our\n[Color Guidelines](https://carbondesignsystem.com/guidelines/color/usage). You\ncan also learn more about concepts like layering\n[here](https://carbondesignsystem.com/guidelines/color/implementation).\n\n#### Light & Dark mode\n\nAll of these updated color tokens are now shipped as CSS Custom Properties in\nv11. This technique makes it incredibly simple and performant to customize the\ntheme of your product. We're most excited about using this for Light & Dark Mode\nsupport in products.\n\nThis technique also can allow teams to customize a specific area of the page, a\nspecific component, or other models within their product. The best part is that\nany component using our color tokens just works, regardless of the page or\ninline theme.\n\n#### Typography\n\nType tokens are being updated in v11 along with the changes to color tokens.\nThese changes involve mostly name changes. The values and roles of these tokens\nremain the same between v10 and v11.\n\nTo learn more about the new type tokens in v11, check out our\n[Typography Guidelines](https://www.carbondesignsystem.com/guidelines/typography/productive/).\nIf you're curious about specific changes to tokens, take a look at our\n[v11 Migration Docs](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#type-tokens).\n\n### Design kits\n\n#### Figma\n\nAll v11 themes are now available in a library in Figma. Head to the\n[get started page](https://carbondesignsystem.com/designing/get-started/#core-design-kits)\nto see the full list of available core libraries. We have leveraged Figma's\nlatest features in this release, which may result in breaking changes to some of\nour components. To meet team's migration preferences, we have separate v11 and\nv10 libraries. If you are still on v10, migrate to the v11 libraries when you\nare ready to do so.\n\n### New packages\n\nCarbon v11 introduces new code packages to simplify how you bring Carbon into\nyour project. For many teams, you may be installing several packages in order to\nuse Carbon, including:\n\n- carbon-components\n- carbon-components-react\n- carbon-icons\n- @carbon/icons-react\n\nStarting in v11, the styles, React components, and icons are all available under\nthe @carbon/react package. Each of the packages above can still be downloaded\nindividually but we brought them together to simplify bringing Carbon into your\nproject.\n\nThe @carbon/styles package is also being introduced in v11. This package\ncontains all of the Sass styles for our components and is being re-exported by\n@carbon/react. The Sass styles in this package have gone through a number of\nupdates as we've shifted over to Dart Sass in order to improve our compile times\nby over 90%.\n\n### Dart Sass\n\nSass files in Carbon now require Dart Sass in order to compile. The decision to\nmove towards Dart Sass was made after the announcement in the blog post, LibSass\nis deprecated. Like many of you who use Sass, we've relied heavily on LibSass\nthrough projects like node-sass. We would not be where we are today without all\nthe hard work and effort that went into these projects.\n\n#### Sass Modules\n\nWith the transition to using sass, Carbon has updated its Sass files to leverage\nSass Modules. This new module system was introduced in 2019 and we knew that it\nwould be a great fit for the way Carbon authors and ships Sass files.\n\nThis new module system created an opportunity to simplify how you bring styles\ninto your project from Carbon, while drastically reducing compile times. The\nbest part is that you can still `@import` any of the files from Carbon if you\nwould like, there is no requirement for you and your project to move to Sass\nModules in order to benefit from these changes.\n\n#### Compile time improvements\n\nOne of the most common and frustrating challenges team can run into when using\nCarbon are long Sass compilation times. Parts of this were related to how Carbon\nwas structured, other parts were related to toolchains, but overall we are\nincredibly excited to announce that we drastically improved the performance of\ncompiling Carbon Sass files in v11.\n\nThrough moving to Dart Sass, migrating to Sass Modules, and changing our overall\nfile structure we were able to achieve a 90% in average recompilation times when\nusing `sass-loader` along with a 60% reduction in initial build times.\n\n### CSS Grid\n\nWe're shipping a brand new way to incorporate the 2x Grid in code using a\ntechnique in CSS called CSS Grid. This implementation ships alongside our\nFlexbox-based grid that currently exists in v10 and we will continue to support\nboth in v11.\n\nCSS Grid, along with CSS Custom Properties, makes it easier to build more\nresilient products on the Grid through CSS Grid-specific techniques or through\nnew features that we're able to bring like sub-grid for more complex products.\n\nIf you're building on any of our Grid components in v10, every one of these will\ncontinue to be supported in v11. If you would like to learn more about how to\nuse CSS Grid in your project, you can check out our documentation in\n[React](https://react.carbondesignsystem.com/?path=/docs/elements-grid--default).\n\n### React Components\n\nWe're shipping several new components in v11 to accompany the changes that we're\nmaking to styles. Theming, layering, CSS Grid, and more are all available as\ncomponents in our React library.\n\nWe're also using this release to address some of the outstanding accessibility\nissues for components like Notification and Tooltip along with consistently\napplying how we name and define certain prop types in v11.\n\n#### Theming and Layering\n\nIn order to support the new theming features coming to v11, we're shipping\ncomponents like GlobalTheme and Theme to make it as easy as possible to change\nthe theme of an entire page or a sub-section of a page. These components are\npaired alongside the useTheme hook to allow component authors to access the\ncurrent theme for a given context.\n\nWe're also introducing a new Layer component to simplify how layering is\naccomplished in v11. Previously, we used the light prop to address the layering\nneeds for the white and g10 themes. Now, the Layer component can be used along\nwith contextual tokens to implement layering across themes.\n\n#### Grid\n\nThe default grid in v11 is now implemented using CSS Grid. As a result, you'll\nonly need to use two components to build layouts on top of the 2x grid: Grid and\nColumn. For teams that already have layouts built on the flexbox version of our\ngrid components, rest assured you can update your code to use FlexGrid along\nwith the existing Row and Column components and your layouts will continue to\nwork as expected.\n\n#### Accessibility updates\n\nIn order to ship accessible versions of some of our components, we've made\nupdates or breaking changes to either change or remove inaccessible behavior.\n\nFor example, our Notification component no longer accepts interactive content as\nthe semantics of this context would be stripped from users of Screen Readers. To\nbetter support common use cases of components where interactive content was\nneeded, we are also shipping new components like Actionable Notification to\noffer a better, accessible experience for these use cases.\n\nTooltip, TooltipIcon, and TooltipDefinition are also receiving updates in v11\nand mirror some of the changes seen in Notification. For example, Tooltips can\nnow only contain interactive content. For situations that require interactive\ncontent, we are shipping a new component: Toggletip.\n\n#### Changes to icons\n\nOne of the largest changes that came to Carbon in v10 was the set of icons that\nwe supported. This set grew tremendously due to the hard work of the brand team\nat IBM, and we went from supporting around 150 icons to over 1600 as a result.\n\nThe package size for these icons quickly ballooned as we shipped an export for\neach icon size. In v11, we decided to reduce the complexity of managing a\npackage that large by shipping the icon as a component and customizing its size\nwith the size prop.\n\nThis approach lead to a 75% decrease in the number of exports and files shipped\nthrough our @carbon/icons-react package and will make it easier to bring this\npackage into your toolchain.\n\n#### Changes to component size\n\nSpeaking of size changes, we have updated the size prop for components in order\nto make sizing consistent across all of our components. Before, this prop would\naccept a variety of values like field, medium, and short. Now, this prop has the\nsame names across components to make sizing clearer.\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/migrating/guide/overview.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/patterns/common-actions/page-data.json b/page-data/patterns/common-actions/page-data.json
index 7327f93761f..ba7f2a52883 100644
--- a/page-data/patterns/common-actions/page-data.json
+++ b/page-data/patterns/common-actions/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-patterns-common-actions-index-mdx","path":"/patterns/common-actions/","result":{"pageContext":{"frontmatter":{"title":"Common actions","description":"Common actions are frequently used actions that appear across different components and workflows."},"relativePagePath":"/patterns/common-actions/index.mdx","titleType":"prepend","MdxNode":{"id":"ea1e33c8-6f86-57c9-a4cb-d839a1e08af0","children":[],"parent":"76a3f3b5-8352-524a-9b5e-08fbc45bc4b3","internal":{"content":"---\ntitle: Common actions\ndescription:\n Common actions are frequently used actions that appear across different\n components and workflows.\n---\n\n\n\nCommon actions frequently appear across different components and workflows. For\nplatform consistency, these actions should only be applied in the ways described\nbelow.\n\n\n\n\n\nAdd\nCancel\nClear\nClose\nCopy\nDelete\nEdit\nErrors\nNext\nRefresh\nRemove\nReset\n\n\n\n## Add\n\nAdd inserts an existing object to a list, set, or system. For example, adding a\ndocument to a folder.\n\n\n\n\n\n\n\n\n\n### Hierarchy and placement\n\nDepending on the importance of the add action on the page, the emphasis can be\nhigh, medium, or low. For example, a high emphasis action should use a single\nprimary button with all others being secondary.\n\n### Considerations\n\nSmall adjustments in your messaging will reduce user uncertainty. Consider the\nfollowing:\n\n- What are the implications of the add action for the user? Are there financial,\n access, or legal considerations?\n- Does the user have the correct permissions for this action?\n- Is the action permanent?\n- What timeframe will the action take (seconds, minutes, hours, days)?\n- What should a user do if the action fails?\n- Is this a single or bulk action?\n\n## Cancel\n\nCancel stops the current action and closes the component or item. Warn the user\nof any negative consequences if the process doesn’t progress, such as data\ncorruption or data loss.\n\nUse a secondary button or a link for cancel actions.\n\n\n\n\n\n\n\n\n\n## Clear\n\nClear removes data from a field or removes selections. Clear can also delete the\ncontents of a document, such as a log. For controls that have a default\nselection or value, such as radio buttons, the default selection or value is\nreset.\n\nUse the `close` icon on the right side of a field, item, or value.\n\n\n\n\n\n\n\n\n\n## Close\n\nClose terminates the current page, window, or menu. Close is also used to\ndismiss information, such as notifications.\n\nUse the `close` icon, which is typically placed on the upper right side of the\nelement. Do not use close in a button.\n\n\n\n\n\n\n\n\n\n## Copy\n\nCopy creates a new identical instance of the selected object(s).\n\nUse the `copy` icon with a confirmation \"copied\" tooltip appearing post-click or\ntap.\n\n\n\n\n\n\n\n\n\n## Delete\n\nDelete destroys an object. Delete actions cannot be easily undone and are\ntypically permanent. Warn the user of any negative consequences if an object is\ndestroyed, such as loss of data. Use either the `delete` or `trash can` icon, a\ndanger button, or a danger option in a menu. A danger modal is used when a\nwarning is needed to confirm an action.\n\n\n\n\n\n\n\n\n\n### Low-impact deletion\n\nUse when it’s trivial to undo deletion or recreate the data. Delete the data\nupon click or tap without further warning.\n\n### Moderate-impact deletion\n\nUse when an action cannot be undone or the data cannot be recreated easily. This\npattern is also useful if you’re deleting more than one thing.\n\nAsk for confirmation of the delete, with guidance about what will occur if they\ndelete.\n\n### High-impact deletion\n\nUse when it would be very expensive or time-consuming to recreate data. Also use\nif the action deletes a large amount of data, or if other important items would\nbe deleted as a result of the action.\n\nIn addition to presenting a dialog, have the user type the name of the resource\nthey are deleting (manual confirmation).\n\n### Post-deletion\n\nAfter the user deletes data, return to the page that lists the data deleted.\nAnimate the removal of the data from the list or page and present a success\nnotification.\n\nIf the deletion fails, raise a notification to tell the user that deletion\nfailed. Send a second notification on another communication channel, like email,\nif possible. Animate the data back onto the page if possible.\n\n## Edit\n\nEdit allows data or values to be changed. Edit commonly triggers a state change\nto the targeted object or input item.\n\nOffer edit as an option in a menu, or as a button or `edit` icon.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n## Errors\n\nErrors occur when an action or process does not succeed. Error notifications can\noccupy full pages, form fields, notifications, and modals. Error notifications\nshould provide context of what happened and a clear path to continue.\n\n\n\n\n\n\n\n\n\nConsider redirecting the user to a previous state, a support page, or offering\nrecommendations. Be honest and helpful.\n\nSome components, like text input and form field errors, are quite small and\nrequire more thoughtful approaches to the space and placement of error handling.\nConsider inline error notifications for these instances.\n\n### Content guidelines\n\nBe brief, honest, and supportive. Explain what happened and what can the user do\nto resolve the error.\n\nFor full-page and large modals, keep error messages no longer than three\nparagraph lines. For form errors, keep error messages no longer than two lines.\n\n## Next\n\nNext advances the user to the next step in a sequence of steps, like in a\nwizard.\n\nRepresent next with a [button with icon](/components/button/usage) or a\nstandalone `forward` icon.\n\n\n\n\n\n\n\n\n\n## Refresh\n\nThis action reloads the view of an object, list, or data set when the displayed\nview has become unsynchronized with the source.\n\nUse the `refresh` icon or a button.\n\n\n\n\n\n\n\n\n\n## Remove\n\nThis action removes an object from a list or item. Remove is distinct from\ndelete, as a removed item is not destroyed. Multiple objects can be removed at\nonce.\n\n\n\n\n\n\n\n\n\n### Hierarchy and placement\n\nRepresent remove as a button or `subtract` icon or glyph. The remove action is\nrarely the primary action on the page and should not be overly emphasized.\n\n### Considerations\n\n- What are the implications of the remove action for the user? Are there\n financial, access, or legal considerations?\n- This action can be confused with deleting.\n- A user may not have the correct permissions for this action.\n- Inform the user if the result is permanent.\n- How long will the action take? Seconds, minutes, hours, or days?\n- What should the user do if the removal fails?\n- Is this a single or bulk action?\n\n## Reset\n\nReset reverts values back to their last saved state. The last saved state\nincludes the values stored the last time the user clicked or triggered\n**Apply**.\n\n\n\n\nReset is typically applied as a link.\n\n\n\n\n\n","type":"Mdx","contentDigest":"ffac431c8d8ef562d4b987a84331ed53","owner":"gatsby-plugin-mdx","counter":5333},"frontmatter":{"title":"Common actions","description":"Common actions are frequently used actions that appear across different components and workflows."},"exports":{},"rawBody":"---\ntitle: Common actions\ndescription:\n Common actions are frequently used actions that appear across different\n components and workflows.\n---\n\n\n\nCommon actions frequently appear across different components and workflows. For\nplatform consistency, these actions should only be applied in the ways described\nbelow.\n\n\n\n\n\nAdd\nCancel\nClear\nClose\nCopy\nDelete\nEdit\nErrors\nNext\nRefresh\nRemove\nReset\n\n\n\n## Add\n\nAdd inserts an existing object to a list, set, or system. For example, adding a\ndocument to a folder.\n\n\n\n\n\n\n\n\n\n### Hierarchy and placement\n\nDepending on the importance of the add action on the page, the emphasis can be\nhigh, medium, or low. For example, a high emphasis action should use a single\nprimary button with all others being secondary.\n\n### Considerations\n\nSmall adjustments in your messaging will reduce user uncertainty. Consider the\nfollowing:\n\n- What are the implications of the add action for the user? Are there financial,\n access, or legal considerations?\n- Does the user have the correct permissions for this action?\n- Is the action permanent?\n- What timeframe will the action take (seconds, minutes, hours, days)?\n- What should a user do if the action fails?\n- Is this a single or bulk action?\n\n## Cancel\n\nCancel stops the current action and closes the component or item. Warn the user\nof any negative consequences if the process doesn’t progress, such as data\ncorruption or data loss.\n\nUse a secondary button or a link for cancel actions.\n\n\n\n\n\n\n\n\n\n## Clear\n\nClear removes data from a field or removes selections. Clear can also delete the\ncontents of a document, such as a log. For controls that have a default\nselection or value, such as radio buttons, the default selection or value is\nreset.\n\nUse the `close` icon on the right side of a field, item, or value.\n\n\n\n\n\n\n\n\n\n## Close\n\nClose terminates the current page, window, or menu. Close is also used to\ndismiss information, such as notifications.\n\nUse the `close` icon, which is typically placed on the upper right side of the\nelement. Do not use close in a button.\n\n\n\n\n\n\n\n\n\n## Copy\n\nCopy creates a new identical instance of the selected object(s).\n\nUse the `copy` icon with a confirmation \"copied\" tooltip appearing post-click or\ntap.\n\n\n\n\n\n\n\n\n\n## Delete\n\nDelete destroys an object. Delete actions cannot be easily undone and are\ntypically permanent. Warn the user of any negative consequences if an object is\ndestroyed, such as loss of data. Use either the `delete` or `trash can` icon, a\ndanger button, or a danger option in a menu. A danger modal is used when a\nwarning is needed to confirm an action.\n\n\n\n\n\n\n\n\n\n### Low-impact deletion\n\nUse when it’s trivial to undo deletion or recreate the data. Delete the data\nupon click or tap without further warning.\n\n### Moderate-impact deletion\n\nUse when an action cannot be undone or the data cannot be recreated easily. This\npattern is also useful if you’re deleting more than one thing.\n\nAsk for confirmation of the delete, with guidance about what will occur if they\ndelete.\n\n### High-impact deletion\n\nUse when it would be very expensive or time-consuming to recreate data. Also use\nif the action deletes a large amount of data, or if other important items would\nbe deleted as a result of the action.\n\nIn addition to presenting a dialog, have the user type the name of the resource\nthey are deleting (manual confirmation).\n\n### Post-deletion\n\nAfter the user deletes data, return to the page that lists the data deleted.\nAnimate the removal of the data from the list or page and present a success\nnotification.\n\nIf the deletion fails, raise a notification to tell the user that deletion\nfailed. Send a second notification on another communication channel, like email,\nif possible. Animate the data back onto the page if possible.\n\n## Edit\n\nEdit allows data or values to be changed. Edit commonly triggers a state change\nto the targeted object or input item.\n\nOffer edit as an option in a menu, or as a button or `edit` icon.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n## Errors\n\nErrors occur when an action or process does not succeed. Error notifications can\noccupy full pages, form fields, notifications, and modals. Error notifications\nshould provide context of what happened and a clear path to continue.\n\n\n\n\n\n\n\n\n\nConsider redirecting the user to a previous state, a support page, or offering\nrecommendations. Be honest and helpful.\n\nSome components, like text input and form field errors, are quite small and\nrequire more thoughtful approaches to the space and placement of error handling.\nConsider inline error notifications for these instances.\n\n### Content guidelines\n\nBe brief, honest, and supportive. Explain what happened and what can the user do\nto resolve the error.\n\nFor full-page and large modals, keep error messages no longer than three\nparagraph lines. For form errors, keep error messages no longer than two lines.\n\n## Next\n\nNext advances the user to the next step in a sequence of steps, like in a\nwizard.\n\nRepresent next with a [button with icon](/components/button/usage) or a\nstandalone `forward` icon.\n\n\n\n\n\n\n\n\n\n## Refresh\n\nThis action reloads the view of an object, list, or data set when the displayed\nview has become unsynchronized with the source.\n\nUse the `refresh` icon or a button.\n\n\n\n\n\n\n\n\n\n## Remove\n\nThis action removes an object from a list or item. Remove is distinct from\ndelete, as a removed item is not destroyed. Multiple objects can be removed at\nonce.\n\n\n\n\n\n\n\n\n\n### Hierarchy and placement\n\nRepresent remove as a button or `subtract` icon or glyph. The remove action is\nrarely the primary action on the page and should not be overly emphasized.\n\n### Considerations\n\n- What are the implications of the remove action for the user? Are there\n financial, access, or legal considerations?\n- This action can be confused with deleting.\n- A user may not have the correct permissions for this action.\n- Inform the user if the result is permanent.\n- How long will the action take? Seconds, minutes, hours, or days?\n- What should the user do if the removal fails?\n- Is this a single or bulk action?\n\n## Reset\n\nReset reverts values back to their last saved state. The last saved state\nincludes the values stored the last time the user clicked or triggered\n**Apply**.\n\n\n\n\nReset is typically applied as a link.\n\n\n\n\n\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/patterns/common-actions/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-patterns-common-actions-index-mdx","path":"/patterns/common-actions/","result":{"pageContext":{"frontmatter":{"title":"Common actions","description":"Common actions are frequently used actions that appear across different components and workflows."},"relativePagePath":"/patterns/common-actions/index.mdx","titleType":"prepend","MdxNode":{"id":"ea1e33c8-6f86-57c9-a4cb-d839a1e08af0","children":[],"parent":"76a3f3b5-8352-524a-9b5e-08fbc45bc4b3","internal":{"content":"---\ntitle: Common actions\ndescription:\n Common actions are frequently used actions that appear across different\n components and workflows.\n---\n\n\n\nCommon actions frequently appear across different components and workflows. For\nplatform consistency, these actions should only be applied in the ways described\nbelow.\n\n\n\n\n\nAdd\nCancel\nClear\nClose\nCopy\nDelete\nEdit\nErrors\nNext\nRefresh\nRemove\nReset\n\n\n\n## Add\n\nAdd inserts an existing object to a list, set, or system. For example, adding a\ndocument to a folder.\n\n\n\n\n\n\n\n\n\n### Hierarchy and placement\n\nDepending on the importance of the add action on the page, the emphasis can be\nhigh, medium, or low. For example, a high emphasis action should use a single\nprimary button with all others being secondary.\n\n### Considerations\n\nSmall adjustments in your messaging will reduce user uncertainty. Consider the\nfollowing:\n\n- What are the implications of the add action for the user? Are there financial,\n access, or legal considerations?\n- Does the user have the correct permissions for this action?\n- Is the action permanent?\n- What timeframe will the action take (seconds, minutes, hours, days)?\n- What should a user do if the action fails?\n- Is this a single or bulk action?\n\n## Cancel\n\nCancel stops the current action and closes the component or item. Warn the user\nof any negative consequences if the process doesn’t progress, such as data\ncorruption or data loss.\n\nUse a secondary button or a link for cancel actions.\n\n\n\n\n\n\n\n\n\n## Clear\n\nClear removes data from a field or removes selections. Clear can also delete the\ncontents of a document, such as a log. For controls that have a default\nselection or value, such as radio buttons, the default selection or value is\nreset.\n\nUse the `close` icon on the right side of a field, item, or value.\n\n\n\n\n\n\n\n\n\n## Close\n\nClose terminates the current page, window, or menu. Close is also used to\ndismiss information, such as notifications.\n\nUse the `close` icon, which is typically placed on the upper right side of the\nelement. Do not use close in a button.\n\n\n\n\n\n\n\n\n\n## Copy\n\nCopy creates a new identical instance of the selected object(s).\n\nUse the `copy` icon with a confirmation \"copied\" tooltip appearing post-click or\ntap.\n\n\n\n\n\n\n\n\n\n## Delete\n\nDelete destroys an object. Delete actions cannot be easily undone and are\ntypically permanent. Warn the user of any negative consequences if an object is\ndestroyed, such as loss of data. Use either the `delete` or `trash can` icon, a\ndanger button, or a danger option in a menu. A danger modal is used when a\nwarning is needed to confirm an action.\n\n\n\n\n\n\n\n\n\n### Low-impact deletion\n\nUse when it’s trivial to undo deletion or recreate the data. Delete the data\nupon click or tap without further warning.\n\n### Moderate-impact deletion\n\nUse when an action cannot be undone or the data cannot be recreated easily. This\npattern is also useful if you’re deleting more than one thing.\n\nAsk for confirmation of the delete, with guidance about what will occur if they\ndelete.\n\n### High-impact deletion\n\nUse when it would be very expensive or time-consuming to recreate data. Also use\nif the action deletes a large amount of data, or if other important items would\nbe deleted as a result of the action.\n\nIn addition to presenting a dialog, have the user type the name of the resource\nthey are deleting (manual confirmation).\n\n### Post-deletion\n\nAfter the user deletes data, return to the page that lists the data deleted.\nAnimate the removal of the data from the list or page and present a success\nnotification.\n\nIf the deletion fails, raise a notification to tell the user that deletion\nfailed. Send a second notification on another communication channel, like email,\nif possible. Animate the data back onto the page if possible.\n\n## Edit\n\nEdit allows data or values to be changed. Edit commonly triggers a state change\nto the targeted object or input item.\n\nOffer edit as an option in a menu, or as a button or `edit` icon.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n## Errors\n\nErrors occur when an action or process does not succeed. Error notifications can\noccupy full pages, form fields, notifications, and modals. Error notifications\nshould provide context of what happened and a clear path to continue.\n\n\n\n\n\n\n\n\n\nConsider redirecting the user to a previous state, a support page, or offering\nrecommendations. Be honest and helpful.\n\nSome components, like text input and form field errors, are quite small and\nrequire more thoughtful approaches to the space and placement of error handling.\nConsider inline error notifications for these instances.\n\n### Content guidelines\n\nBe brief, honest, and supportive. Explain what happened and what can the user do\nto resolve the error.\n\nFor full-page and large modals, keep error messages no longer than three\nparagraph lines. For form errors, keep error messages no longer than two lines.\n\n## Next\n\nNext advances the user to the next step in a sequence of steps, like in a\nwizard.\n\nRepresent next with a [button with icon](/components/button/usage) or a\nstandalone `forward` icon.\n\n\n\n\n\n\n\n\n\n## Refresh\n\nThis action reloads the view of an object, list, or data set when the displayed\nview has become unsynchronized with the source.\n\nUse the `refresh` icon or a button.\n\n\n\n\n\n\n\n\n\n## Remove\n\nThis action removes an object from a list or item. Remove is distinct from\ndelete, as a removed item is not destroyed. Multiple objects can be removed at\nonce.\n\n\n\n\n\n\n\n\n\n### Hierarchy and placement\n\nRepresent remove as a button or `subtract` icon or glyph. The remove action is\nrarely the primary action on the page and should not be overly emphasized.\n\n### Considerations\n\n- What are the implications of the remove action for the user? Are there\n financial, access, or legal considerations?\n- This action can be confused with deleting.\n- A user may not have the correct permissions for this action.\n- Inform the user if the result is permanent.\n- How long will the action take? Seconds, minutes, hours, or days?\n- What should the user do if the removal fails?\n- Is this a single or bulk action?\n\n## Reset\n\nReset reverts values back to their last saved state. The last saved state\nincludes the values stored the last time the user clicked or triggered\n**Apply**.\n\n\n\n\nReset is typically applied as a link.\n\n\n\n\n\n","type":"Mdx","contentDigest":"ffac431c8d8ef562d4b987a84331ed53","owner":"gatsby-plugin-mdx","counter":5334},"frontmatter":{"title":"Common actions","description":"Common actions are frequently used actions that appear across different components and workflows."},"exports":{},"rawBody":"---\ntitle: Common actions\ndescription:\n Common actions are frequently used actions that appear across different\n components and workflows.\n---\n\n\n\nCommon actions frequently appear across different components and workflows. For\nplatform consistency, these actions should only be applied in the ways described\nbelow.\n\n\n\n\n\nAdd\nCancel\nClear\nClose\nCopy\nDelete\nEdit\nErrors\nNext\nRefresh\nRemove\nReset\n\n\n\n## Add\n\nAdd inserts an existing object to a list, set, or system. For example, adding a\ndocument to a folder.\n\n\n\n\n\n\n\n\n\n### Hierarchy and placement\n\nDepending on the importance of the add action on the page, the emphasis can be\nhigh, medium, or low. For example, a high emphasis action should use a single\nprimary button with all others being secondary.\n\n### Considerations\n\nSmall adjustments in your messaging will reduce user uncertainty. Consider the\nfollowing:\n\n- What are the implications of the add action for the user? Are there financial,\n access, or legal considerations?\n- Does the user have the correct permissions for this action?\n- Is the action permanent?\n- What timeframe will the action take (seconds, minutes, hours, days)?\n- What should a user do if the action fails?\n- Is this a single or bulk action?\n\n## Cancel\n\nCancel stops the current action and closes the component or item. Warn the user\nof any negative consequences if the process doesn’t progress, such as data\ncorruption or data loss.\n\nUse a secondary button or a link for cancel actions.\n\n\n\n\n\n\n\n\n\n## Clear\n\nClear removes data from a field or removes selections. Clear can also delete the\ncontents of a document, such as a log. For controls that have a default\nselection or value, such as radio buttons, the default selection or value is\nreset.\n\nUse the `close` icon on the right side of a field, item, or value.\n\n\n\n\n\n\n\n\n\n## Close\n\nClose terminates the current page, window, or menu. Close is also used to\ndismiss information, such as notifications.\n\nUse the `close` icon, which is typically placed on the upper right side of the\nelement. Do not use close in a button.\n\n\n\n\n\n\n\n\n\n## Copy\n\nCopy creates a new identical instance of the selected object(s).\n\nUse the `copy` icon with a confirmation \"copied\" tooltip appearing post-click or\ntap.\n\n\n\n\n\n\n\n\n\n## Delete\n\nDelete destroys an object. Delete actions cannot be easily undone and are\ntypically permanent. Warn the user of any negative consequences if an object is\ndestroyed, such as loss of data. Use either the `delete` or `trash can` icon, a\ndanger button, or a danger option in a menu. A danger modal is used when a\nwarning is needed to confirm an action.\n\n\n\n\n\n\n\n\n\n### Low-impact deletion\n\nUse when it’s trivial to undo deletion or recreate the data. Delete the data\nupon click or tap without further warning.\n\n### Moderate-impact deletion\n\nUse when an action cannot be undone or the data cannot be recreated easily. This\npattern is also useful if you’re deleting more than one thing.\n\nAsk for confirmation of the delete, with guidance about what will occur if they\ndelete.\n\n### High-impact deletion\n\nUse when it would be very expensive or time-consuming to recreate data. Also use\nif the action deletes a large amount of data, or if other important items would\nbe deleted as a result of the action.\n\nIn addition to presenting a dialog, have the user type the name of the resource\nthey are deleting (manual confirmation).\n\n### Post-deletion\n\nAfter the user deletes data, return to the page that lists the data deleted.\nAnimate the removal of the data from the list or page and present a success\nnotification.\n\nIf the deletion fails, raise a notification to tell the user that deletion\nfailed. Send a second notification on another communication channel, like email,\nif possible. Animate the data back onto the page if possible.\n\n## Edit\n\nEdit allows data or values to be changed. Edit commonly triggers a state change\nto the targeted object or input item.\n\nOffer edit as an option in a menu, or as a button or `edit` icon.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n## Errors\n\nErrors occur when an action or process does not succeed. Error notifications can\noccupy full pages, form fields, notifications, and modals. Error notifications\nshould provide context of what happened and a clear path to continue.\n\n\n\n\n\n\n\n\n\nConsider redirecting the user to a previous state, a support page, or offering\nrecommendations. Be honest and helpful.\n\nSome components, like text input and form field errors, are quite small and\nrequire more thoughtful approaches to the space and placement of error handling.\nConsider inline error notifications for these instances.\n\n### Content guidelines\n\nBe brief, honest, and supportive. Explain what happened and what can the user do\nto resolve the error.\n\nFor full-page and large modals, keep error messages no longer than three\nparagraph lines. For form errors, keep error messages no longer than two lines.\n\n## Next\n\nNext advances the user to the next step in a sequence of steps, like in a\nwizard.\n\nRepresent next with a [button with icon](/components/button/usage) or a\nstandalone `forward` icon.\n\n\n\n\n\n\n\n\n\n## Refresh\n\nThis action reloads the view of an object, list, or data set when the displayed\nview has become unsynchronized with the source.\n\nUse the `refresh` icon or a button.\n\n\n\n\n\n\n\n\n\n## Remove\n\nThis action removes an object from a list or item. Remove is distinct from\ndelete, as a removed item is not destroyed. Multiple objects can be removed at\nonce.\n\n\n\n\n\n\n\n\n\n### Hierarchy and placement\n\nRepresent remove as a button or `subtract` icon or glyph. The remove action is\nrarely the primary action on the page and should not be overly emphasized.\n\n### Considerations\n\n- What are the implications of the remove action for the user? Are there\n financial, access, or legal considerations?\n- This action can be confused with deleting.\n- A user may not have the correct permissions for this action.\n- Inform the user if the result is permanent.\n- How long will the action take? Seconds, minutes, hours, or days?\n- What should the user do if the removal fails?\n- Is this a single or bulk action?\n\n## Reset\n\nReset reverts values back to their last saved state. The last saved state\nincludes the values stored the last time the user clicked or triggered\n**Apply**.\n\n\n\n\nReset is typically applied as a link.\n\n\n\n\n\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/patterns/common-actions/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/patterns/dialog-pattern/page-data.json b/page-data/patterns/dialog-pattern/page-data.json
index 3f3b751a04a..de3c293b5ef 100644
--- a/page-data/patterns/dialog-pattern/page-data.json
+++ b/page-data/patterns/dialog-pattern/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-patterns-dialog-pattern-index-mdx","path":"/patterns/dialog-pattern/","result":{"pageContext":{"frontmatter":{"title":"Dialogs","description":"A dialog is a “conversation” between the system and the user. It is prompted when the system needs input from the user or to give the user urgent information concerning their current workflow."},"relativePagePath":"/patterns/dialog-pattern/index.mdx","titleType":"prepend","MdxNode":{"id":"65c8fae2-53b6-5573-a973-835b04fae326","children":[],"parent":"48c172c5-3ab2-5225-b468-5495ec109a83","internal":{"content":"---\ntitle: Dialogs\ndescription:\n A dialog is a “conversation” between the system and the user. It is prompted\n when the system needs input from the user or to give the user urgent\n information concerning their current workflow.\n---\n\n\n\nA dialog is a “conversation” between the system and the user. It is prompted\nwhen the system needs input from the user or to give the user urgent information\nconcerning their current workflow. There are two types of dialogs, modal and\nnon-modal.\n\n\n\n\n\nOverview\nModal dialogs\nNon-modal dialogs\nDesigning with dialogs\nRelated components and patterns\nAccessibility\nReferences\nFeedback\n\n\n\n## Overview\n\nDialogs work best when used for short tasks or to alert the user to task\nrelevant information. Dialogs are useful in many scenarios; they are less\ndisorientating than navigating a user to a new page for simple tasks or\nknowledge gathering. However, dialogs are disruptive and can be distracting to\nthe user. Use them sparingly.\n\nA dialog is triggered by a user’s action, appears on top of the main page\ncontent, and is persistent until dismissed. The purpose of a dialog should be\nimmediately apparent to the user, with a clear and obvious path to completion.\n\n### Anatomy of a dialog\n\n\n\n\n\n\n\n\n\n1. **Header:** Includes a title, optional label, and the close icon. The title\n should be brief and clearly describe the dialogs’s task or purpose. Use the\n optional label above the title set the context for the information in the\n dialog.\n2. **Body:** Contains the information and/or controls needed to complete the\n dialog’s task. It can include message text and components.\n3. **Actions:** The main actions needed to complete or cancel the dialog task.\n [Button groupings](/patterns/dialog-pattern#button-groups) change based on\n modal variant. Use descriptive words for the actions like Add, Delete, Save\n and avoid vague words like Done or OK.\n4. **x:** The close `x` icon will close the dialog without submitting any data.\n5. **Overlay:** (Modal dialogs only) Screen overlay that obscures the on page\n content.\n\n### When to use a dialog\n\n- Use to focus the user’s attention.\n- Use for short task completion.\n- Use to gather input from the user.\n- Use to display relevant information.\n\n### When not to use a dialog\n\n- Don’t use if the content is unrelated to the current workflow.\n- Don’t use to display complex or large amounts of data.\n- Don’t recreate a full app or page in a dialog.\n- Don’t use when the user hasn’t triggered the dialog.\n\n### Dialog types\n\nThere are two types of dialogs, modal and non-modal.\n\nA _modal_ dialog triggers a state (or mode) that focuses the user’s attention\nexclusively on one task or piece of relevant information. When a modal dialog is\nactive, the content of the underneath page is obscured and inaccessible until\nthe user completes the task or dismisses the modal.\n\nWhen a _non-modal_ dialog is active the user can continue viewing and\ninteracting with the main page while the dialog is open. Non-modal dialogs are\ncommonly used to present non-critical information or optional user tasks.\n\n| Type | Usage | Context |\n| --------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Modal | Use to present critical information or request required input needed to complete a workflow. | Focuses the users attention exclusively on one task or piece of information. On-page content is obscured from the user while the modal dialog is open. |\n| Non-modal | Use to present non-critical information or optional user tasks. | On-page content can be accessed and interacted with while the dialog is still open. |\n\n\n\n\n\n\n\n\n\n
Modal dialog (left) and non-modal dialog (right)
\n\n### Best practices\n\n#### Use dialogs sparingly\n\nDon’t overuse dialogs. They are disruptive and can easily annoy the user if used\nincorrectly or too frequently. When dialogs are used for non-workflow related\ntasks, it is likely a user will start ignoring or dismissing the dialogs without\nfully understanding the content. This can cause users to make hurried or\nimpulsive choices when dealing with more critical dialogs.\n\n#### Dialogs should be user initiated\n\nA user action, such as clicking a button, should trigger the dialog to open.\nDon’t interrupt the user by opening a dialog when they aren’t expecting it.\nAvoid system generated pop-ups that distract the user while working, such as Net\nPromoter Score. Triggers can either be a direct or indirect consequence of a\nuser’s action. An example of an indirect action is a user closing a tab with\nunsaved content that then causes a dialog to ask if they want to save their\nchanges before closing. If the system is autogenerating an alert that is not a\nconsequence of a user’s action, but a response to processes happening in the\nbackground, then a toast notification should be used instead.\n\n#### Keep dialog tasks simple and focused\n\nDialog tasks should be direct and easy to complete. Avoid feature creep in\ndialogs where a once simple dialog has become bloated with interactions. When\ndeciding to use a dialog consider how the task could expanded in the future and\nif a dialog will be able to effectively incorporate additions. An example of a\nsimple task would adding a new item to a list where the item details are added\nand submitted via a dialog.\n\n## Modal dialogs\n\nUse a modal dialog to present critical information or request user input needed\nto complete a user’s workflow. Modal dialogs are disruptive and should be used\nsparingly. When active, a user is blocked from the on-page content and cannot\nreturn to their previous workflow until the modal task is completed or the user\ndismisses the modal. Any information or input requested should be directly\nrelated to the user’s task at hand.\n\nModal dialogs are commonly used for short and non-frequent tasks, such as\nediting or management tasks. If a user needs to repeatedly perform a task,\nconsider making the task do-able from the main page. A modal dialog adds to a\nworkflow’s interaction cost; it takes the user out of their previous context and\nrequires additional actions to complete and dismiss. When considering, ask is\nthis critical to their current workflow?\n\n\n\n\n\n\n\n\n\n### When to use\n\n#### An immediate response is required from the user\n\nUse a dialog to request information that is preventing the system from\ncontinuing a user-initiated process.\n\n#### Notify the user of urgent information\n\nUse a modal dialog to notify the user of urgent information concerning their\ncurrent work. Commonly used to report system errors or convey a consequence of a\nuser’s action.\n\n#### Confirm a user decision\n\nUse a modal dialog to confirm user decisions. Clearly describe the action being\nconfirmed and explain any potential consequences that it may cause. Both the\ntitle and the button should reflect the action that will occur. If the action is\ndestructive or irreversible then use a transactional danger modal.\n\n### When not to use\n\n#### Modals prevent access to the main page\n\nDon’t use if additional information outside the modal needs to be consulted.\nWhile a modal dialog is active a user cannot interact with the main page and is\nrestricted to only the information in the modal for making decisions. Modal\ntasks should be easy to complete with the limited information presented in the\ndialog itself. If a user needs access to additional information then consider\nusing a full page instead.\n\n#### Don’t nest modals\n\nOne modal should never trigger another modal. If the first modal task is\ndependent on a confirmation modal to approve then that first task should not be\npreformed in a modal.\n\n#### Don’t make modals full page\n\nIf a modal dialog needs more space than the large modal component allows then\nthe content should be displayed on a page of its own and not in a modal. A modal\nis not an alternative to page.\n\n### Modal variants\n\n\n\n\n\n\n\n\n\n| Variant | Usage |\n| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |\n| [Passive](/components/modal/usage#passive-modal) | Presents information the user needs to be aware of concerning their current workflow. Contains no actions for the user to take. |\n| [Transactional](/components/modal/usage#transactional-modal) | Requires an action to be taken in order for the modal to be completed and closed. Contains a cancel and primary action buttons. |\n| [Acknowledgment](/components/modal/usage#acknowledgment-modal) | System requires an acknowledgement of the information from the user. Contains only a single button, commonly \"OK\". |\n| [Progress](/components/modal/usage/#progress-modal) | Requires several steps to be completed before it can be closed. Contains a cancel, previous and next/completion buttons. |\n\n### Dismissing variant modals\n\nFor passive modals:\n\n- **x**: Clicking the close `x` icon in the upper right will close the modal\n without submitting any data and return the user to its previous context.\n- **Click elsewhere**: Clicking outside the passive modal area will\n automatically close the modal.\n- **Esc**: Press `ESC` on the keyboard\n\nFor transactional, progress, and acknowledgement modals:\n\n- **Task completion**: clicking the primary action will complete the task and\n automatically close the modal.\n- **Cancel button**: clicking the cancel button will close the modal and return\n the user to its previous context. Cancel undoes all applied changes.\n- **x**: Clicking the close `x` icon in the upper right will close the modal\n without submitting any data and return the user to its previous context.\n- **Esc**: Press `ESC` on the keyboard\n\n## Non-modal dialogs\n\nUse non-modal dialogs to display non-critical information or optional tasks\nrelated to the user’s current workflow, like \"find and replace\". A user still\nhas access to the on-page content while the non-modal dialog is open and a\nresponse is not required to continue working. However, a non-modal dialog does\nrequire an action from the user to be dismissed.\n\n\n\n\n\n\n\n\n\n \n\n### When to use\n\n#### When access to the page is needed\n\nUse when a user needs to compare or refer to information in the main page\nalongside the modal. users can interact with the non-modal content and the\non-page content simultaneously.\n\nA non-modal dialog window can be moved from its original placement on the\nscreen. This allows the user to access information that might otherwise be\nhidden by the dialog.\n\n#### Aid or accelerate a user’s work flow\n\nUse to perform tasks or present informational along side the main page content\nthat can accelerate or aid a user’s workflow. For example, a \"find and replace\"\ndialog can help a user perform and automate edits quicker. The user can chose to\nautomate the changes or navigate through the page by using the \"find\" feature\nand manually make updates.\n\n#### Display additional information\n\nUse to display additional information that can help inform a user’s decision or\nworkflow. For example, use for incontext help or tutorials such as a knowledge\ncenter.\n\n### When not to use\n\n#### Don’t use if the user’s response is required\n\nUse for optional or non-critical tasks only. If a user’s response or input is\nrequired to progress the workflow, use a modal dialog.\n\n### Non-modal variants\n\n| Name | Description |\n| ------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| Passive | Presents additional information concerning the user’s current workflow. Contains no actions for the user to take. |\n| Transactional | Presents the user with optional action/s. Actions can be repeated without closing the dialog. Contains at least one button. |\n\n### Dismissing non-modal dialogs\n\nThere are several possible ways to exit a non-modal dialog.\n\n- **x**: Clicking the close `x` icon in the upper right will close the modal\n without submitting any data.\n- **Cancel button**: If a cancel button is used then clicking it will close the\n modal. Cancel undoes all applied changes.\n- **Esc**: Press `ESC` on the keyboard\n\n## Designing with dialogs\n\n### Button groups\n\nWhen placing buttons, Cancel is always the outmost left button option and the\nprimary action is always the outmost right button. There should only ever be one\nprimary action per dialog. Dialog buttons are always full bleed and attached to\nthe bottom of a dialog.\n\n\n\n\n\n\n\n\n\n
\n Button groups: one button, two buttons, three buttons, and progress buttons.\n
\n\n#### One button\n\nSingle buttons are placed on the right side, span 50% of the dialog, and bleed\nto the edge. The single button format is most commonly used for acknowledgment\ndialogs. In most scenarios, a primary button is used when only one button is\nneeded.\n\n#### Two buttons\n\nWhen using two buttons, the secondary button is on the left and the primary\nbutton is placed on the right. Each button spans 50% of the dialog and are full\nbleed to the edge.\n\n#### Three buttons\n\nWhen three buttons are needed, each is 25% of the dialog width and aligned to\nthe right side of the dialog. Only the outmost right button is allowed to be a\nprimary button with the other two being secondary buttons. If all three actions\nhave the same weight then all three should be secondary buttons.\n\n#### Progress indicator buttons\n\nThe three progress indicator buttons are: Cancel, Previous, Next. Each button’s\nwidth is 25% of the dialog window and are full bleed. Previous and Next should\nbe grouped together and placed on the right half of the dialog, with Previous as\na secondary button and Next as a primary button. The Cancel button is aligned to\nleft side of the dialog and uses a ghost button.\n\nIn the last step of the sequence, the Next button label should change to reflect\nthe final action.\n\n### Behaviors\n\n#### Trigger\n\nDialogs are triggered as a result of a user’s action and are not system\ngenerated. Common components that can trigger a dialog include, button, link, or\nicon.\n\n#### Focus\n\nOnce the dialog is open, set the initial focus to the first location that\naccepts user input. Focus should then remain trapped in the dialog until it is\nclosed.\n\n#### Scrolling\n\nThe modal component has four set sizes and each size has a set max-height. If\nthe dialog content is longer than the dialog height then the body section should\nscroll vertically with the header and footer remaining fixed in place.\n\n#### Validation\n\nValidate a user’s entries before the dialog is closed. If any entry is invalid\nthen the dialog should remain open with the entry marked with an error state and\ninclude an inline error message. The message should inform the user what has\nhappened and provide guidance on next steps or possible resolutions. Effective\nand immediate error messaging can help the user to understand the problem and\nhow to fix it.\n\nWhen possible, we recommend validating the user’s data before submission. This\ntype of inline validation (aka\n[client-side validation](/patterns/forms-pattern#errors-and-validation)) should\nhappen as soon as the field loses focus. This will help easily identify the\nelements that need to be corrected. On field error messages should disappear\nwhen the form criteria is met. If the data was not able to be submitted due to\nserver-side issues then an inline notification should appear.\n\nDecrease the chances of invalid data by using selection controls and bound entry\ncontrols components that provide users with specific input choices, for example\nradio buttons and dropdowns.\n\n\n\n\n\n\n\n\n\n
\n Real-time validation. The user has left the first required field empty.{' '}\n
\n\n#### Task completion and loading\n\nThe task completion action should take place immediately. If a short loading\nperiod is needed then a loading spinner and overlay should appear on top of the\nmodal body area with content disabled. The primary action button should be\ndisabled while loading is in progress.\n\nIf the action requires more than a few seconds to complete, display progress\ninformation elsewhere on the screen to inform the user how long it will take to\ncomplete.\n\n\n\n\n\n\n\n\n\n### Using components\n\nAppropriate components to use in a dialog include form inputs and controls that\naid in collecting information from the user. Other components like content\nswitcher and structured list can be used to organize information. When possible,\navoid using complex components that can complicate task completion or prolong a\nuser’s time in the modal. A user’s journey through the modal should be direct\nand short.\n\n#### Avoid components that will direct the user away from the dialog\n\nAvoid components like links that will take the user away from the current\ncontext and the task at hand. A dialog’s purpose is to focus the user’s\nattention on a particular task and should not encourage any action that is not\nrelated to that task’s completion.\n\n#### Avoid components that hide information\n\nWhen possible avoid components that hide information or choices from the\nuser—like accordion and tabs—and require additional effort from the user to\ndiscover all the available content. Time spent in a modal should be minimal and\nonly information needed to complete the task should be included. If there is too\nmuch information for a user to consume in a dialog context, consider using a\nfull page instead.\n\n#### Avoid complex interactions with data tables\n\nWhen possible avoid using a data table in a dialog as it is a complex component\nwith its own workflow and decision making that can overly complicate a user’s\nchoice and task completion in relation to the dialog. If a data table is\nnecessary then the tables should be kept as simple as possible with limited\ninteractions. For example, you can use data table to make selections that will\nbe incurred by the dialogs action but avoid preforming table functions like\nbatch editing or batch actions inside the modal itself. For smaller sets of data\nor selections consider using a structured list, dropdown, or tile set instead.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n## Accessibility\n\n### Focus\n\n1. Shift the focus into the dialog when triggered.\n2. After the dialog opens, initial focus should be set on the first focusable\n element in the modal.\n3. For modal dialogs, the focus should be trapped inside the dialog and must not\n move outside the modal until it is closed.\n4. After a modal dialog closes, focus should return to the element that invoked\n the modal.\n\nReference\n[WCAG 2.4.3 Focus order success criterion](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-focus-order.html)\nfor additional guidelines.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n### Keyboard navigation\n\n- `ESC`: close the dialog\n- `tab`: navigates the user to the different interactive elements\n- `space bar`: triggers the selected element\n- `enter`: triggers the selected element\n\n### Tab order\n\n1. First interactive element in the body area.\n2. Proceed left to right and top to bottom through the rest of the body\n elements.\n3. Primary action\n4. Secondary action\n5. Close icon\n\n### ARIA\n\nSee WAI-ARIA Authoring Practices\n[Modal Dialog Example, Accessibility Features](https://www.w3.org/TR/wai-aria-practices-1.1/examples/dialog-modal/dialog.html)\nsection for best practices.\n\n## Related components and patterns\n\n\n\n\n#### Components:\n\n- [Buttons](/components/button/usage)\n- [Modal](/components/modal/usage)\n- [Notification](/components/notification/usage)\n\n\n\n\n#### Patterns:\n\n- [Forms](/patterns/forms-pattern)\n- [Notifications](/patterns/notification-pattern)\n\n\n\n\n## References\n\n- Apple Human Interface Guidelines,\n [Modality](https://developer.apple.com/design/human-interface-guidelines/ios/app-architecture/modality/)\n (2019)\n- Apple Human Interface Guidelines,\n [Dialogs](https://developer.apple.com/design/human-interface-guidelines/macos/windows-and-views/dialogs/)\n (2019)\n- Therese Fessenden,\n [Modal & Nonmodal Dialogs: When (& When Not) to Use Them](https://www.nngroup.com/articles/modal-nonmodal-dialog/)\n (Nielsen Norman Group, 2017)\n- James Jacobs,\n [Modern Enterprise UI design — Part 2: Modal dialogs](https://medium.com/pulsar/modern-enterprise-ui-design-part-2-modal-dialogs-2ccd3cc33c92)\n (2019)\n- Micosoft Docs,\n [About Dialog Boxes](https://docs.microsoft.com/en-us/windows/win32/dlgbox/about-dialog-boxes)\n (2019)\n- [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/)\n (W3C, 2018)\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments on\n[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","type":"Mdx","contentDigest":"f2d82eb1cc6e2a4decfe552b6946aa38","owner":"gatsby-plugin-mdx","counter":5336},"frontmatter":{"title":"Dialogs","description":"A dialog is a “conversation” between the system and the user. It is prompted when the system needs input from the user or to give the user urgent information concerning their current workflow."},"exports":{},"rawBody":"---\ntitle: Dialogs\ndescription:\n A dialog is a “conversation” between the system and the user. It is prompted\n when the system needs input from the user or to give the user urgent\n information concerning their current workflow.\n---\n\n\n\nA dialog is a “conversation” between the system and the user. It is prompted\nwhen the system needs input from the user or to give the user urgent information\nconcerning their current workflow. There are two types of dialogs, modal and\nnon-modal.\n\n\n\n\n\nOverview\nModal dialogs\nNon-modal dialogs\nDesigning with dialogs\nRelated components and patterns\nAccessibility\nReferences\nFeedback\n\n\n\n## Overview\n\nDialogs work best when used for short tasks or to alert the user to task\nrelevant information. Dialogs are useful in many scenarios; they are less\ndisorientating than navigating a user to a new page for simple tasks or\nknowledge gathering. However, dialogs are disruptive and can be distracting to\nthe user. Use them sparingly.\n\nA dialog is triggered by a user’s action, appears on top of the main page\ncontent, and is persistent until dismissed. The purpose of a dialog should be\nimmediately apparent to the user, with a clear and obvious path to completion.\n\n### Anatomy of a dialog\n\n\n\n\n\n\n\n\n\n1. **Header:** Includes a title, optional label, and the close icon. The title\n should be brief and clearly describe the dialogs’s task or purpose. Use the\n optional label above the title set the context for the information in the\n dialog.\n2. **Body:** Contains the information and/or controls needed to complete the\n dialog’s task. It can include message text and components.\n3. **Actions:** The main actions needed to complete or cancel the dialog task.\n [Button groupings](/patterns/dialog-pattern#button-groups) change based on\n modal variant. Use descriptive words for the actions like Add, Delete, Save\n and avoid vague words like Done or OK.\n4. **x:** The close `x` icon will close the dialog without submitting any data.\n5. **Overlay:** (Modal dialogs only) Screen overlay that obscures the on page\n content.\n\n### When to use a dialog\n\n- Use to focus the user’s attention.\n- Use for short task completion.\n- Use to gather input from the user.\n- Use to display relevant information.\n\n### When not to use a dialog\n\n- Don’t use if the content is unrelated to the current workflow.\n- Don’t use to display complex or large amounts of data.\n- Don’t recreate a full app or page in a dialog.\n- Don’t use when the user hasn’t triggered the dialog.\n\n### Dialog types\n\nThere are two types of dialogs, modal and non-modal.\n\nA _modal_ dialog triggers a state (or mode) that focuses the user’s attention\nexclusively on one task or piece of relevant information. When a modal dialog is\nactive, the content of the underneath page is obscured and inaccessible until\nthe user completes the task or dismisses the modal.\n\nWhen a _non-modal_ dialog is active the user can continue viewing and\ninteracting with the main page while the dialog is open. Non-modal dialogs are\ncommonly used to present non-critical information or optional user tasks.\n\n| Type | Usage | Context |\n| --------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Modal | Use to present critical information or request required input needed to complete a workflow. | Focuses the users attention exclusively on one task or piece of information. On-page content is obscured from the user while the modal dialog is open. |\n| Non-modal | Use to present non-critical information or optional user tasks. | On-page content can be accessed and interacted with while the dialog is still open. |\n\n\n\n\n\n\n\n\n\n
Modal dialog (left) and non-modal dialog (right)
\n\n### Best practices\n\n#### Use dialogs sparingly\n\nDon’t overuse dialogs. They are disruptive and can easily annoy the user if used\nincorrectly or too frequently. When dialogs are used for non-workflow related\ntasks, it is likely a user will start ignoring or dismissing the dialogs without\nfully understanding the content. This can cause users to make hurried or\nimpulsive choices when dealing with more critical dialogs.\n\n#### Dialogs should be user initiated\n\nA user action, such as clicking a button, should trigger the dialog to open.\nDon’t interrupt the user by opening a dialog when they aren’t expecting it.\nAvoid system generated pop-ups that distract the user while working, such as Net\nPromoter Score. Triggers can either be a direct or indirect consequence of a\nuser’s action. An example of an indirect action is a user closing a tab with\nunsaved content that then causes a dialog to ask if they want to save their\nchanges before closing. If the system is autogenerating an alert that is not a\nconsequence of a user’s action, but a response to processes happening in the\nbackground, then a toast notification should be used instead.\n\n#### Keep dialog tasks simple and focused\n\nDialog tasks should be direct and easy to complete. Avoid feature creep in\ndialogs where a once simple dialog has become bloated with interactions. When\ndeciding to use a dialog consider how the task could expanded in the future and\nif a dialog will be able to effectively incorporate additions. An example of a\nsimple task would adding a new item to a list where the item details are added\nand submitted via a dialog.\n\n## Modal dialogs\n\nUse a modal dialog to present critical information or request user input needed\nto complete a user’s workflow. Modal dialogs are disruptive and should be used\nsparingly. When active, a user is blocked from the on-page content and cannot\nreturn to their previous workflow until the modal task is completed or the user\ndismisses the modal. Any information or input requested should be directly\nrelated to the user’s task at hand.\n\nModal dialogs are commonly used for short and non-frequent tasks, such as\nediting or management tasks. If a user needs to repeatedly perform a task,\nconsider making the task do-able from the main page. A modal dialog adds to a\nworkflow’s interaction cost; it takes the user out of their previous context and\nrequires additional actions to complete and dismiss. When considering, ask is\nthis critical to their current workflow?\n\n\n\n\n\n\n\n\n\n### When to use\n\n#### An immediate response is required from the user\n\nUse a dialog to request information that is preventing the system from\ncontinuing a user-initiated process.\n\n#### Notify the user of urgent information\n\nUse a modal dialog to notify the user of urgent information concerning their\ncurrent work. Commonly used to report system errors or convey a consequence of a\nuser’s action.\n\n#### Confirm a user decision\n\nUse a modal dialog to confirm user decisions. Clearly describe the action being\nconfirmed and explain any potential consequences that it may cause. Both the\ntitle and the button should reflect the action that will occur. If the action is\ndestructive or irreversible then use a transactional danger modal.\n\n### When not to use\n\n#### Modals prevent access to the main page\n\nDon’t use if additional information outside the modal needs to be consulted.\nWhile a modal dialog is active a user cannot interact with the main page and is\nrestricted to only the information in the modal for making decisions. Modal\ntasks should be easy to complete with the limited information presented in the\ndialog itself. If a user needs access to additional information then consider\nusing a full page instead.\n\n#### Don’t nest modals\n\nOne modal should never trigger another modal. If the first modal task is\ndependent on a confirmation modal to approve then that first task should not be\npreformed in a modal.\n\n#### Don’t make modals full page\n\nIf a modal dialog needs more space than the large modal component allows then\nthe content should be displayed on a page of its own and not in a modal. A modal\nis not an alternative to page.\n\n### Modal variants\n\n\n\n\n\n\n\n\n\n| Variant | Usage |\n| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |\n| [Passive](/components/modal/usage#passive-modal) | Presents information the user needs to be aware of concerning their current workflow. Contains no actions for the user to take. |\n| [Transactional](/components/modal/usage#transactional-modal) | Requires an action to be taken in order for the modal to be completed and closed. Contains a cancel and primary action buttons. |\n| [Acknowledgment](/components/modal/usage#acknowledgment-modal) | System requires an acknowledgement of the information from the user. Contains only a single button, commonly \"OK\". |\n| [Progress](/components/modal/usage/#progress-modal) | Requires several steps to be completed before it can be closed. Contains a cancel, previous and next/completion buttons. |\n\n### Dismissing variant modals\n\nFor passive modals:\n\n- **x**: Clicking the close `x` icon in the upper right will close the modal\n without submitting any data and return the user to its previous context.\n- **Click elsewhere**: Clicking outside the passive modal area will\n automatically close the modal.\n- **Esc**: Press `ESC` on the keyboard\n\nFor transactional, progress, and acknowledgement modals:\n\n- **Task completion**: clicking the primary action will complete the task and\n automatically close the modal.\n- **Cancel button**: clicking the cancel button will close the modal and return\n the user to its previous context. Cancel undoes all applied changes.\n- **x**: Clicking the close `x` icon in the upper right will close the modal\n without submitting any data and return the user to its previous context.\n- **Esc**: Press `ESC` on the keyboard\n\n## Non-modal dialogs\n\nUse non-modal dialogs to display non-critical information or optional tasks\nrelated to the user’s current workflow, like \"find and replace\". A user still\nhas access to the on-page content while the non-modal dialog is open and a\nresponse is not required to continue working. However, a non-modal dialog does\nrequire an action from the user to be dismissed.\n\n\n\n\n\n\n\n\n\n \n\n### When to use\n\n#### When access to the page is needed\n\nUse when a user needs to compare or refer to information in the main page\nalongside the modal. users can interact with the non-modal content and the\non-page content simultaneously.\n\nA non-modal dialog window can be moved from its original placement on the\nscreen. This allows the user to access information that might otherwise be\nhidden by the dialog.\n\n#### Aid or accelerate a user’s work flow\n\nUse to perform tasks or present informational along side the main page content\nthat can accelerate or aid a user’s workflow. For example, a \"find and replace\"\ndialog can help a user perform and automate edits quicker. The user can chose to\nautomate the changes or navigate through the page by using the \"find\" feature\nand manually make updates.\n\n#### Display additional information\n\nUse to display additional information that can help inform a user’s decision or\nworkflow. For example, use for incontext help or tutorials such as a knowledge\ncenter.\n\n### When not to use\n\n#### Don’t use if the user’s response is required\n\nUse for optional or non-critical tasks only. If a user’s response or input is\nrequired to progress the workflow, use a modal dialog.\n\n### Non-modal variants\n\n| Name | Description |\n| ------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| Passive | Presents additional information concerning the user’s current workflow. Contains no actions for the user to take. |\n| Transactional | Presents the user with optional action/s. Actions can be repeated without closing the dialog. Contains at least one button. |\n\n### Dismissing non-modal dialogs\n\nThere are several possible ways to exit a non-modal dialog.\n\n- **x**: Clicking the close `x` icon in the upper right will close the modal\n without submitting any data.\n- **Cancel button**: If a cancel button is used then clicking it will close the\n modal. Cancel undoes all applied changes.\n- **Esc**: Press `ESC` on the keyboard\n\n## Designing with dialogs\n\n### Button groups\n\nWhen placing buttons, Cancel is always the outmost left button option and the\nprimary action is always the outmost right button. There should only ever be one\nprimary action per dialog. Dialog buttons are always full bleed and attached to\nthe bottom of a dialog.\n\n\n\n\n\n\n\n\n\n
\n Button groups: one button, two buttons, three buttons, and progress buttons.\n
\n\n#### One button\n\nSingle buttons are placed on the right side, span 50% of the dialog, and bleed\nto the edge. The single button format is most commonly used for acknowledgment\ndialogs. In most scenarios, a primary button is used when only one button is\nneeded.\n\n#### Two buttons\n\nWhen using two buttons, the secondary button is on the left and the primary\nbutton is placed on the right. Each button spans 50% of the dialog and are full\nbleed to the edge.\n\n#### Three buttons\n\nWhen three buttons are needed, each is 25% of the dialog width and aligned to\nthe right side of the dialog. Only the outmost right button is allowed to be a\nprimary button with the other two being secondary buttons. If all three actions\nhave the same weight then all three should be secondary buttons.\n\n#### Progress indicator buttons\n\nThe three progress indicator buttons are: Cancel, Previous, Next. Each button’s\nwidth is 25% of the dialog window and are full bleed. Previous and Next should\nbe grouped together and placed on the right half of the dialog, with Previous as\na secondary button and Next as a primary button. The Cancel button is aligned to\nleft side of the dialog and uses a ghost button.\n\nIn the last step of the sequence, the Next button label should change to reflect\nthe final action.\n\n### Behaviors\n\n#### Trigger\n\nDialogs are triggered as a result of a user’s action and are not system\ngenerated. Common components that can trigger a dialog include, button, link, or\nicon.\n\n#### Focus\n\nOnce the dialog is open, set the initial focus to the first location that\naccepts user input. Focus should then remain trapped in the dialog until it is\nclosed.\n\n#### Scrolling\n\nThe modal component has four set sizes and each size has a set max-height. If\nthe dialog content is longer than the dialog height then the body section should\nscroll vertically with the header and footer remaining fixed in place.\n\n#### Validation\n\nValidate a user’s entries before the dialog is closed. If any entry is invalid\nthen the dialog should remain open with the entry marked with an error state and\ninclude an inline error message. The message should inform the user what has\nhappened and provide guidance on next steps or possible resolutions. Effective\nand immediate error messaging can help the user to understand the problem and\nhow to fix it.\n\nWhen possible, we recommend validating the user’s data before submission. This\ntype of inline validation (aka\n[client-side validation](/patterns/forms-pattern#errors-and-validation)) should\nhappen as soon as the field loses focus. This will help easily identify the\nelements that need to be corrected. On field error messages should disappear\nwhen the form criteria is met. If the data was not able to be submitted due to\nserver-side issues then an inline notification should appear.\n\nDecrease the chances of invalid data by using selection controls and bound entry\ncontrols components that provide users with specific input choices, for example\nradio buttons and dropdowns.\n\n\n\n\n\n\n\n\n\n
\n Real-time validation. The user has left the first required field empty.{' '}\n
\n\n#### Task completion and loading\n\nThe task completion action should take place immediately. If a short loading\nperiod is needed then a loading spinner and overlay should appear on top of the\nmodal body area with content disabled. The primary action button should be\ndisabled while loading is in progress.\n\nIf the action requires more than a few seconds to complete, display progress\ninformation elsewhere on the screen to inform the user how long it will take to\ncomplete.\n\n\n\n\n\n\n\n\n\n### Using components\n\nAppropriate components to use in a dialog include form inputs and controls that\naid in collecting information from the user. Other components like content\nswitcher and structured list can be used to organize information. When possible,\navoid using complex components that can complicate task completion or prolong a\nuser’s time in the modal. A user’s journey through the modal should be direct\nand short.\n\n#### Avoid components that will direct the user away from the dialog\n\nAvoid components like links that will take the user away from the current\ncontext and the task at hand. A dialog’s purpose is to focus the user’s\nattention on a particular task and should not encourage any action that is not\nrelated to that task’s completion.\n\n#### Avoid components that hide information\n\nWhen possible avoid components that hide information or choices from the\nuser—like accordion and tabs—and require additional effort from the user to\ndiscover all the available content. Time spent in a modal should be minimal and\nonly information needed to complete the task should be included. If there is too\nmuch information for a user to consume in a dialog context, consider using a\nfull page instead.\n\n#### Avoid complex interactions with data tables\n\nWhen possible avoid using a data table in a dialog as it is a complex component\nwith its own workflow and decision making that can overly complicate a user’s\nchoice and task completion in relation to the dialog. If a data table is\nnecessary then the tables should be kept as simple as possible with limited\ninteractions. For example, you can use data table to make selections that will\nbe incurred by the dialogs action but avoid preforming table functions like\nbatch editing or batch actions inside the modal itself. For smaller sets of data\nor selections consider using a structured list, dropdown, or tile set instead.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n## Accessibility\n\n### Focus\n\n1. Shift the focus into the dialog when triggered.\n2. After the dialog opens, initial focus should be set on the first focusable\n element in the modal.\n3. For modal dialogs, the focus should be trapped inside the dialog and must not\n move outside the modal until it is closed.\n4. After a modal dialog closes, focus should return to the element that invoked\n the modal.\n\nReference\n[WCAG 2.4.3 Focus order success criterion](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-focus-order.html)\nfor additional guidelines.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n### Keyboard navigation\n\n- `ESC`: close the dialog\n- `tab`: navigates the user to the different interactive elements\n- `space bar`: triggers the selected element\n- `enter`: triggers the selected element\n\n### Tab order\n\n1. First interactive element in the body area.\n2. Proceed left to right and top to bottom through the rest of the body\n elements.\n3. Primary action\n4. Secondary action\n5. Close icon\n\n### ARIA\n\nSee WAI-ARIA Authoring Practices\n[Modal Dialog Example, Accessibility Features](https://www.w3.org/TR/wai-aria-practices-1.1/examples/dialog-modal/dialog.html)\nsection for best practices.\n\n## Related components and patterns\n\n\n\n\n#### Components:\n\n- [Buttons](/components/button/usage)\n- [Modal](/components/modal/usage)\n- [Notification](/components/notification/usage)\n\n\n\n\n#### Patterns:\n\n- [Forms](/patterns/forms-pattern)\n- [Notifications](/patterns/notification-pattern)\n\n\n\n\n## References\n\n- Apple Human Interface Guidelines,\n [Modality](https://developer.apple.com/design/human-interface-guidelines/ios/app-architecture/modality/)\n (2019)\n- Apple Human Interface Guidelines,\n [Dialogs](https://developer.apple.com/design/human-interface-guidelines/macos/windows-and-views/dialogs/)\n (2019)\n- Therese Fessenden,\n [Modal & Nonmodal Dialogs: When (& When Not) to Use Them](https://www.nngroup.com/articles/modal-nonmodal-dialog/)\n (Nielsen Norman Group, 2017)\n- James Jacobs,\n [Modern Enterprise UI design — Part 2: Modal dialogs](https://medium.com/pulsar/modern-enterprise-ui-design-part-2-modal-dialogs-2ccd3cc33c92)\n (2019)\n- Micosoft Docs,\n [About Dialog Boxes](https://docs.microsoft.com/en-us/windows/win32/dlgbox/about-dialog-boxes)\n (2019)\n- [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/)\n (W3C, 2018)\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments on\n[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/patterns/dialog-pattern/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-patterns-dialog-pattern-index-mdx","path":"/patterns/dialog-pattern/","result":{"pageContext":{"frontmatter":{"title":"Dialogs","description":"A dialog is a “conversation” between the system and the user. It is prompted when the system needs input from the user or to give the user urgent information concerning their current workflow."},"relativePagePath":"/patterns/dialog-pattern/index.mdx","titleType":"prepend","MdxNode":{"id":"65c8fae2-53b6-5573-a973-835b04fae326","children":[],"parent":"48c172c5-3ab2-5225-b468-5495ec109a83","internal":{"content":"---\ntitle: Dialogs\ndescription:\n A dialog is a “conversation” between the system and the user. It is prompted\n when the system needs input from the user or to give the user urgent\n information concerning their current workflow.\n---\n\n\n\nA dialog is a “conversation” between the system and the user. It is prompted\nwhen the system needs input from the user or to give the user urgent information\nconcerning their current workflow. There are two types of dialogs, modal and\nnon-modal.\n\n\n\n\n\nOverview\nModal dialogs\nNon-modal dialogs\nDesigning with dialogs\nRelated components and patterns\nAccessibility\nReferences\nFeedback\n\n\n\n## Overview\n\nDialogs work best when used for short tasks or to alert the user to task\nrelevant information. Dialogs are useful in many scenarios; they are less\ndisorientating than navigating a user to a new page for simple tasks or\nknowledge gathering. However, dialogs are disruptive and can be distracting to\nthe user. Use them sparingly.\n\nA dialog is triggered by a user’s action, appears on top of the main page\ncontent, and is persistent until dismissed. The purpose of a dialog should be\nimmediately apparent to the user, with a clear and obvious path to completion.\n\n### Anatomy of a dialog\n\n\n\n\n\n\n\n\n\n1. **Header:** Includes a title, optional label, and the close icon. The title\n should be brief and clearly describe the dialogs’s task or purpose. Use the\n optional label above the title set the context for the information in the\n dialog.\n2. **Body:** Contains the information and/or controls needed to complete the\n dialog’s task. It can include message text and components.\n3. **Actions:** The main actions needed to complete or cancel the dialog task.\n [Button groupings](/patterns/dialog-pattern#button-groups) change based on\n modal variant. Use descriptive words for the actions like Add, Delete, Save\n and avoid vague words like Done or OK.\n4. **x:** The close `x` icon will close the dialog without submitting any data.\n5. **Overlay:** (Modal dialogs only) Screen overlay that obscures the on page\n content.\n\n### When to use a dialog\n\n- Use to focus the user’s attention.\n- Use for short task completion.\n- Use to gather input from the user.\n- Use to display relevant information.\n\n### When not to use a dialog\n\n- Don’t use if the content is unrelated to the current workflow.\n- Don’t use to display complex or large amounts of data.\n- Don’t recreate a full app or page in a dialog.\n- Don’t use when the user hasn’t triggered the dialog.\n\n### Dialog types\n\nThere are two types of dialogs, modal and non-modal.\n\nA _modal_ dialog triggers a state (or mode) that focuses the user’s attention\nexclusively on one task or piece of relevant information. When a modal dialog is\nactive, the content of the underneath page is obscured and inaccessible until\nthe user completes the task or dismisses the modal.\n\nWhen a _non-modal_ dialog is active the user can continue viewing and\ninteracting with the main page while the dialog is open. Non-modal dialogs are\ncommonly used to present non-critical information or optional user tasks.\n\n| Type | Usage | Context |\n| --------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Modal | Use to present critical information or request required input needed to complete a workflow. | Focuses the users attention exclusively on one task or piece of information. On-page content is obscured from the user while the modal dialog is open. |\n| Non-modal | Use to present non-critical information or optional user tasks. | On-page content can be accessed and interacted with while the dialog is still open. |\n\n\n\n\n\n\n\n\n\n
Modal dialog (left) and non-modal dialog (right)
\n\n### Best practices\n\n#### Use dialogs sparingly\n\nDon’t overuse dialogs. They are disruptive and can easily annoy the user if used\nincorrectly or too frequently. When dialogs are used for non-workflow related\ntasks, it is likely a user will start ignoring or dismissing the dialogs without\nfully understanding the content. This can cause users to make hurried or\nimpulsive choices when dealing with more critical dialogs.\n\n#### Dialogs should be user initiated\n\nA user action, such as clicking a button, should trigger the dialog to open.\nDon’t interrupt the user by opening a dialog when they aren’t expecting it.\nAvoid system generated pop-ups that distract the user while working, such as Net\nPromoter Score. Triggers can either be a direct or indirect consequence of a\nuser’s action. An example of an indirect action is a user closing a tab with\nunsaved content that then causes a dialog to ask if they want to save their\nchanges before closing. If the system is autogenerating an alert that is not a\nconsequence of a user’s action, but a response to processes happening in the\nbackground, then a toast notification should be used instead.\n\n#### Keep dialog tasks simple and focused\n\nDialog tasks should be direct and easy to complete. Avoid feature creep in\ndialogs where a once simple dialog has become bloated with interactions. When\ndeciding to use a dialog consider how the task could expanded in the future and\nif a dialog will be able to effectively incorporate additions. An example of a\nsimple task would adding a new item to a list where the item details are added\nand submitted via a dialog.\n\n## Modal dialogs\n\nUse a modal dialog to present critical information or request user input needed\nto complete a user’s workflow. Modal dialogs are disruptive and should be used\nsparingly. When active, a user is blocked from the on-page content and cannot\nreturn to their previous workflow until the modal task is completed or the user\ndismisses the modal. Any information or input requested should be directly\nrelated to the user’s task at hand.\n\nModal dialogs are commonly used for short and non-frequent tasks, such as\nediting or management tasks. If a user needs to repeatedly perform a task,\nconsider making the task do-able from the main page. A modal dialog adds to a\nworkflow’s interaction cost; it takes the user out of their previous context and\nrequires additional actions to complete and dismiss. When considering, ask is\nthis critical to their current workflow?\n\n\n\n\n\n\n\n\n\n### When to use\n\n#### An immediate response is required from the user\n\nUse a dialog to request information that is preventing the system from\ncontinuing a user-initiated process.\n\n#### Notify the user of urgent information\n\nUse a modal dialog to notify the user of urgent information concerning their\ncurrent work. Commonly used to report system errors or convey a consequence of a\nuser’s action.\n\n#### Confirm a user decision\n\nUse a modal dialog to confirm user decisions. Clearly describe the action being\nconfirmed and explain any potential consequences that it may cause. Both the\ntitle and the button should reflect the action that will occur. If the action is\ndestructive or irreversible then use a transactional danger modal.\n\n### When not to use\n\n#### Modals prevent access to the main page\n\nDon’t use if additional information outside the modal needs to be consulted.\nWhile a modal dialog is active a user cannot interact with the main page and is\nrestricted to only the information in the modal for making decisions. Modal\ntasks should be easy to complete with the limited information presented in the\ndialog itself. If a user needs access to additional information then consider\nusing a full page instead.\n\n#### Don’t nest modals\n\nOne modal should never trigger another modal. If the first modal task is\ndependent on a confirmation modal to approve then that first task should not be\npreformed in a modal.\n\n#### Don’t make modals full page\n\nIf a modal dialog needs more space than the large modal component allows then\nthe content should be displayed on a page of its own and not in a modal. A modal\nis not an alternative to page.\n\n### Modal variants\n\n\n\n\n\n\n\n\n\n| Variant | Usage |\n| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |\n| [Passive](/components/modal/usage#passive-modal) | Presents information the user needs to be aware of concerning their current workflow. Contains no actions for the user to take. |\n| [Transactional](/components/modal/usage#transactional-modal) | Requires an action to be taken in order for the modal to be completed and closed. Contains a cancel and primary action buttons. |\n| [Acknowledgment](/components/modal/usage#acknowledgment-modal) | System requires an acknowledgement of the information from the user. Contains only a single button, commonly \"OK\". |\n| [Progress](/components/modal/usage/#progress-modal) | Requires several steps to be completed before it can be closed. Contains a cancel, previous and next/completion buttons. |\n\n### Dismissing variant modals\n\nFor passive modals:\n\n- **x**: Clicking the close `x` icon in the upper right will close the modal\n without submitting any data and return the user to its previous context.\n- **Click elsewhere**: Clicking outside the passive modal area will\n automatically close the modal.\n- **Esc**: Press `ESC` on the keyboard\n\nFor transactional, progress, and acknowledgement modals:\n\n- **Task completion**: clicking the primary action will complete the task and\n automatically close the modal.\n- **Cancel button**: clicking the cancel button will close the modal and return\n the user to its previous context. Cancel undoes all applied changes.\n- **x**: Clicking the close `x` icon in the upper right will close the modal\n without submitting any data and return the user to its previous context.\n- **Esc**: Press `ESC` on the keyboard\n\n## Non-modal dialogs\n\nUse non-modal dialogs to display non-critical information or optional tasks\nrelated to the user’s current workflow, like \"find and replace\". A user still\nhas access to the on-page content while the non-modal dialog is open and a\nresponse is not required to continue working. However, a non-modal dialog does\nrequire an action from the user to be dismissed.\n\n\n\n\n\n\n\n\n\n \n\n### When to use\n\n#### When access to the page is needed\n\nUse when a user needs to compare or refer to information in the main page\nalongside the modal. users can interact with the non-modal content and the\non-page content simultaneously.\n\nA non-modal dialog window can be moved from its original placement on the\nscreen. This allows the user to access information that might otherwise be\nhidden by the dialog.\n\n#### Aid or accelerate a user’s work flow\n\nUse to perform tasks or present informational along side the main page content\nthat can accelerate or aid a user’s workflow. For example, a \"find and replace\"\ndialog can help a user perform and automate edits quicker. The user can chose to\nautomate the changes or navigate through the page by using the \"find\" feature\nand manually make updates.\n\n#### Display additional information\n\nUse to display additional information that can help inform a user’s decision or\nworkflow. For example, use for incontext help or tutorials such as a knowledge\ncenter.\n\n### When not to use\n\n#### Don’t use if the user’s response is required\n\nUse for optional or non-critical tasks only. If a user’s response or input is\nrequired to progress the workflow, use a modal dialog.\n\n### Non-modal variants\n\n| Name | Description |\n| ------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| Passive | Presents additional information concerning the user’s current workflow. Contains no actions for the user to take. |\n| Transactional | Presents the user with optional action/s. Actions can be repeated without closing the dialog. Contains at least one button. |\n\n### Dismissing non-modal dialogs\n\nThere are several possible ways to exit a non-modal dialog.\n\n- **x**: Clicking the close `x` icon in the upper right will close the modal\n without submitting any data.\n- **Cancel button**: If a cancel button is used then clicking it will close the\n modal. Cancel undoes all applied changes.\n- **Esc**: Press `ESC` on the keyboard\n\n## Designing with dialogs\n\n### Button groups\n\nWhen placing buttons, Cancel is always the outmost left button option and the\nprimary action is always the outmost right button. There should only ever be one\nprimary action per dialog. Dialog buttons are always full bleed and attached to\nthe bottom of a dialog.\n\n\n\n\n\n\n\n\n\n
\n Button groups: one button, two buttons, three buttons, and progress buttons.\n
\n\n#### One button\n\nSingle buttons are placed on the right side, span 50% of the dialog, and bleed\nto the edge. The single button format is most commonly used for acknowledgment\ndialogs. In most scenarios, a primary button is used when only one button is\nneeded.\n\n#### Two buttons\n\nWhen using two buttons, the secondary button is on the left and the primary\nbutton is placed on the right. Each button spans 50% of the dialog and are full\nbleed to the edge.\n\n#### Three buttons\n\nWhen three buttons are needed, each is 25% of the dialog width and aligned to\nthe right side of the dialog. Only the outmost right button is allowed to be a\nprimary button with the other two being secondary buttons. If all three actions\nhave the same weight then all three should be secondary buttons.\n\n#### Progress indicator buttons\n\nThe three progress indicator buttons are: Cancel, Previous, Next. Each button’s\nwidth is 25% of the dialog window and are full bleed. Previous and Next should\nbe grouped together and placed on the right half of the dialog, with Previous as\na secondary button and Next as a primary button. The Cancel button is aligned to\nleft side of the dialog and uses a ghost button.\n\nIn the last step of the sequence, the Next button label should change to reflect\nthe final action.\n\n### Behaviors\n\n#### Trigger\n\nDialogs are triggered as a result of a user’s action and are not system\ngenerated. Common components that can trigger a dialog include, button, link, or\nicon.\n\n#### Focus\n\nOnce the dialog is open, set the initial focus to the first location that\naccepts user input. Focus should then remain trapped in the dialog until it is\nclosed.\n\n#### Scrolling\n\nThe modal component has four set sizes and each size has a set max-height. If\nthe dialog content is longer than the dialog height then the body section should\nscroll vertically with the header and footer remaining fixed in place.\n\n#### Validation\n\nValidate a user’s entries before the dialog is closed. If any entry is invalid\nthen the dialog should remain open with the entry marked with an error state and\ninclude an inline error message. The message should inform the user what has\nhappened and provide guidance on next steps or possible resolutions. Effective\nand immediate error messaging can help the user to understand the problem and\nhow to fix it.\n\nWhen possible, we recommend validating the user’s data before submission. This\ntype of inline validation (aka\n[client-side validation](/patterns/forms-pattern#errors-and-validation)) should\nhappen as soon as the field loses focus. This will help easily identify the\nelements that need to be corrected. On field error messages should disappear\nwhen the form criteria is met. If the data was not able to be submitted due to\nserver-side issues then an inline notification should appear.\n\nDecrease the chances of invalid data by using selection controls and bound entry\ncontrols components that provide users with specific input choices, for example\nradio buttons and dropdowns.\n\n\n\n\n\n\n\n\n\n
\n Real-time validation. The user has left the first required field empty.{' '}\n
\n\n#### Task completion and loading\n\nThe task completion action should take place immediately. If a short loading\nperiod is needed then a loading spinner and overlay should appear on top of the\nmodal body area with content disabled. The primary action button should be\ndisabled while loading is in progress.\n\nIf the action requires more than a few seconds to complete, display progress\ninformation elsewhere on the screen to inform the user how long it will take to\ncomplete.\n\n\n\n\n\n\n\n\n\n### Using components\n\nAppropriate components to use in a dialog include form inputs and controls that\naid in collecting information from the user. Other components like content\nswitcher and structured list can be used to organize information. When possible,\navoid using complex components that can complicate task completion or prolong a\nuser’s time in the modal. A user’s journey through the modal should be direct\nand short.\n\n#### Avoid components that will direct the user away from the dialog\n\nAvoid components like links that will take the user away from the current\ncontext and the task at hand. A dialog’s purpose is to focus the user’s\nattention on a particular task and should not encourage any action that is not\nrelated to that task’s completion.\n\n#### Avoid components that hide information\n\nWhen possible avoid components that hide information or choices from the\nuser—like accordion and tabs—and require additional effort from the user to\ndiscover all the available content. Time spent in a modal should be minimal and\nonly information needed to complete the task should be included. If there is too\nmuch information for a user to consume in a dialog context, consider using a\nfull page instead.\n\n#### Avoid complex interactions with data tables\n\nWhen possible avoid using a data table in a dialog as it is a complex component\nwith its own workflow and decision making that can overly complicate a user’s\nchoice and task completion in relation to the dialog. If a data table is\nnecessary then the tables should be kept as simple as possible with limited\ninteractions. For example, you can use data table to make selections that will\nbe incurred by the dialogs action but avoid preforming table functions like\nbatch editing or batch actions inside the modal itself. For smaller sets of data\nor selections consider using a structured list, dropdown, or tile set instead.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n## Accessibility\n\n### Focus\n\n1. Shift the focus into the dialog when triggered.\n2. After the dialog opens, initial focus should be set on the first focusable\n element in the modal.\n3. For modal dialogs, the focus should be trapped inside the dialog and must not\n move outside the modal until it is closed.\n4. After a modal dialog closes, focus should return to the element that invoked\n the modal.\n\nReference\n[WCAG 2.4.3 Focus order success criterion](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-focus-order.html)\nfor additional guidelines.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n### Keyboard navigation\n\n- `ESC`: close the dialog\n- `tab`: navigates the user to the different interactive elements\n- `space bar`: triggers the selected element\n- `enter`: triggers the selected element\n\n### Tab order\n\n1. First interactive element in the body area.\n2. Proceed left to right and top to bottom through the rest of the body\n elements.\n3. Primary action\n4. Secondary action\n5. Close icon\n\n### ARIA\n\nSee WAI-ARIA Authoring Practices\n[Modal Dialog Example, Accessibility Features](https://www.w3.org/TR/wai-aria-practices-1.1/examples/dialog-modal/dialog.html)\nsection for best practices.\n\n## Related components and patterns\n\n\n\n\n#### Components:\n\n- [Buttons](/components/button/usage)\n- [Modal](/components/modal/usage)\n- [Notification](/components/notification/usage)\n\n\n\n\n#### Patterns:\n\n- [Forms](/patterns/forms-pattern)\n- [Notifications](/patterns/notification-pattern)\n\n\n\n\n## References\n\n- Apple Human Interface Guidelines,\n [Modality](https://developer.apple.com/design/human-interface-guidelines/ios/app-architecture/modality/)\n (2019)\n- Apple Human Interface Guidelines,\n [Dialogs](https://developer.apple.com/design/human-interface-guidelines/macos/windows-and-views/dialogs/)\n (2019)\n- Therese Fessenden,\n [Modal & Nonmodal Dialogs: When (& When Not) to Use Them](https://www.nngroup.com/articles/modal-nonmodal-dialog/)\n (Nielsen Norman Group, 2017)\n- James Jacobs,\n [Modern Enterprise UI design — Part 2: Modal dialogs](https://medium.com/pulsar/modern-enterprise-ui-design-part-2-modal-dialogs-2ccd3cc33c92)\n (2019)\n- Micosoft Docs,\n [About Dialog Boxes](https://docs.microsoft.com/en-us/windows/win32/dlgbox/about-dialog-boxes)\n (2019)\n- [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/)\n (W3C, 2018)\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments on\n[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","type":"Mdx","contentDigest":"f2d82eb1cc6e2a4decfe552b6946aa38","owner":"gatsby-plugin-mdx","counter":5332},"frontmatter":{"title":"Dialogs","description":"A dialog is a “conversation” between the system and the user. It is prompted when the system needs input from the user or to give the user urgent information concerning their current workflow."},"exports":{},"rawBody":"---\ntitle: Dialogs\ndescription:\n A dialog is a “conversation” between the system and the user. It is prompted\n when the system needs input from the user or to give the user urgent\n information concerning their current workflow.\n---\n\n\n\nA dialog is a “conversation” between the system and the user. It is prompted\nwhen the system needs input from the user or to give the user urgent information\nconcerning their current workflow. There are two types of dialogs, modal and\nnon-modal.\n\n\n\n\n\nOverview\nModal dialogs\nNon-modal dialogs\nDesigning with dialogs\nRelated components and patterns\nAccessibility\nReferences\nFeedback\n\n\n\n## Overview\n\nDialogs work best when used for short tasks or to alert the user to task\nrelevant information. Dialogs are useful in many scenarios; they are less\ndisorientating than navigating a user to a new page for simple tasks or\nknowledge gathering. However, dialogs are disruptive and can be distracting to\nthe user. Use them sparingly.\n\nA dialog is triggered by a user’s action, appears on top of the main page\ncontent, and is persistent until dismissed. The purpose of a dialog should be\nimmediately apparent to the user, with a clear and obvious path to completion.\n\n### Anatomy of a dialog\n\n\n\n\n\n\n\n\n\n1. **Header:** Includes a title, optional label, and the close icon. The title\n should be brief and clearly describe the dialogs’s task or purpose. Use the\n optional label above the title set the context for the information in the\n dialog.\n2. **Body:** Contains the information and/or controls needed to complete the\n dialog’s task. It can include message text and components.\n3. **Actions:** The main actions needed to complete or cancel the dialog task.\n [Button groupings](/patterns/dialog-pattern#button-groups) change based on\n modal variant. Use descriptive words for the actions like Add, Delete, Save\n and avoid vague words like Done or OK.\n4. **x:** The close `x` icon will close the dialog without submitting any data.\n5. **Overlay:** (Modal dialogs only) Screen overlay that obscures the on page\n content.\n\n### When to use a dialog\n\n- Use to focus the user’s attention.\n- Use for short task completion.\n- Use to gather input from the user.\n- Use to display relevant information.\n\n### When not to use a dialog\n\n- Don’t use if the content is unrelated to the current workflow.\n- Don’t use to display complex or large amounts of data.\n- Don’t recreate a full app or page in a dialog.\n- Don’t use when the user hasn’t triggered the dialog.\n\n### Dialog types\n\nThere are two types of dialogs, modal and non-modal.\n\nA _modal_ dialog triggers a state (or mode) that focuses the user’s attention\nexclusively on one task or piece of relevant information. When a modal dialog is\nactive, the content of the underneath page is obscured and inaccessible until\nthe user completes the task or dismisses the modal.\n\nWhen a _non-modal_ dialog is active the user can continue viewing and\ninteracting with the main page while the dialog is open. Non-modal dialogs are\ncommonly used to present non-critical information or optional user tasks.\n\n| Type | Usage | Context |\n| --------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Modal | Use to present critical information or request required input needed to complete a workflow. | Focuses the users attention exclusively on one task or piece of information. On-page content is obscured from the user while the modal dialog is open. |\n| Non-modal | Use to present non-critical information or optional user tasks. | On-page content can be accessed and interacted with while the dialog is still open. |\n\n\n\n\n\n\n\n\n\n
Modal dialog (left) and non-modal dialog (right)
\n\n### Best practices\n\n#### Use dialogs sparingly\n\nDon’t overuse dialogs. They are disruptive and can easily annoy the user if used\nincorrectly or too frequently. When dialogs are used for non-workflow related\ntasks, it is likely a user will start ignoring or dismissing the dialogs without\nfully understanding the content. This can cause users to make hurried or\nimpulsive choices when dealing with more critical dialogs.\n\n#### Dialogs should be user initiated\n\nA user action, such as clicking a button, should trigger the dialog to open.\nDon’t interrupt the user by opening a dialog when they aren’t expecting it.\nAvoid system generated pop-ups that distract the user while working, such as Net\nPromoter Score. Triggers can either be a direct or indirect consequence of a\nuser’s action. An example of an indirect action is a user closing a tab with\nunsaved content that then causes a dialog to ask if they want to save their\nchanges before closing. If the system is autogenerating an alert that is not a\nconsequence of a user’s action, but a response to processes happening in the\nbackground, then a toast notification should be used instead.\n\n#### Keep dialog tasks simple and focused\n\nDialog tasks should be direct and easy to complete. Avoid feature creep in\ndialogs where a once simple dialog has become bloated with interactions. When\ndeciding to use a dialog consider how the task could expanded in the future and\nif a dialog will be able to effectively incorporate additions. An example of a\nsimple task would adding a new item to a list where the item details are added\nand submitted via a dialog.\n\n## Modal dialogs\n\nUse a modal dialog to present critical information or request user input needed\nto complete a user’s workflow. Modal dialogs are disruptive and should be used\nsparingly. When active, a user is blocked from the on-page content and cannot\nreturn to their previous workflow until the modal task is completed or the user\ndismisses the modal. Any information or input requested should be directly\nrelated to the user’s task at hand.\n\nModal dialogs are commonly used for short and non-frequent tasks, such as\nediting or management tasks. If a user needs to repeatedly perform a task,\nconsider making the task do-able from the main page. A modal dialog adds to a\nworkflow’s interaction cost; it takes the user out of their previous context and\nrequires additional actions to complete and dismiss. When considering, ask is\nthis critical to their current workflow?\n\n\n\n\n\n\n\n\n\n### When to use\n\n#### An immediate response is required from the user\n\nUse a dialog to request information that is preventing the system from\ncontinuing a user-initiated process.\n\n#### Notify the user of urgent information\n\nUse a modal dialog to notify the user of urgent information concerning their\ncurrent work. Commonly used to report system errors or convey a consequence of a\nuser’s action.\n\n#### Confirm a user decision\n\nUse a modal dialog to confirm user decisions. Clearly describe the action being\nconfirmed and explain any potential consequences that it may cause. Both the\ntitle and the button should reflect the action that will occur. If the action is\ndestructive or irreversible then use a transactional danger modal.\n\n### When not to use\n\n#### Modals prevent access to the main page\n\nDon’t use if additional information outside the modal needs to be consulted.\nWhile a modal dialog is active a user cannot interact with the main page and is\nrestricted to only the information in the modal for making decisions. Modal\ntasks should be easy to complete with the limited information presented in the\ndialog itself. If a user needs access to additional information then consider\nusing a full page instead.\n\n#### Don’t nest modals\n\nOne modal should never trigger another modal. If the first modal task is\ndependent on a confirmation modal to approve then that first task should not be\npreformed in a modal.\n\n#### Don’t make modals full page\n\nIf a modal dialog needs more space than the large modal component allows then\nthe content should be displayed on a page of its own and not in a modal. A modal\nis not an alternative to page.\n\n### Modal variants\n\n\n\n\n\n\n\n\n\n| Variant | Usage |\n| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |\n| [Passive](/components/modal/usage#passive-modal) | Presents information the user needs to be aware of concerning their current workflow. Contains no actions for the user to take. |\n| [Transactional](/components/modal/usage#transactional-modal) | Requires an action to be taken in order for the modal to be completed and closed. Contains a cancel and primary action buttons. |\n| [Acknowledgment](/components/modal/usage#acknowledgment-modal) | System requires an acknowledgement of the information from the user. Contains only a single button, commonly \"OK\". |\n| [Progress](/components/modal/usage/#progress-modal) | Requires several steps to be completed before it can be closed. Contains a cancel, previous and next/completion buttons. |\n\n### Dismissing variant modals\n\nFor passive modals:\n\n- **x**: Clicking the close `x` icon in the upper right will close the modal\n without submitting any data and return the user to its previous context.\n- **Click elsewhere**: Clicking outside the passive modal area will\n automatically close the modal.\n- **Esc**: Press `ESC` on the keyboard\n\nFor transactional, progress, and acknowledgement modals:\n\n- **Task completion**: clicking the primary action will complete the task and\n automatically close the modal.\n- **Cancel button**: clicking the cancel button will close the modal and return\n the user to its previous context. Cancel undoes all applied changes.\n- **x**: Clicking the close `x` icon in the upper right will close the modal\n without submitting any data and return the user to its previous context.\n- **Esc**: Press `ESC` on the keyboard\n\n## Non-modal dialogs\n\nUse non-modal dialogs to display non-critical information or optional tasks\nrelated to the user’s current workflow, like \"find and replace\". A user still\nhas access to the on-page content while the non-modal dialog is open and a\nresponse is not required to continue working. However, a non-modal dialog does\nrequire an action from the user to be dismissed.\n\n\n\n\n\n\n\n\n\n \n\n### When to use\n\n#### When access to the page is needed\n\nUse when a user needs to compare or refer to information in the main page\nalongside the modal. users can interact with the non-modal content and the\non-page content simultaneously.\n\nA non-modal dialog window can be moved from its original placement on the\nscreen. This allows the user to access information that might otherwise be\nhidden by the dialog.\n\n#### Aid or accelerate a user’s work flow\n\nUse to perform tasks or present informational along side the main page content\nthat can accelerate or aid a user’s workflow. For example, a \"find and replace\"\ndialog can help a user perform and automate edits quicker. The user can chose to\nautomate the changes or navigate through the page by using the \"find\" feature\nand manually make updates.\n\n#### Display additional information\n\nUse to display additional information that can help inform a user’s decision or\nworkflow. For example, use for incontext help or tutorials such as a knowledge\ncenter.\n\n### When not to use\n\n#### Don’t use if the user’s response is required\n\nUse for optional or non-critical tasks only. If a user’s response or input is\nrequired to progress the workflow, use a modal dialog.\n\n### Non-modal variants\n\n| Name | Description |\n| ------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| Passive | Presents additional information concerning the user’s current workflow. Contains no actions for the user to take. |\n| Transactional | Presents the user with optional action/s. Actions can be repeated without closing the dialog. Contains at least one button. |\n\n### Dismissing non-modal dialogs\n\nThere are several possible ways to exit a non-modal dialog.\n\n- **x**: Clicking the close `x` icon in the upper right will close the modal\n without submitting any data.\n- **Cancel button**: If a cancel button is used then clicking it will close the\n modal. Cancel undoes all applied changes.\n- **Esc**: Press `ESC` on the keyboard\n\n## Designing with dialogs\n\n### Button groups\n\nWhen placing buttons, Cancel is always the outmost left button option and the\nprimary action is always the outmost right button. There should only ever be one\nprimary action per dialog. Dialog buttons are always full bleed and attached to\nthe bottom of a dialog.\n\n\n\n\n\n\n\n\n\n
\n Button groups: one button, two buttons, three buttons, and progress buttons.\n
\n\n#### One button\n\nSingle buttons are placed on the right side, span 50% of the dialog, and bleed\nto the edge. The single button format is most commonly used for acknowledgment\ndialogs. In most scenarios, a primary button is used when only one button is\nneeded.\n\n#### Two buttons\n\nWhen using two buttons, the secondary button is on the left and the primary\nbutton is placed on the right. Each button spans 50% of the dialog and are full\nbleed to the edge.\n\n#### Three buttons\n\nWhen three buttons are needed, each is 25% of the dialog width and aligned to\nthe right side of the dialog. Only the outmost right button is allowed to be a\nprimary button with the other two being secondary buttons. If all three actions\nhave the same weight then all three should be secondary buttons.\n\n#### Progress indicator buttons\n\nThe three progress indicator buttons are: Cancel, Previous, Next. Each button’s\nwidth is 25% of the dialog window and are full bleed. Previous and Next should\nbe grouped together and placed on the right half of the dialog, with Previous as\na secondary button and Next as a primary button. The Cancel button is aligned to\nleft side of the dialog and uses a ghost button.\n\nIn the last step of the sequence, the Next button label should change to reflect\nthe final action.\n\n### Behaviors\n\n#### Trigger\n\nDialogs are triggered as a result of a user’s action and are not system\ngenerated. Common components that can trigger a dialog include, button, link, or\nicon.\n\n#### Focus\n\nOnce the dialog is open, set the initial focus to the first location that\naccepts user input. Focus should then remain trapped in the dialog until it is\nclosed.\n\n#### Scrolling\n\nThe modal component has four set sizes and each size has a set max-height. If\nthe dialog content is longer than the dialog height then the body section should\nscroll vertically with the header and footer remaining fixed in place.\n\n#### Validation\n\nValidate a user’s entries before the dialog is closed. If any entry is invalid\nthen the dialog should remain open with the entry marked with an error state and\ninclude an inline error message. The message should inform the user what has\nhappened and provide guidance on next steps or possible resolutions. Effective\nand immediate error messaging can help the user to understand the problem and\nhow to fix it.\n\nWhen possible, we recommend validating the user’s data before submission. This\ntype of inline validation (aka\n[client-side validation](/patterns/forms-pattern#errors-and-validation)) should\nhappen as soon as the field loses focus. This will help easily identify the\nelements that need to be corrected. On field error messages should disappear\nwhen the form criteria is met. If the data was not able to be submitted due to\nserver-side issues then an inline notification should appear.\n\nDecrease the chances of invalid data by using selection controls and bound entry\ncontrols components that provide users with specific input choices, for example\nradio buttons and dropdowns.\n\n\n\n\n\n\n\n\n\n
\n Real-time validation. The user has left the first required field empty.{' '}\n
\n\n#### Task completion and loading\n\nThe task completion action should take place immediately. If a short loading\nperiod is needed then a loading spinner and overlay should appear on top of the\nmodal body area with content disabled. The primary action button should be\ndisabled while loading is in progress.\n\nIf the action requires more than a few seconds to complete, display progress\ninformation elsewhere on the screen to inform the user how long it will take to\ncomplete.\n\n\n\n\n\n\n\n\n\n### Using components\n\nAppropriate components to use in a dialog include form inputs and controls that\naid in collecting information from the user. Other components like content\nswitcher and structured list can be used to organize information. When possible,\navoid using complex components that can complicate task completion or prolong a\nuser’s time in the modal. A user’s journey through the modal should be direct\nand short.\n\n#### Avoid components that will direct the user away from the dialog\n\nAvoid components like links that will take the user away from the current\ncontext and the task at hand. A dialog’s purpose is to focus the user’s\nattention on a particular task and should not encourage any action that is not\nrelated to that task’s completion.\n\n#### Avoid components that hide information\n\nWhen possible avoid components that hide information or choices from the\nuser—like accordion and tabs—and require additional effort from the user to\ndiscover all the available content. Time spent in a modal should be minimal and\nonly information needed to complete the task should be included. If there is too\nmuch information for a user to consume in a dialog context, consider using a\nfull page instead.\n\n#### Avoid complex interactions with data tables\n\nWhen possible avoid using a data table in a dialog as it is a complex component\nwith its own workflow and decision making that can overly complicate a user’s\nchoice and task completion in relation to the dialog. If a data table is\nnecessary then the tables should be kept as simple as possible with limited\ninteractions. For example, you can use data table to make selections that will\nbe incurred by the dialogs action but avoid preforming table functions like\nbatch editing or batch actions inside the modal itself. For smaller sets of data\nor selections consider using a structured list, dropdown, or tile set instead.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n## Accessibility\n\n### Focus\n\n1. Shift the focus into the dialog when triggered.\n2. After the dialog opens, initial focus should be set on the first focusable\n element in the modal.\n3. For modal dialogs, the focus should be trapped inside the dialog and must not\n move outside the modal until it is closed.\n4. After a modal dialog closes, focus should return to the element that invoked\n the modal.\n\nReference\n[WCAG 2.4.3 Focus order success criterion](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-focus-order.html)\nfor additional guidelines.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n### Keyboard navigation\n\n- `ESC`: close the dialog\n- `tab`: navigates the user to the different interactive elements\n- `space bar`: triggers the selected element\n- `enter`: triggers the selected element\n\n### Tab order\n\n1. First interactive element in the body area.\n2. Proceed left to right and top to bottom through the rest of the body\n elements.\n3. Primary action\n4. Secondary action\n5. Close icon\n\n### ARIA\n\nSee WAI-ARIA Authoring Practices\n[Modal Dialog Example, Accessibility Features](https://www.w3.org/TR/wai-aria-practices-1.1/examples/dialog-modal/dialog.html)\nsection for best practices.\n\n## Related components and patterns\n\n\n\n\n#### Components:\n\n- [Buttons](/components/button/usage)\n- [Modal](/components/modal/usage)\n- [Notification](/components/notification/usage)\n\n\n\n\n#### Patterns:\n\n- [Forms](/patterns/forms-pattern)\n- [Notifications](/patterns/notification-pattern)\n\n\n\n\n## References\n\n- Apple Human Interface Guidelines,\n [Modality](https://developer.apple.com/design/human-interface-guidelines/ios/app-architecture/modality/)\n (2019)\n- Apple Human Interface Guidelines,\n [Dialogs](https://developer.apple.com/design/human-interface-guidelines/macos/windows-and-views/dialogs/)\n (2019)\n- Therese Fessenden,\n [Modal & Nonmodal Dialogs: When (& When Not) to Use Them](https://www.nngroup.com/articles/modal-nonmodal-dialog/)\n (Nielsen Norman Group, 2017)\n- James Jacobs,\n [Modern Enterprise UI design — Part 2: Modal dialogs](https://medium.com/pulsar/modern-enterprise-ui-design-part-2-modal-dialogs-2ccd3cc33c92)\n (2019)\n- Micosoft Docs,\n [About Dialog Boxes](https://docs.microsoft.com/en-us/windows/win32/dlgbox/about-dialog-boxes)\n (2019)\n- [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/)\n (W3C, 2018)\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments on\n[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/patterns/dialog-pattern/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/patterns/disabled-states/page-data.json b/page-data/patterns/disabled-states/page-data.json
index 93c31c721ff..41bf598189a 100644
--- a/page-data/patterns/disabled-states/page-data.json
+++ b/page-data/patterns/disabled-states/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-patterns-disabled-states-index-mdx","path":"/patterns/disabled-states/","result":{"pageContext":{"frontmatter":{"title":"Disabled states","description":"A disabled state is applied to a component when the user is not allowed to interact with the component due to either permissions, dependencies, or pre-requisites."},"relativePagePath":"/patterns/disabled-states/index.mdx","titleType":"prepend","MdxNode":{"id":"5d9de59a-34fc-50b6-b315-157917eb5997","children":[],"parent":"5a4cb978-91dd-5028-aa13-08507c3bcdf1","internal":{"content":"---\ntitle: Disabled states\ndescription:\n A disabled state is applied to a component when the user is not allowed to\n interact with the component due to either permissions, dependencies, or\n pre-requisites.\n---\n\n\n\nA disabled state is applied to a component when the user is not allowed to\ninteract with the component due to either permissions, dependencies, or\npre-requisites. Disabled states completely remove the interactive function of a\ncomponent.\n\n\n\n\n\nDisabled variations\nDefault disabled\nRead-only\nHidden\n\n\n\n## Disabled variations\n\n| Variation | Description |\n| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| _Default disabled_ | Cannot be clicked, selected or interacted with. It is not read by a screen reader and takes on the default disabled visual style. |\n| _Read-only_ | The user cannot interact with it but content is still readable and accessible to a screen reader. The visual style should contain no interactive indicators such as `$interactive-01`, hover states, or text embellishments (i.e., underlines). |\n| _Hidden_ | The component is completely hidden from view. The user does not know the option is there. |\n\n## Default disabled\n\nA default disabled state is used when a component is temporarily disabled due to\ndependencies (when one piece of software relies on another one) or\npre-requisites. This scenario is a temporary state change that is most commonly\ntriggered by a user’s action or inaction. Once the dependencies have been\nresolved and/or the pre-requisites have been fulfilled, the default disabled\ncomponent returns to its enabled state. In a temporarily disabled scenario the\ncomponent should never fully disappear from the user’s view.\n\n\n\n\n\n\n\n\n\n### Style\n\nDefault disabled states are most commonly styled by a decrease in opacity with\nno hover state change and `not-allowed` cursor applied. Refer to each individual\ncomponent for the accurate disabled state.\n\n| Attribute | Default disabled style |\n| ----------- | ---------------------- |\n| _Component_ | 50% opacity |\n| _Text_ | 25% opacity |\n| _Icons_ | 50% opacity |\n| _Hover_ | None |\n| _Cursor_ | `not-allowed` |\n\n \n\n\n\n\n\n\n\n\n\n### Additional warning\n\nAn [inline warning notification](/components/notification/usage) can be shown in\ncases where a temporarily disabled item affects multiple items or the primary\naction of the flow. The notification should describe how the user can enable or\nre-enable the disabled component.\n\n\n\n\n\n\n\n\n\n## Read-only\n\nIn scenarios where the content of a disabled component or element is still\nrelevant to the user or important to task completion, then the read-only\nvariation is used. This allows the user to read the information but not interact\nwith or change it. Read-only content should always be accessible to a screen\nreader.\n\n### Style\n\nThe visual style of the read-only states vary by component but should never\ncontain any interactive indicators such as `$brand-01` color usage, hover\nstates, or text embellishments (i.e., underlines).\n\n## Hidden\n\nThe hidden disabled variation is used when something or someone does not have\npermission to view, interact with, or take action on an element of the UI. This\nvariation completely hides the component, page, action, etc. from the user’s\ninterface. The only way to enable the hidden element and have it resurfaced on\nthe UI is to change the assigned permission.\n\nFor example, when a user is the organization owner they are allowed to add\nmembers to the organization. Any users that are not an organization owner would\nnot be shown the “Add member” button on a team directory page. Once the user is\nmade an organization owner, **then and only then** will the button be visible.\n\n\n\n\n\n\n\n\n","type":"Mdx","contentDigest":"f27b00fc38c4a2ad0e1297cfb0cb717f","owner":"gatsby-plugin-mdx","counter":5330},"frontmatter":{"title":"Disabled states","description":"A disabled state is applied to a component when the user is not allowed to interact with the component due to either permissions, dependencies, or pre-requisites."},"exports":{},"rawBody":"---\ntitle: Disabled states\ndescription:\n A disabled state is applied to a component when the user is not allowed to\n interact with the component due to either permissions, dependencies, or\n pre-requisites.\n---\n\n\n\nA disabled state is applied to a component when the user is not allowed to\ninteract with the component due to either permissions, dependencies, or\npre-requisites. Disabled states completely remove the interactive function of a\ncomponent.\n\n\n\n\n\nDisabled variations\nDefault disabled\nRead-only\nHidden\n\n\n\n## Disabled variations\n\n| Variation | Description |\n| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| _Default disabled_ | Cannot be clicked, selected or interacted with. It is not read by a screen reader and takes on the default disabled visual style. |\n| _Read-only_ | The user cannot interact with it but content is still readable and accessible to a screen reader. The visual style should contain no interactive indicators such as `$interactive-01`, hover states, or text embellishments (i.e., underlines). |\n| _Hidden_ | The component is completely hidden from view. The user does not know the option is there. |\n\n## Default disabled\n\nA default disabled state is used when a component is temporarily disabled due to\ndependencies (when one piece of software relies on another one) or\npre-requisites. This scenario is a temporary state change that is most commonly\ntriggered by a user’s action or inaction. Once the dependencies have been\nresolved and/or the pre-requisites have been fulfilled, the default disabled\ncomponent returns to its enabled state. In a temporarily disabled scenario the\ncomponent should never fully disappear from the user’s view.\n\n\n\n\n\n\n\n\n\n### Style\n\nDefault disabled states are most commonly styled by a decrease in opacity with\nno hover state change and `not-allowed` cursor applied. Refer to each individual\ncomponent for the accurate disabled state.\n\n| Attribute | Default disabled style |\n| ----------- | ---------------------- |\n| _Component_ | 50% opacity |\n| _Text_ | 25% opacity |\n| _Icons_ | 50% opacity |\n| _Hover_ | None |\n| _Cursor_ | `not-allowed` |\n\n \n\n\n\n\n\n\n\n\n\n### Additional warning\n\nAn [inline warning notification](/components/notification/usage) can be shown in\ncases where a temporarily disabled item affects multiple items or the primary\naction of the flow. The notification should describe how the user can enable or\nre-enable the disabled component.\n\n\n\n\n\n\n\n\n\n## Read-only\n\nIn scenarios where the content of a disabled component or element is still\nrelevant to the user or important to task completion, then the read-only\nvariation is used. This allows the user to read the information but not interact\nwith or change it. Read-only content should always be accessible to a screen\nreader.\n\n### Style\n\nThe visual style of the read-only states vary by component but should never\ncontain any interactive indicators such as `$brand-01` color usage, hover\nstates, or text embellishments (i.e., underlines).\n\n## Hidden\n\nThe hidden disabled variation is used when something or someone does not have\npermission to view, interact with, or take action on an element of the UI. This\nvariation completely hides the component, page, action, etc. from the user’s\ninterface. The only way to enable the hidden element and have it resurfaced on\nthe UI is to change the assigned permission.\n\nFor example, when a user is the organization owner they are allowed to add\nmembers to the organization. Any users that are not an organization owner would\nnot be shown the “Add member” button on a team directory page. Once the user is\nmade an organization owner, **then and only then** will the button be visible.\n\n\n\n\n\n\n\n\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/patterns/disabled-states/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-patterns-disabled-states-index-mdx","path":"/patterns/disabled-states/","result":{"pageContext":{"frontmatter":{"title":"Disabled states","description":"A disabled state is applied to a component when the user is not allowed to interact with the component due to either permissions, dependencies, or pre-requisites."},"relativePagePath":"/patterns/disabled-states/index.mdx","titleType":"prepend","MdxNode":{"id":"5d9de59a-34fc-50b6-b315-157917eb5997","children":[],"parent":"5a4cb978-91dd-5028-aa13-08507c3bcdf1","internal":{"content":"---\ntitle: Disabled states\ndescription:\n A disabled state is applied to a component when the user is not allowed to\n interact with the component due to either permissions, dependencies, or\n pre-requisites.\n---\n\n\n\nA disabled state is applied to a component when the user is not allowed to\ninteract with the component due to either permissions, dependencies, or\npre-requisites. Disabled states completely remove the interactive function of a\ncomponent.\n\n\n\n\n\nDisabled variations\nDefault disabled\nRead-only\nHidden\n\n\n\n## Disabled variations\n\n| Variation | Description |\n| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| _Default disabled_ | Cannot be clicked, selected or interacted with. It is not read by a screen reader and takes on the default disabled visual style. |\n| _Read-only_ | The user cannot interact with it but content is still readable and accessible to a screen reader. The visual style should contain no interactive indicators such as `$interactive-01`, hover states, or text embellishments (i.e., underlines). |\n| _Hidden_ | The component is completely hidden from view. The user does not know the option is there. |\n\n## Default disabled\n\nA default disabled state is used when a component is temporarily disabled due to\ndependencies (when one piece of software relies on another one) or\npre-requisites. This scenario is a temporary state change that is most commonly\ntriggered by a user’s action or inaction. Once the dependencies have been\nresolved and/or the pre-requisites have been fulfilled, the default disabled\ncomponent returns to its enabled state. In a temporarily disabled scenario the\ncomponent should never fully disappear from the user’s view.\n\n\n\n\n\n\n\n\n\n### Style\n\nDefault disabled states are most commonly styled by a decrease in opacity with\nno hover state change and `not-allowed` cursor applied. Refer to each individual\ncomponent for the accurate disabled state.\n\n| Attribute | Default disabled style |\n| ----------- | ---------------------- |\n| _Component_ | 50% opacity |\n| _Text_ | 25% opacity |\n| _Icons_ | 50% opacity |\n| _Hover_ | None |\n| _Cursor_ | `not-allowed` |\n\n \n\n\n\n\n\n\n\n\n\n### Additional warning\n\nAn [inline warning notification](/components/notification/usage) can be shown in\ncases where a temporarily disabled item affects multiple items or the primary\naction of the flow. The notification should describe how the user can enable or\nre-enable the disabled component.\n\n\n\n\n\n\n\n\n\n## Read-only\n\nIn scenarios where the content of a disabled component or element is still\nrelevant to the user or important to task completion, then the read-only\nvariation is used. This allows the user to read the information but not interact\nwith or change it. Read-only content should always be accessible to a screen\nreader.\n\n### Style\n\nThe visual style of the read-only states vary by component but should never\ncontain any interactive indicators such as `$brand-01` color usage, hover\nstates, or text embellishments (i.e., underlines).\n\n## Hidden\n\nThe hidden disabled variation is used when something or someone does not have\npermission to view, interact with, or take action on an element of the UI. This\nvariation completely hides the component, page, action, etc. from the user’s\ninterface. The only way to enable the hidden element and have it resurfaced on\nthe UI is to change the assigned permission.\n\nFor example, when a user is the organization owner they are allowed to add\nmembers to the organization. Any users that are not an organization owner would\nnot be shown the “Add member” button on a team directory page. Once the user is\nmade an organization owner, **then and only then** will the button be visible.\n\n\n\n\n\n\n\n\n","type":"Mdx","contentDigest":"f27b00fc38c4a2ad0e1297cfb0cb717f","owner":"gatsby-plugin-mdx","counter":5333},"frontmatter":{"title":"Disabled states","description":"A disabled state is applied to a component when the user is not allowed to interact with the component due to either permissions, dependencies, or pre-requisites."},"exports":{},"rawBody":"---\ntitle: Disabled states\ndescription:\n A disabled state is applied to a component when the user is not allowed to\n interact with the component due to either permissions, dependencies, or\n pre-requisites.\n---\n\n\n\nA disabled state is applied to a component when the user is not allowed to\ninteract with the component due to either permissions, dependencies, or\npre-requisites. Disabled states completely remove the interactive function of a\ncomponent.\n\n\n\n\n\nDisabled variations\nDefault disabled\nRead-only\nHidden\n\n\n\n## Disabled variations\n\n| Variation | Description |\n| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| _Default disabled_ | Cannot be clicked, selected or interacted with. It is not read by a screen reader and takes on the default disabled visual style. |\n| _Read-only_ | The user cannot interact with it but content is still readable and accessible to a screen reader. The visual style should contain no interactive indicators such as `$interactive-01`, hover states, or text embellishments (i.e., underlines). |\n| _Hidden_ | The component is completely hidden from view. The user does not know the option is there. |\n\n## Default disabled\n\nA default disabled state is used when a component is temporarily disabled due to\ndependencies (when one piece of software relies on another one) or\npre-requisites. This scenario is a temporary state change that is most commonly\ntriggered by a user’s action or inaction. Once the dependencies have been\nresolved and/or the pre-requisites have been fulfilled, the default disabled\ncomponent returns to its enabled state. In a temporarily disabled scenario the\ncomponent should never fully disappear from the user’s view.\n\n\n\n\n\n\n\n\n\n### Style\n\nDefault disabled states are most commonly styled by a decrease in opacity with\nno hover state change and `not-allowed` cursor applied. Refer to each individual\ncomponent for the accurate disabled state.\n\n| Attribute | Default disabled style |\n| ----------- | ---------------------- |\n| _Component_ | 50% opacity |\n| _Text_ | 25% opacity |\n| _Icons_ | 50% opacity |\n| _Hover_ | None |\n| _Cursor_ | `not-allowed` |\n\n \n\n\n\n\n\n\n\n\n\n### Additional warning\n\nAn [inline warning notification](/components/notification/usage) can be shown in\ncases where a temporarily disabled item affects multiple items or the primary\naction of the flow. The notification should describe how the user can enable or\nre-enable the disabled component.\n\n\n\n\n\n\n\n\n\n## Read-only\n\nIn scenarios where the content of a disabled component or element is still\nrelevant to the user or important to task completion, then the read-only\nvariation is used. This allows the user to read the information but not interact\nwith or change it. Read-only content should always be accessible to a screen\nreader.\n\n### Style\n\nThe visual style of the read-only states vary by component but should never\ncontain any interactive indicators such as `$brand-01` color usage, hover\nstates, or text embellishments (i.e., underlines).\n\n## Hidden\n\nThe hidden disabled variation is used when something or someone does not have\npermission to view, interact with, or take action on an element of the UI. This\nvariation completely hides the component, page, action, etc. from the user’s\ninterface. The only way to enable the hidden element and have it resurfaced on\nthe UI is to change the assigned permission.\n\nFor example, when a user is the organization owner they are allowed to add\nmembers to the organization. Any users that are not an organization owner would\nnot be shown the “Add member” button on a team directory page. Once the user is\nmade an organization owner, **then and only then** will the button be visible.\n\n\n\n\n\n\n\n\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/patterns/disabled-states/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/patterns/disclosures-pattern/page-data.json b/page-data/patterns/disclosures-pattern/page-data.json
index 80cbf7031e5..6929c6d3697 100644
--- a/page-data/patterns/disclosures-pattern/page-data.json
+++ b/page-data/patterns/disclosures-pattern/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-patterns-disclosures-pattern-index-mdx","path":"/patterns/disclosures-pattern/","result":{"pageContext":{"frontmatter":{"title":"Disclosures","description":"Disclosures are moments that open up on a page and reveal additional information related to the source it is triggered from."},"relativePagePath":"/patterns/disclosures-pattern/index.mdx","titleType":"prepend","MdxNode":{"id":"e1f54a23-8631-5d6e-be2d-a83139683480","children":[],"parent":"48dcaf3e-287e-5534-a03c-960d62863884","internal":{"content":"---\ntitle: Disclosures\ndescription:\n Disclosures are moments that open up on a page and reveal additional\n information related to the source it is triggered from.\n---\n\n\n\nDisclosures are moments that open up on a page and reveal additional information\nrelated to the source it is triggered from.\n\n\n\n\n\nOverview\nProfile menu\nSettings and filter menus\nCombo button\nAccessibility\nRelated\nReferences\nFeedback\n\n\n\n## Overview\n\nDisclosures support a wide range of different use cases in product interfaces\nand are commonly used to reveal more information or details about an element or\ncontent on a page. Unlike tooltips, the content expanded by a disclosure may\ncontain interactive elements.\n\nAt its core, a disclosure is comprised of two parts—a trigger that the user\ninteracts with by clicking or using their keyboard and the container that opens\nand discloses the content.\n\n### When to use\n\n- Use when disclosing additional content about part of a UI.\n- Use when there is a need to include interactive elements in a popover.\n- Use to show settings, filtering, or sorting menus that affect sections of a\n page, for example in data tables, or an entire page.\n- Use when displaying content within types of dropdowns, for example profile\n menus, combo buttons, and menu buttons.\n\n### When not to use\n\n- Don't use to present critical information or request required input needed to\n complete a workflow. Use the\n [modal component](https://www.carbondesignsystem.com/components/modal/usage/)\n instead.\n- Don’t use when the user hasn’t explicitly triggered the popover to open on\n click.\n- Don't use if the popover needs to have a width larger than six columns.\n\n### Best practices\n\n#### Keep disclosures at a reasonable size\n\nA disclosure should not take up a considerable amount of the size of the screen.\nDisclosures are meant to be smaller moments that can open on top of different\nareas of a page. They should not seem like a disruption to the users workflow\nand should not act as a screen takeover. Keep all content in a disclosure\nconcise and only include information that is necessary. We recommend having a\nwidth of six columns or less.\n\n#### Disclosures should be user initiated\n\nDisclosures should always be triggered to open or close by the user. Disclosures\nshould never open automatically because this could be potentially intrusive to\nthe user's workflow.\n\n#### One disclosure should open at a time\n\nIf there are multiple instances on a page where a disclosure is present, only\none should open at a time to avoid screen clutter and to help the user stay\nfocused on the information being disclosed.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n#### Avoid nesting disclosures\n\nDo not nest one disclosure within another disclosure. Nesting disclosures\ncreates a stacking effect and could confuse the user of where they should be\nfocusing their attention and which disclosure they should be interacting with.\nUsing submenus in a context menu that fly out to the sides is an acceptable way\nto disclose additional information in a disclosure.\n\n#### Do not hide critical information within a disclosure\n\nDo not hide important information inside of a disclosure that the user may need\nin order to complete a task or workflow. Keep critical information at a higher\nlevel so the user has better visibility.\n\n### Behaviors\n\n**Opening and closing a disclosure**\n\nTo open a disclosure to reveal its content, click the trigger button it is\nrelated to. If using a keyboard, press `Enter` or `Space`.\n\nTo close a disclosure, either click on the trigger button again, click anywhere\noutside of the open disclosure container or click on the close `x` icon if it is\npresent within the disclosure. If using a keyboard, press `Esc` or `Tab` to tab\nout of the disclosure.\n\n#### Dismissible action\n\nDepending on the type of content in a disclosure, it can be useful to display a\nclose `x` icon. Be mindful when and where you place a close icon in a\ndisclosure. The close icon should always be in the top right corner of the\npopover and should not interfere or overlap with inline interactive elements.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n### Visual guidance\n\n#### Trigger button container\n\nA disclosure is controlled by a trigger button. The trigger button can visually\nchange its shape and size depending on the usecase.\n\nThe trigger button can use any of our button types and can be set at these three\nsizes—48px (lg), 40px (md) or 32px (sm).\n\n\n\n\n\n\n\n\n\n
Example of trigger button container height sizes.
\n\n#### Trigger button icon\n\nIf a trigger button contains an icon, the icon size should be either 20px or\n16px.\n\n\n\n\n\n\n\n\n\n
Example of trigger button icon sizes.
\n\n#### Popover\n\nA popover component is used as the underlying layer of a disclosure to disclose\nits content. See the\n[popover component](https://v11.carbondesignsystem.com/components/popover/usage/)\nguidance for more information.\n\n\n\n\n\n\n\n\n\n
Example of a popover container.
\n\n### Content\n\nThe type of content in a disclosure can vary depending on the use case. A\ndisclosure can be simple and contain solely informational text. In some cases\ncontent can be more complex and include a combination of multiple sections and\ninteractive elements. Below are some common examples and best practices of how\nto show body text, heading text, and footer content in disclosures.\n\n#### Heading text\n\nHeading text can be placed above body text in a disclosure. Placing the heading\ntext with 0px padding above the body text or adding a divider between the\nheading text and body text are two different common use cases.\n\n\n\n\n\n\n\n\n\n
Example of a disclosure with heading text.
\n\n#### Footer content\n\nFooter content can be placed below the body text it is related to. Placing the\nfooter content with 16px padding below the body text or adding a divider between\nthe footer content and body text are two different common use cases.\n\n\n\n\n\n\n\n\n\n
Example of a disclosure with footer content.
\n\n#### Multiple sections of text\n\nDepending on the use case, you may need a disclosure to show multiple sections\nof content. Use padding or dividers to visually create sections. Profile menus\nand context menus typically display multiple sections of content depending on\nthe complexity of the menu.\n\n\n\n\n\n\n\n\n\n
Example of a disclosure with multiple sections.
\n\n#### Interactive elements\n\nDisclosures allow you to place interactive elements in a popover while still\nkeeping it accessible. Settings and filters often include components like radio\nbuttons and checkboxes that the user can interact with to adjust specific\ncontent. Searching within a menu is another common use case of including\ninteractive elements within a popover.\n\n\n\n\n\n\n\n\n\n
Example of a disclosure with interactive content.
\n\n## Common use cases\n\nDisclosures are used for a wide variety of use cases. The following variants are\na few examples of common disclosures that you may come across frequently in\nproduct interfaces.\n\n| Example | Use cases |\n| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Profile menu | Profile menus are typically part of a UI shell header and can have navigational options related to a user's account or active session. |\n| Settings and filter menus | Settings and filter menus are frequently used within data table toolbars to enable users to adjust content. Filter and sort menus can also be used for filtering large amounts of content on a page or an entire page. |\n| Combo button | Combo buttons are used to contain multiple related actions that come with a default, primary action. Additional actions live in the menu. |\n\n## Profile menu\n\nProfile menus follow the disclosure pattern by clicking an icon button that\nopens a popover. Profile menus are essential to a product's UI and users rely on\nit to find global content related to their account, product, and active session\ninformation. Profile menus provide a way to log in or out of an account and let\nusers access their settings. Additional links and icons can be added to a\nprofile menu depending on the use case.\n\nSee the\n[profile menu pattern](https://pages.github.ibm.com/cdai-design/pal/patterns/profile-header-menu/)\nfor more information.\n\n### Anatomy\n\n\n\n\n\n\n\n\n\n
Anatomy of a profile menu.
\n\n1. **Toolbar profile image:** A profile image, initials, or icon of a user.\n2. **Menu profile image:** A profile image that is paired with high level\n information about the user, such as a name or handle.\n3. **Section dividers (optional):** To group related content by creating visual\n sections.\n4. **Contextual information (optional):** Global information that is related to\n the account or active session.\n5. **Link (optional):** Additional links that are not main menu items. Links can\n be used for editing, prompting a modal, etc.\n6. **Menu items:** The main and most commonly used menu items that are\n navigational.\n7. **Icon (optional):** Additional icons to place inline with menu items.\n\n### Structure\n\nA profile menu is made up of two parts—an icon button and a popover. Profile\nmenus support a variety of content that can range in complexity. Some profile\nmenus are simple while other menus may be more complex and require multiple\nsections of information. Profile menus that are complex may benefit from\nincluding interactive elements depending on the use case.\n\n\n\n\n\n\n\n\n\n
Example of a simple and complex profile menu.
\n\n### Functionality\n\n#### Mouse\n\nClicking the icon button triggers the profile menu to open and reveals\ninformation related to the users profile and account. The user can then click on\nmenu items and other interactive elements within the menu. To close the menu,\nclick on the icon button trigger again or anywhere on the page out side of the\nmenu.\n\n\n\n\n\n\n\n\n\n#### Keyboard\n\n- `Tab` to the icon button trigger to apply focus.\n- To open the profile menu press `Enter` or `Space`.\n- Once opened, focus goes to the first item in the menu.\n- To navigate the profile menu items press the `Up` and `Down` arrow keys.\n- To select an item in the profile menu press `Enter`.\n- To close the profile menu press `Esc` .\n\n### Best practices\n\n#### Use with a global toolbar header\n\nIf a product has a global toolbar header and offers login capabilities, use the\nprofile menu. Provide a way for the user to log out of an account, make changes\nto profile information, or navigate to settings.\n\n#### Show information that is pertinent to the user account or session\n\nInclude sections on a global contextual level that may be helpful to the user to\nsee in the profile menu. For example, indicating the current plan or location\nwith an option to edit or change the current information can be valuable to\ninclude in a profile menu depending on the use case.\n\n#### Add icons and links to help guide the user\n\nWhen appropriate, pair icons with related menu items or information to indicate\nthe action that will be performed once it is clicked. Provide links next to\nrelated menu items or information to specify there are additional quick actions\nto take, whether it be upgrading an account plan or changing a location. Only\nadd icons and links to a profile menu if completely necessary in order to not\noverwhelm the user and to reduce visual clutter within the menu.\n\n## Settings and filter menus\n\nSettings and filters follow the disclosure pattern by clicking an icon button\nthat opens a popover. Interactive elements are often found in settings and\nfilters in order to modify or adjust specific content. The disclosure pattern\nallows you to nest interactive elements inside of a popover while still being\naccessible.\n\n### Anatomy\n\n\n\n\n\n\n\n\n\n
Anatomy of a settings menu.
\n\n1. **Icon button:** A trigger to open and close the popover.\n2. **Popover:** Uses the popover component as an underlying layer.\n3. **Content area:** Area to place text and interactive elements.\n4. **Button group:** To cancel or apply changes in settings or filters that\n affect other content on the page.\n\n### Structure\n\nSettings or filter menus are made up of two parts—an icon button and a popover.\nThese types of menus usually contain interactive elements. For example, use\nbuttons to clear filters, use checkboxes, radio buttons, or dropdowns to adjust\ncontent and use sets of buttons to reset or apply changes. Content may vary\ndepending on what is being filtered, sorted, or what settings need to be\ndefined.\n\n\n\n\n\n\n\n\n\n
Example of a filter menu structure
\n\n### Functionality\n\n#### Mouse\n\nClicking the icon button triggers the popover to open. Upon opening the menu,\nthe first interactive element in the menu receives focus. To close the menu\nclick on the icon button again, or anywhere on the page outside of the menu.\n\n\n\n\n\n\n\n\n\n
Example of a closed and opened filter menu.
\n\n#### Keyboard\n\n- `Tab` to the icon button trigger to apply focus.\n- To open the settings or filter menu press `Enter` or `Space`.\n- Upon opening the menu, the first interactive element in the menu receives\n focus.\n- To shift focus to different interactive elements in the menu press the `Tab`\n or `Shift` + `Tab`.\n- To close the settings or filter menu press `Esc`. Pressing `Enter` or `Space`\n on a button can also close the menu.\n\n### Best practices\n\n#### Use a set of buttons to apply all changes\n\nIn some use cases when live filtering is not feasible or the preferred method,\nuse a set of buttons to either reset or apply all selected changes in the\nsettings or filter menu. Once the \"Apply\" button has been selected, the menu\ncloses and the results are updated.\n\n#### Don't overcrowd menus with unnecessary content\n\nOnly include content or interactive elements that are necessary. Overcrowding\ndisclosures with too many options or additional content can be distracting to\nthe user.\n\n#### Include enough space between elements\n\nWhen placing interactive elements, be mindful of the padding between the\ninteractive element and other content in the disclosure. A good rule of thumb is\nto keep at least 16px padding between different elements and content.\n\n## Combo button\n\nA combo button is a type of disclosure pattern and displays a primary default\naction that discloses a list of additional, related actions to choose from in a\npopover.\n\n### Anatomy\n\n\n\n\n\n\n\n\n\n
Anatomy of a combo button.
\n\n1. **Primary button:** A default action.\n2. **Icon button:** A trigger to open and close the popover.\n3. **Content area:** A list of additional actions.\n4. **Menu:** Uses the popover component as an underlying layer.\n\n### Structure\n\nA combo button is made up of three parts—a primary button, an icon button, and a\npopover. Dividers are shown to visually separate different actions that are\nrelated to each other.\n\n\n\n\n\n\n\n\n\n### Functionality\n\n#### Mouse\n\nClicking the primary default action will perform the defaulted action. Clicking\nthe icon button triggers the popover to open and reveals the additional actions\nto choose from in a menu. Clicking on an action in the menu will perform the\naction. To close the menu click on the icon button again, or anywhere on the\npage outside of the menu.\n\n\n\n\n\n\n\n\n\n#### Keyboard\n\nPrimary default button: `Tab` to the primary default button to apply focus.\nTrigger the primary default button by pressing `Enter` or `Space`.\n\nIcon button: `Tab` to the icon button to apply focus. Open the menu by\npressing `Enter`, `Space`, or the `Down` arrow key.\n\nMenu: When the menu is opened, focus will go to the first additional action in\nthe menu list. Move between menu actions by pressing the `Up` and `Down` arrow\nkeys. Close the menu by pressing `Enter` or `Space` to activate the action with\nfocus or `Esc` to cancel.\n\n### Best practices\n\n#### Choose a default action\n\nRemember to choose the default, primary action that will be displayed in the\nprimary button so it is not hidden within the menu of additional actions. The\nprimary default action is typically the most commonly used action there is to\ntake.\n\n#### Use to reduce visual complexity on a page\n\nCombo buttons reduce visual complexity by grouping similar commands together.\nFor example, how navigation menus group together related options to enable\nconceptual understanding of the site information structure.\n\n#### Avoid using extra icons\n\nAvoid using extra icons inside of the default, primary button and the additional\nactions in the menu to reduce visual noise between elements. Keep button labels\nclear and concise.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n## Accessibility\n\n#### Screen readers\n\nVoiceOver: Users can trigger a button to open a disclosure popover by pressing\n`Enter` or `Space` while the trigger has focus.\n\nJAWS: Users can trigger a button to open a disclosure popover by pressing\n`Enter` or `Space` while the trigger has focus.\n\nNVDA: Users can trigger a button to open a disclosure popover by pressing\n`Enter` or `Space` while the trigger has focus.\n\n## Related\n\n#### Button\n\nButtons are clickable interactive elements that are commonly used in disclosures\nas the trigger to open a popover. There are multiple variants of button that\nshould be used for certain use cases. For further guidance, see Carbon's\n[button component](https://www.carbondesignsystem.com/components/button/usage/)\nguidance.\n\n#### Popover\n\nPopovers are frequently used in disclosures to show additional content. Popovers\nare also used in components like tooltips, overflow menus, and dropdown menus.\nFor further guidance of how to use a popover, see Carbon’s\n[popover component](https://v11.carbondesignsystem.com/components/popover/usage/).\n\n#### Toggletip\n\nToggletip uses the disclosure pattern to toggle the visibility of a popover. The\npopover may contain a variety of information, from descriptive text to\ninteractive elements. Toggletips are triggered on click to disclose the\ninformation inside of a popover. For further guidance, see Carbon's\n[toggletip component](https://v11.carbondesignsystem.com/components/toggletip/usage/)\nguidance.\n\n## References\n\nContext menu,\n[Delivering Relevant Tools for Tasks](https://www.nngroup.com/articles/contextual-menus/),(Nielsen\nNorman Group)\n\nSplit\nButtons,[Component definition](https://www.nngroup.com/articles/split-buttons/),(Nielsen\nNorman Group)\n\nPopup,[Component research](https://open-ui.org/components/popup.research#popup),(OpenUI)\n\nEnabling\nPopups,[Initial Explainer](https://open-ui.org/components/popup.research.explainer),(OpenUI)\n\nDisclosure,[W3C WAI-ARIA practices](https://v11.carbondesignsystem.com/components/popover/usage/%5Bhttps://www.w3.org/TR/wai-aria-practices-1.1/#disclosure),(W3C\nWorking Group Note)\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments on\n[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","type":"Mdx","contentDigest":"78bd2053c1314e91f1427e1194420b17","owner":"gatsby-plugin-mdx","counter":5332},"frontmatter":{"title":"Disclosures","description":"Disclosures are moments that open up on a page and reveal additional information related to the source it is triggered from."},"exports":{},"rawBody":"---\ntitle: Disclosures\ndescription:\n Disclosures are moments that open up on a page and reveal additional\n information related to the source it is triggered from.\n---\n\n\n\nDisclosures are moments that open up on a page and reveal additional information\nrelated to the source it is triggered from.\n\n\n\n\n\nOverview\nProfile menu\nSettings and filter menus\nCombo button\nAccessibility\nRelated\nReferences\nFeedback\n\n\n\n## Overview\n\nDisclosures support a wide range of different use cases in product interfaces\nand are commonly used to reveal more information or details about an element or\ncontent on a page. Unlike tooltips, the content expanded by a disclosure may\ncontain interactive elements.\n\nAt its core, a disclosure is comprised of two parts—a trigger that the user\ninteracts with by clicking or using their keyboard and the container that opens\nand discloses the content.\n\n### When to use\n\n- Use when disclosing additional content about part of a UI.\n- Use when there is a need to include interactive elements in a popover.\n- Use to show settings, filtering, or sorting menus that affect sections of a\n page, for example in data tables, or an entire page.\n- Use when displaying content within types of dropdowns, for example profile\n menus, combo buttons, and menu buttons.\n\n### When not to use\n\n- Don't use to present critical information or request required input needed to\n complete a workflow. Use the\n [modal component](https://www.carbondesignsystem.com/components/modal/usage/)\n instead.\n- Don’t use when the user hasn’t explicitly triggered the popover to open on\n click.\n- Don't use if the popover needs to have a width larger than six columns.\n\n### Best practices\n\n#### Keep disclosures at a reasonable size\n\nA disclosure should not take up a considerable amount of the size of the screen.\nDisclosures are meant to be smaller moments that can open on top of different\nareas of a page. They should not seem like a disruption to the users workflow\nand should not act as a screen takeover. Keep all content in a disclosure\nconcise and only include information that is necessary. We recommend having a\nwidth of six columns or less.\n\n#### Disclosures should be user initiated\n\nDisclosures should always be triggered to open or close by the user. Disclosures\nshould never open automatically because this could be potentially intrusive to\nthe user's workflow.\n\n#### One disclosure should open at a time\n\nIf there are multiple instances on a page where a disclosure is present, only\none should open at a time to avoid screen clutter and to help the user stay\nfocused on the information being disclosed.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n#### Avoid nesting disclosures\n\nDo not nest one disclosure within another disclosure. Nesting disclosures\ncreates a stacking effect and could confuse the user of where they should be\nfocusing their attention and which disclosure they should be interacting with.\nUsing submenus in a context menu that fly out to the sides is an acceptable way\nto disclose additional information in a disclosure.\n\n#### Do not hide critical information within a disclosure\n\nDo not hide important information inside of a disclosure that the user may need\nin order to complete a task or workflow. Keep critical information at a higher\nlevel so the user has better visibility.\n\n### Behaviors\n\n**Opening and closing a disclosure**\n\nTo open a disclosure to reveal its content, click the trigger button it is\nrelated to. If using a keyboard, press `Enter` or `Space`.\n\nTo close a disclosure, either click on the trigger button again, click anywhere\noutside of the open disclosure container or click on the close `x` icon if it is\npresent within the disclosure. If using a keyboard, press `Esc` or `Tab` to tab\nout of the disclosure.\n\n#### Dismissible action\n\nDepending on the type of content in a disclosure, it can be useful to display a\nclose `x` icon. Be mindful when and where you place a close icon in a\ndisclosure. The close icon should always be in the top right corner of the\npopover and should not interfere or overlap with inline interactive elements.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n### Visual guidance\n\n#### Trigger button container\n\nA disclosure is controlled by a trigger button. The trigger button can visually\nchange its shape and size depending on the usecase.\n\nThe trigger button can use any of our button types and can be set at these three\nsizes—48px (lg), 40px (md) or 32px (sm).\n\n\n\n\n\n\n\n\n\n
Example of trigger button container height sizes.
\n\n#### Trigger button icon\n\nIf a trigger button contains an icon, the icon size should be either 20px or\n16px.\n\n\n\n\n\n\n\n\n\n
Example of trigger button icon sizes.
\n\n#### Popover\n\nA popover component is used as the underlying layer of a disclosure to disclose\nits content. See the\n[popover component](https://v11.carbondesignsystem.com/components/popover/usage/)\nguidance for more information.\n\n\n\n\n\n\n\n\n\n
Example of a popover container.
\n\n### Content\n\nThe type of content in a disclosure can vary depending on the use case. A\ndisclosure can be simple and contain solely informational text. In some cases\ncontent can be more complex and include a combination of multiple sections and\ninteractive elements. Below are some common examples and best practices of how\nto show body text, heading text, and footer content in disclosures.\n\n#### Heading text\n\nHeading text can be placed above body text in a disclosure. Placing the heading\ntext with 0px padding above the body text or adding a divider between the\nheading text and body text are two different common use cases.\n\n\n\n\n\n\n\n\n\n
Example of a disclosure with heading text.
\n\n#### Footer content\n\nFooter content can be placed below the body text it is related to. Placing the\nfooter content with 16px padding below the body text or adding a divider between\nthe footer content and body text are two different common use cases.\n\n\n\n\n\n\n\n\n\n
Example of a disclosure with footer content.
\n\n#### Multiple sections of text\n\nDepending on the use case, you may need a disclosure to show multiple sections\nof content. Use padding or dividers to visually create sections. Profile menus\nand context menus typically display multiple sections of content depending on\nthe complexity of the menu.\n\n\n\n\n\n\n\n\n\n
Example of a disclosure with multiple sections.
\n\n#### Interactive elements\n\nDisclosures allow you to place interactive elements in a popover while still\nkeeping it accessible. Settings and filters often include components like radio\nbuttons and checkboxes that the user can interact with to adjust specific\ncontent. Searching within a menu is another common use case of including\ninteractive elements within a popover.\n\n\n\n\n\n\n\n\n\n
Example of a disclosure with interactive content.
\n\n## Common use cases\n\nDisclosures are used for a wide variety of use cases. The following variants are\na few examples of common disclosures that you may come across frequently in\nproduct interfaces.\n\n| Example | Use cases |\n| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Profile menu | Profile menus are typically part of a UI shell header and can have navigational options related to a user's account or active session. |\n| Settings and filter menus | Settings and filter menus are frequently used within data table toolbars to enable users to adjust content. Filter and sort menus can also be used for filtering large amounts of content on a page or an entire page. |\n| Combo button | Combo buttons are used to contain multiple related actions that come with a default, primary action. Additional actions live in the menu. |\n\n## Profile menu\n\nProfile menus follow the disclosure pattern by clicking an icon button that\nopens a popover. Profile menus are essential to a product's UI and users rely on\nit to find global content related to their account, product, and active session\ninformation. Profile menus provide a way to log in or out of an account and let\nusers access their settings. Additional links and icons can be added to a\nprofile menu depending on the use case.\n\nSee the\n[profile menu pattern](https://pages.github.ibm.com/cdai-design/pal/patterns/profile-header-menu/)\nfor more information.\n\n### Anatomy\n\n\n\n\n\n\n\n\n\n
Anatomy of a profile menu.
\n\n1. **Toolbar profile image:** A profile image, initials, or icon of a user.\n2. **Menu profile image:** A profile image that is paired with high level\n information about the user, such as a name or handle.\n3. **Section dividers (optional):** To group related content by creating visual\n sections.\n4. **Contextual information (optional):** Global information that is related to\n the account or active session.\n5. **Link (optional):** Additional links that are not main menu items. Links can\n be used for editing, prompting a modal, etc.\n6. **Menu items:** The main and most commonly used menu items that are\n navigational.\n7. **Icon (optional):** Additional icons to place inline with menu items.\n\n### Structure\n\nA profile menu is made up of two parts—an icon button and a popover. Profile\nmenus support a variety of content that can range in complexity. Some profile\nmenus are simple while other menus may be more complex and require multiple\nsections of information. Profile menus that are complex may benefit from\nincluding interactive elements depending on the use case.\n\n\n\n\n\n\n\n\n\n
Example of a simple and complex profile menu.
\n\n### Functionality\n\n#### Mouse\n\nClicking the icon button triggers the profile menu to open and reveals\ninformation related to the users profile and account. The user can then click on\nmenu items and other interactive elements within the menu. To close the menu,\nclick on the icon button trigger again or anywhere on the page out side of the\nmenu.\n\n\n\n\n\n\n\n\n\n#### Keyboard\n\n- `Tab` to the icon button trigger to apply focus.\n- To open the profile menu press `Enter` or `Space`.\n- Once opened, focus goes to the first item in the menu.\n- To navigate the profile menu items press the `Up` and `Down` arrow keys.\n- To select an item in the profile menu press `Enter`.\n- To close the profile menu press `Esc` .\n\n### Best practices\n\n#### Use with a global toolbar header\n\nIf a product has a global toolbar header and offers login capabilities, use the\nprofile menu. Provide a way for the user to log out of an account, make changes\nto profile information, or navigate to settings.\n\n#### Show information that is pertinent to the user account or session\n\nInclude sections on a global contextual level that may be helpful to the user to\nsee in the profile menu. For example, indicating the current plan or location\nwith an option to edit or change the current information can be valuable to\ninclude in a profile menu depending on the use case.\n\n#### Add icons and links to help guide the user\n\nWhen appropriate, pair icons with related menu items or information to indicate\nthe action that will be performed once it is clicked. Provide links next to\nrelated menu items or information to specify there are additional quick actions\nto take, whether it be upgrading an account plan or changing a location. Only\nadd icons and links to a profile menu if completely necessary in order to not\noverwhelm the user and to reduce visual clutter within the menu.\n\n## Settings and filter menus\n\nSettings and filters follow the disclosure pattern by clicking an icon button\nthat opens a popover. Interactive elements are often found in settings and\nfilters in order to modify or adjust specific content. The disclosure pattern\nallows you to nest interactive elements inside of a popover while still being\naccessible.\n\n### Anatomy\n\n\n\n\n\n\n\n\n\n
Anatomy of a settings menu.
\n\n1. **Icon button:** A trigger to open and close the popover.\n2. **Popover:** Uses the popover component as an underlying layer.\n3. **Content area:** Area to place text and interactive elements.\n4. **Button group:** To cancel or apply changes in settings or filters that\n affect other content on the page.\n\n### Structure\n\nSettings or filter menus are made up of two parts—an icon button and a popover.\nThese types of menus usually contain interactive elements. For example, use\nbuttons to clear filters, use checkboxes, radio buttons, or dropdowns to adjust\ncontent and use sets of buttons to reset or apply changes. Content may vary\ndepending on what is being filtered, sorted, or what settings need to be\ndefined.\n\n\n\n\n\n\n\n\n\n
Example of a filter menu structure
\n\n### Functionality\n\n#### Mouse\n\nClicking the icon button triggers the popover to open. Upon opening the menu,\nthe first interactive element in the menu receives focus. To close the menu\nclick on the icon button again, or anywhere on the page outside of the menu.\n\n\n\n\n\n\n\n\n\n
Example of a closed and opened filter menu.
\n\n#### Keyboard\n\n- `Tab` to the icon button trigger to apply focus.\n- To open the settings or filter menu press `Enter` or `Space`.\n- Upon opening the menu, the first interactive element in the menu receives\n focus.\n- To shift focus to different interactive elements in the menu press the `Tab`\n or `Shift` + `Tab`.\n- To close the settings or filter menu press `Esc`. Pressing `Enter` or `Space`\n on a button can also close the menu.\n\n### Best practices\n\n#### Use a set of buttons to apply all changes\n\nIn some use cases when live filtering is not feasible or the preferred method,\nuse a set of buttons to either reset or apply all selected changes in the\nsettings or filter menu. Once the \"Apply\" button has been selected, the menu\ncloses and the results are updated.\n\n#### Don't overcrowd menus with unnecessary content\n\nOnly include content or interactive elements that are necessary. Overcrowding\ndisclosures with too many options or additional content can be distracting to\nthe user.\n\n#### Include enough space between elements\n\nWhen placing interactive elements, be mindful of the padding between the\ninteractive element and other content in the disclosure. A good rule of thumb is\nto keep at least 16px padding between different elements and content.\n\n## Combo button\n\nA combo button is a type of disclosure pattern and displays a primary default\naction that discloses a list of additional, related actions to choose from in a\npopover.\n\n### Anatomy\n\n\n\n\n\n\n\n\n\n
Anatomy of a combo button.
\n\n1. **Primary button:** A default action.\n2. **Icon button:** A trigger to open and close the popover.\n3. **Content area:** A list of additional actions.\n4. **Menu:** Uses the popover component as an underlying layer.\n\n### Structure\n\nA combo button is made up of three parts—a primary button, an icon button, and a\npopover. Dividers are shown to visually separate different actions that are\nrelated to each other.\n\n\n\n\n\n\n\n\n\n### Functionality\n\n#### Mouse\n\nClicking the primary default action will perform the defaulted action. Clicking\nthe icon button triggers the popover to open and reveals the additional actions\nto choose from in a menu. Clicking on an action in the menu will perform the\naction. To close the menu click on the icon button again, or anywhere on the\npage outside of the menu.\n\n\n\n\n\n\n\n\n\n#### Keyboard\n\nPrimary default button: `Tab` to the primary default button to apply focus.\nTrigger the primary default button by pressing `Enter` or `Space`.\n\nIcon button: `Tab` to the icon button to apply focus. Open the menu by\npressing `Enter`, `Space`, or the `Down` arrow key.\n\nMenu: When the menu is opened, focus will go to the first additional action in\nthe menu list. Move between menu actions by pressing the `Up` and `Down` arrow\nkeys. Close the menu by pressing `Enter` or `Space` to activate the action with\nfocus or `Esc` to cancel.\n\n### Best practices\n\n#### Choose a default action\n\nRemember to choose the default, primary action that will be displayed in the\nprimary button so it is not hidden within the menu of additional actions. The\nprimary default action is typically the most commonly used action there is to\ntake.\n\n#### Use to reduce visual complexity on a page\n\nCombo buttons reduce visual complexity by grouping similar commands together.\nFor example, how navigation menus group together related options to enable\nconceptual understanding of the site information structure.\n\n#### Avoid using extra icons\n\nAvoid using extra icons inside of the default, primary button and the additional\nactions in the menu to reduce visual noise between elements. Keep button labels\nclear and concise.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n## Accessibility\n\n#### Screen readers\n\nVoiceOver: Users can trigger a button to open a disclosure popover by pressing\n`Enter` or `Space` while the trigger has focus.\n\nJAWS: Users can trigger a button to open a disclosure popover by pressing\n`Enter` or `Space` while the trigger has focus.\n\nNVDA: Users can trigger a button to open a disclosure popover by pressing\n`Enter` or `Space` while the trigger has focus.\n\n## Related\n\n#### Button\n\nButtons are clickable interactive elements that are commonly used in disclosures\nas the trigger to open a popover. There are multiple variants of button that\nshould be used for certain use cases. For further guidance, see Carbon's\n[button component](https://www.carbondesignsystem.com/components/button/usage/)\nguidance.\n\n#### Popover\n\nPopovers are frequently used in disclosures to show additional content. Popovers\nare also used in components like tooltips, overflow menus, and dropdown menus.\nFor further guidance of how to use a popover, see Carbon’s\n[popover component](https://v11.carbondesignsystem.com/components/popover/usage/).\n\n#### Toggletip\n\nToggletip uses the disclosure pattern to toggle the visibility of a popover. The\npopover may contain a variety of information, from descriptive text to\ninteractive elements. Toggletips are triggered on click to disclose the\ninformation inside of a popover. For further guidance, see Carbon's\n[toggletip component](https://v11.carbondesignsystem.com/components/toggletip/usage/)\nguidance.\n\n## References\n\nContext menu,\n[Delivering Relevant Tools for Tasks](https://www.nngroup.com/articles/contextual-menus/),(Nielsen\nNorman Group)\n\nSplit\nButtons,[Component definition](https://www.nngroup.com/articles/split-buttons/),(Nielsen\nNorman Group)\n\nPopup,[Component research](https://open-ui.org/components/popup.research#popup),(OpenUI)\n\nEnabling\nPopups,[Initial Explainer](https://open-ui.org/components/popup.research.explainer),(OpenUI)\n\nDisclosure,[W3C WAI-ARIA practices](https://v11.carbondesignsystem.com/components/popover/usage/%5Bhttps://www.w3.org/TR/wai-aria-practices-1.1/#disclosure),(W3C\nWorking Group Note)\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments on\n[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/patterns/disclosures-pattern/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-patterns-disclosures-pattern-index-mdx","path":"/patterns/disclosures-pattern/","result":{"pageContext":{"frontmatter":{"title":"Disclosures","description":"Disclosures are moments that open up on a page and reveal additional information related to the source it is triggered from."},"relativePagePath":"/patterns/disclosures-pattern/index.mdx","titleType":"prepend","MdxNode":{"id":"e1f54a23-8631-5d6e-be2d-a83139683480","children":[],"parent":"48dcaf3e-287e-5534-a03c-960d62863884","internal":{"content":"---\ntitle: Disclosures\ndescription:\n Disclosures are moments that open up on a page and reveal additional\n information related to the source it is triggered from.\n---\n\n\n\nDisclosures are moments that open up on a page and reveal additional information\nrelated to the source it is triggered from.\n\n\n\n\n\nOverview\nProfile menu\nSettings and filter menus\nCombo button\nAccessibility\nRelated\nReferences\nFeedback\n\n\n\n## Overview\n\nDisclosures support a wide range of different use cases in product interfaces\nand are commonly used to reveal more information or details about an element or\ncontent on a page. Unlike tooltips, the content expanded by a disclosure may\ncontain interactive elements.\n\nAt its core, a disclosure is comprised of two parts—a trigger that the user\ninteracts with by clicking or using their keyboard and the container that opens\nand discloses the content.\n\n### When to use\n\n- Use when disclosing additional content about part of a UI.\n- Use when there is a need to include interactive elements in a popover.\n- Use to show settings, filtering, or sorting menus that affect sections of a\n page, for example in data tables, or an entire page.\n- Use when displaying content within types of dropdowns, for example profile\n menus, combo buttons, and menu buttons.\n\n### When not to use\n\n- Don't use to present critical information or request required input needed to\n complete a workflow. Use the\n [modal component](https://www.carbondesignsystem.com/components/modal/usage/)\n instead.\n- Don’t use when the user hasn’t explicitly triggered the popover to open on\n click.\n- Don't use if the popover needs to have a width larger than six columns.\n\n### Best practices\n\n#### Keep disclosures at a reasonable size\n\nA disclosure should not take up a considerable amount of the size of the screen.\nDisclosures are meant to be smaller moments that can open on top of different\nareas of a page. They should not seem like a disruption to the users workflow\nand should not act as a screen takeover. Keep all content in a disclosure\nconcise and only include information that is necessary. We recommend having a\nwidth of six columns or less.\n\n#### Disclosures should be user initiated\n\nDisclosures should always be triggered to open or close by the user. Disclosures\nshould never open automatically because this could be potentially intrusive to\nthe user's workflow.\n\n#### One disclosure should open at a time\n\nIf there are multiple instances on a page where a disclosure is present, only\none should open at a time to avoid screen clutter and to help the user stay\nfocused on the information being disclosed.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n#### Avoid nesting disclosures\n\nDo not nest one disclosure within another disclosure. Nesting disclosures\ncreates a stacking effect and could confuse the user of where they should be\nfocusing their attention and which disclosure they should be interacting with.\nUsing submenus in a context menu that fly out to the sides is an acceptable way\nto disclose additional information in a disclosure.\n\n#### Do not hide critical information within a disclosure\n\nDo not hide important information inside of a disclosure that the user may need\nin order to complete a task or workflow. Keep critical information at a higher\nlevel so the user has better visibility.\n\n### Behaviors\n\n**Opening and closing a disclosure**\n\nTo open a disclosure to reveal its content, click the trigger button it is\nrelated to. If using a keyboard, press `Enter` or `Space`.\n\nTo close a disclosure, either click on the trigger button again, click anywhere\noutside of the open disclosure container or click on the close `x` icon if it is\npresent within the disclosure. If using a keyboard, press `Esc` or `Tab` to tab\nout of the disclosure.\n\n#### Dismissible action\n\nDepending on the type of content in a disclosure, it can be useful to display a\nclose `x` icon. Be mindful when and where you place a close icon in a\ndisclosure. The close icon should always be in the top right corner of the\npopover and should not interfere or overlap with inline interactive elements.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n### Visual guidance\n\n#### Trigger button container\n\nA disclosure is controlled by a trigger button. The trigger button can visually\nchange its shape and size depending on the usecase.\n\nThe trigger button can use any of our button types and can be set at these three\nsizes—48px (lg), 40px (md) or 32px (sm).\n\n\n\n\n\n\n\n\n\n
Example of trigger button container height sizes.
\n\n#### Trigger button icon\n\nIf a trigger button contains an icon, the icon size should be either 20px or\n16px.\n\n\n\n\n\n\n\n\n\n
Example of trigger button icon sizes.
\n\n#### Popover\n\nA popover component is used as the underlying layer of a disclosure to disclose\nits content. See the\n[popover component](https://v11.carbondesignsystem.com/components/popover/usage/)\nguidance for more information.\n\n\n\n\n\n\n\n\n\n
Example of a popover container.
\n\n### Content\n\nThe type of content in a disclosure can vary depending on the use case. A\ndisclosure can be simple and contain solely informational text. In some cases\ncontent can be more complex and include a combination of multiple sections and\ninteractive elements. Below are some common examples and best practices of how\nto show body text, heading text, and footer content in disclosures.\n\n#### Heading text\n\nHeading text can be placed above body text in a disclosure. Placing the heading\ntext with 0px padding above the body text or adding a divider between the\nheading text and body text are two different common use cases.\n\n\n\n\n\n\n\n\n\n
Example of a disclosure with heading text.
\n\n#### Footer content\n\nFooter content can be placed below the body text it is related to. Placing the\nfooter content with 16px padding below the body text or adding a divider between\nthe footer content and body text are two different common use cases.\n\n\n\n\n\n\n\n\n\n
Example of a disclosure with footer content.
\n\n#### Multiple sections of text\n\nDepending on the use case, you may need a disclosure to show multiple sections\nof content. Use padding or dividers to visually create sections. Profile menus\nand context menus typically display multiple sections of content depending on\nthe complexity of the menu.\n\n\n\n\n\n\n\n\n\n
Example of a disclosure with multiple sections.
\n\n#### Interactive elements\n\nDisclosures allow you to place interactive elements in a popover while still\nkeeping it accessible. Settings and filters often include components like radio\nbuttons and checkboxes that the user can interact with to adjust specific\ncontent. Searching within a menu is another common use case of including\ninteractive elements within a popover.\n\n\n\n\n\n\n\n\n\n
Example of a disclosure with interactive content.
\n\n## Common use cases\n\nDisclosures are used for a wide variety of use cases. The following variants are\na few examples of common disclosures that you may come across frequently in\nproduct interfaces.\n\n| Example | Use cases |\n| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Profile menu | Profile menus are typically part of a UI shell header and can have navigational options related to a user's account or active session. |\n| Settings and filter menus | Settings and filter menus are frequently used within data table toolbars to enable users to adjust content. Filter and sort menus can also be used for filtering large amounts of content on a page or an entire page. |\n| Combo button | Combo buttons are used to contain multiple related actions that come with a default, primary action. Additional actions live in the menu. |\n\n## Profile menu\n\nProfile menus follow the disclosure pattern by clicking an icon button that\nopens a popover. Profile menus are essential to a product's UI and users rely on\nit to find global content related to their account, product, and active session\ninformation. Profile menus provide a way to log in or out of an account and let\nusers access their settings. Additional links and icons can be added to a\nprofile menu depending on the use case.\n\nSee the\n[profile menu pattern](https://pages.github.ibm.com/cdai-design/pal/patterns/profile-header-menu/)\nfor more information.\n\n### Anatomy\n\n\n\n\n\n\n\n\n\n
Anatomy of a profile menu.
\n\n1. **Toolbar profile image:** A profile image, initials, or icon of a user.\n2. **Menu profile image:** A profile image that is paired with high level\n information about the user, such as a name or handle.\n3. **Section dividers (optional):** To group related content by creating visual\n sections.\n4. **Contextual information (optional):** Global information that is related to\n the account or active session.\n5. **Link (optional):** Additional links that are not main menu items. Links can\n be used for editing, prompting a modal, etc.\n6. **Menu items:** The main and most commonly used menu items that are\n navigational.\n7. **Icon (optional):** Additional icons to place inline with menu items.\n\n### Structure\n\nA profile menu is made up of two parts—an icon button and a popover. Profile\nmenus support a variety of content that can range in complexity. Some profile\nmenus are simple while other menus may be more complex and require multiple\nsections of information. Profile menus that are complex may benefit from\nincluding interactive elements depending on the use case.\n\n\n\n\n\n\n\n\n\n
Example of a simple and complex profile menu.
\n\n### Functionality\n\n#### Mouse\n\nClicking the icon button triggers the profile menu to open and reveals\ninformation related to the users profile and account. The user can then click on\nmenu items and other interactive elements within the menu. To close the menu,\nclick on the icon button trigger again or anywhere on the page out side of the\nmenu.\n\n\n\n\n\n\n\n\n\n#### Keyboard\n\n- `Tab` to the icon button trigger to apply focus.\n- To open the profile menu press `Enter` or `Space`.\n- Once opened, focus goes to the first item in the menu.\n- To navigate the profile menu items press the `Up` and `Down` arrow keys.\n- To select an item in the profile menu press `Enter`.\n- To close the profile menu press `Esc` .\n\n### Best practices\n\n#### Use with a global toolbar header\n\nIf a product has a global toolbar header and offers login capabilities, use the\nprofile menu. Provide a way for the user to log out of an account, make changes\nto profile information, or navigate to settings.\n\n#### Show information that is pertinent to the user account or session\n\nInclude sections on a global contextual level that may be helpful to the user to\nsee in the profile menu. For example, indicating the current plan or location\nwith an option to edit or change the current information can be valuable to\ninclude in a profile menu depending on the use case.\n\n#### Add icons and links to help guide the user\n\nWhen appropriate, pair icons with related menu items or information to indicate\nthe action that will be performed once it is clicked. Provide links next to\nrelated menu items or information to specify there are additional quick actions\nto take, whether it be upgrading an account plan or changing a location. Only\nadd icons and links to a profile menu if completely necessary in order to not\noverwhelm the user and to reduce visual clutter within the menu.\n\n## Settings and filter menus\n\nSettings and filters follow the disclosure pattern by clicking an icon button\nthat opens a popover. Interactive elements are often found in settings and\nfilters in order to modify or adjust specific content. The disclosure pattern\nallows you to nest interactive elements inside of a popover while still being\naccessible.\n\n### Anatomy\n\n\n\n\n\n\n\n\n\n
Anatomy of a settings menu.
\n\n1. **Icon button:** A trigger to open and close the popover.\n2. **Popover:** Uses the popover component as an underlying layer.\n3. **Content area:** Area to place text and interactive elements.\n4. **Button group:** To cancel or apply changes in settings or filters that\n affect other content on the page.\n\n### Structure\n\nSettings or filter menus are made up of two parts—an icon button and a popover.\nThese types of menus usually contain interactive elements. For example, use\nbuttons to clear filters, use checkboxes, radio buttons, or dropdowns to adjust\ncontent and use sets of buttons to reset or apply changes. Content may vary\ndepending on what is being filtered, sorted, or what settings need to be\ndefined.\n\n\n\n\n\n\n\n\n\n
Example of a filter menu structure
\n\n### Functionality\n\n#### Mouse\n\nClicking the icon button triggers the popover to open. Upon opening the menu,\nthe first interactive element in the menu receives focus. To close the menu\nclick on the icon button again, or anywhere on the page outside of the menu.\n\n\n\n\n\n\n\n\n\n
Example of a closed and opened filter menu.
\n\n#### Keyboard\n\n- `Tab` to the icon button trigger to apply focus.\n- To open the settings or filter menu press `Enter` or `Space`.\n- Upon opening the menu, the first interactive element in the menu receives\n focus.\n- To shift focus to different interactive elements in the menu press the `Tab`\n or `Shift` + `Tab`.\n- To close the settings or filter menu press `Esc`. Pressing `Enter` or `Space`\n on a button can also close the menu.\n\n### Best practices\n\n#### Use a set of buttons to apply all changes\n\nIn some use cases when live filtering is not feasible or the preferred method,\nuse a set of buttons to either reset or apply all selected changes in the\nsettings or filter menu. Once the \"Apply\" button has been selected, the menu\ncloses and the results are updated.\n\n#### Don't overcrowd menus with unnecessary content\n\nOnly include content or interactive elements that are necessary. Overcrowding\ndisclosures with too many options or additional content can be distracting to\nthe user.\n\n#### Include enough space between elements\n\nWhen placing interactive elements, be mindful of the padding between the\ninteractive element and other content in the disclosure. A good rule of thumb is\nto keep at least 16px padding between different elements and content.\n\n## Combo button\n\nA combo button is a type of disclosure pattern and displays a primary default\naction that discloses a list of additional, related actions to choose from in a\npopover.\n\n### Anatomy\n\n\n\n\n\n\n\n\n\n
Anatomy of a combo button.
\n\n1. **Primary button:** A default action.\n2. **Icon button:** A trigger to open and close the popover.\n3. **Content area:** A list of additional actions.\n4. **Menu:** Uses the popover component as an underlying layer.\n\n### Structure\n\nA combo button is made up of three parts—a primary button, an icon button, and a\npopover. Dividers are shown to visually separate different actions that are\nrelated to each other.\n\n\n\n\n\n\n\n\n\n### Functionality\n\n#### Mouse\n\nClicking the primary default action will perform the defaulted action. Clicking\nthe icon button triggers the popover to open and reveals the additional actions\nto choose from in a menu. Clicking on an action in the menu will perform the\naction. To close the menu click on the icon button again, or anywhere on the\npage outside of the menu.\n\n\n\n\n\n\n\n\n\n#### Keyboard\n\nPrimary default button: `Tab` to the primary default button to apply focus.\nTrigger the primary default button by pressing `Enter` or `Space`.\n\nIcon button: `Tab` to the icon button to apply focus. Open the menu by\npressing `Enter`, `Space`, or the `Down` arrow key.\n\nMenu: When the menu is opened, focus will go to the first additional action in\nthe menu list. Move between menu actions by pressing the `Up` and `Down` arrow\nkeys. Close the menu by pressing `Enter` or `Space` to activate the action with\nfocus or `Esc` to cancel.\n\n### Best practices\n\n#### Choose a default action\n\nRemember to choose the default, primary action that will be displayed in the\nprimary button so it is not hidden within the menu of additional actions. The\nprimary default action is typically the most commonly used action there is to\ntake.\n\n#### Use to reduce visual complexity on a page\n\nCombo buttons reduce visual complexity by grouping similar commands together.\nFor example, how navigation menus group together related options to enable\nconceptual understanding of the site information structure.\n\n#### Avoid using extra icons\n\nAvoid using extra icons inside of the default, primary button and the additional\nactions in the menu to reduce visual noise between elements. Keep button labels\nclear and concise.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n## Accessibility\n\n#### Screen readers\n\nVoiceOver: Users can trigger a button to open a disclosure popover by pressing\n`Enter` or `Space` while the trigger has focus.\n\nJAWS: Users can trigger a button to open a disclosure popover by pressing\n`Enter` or `Space` while the trigger has focus.\n\nNVDA: Users can trigger a button to open a disclosure popover by pressing\n`Enter` or `Space` while the trigger has focus.\n\n## Related\n\n#### Button\n\nButtons are clickable interactive elements that are commonly used in disclosures\nas the trigger to open a popover. There are multiple variants of button that\nshould be used for certain use cases. For further guidance, see Carbon's\n[button component](https://www.carbondesignsystem.com/components/button/usage/)\nguidance.\n\n#### Popover\n\nPopovers are frequently used in disclosures to show additional content. Popovers\nare also used in components like tooltips, overflow menus, and dropdown menus.\nFor further guidance of how to use a popover, see Carbon’s\n[popover component](https://v11.carbondesignsystem.com/components/popover/usage/).\n\n#### Toggletip\n\nToggletip uses the disclosure pattern to toggle the visibility of a popover. The\npopover may contain a variety of information, from descriptive text to\ninteractive elements. Toggletips are triggered on click to disclose the\ninformation inside of a popover. For further guidance, see Carbon's\n[toggletip component](https://v11.carbondesignsystem.com/components/toggletip/usage/)\nguidance.\n\n## References\n\nContext menu,\n[Delivering Relevant Tools for Tasks](https://www.nngroup.com/articles/contextual-menus/),(Nielsen\nNorman Group)\n\nSplit\nButtons,[Component definition](https://www.nngroup.com/articles/split-buttons/),(Nielsen\nNorman Group)\n\nPopup,[Component research](https://open-ui.org/components/popup.research#popup),(OpenUI)\n\nEnabling\nPopups,[Initial Explainer](https://open-ui.org/components/popup.research.explainer),(OpenUI)\n\nDisclosure,[W3C WAI-ARIA practices](https://v11.carbondesignsystem.com/components/popover/usage/%5Bhttps://www.w3.org/TR/wai-aria-practices-1.1/#disclosure),(W3C\nWorking Group Note)\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments on\n[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","type":"Mdx","contentDigest":"78bd2053c1314e91f1427e1194420b17","owner":"gatsby-plugin-mdx","counter":5335},"frontmatter":{"title":"Disclosures","description":"Disclosures are moments that open up on a page and reveal additional information related to the source it is triggered from."},"exports":{},"rawBody":"---\ntitle: Disclosures\ndescription:\n Disclosures are moments that open up on a page and reveal additional\n information related to the source it is triggered from.\n---\n\n\n\nDisclosures are moments that open up on a page and reveal additional information\nrelated to the source it is triggered from.\n\n\n\n\n\nOverview\nProfile menu\nSettings and filter menus\nCombo button\nAccessibility\nRelated\nReferences\nFeedback\n\n\n\n## Overview\n\nDisclosures support a wide range of different use cases in product interfaces\nand are commonly used to reveal more information or details about an element or\ncontent on a page. Unlike tooltips, the content expanded by a disclosure may\ncontain interactive elements.\n\nAt its core, a disclosure is comprised of two parts—a trigger that the user\ninteracts with by clicking or using their keyboard and the container that opens\nand discloses the content.\n\n### When to use\n\n- Use when disclosing additional content about part of a UI.\n- Use when there is a need to include interactive elements in a popover.\n- Use to show settings, filtering, or sorting menus that affect sections of a\n page, for example in data tables, or an entire page.\n- Use when displaying content within types of dropdowns, for example profile\n menus, combo buttons, and menu buttons.\n\n### When not to use\n\n- Don't use to present critical information or request required input needed to\n complete a workflow. Use the\n [modal component](https://www.carbondesignsystem.com/components/modal/usage/)\n instead.\n- Don’t use when the user hasn’t explicitly triggered the popover to open on\n click.\n- Don't use if the popover needs to have a width larger than six columns.\n\n### Best practices\n\n#### Keep disclosures at a reasonable size\n\nA disclosure should not take up a considerable amount of the size of the screen.\nDisclosures are meant to be smaller moments that can open on top of different\nareas of a page. They should not seem like a disruption to the users workflow\nand should not act as a screen takeover. Keep all content in a disclosure\nconcise and only include information that is necessary. We recommend having a\nwidth of six columns or less.\n\n#### Disclosures should be user initiated\n\nDisclosures should always be triggered to open or close by the user. Disclosures\nshould never open automatically because this could be potentially intrusive to\nthe user's workflow.\n\n#### One disclosure should open at a time\n\nIf there are multiple instances on a page where a disclosure is present, only\none should open at a time to avoid screen clutter and to help the user stay\nfocused on the information being disclosed.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n#### Avoid nesting disclosures\n\nDo not nest one disclosure within another disclosure. Nesting disclosures\ncreates a stacking effect and could confuse the user of where they should be\nfocusing their attention and which disclosure they should be interacting with.\nUsing submenus in a context menu that fly out to the sides is an acceptable way\nto disclose additional information in a disclosure.\n\n#### Do not hide critical information within a disclosure\n\nDo not hide important information inside of a disclosure that the user may need\nin order to complete a task or workflow. Keep critical information at a higher\nlevel so the user has better visibility.\n\n### Behaviors\n\n**Opening and closing a disclosure**\n\nTo open a disclosure to reveal its content, click the trigger button it is\nrelated to. If using a keyboard, press `Enter` or `Space`.\n\nTo close a disclosure, either click on the trigger button again, click anywhere\noutside of the open disclosure container or click on the close `x` icon if it is\npresent within the disclosure. If using a keyboard, press `Esc` or `Tab` to tab\nout of the disclosure.\n\n#### Dismissible action\n\nDepending on the type of content in a disclosure, it can be useful to display a\nclose `x` icon. Be mindful when and where you place a close icon in a\ndisclosure. The close icon should always be in the top right corner of the\npopover and should not interfere or overlap with inline interactive elements.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n### Visual guidance\n\n#### Trigger button container\n\nA disclosure is controlled by a trigger button. The trigger button can visually\nchange its shape and size depending on the usecase.\n\nThe trigger button can use any of our button types and can be set at these three\nsizes—48px (lg), 40px (md) or 32px (sm).\n\n\n\n\n\n\n\n\n\n
Example of trigger button container height sizes.
\n\n#### Trigger button icon\n\nIf a trigger button contains an icon, the icon size should be either 20px or\n16px.\n\n\n\n\n\n\n\n\n\n
Example of trigger button icon sizes.
\n\n#### Popover\n\nA popover component is used as the underlying layer of a disclosure to disclose\nits content. See the\n[popover component](https://v11.carbondesignsystem.com/components/popover/usage/)\nguidance for more information.\n\n\n\n\n\n\n\n\n\n
Example of a popover container.
\n\n### Content\n\nThe type of content in a disclosure can vary depending on the use case. A\ndisclosure can be simple and contain solely informational text. In some cases\ncontent can be more complex and include a combination of multiple sections and\ninteractive elements. Below are some common examples and best practices of how\nto show body text, heading text, and footer content in disclosures.\n\n#### Heading text\n\nHeading text can be placed above body text in a disclosure. Placing the heading\ntext with 0px padding above the body text or adding a divider between the\nheading text and body text are two different common use cases.\n\n\n\n\n\n\n\n\n\n
Example of a disclosure with heading text.
\n\n#### Footer content\n\nFooter content can be placed below the body text it is related to. Placing the\nfooter content with 16px padding below the body text or adding a divider between\nthe footer content and body text are two different common use cases.\n\n\n\n\n\n\n\n\n\n
Example of a disclosure with footer content.
\n\n#### Multiple sections of text\n\nDepending on the use case, you may need a disclosure to show multiple sections\nof content. Use padding or dividers to visually create sections. Profile menus\nand context menus typically display multiple sections of content depending on\nthe complexity of the menu.\n\n\n\n\n\n\n\n\n\n
Example of a disclosure with multiple sections.
\n\n#### Interactive elements\n\nDisclosures allow you to place interactive elements in a popover while still\nkeeping it accessible. Settings and filters often include components like radio\nbuttons and checkboxes that the user can interact with to adjust specific\ncontent. Searching within a menu is another common use case of including\ninteractive elements within a popover.\n\n\n\n\n\n\n\n\n\n
Example of a disclosure with interactive content.
\n\n## Common use cases\n\nDisclosures are used for a wide variety of use cases. The following variants are\na few examples of common disclosures that you may come across frequently in\nproduct interfaces.\n\n| Example | Use cases |\n| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Profile menu | Profile menus are typically part of a UI shell header and can have navigational options related to a user's account or active session. |\n| Settings and filter menus | Settings and filter menus are frequently used within data table toolbars to enable users to adjust content. Filter and sort menus can also be used for filtering large amounts of content on a page or an entire page. |\n| Combo button | Combo buttons are used to contain multiple related actions that come with a default, primary action. Additional actions live in the menu. |\n\n## Profile menu\n\nProfile menus follow the disclosure pattern by clicking an icon button that\nopens a popover. Profile menus are essential to a product's UI and users rely on\nit to find global content related to their account, product, and active session\ninformation. Profile menus provide a way to log in or out of an account and let\nusers access their settings. Additional links and icons can be added to a\nprofile menu depending on the use case.\n\nSee the\n[profile menu pattern](https://pages.github.ibm.com/cdai-design/pal/patterns/profile-header-menu/)\nfor more information.\n\n### Anatomy\n\n\n\n\n\n\n\n\n\n
Anatomy of a profile menu.
\n\n1. **Toolbar profile image:** A profile image, initials, or icon of a user.\n2. **Menu profile image:** A profile image that is paired with high level\n information about the user, such as a name or handle.\n3. **Section dividers (optional):** To group related content by creating visual\n sections.\n4. **Contextual information (optional):** Global information that is related to\n the account or active session.\n5. **Link (optional):** Additional links that are not main menu items. Links can\n be used for editing, prompting a modal, etc.\n6. **Menu items:** The main and most commonly used menu items that are\n navigational.\n7. **Icon (optional):** Additional icons to place inline with menu items.\n\n### Structure\n\nA profile menu is made up of two parts—an icon button and a popover. Profile\nmenus support a variety of content that can range in complexity. Some profile\nmenus are simple while other menus may be more complex and require multiple\nsections of information. Profile menus that are complex may benefit from\nincluding interactive elements depending on the use case.\n\n\n\n\n\n\n\n\n\n
Example of a simple and complex profile menu.
\n\n### Functionality\n\n#### Mouse\n\nClicking the icon button triggers the profile menu to open and reveals\ninformation related to the users profile and account. The user can then click on\nmenu items and other interactive elements within the menu. To close the menu,\nclick on the icon button trigger again or anywhere on the page out side of the\nmenu.\n\n\n\n\n\n\n\n\n\n#### Keyboard\n\n- `Tab` to the icon button trigger to apply focus.\n- To open the profile menu press `Enter` or `Space`.\n- Once opened, focus goes to the first item in the menu.\n- To navigate the profile menu items press the `Up` and `Down` arrow keys.\n- To select an item in the profile menu press `Enter`.\n- To close the profile menu press `Esc` .\n\n### Best practices\n\n#### Use with a global toolbar header\n\nIf a product has a global toolbar header and offers login capabilities, use the\nprofile menu. Provide a way for the user to log out of an account, make changes\nto profile information, or navigate to settings.\n\n#### Show information that is pertinent to the user account or session\n\nInclude sections on a global contextual level that may be helpful to the user to\nsee in the profile menu. For example, indicating the current plan or location\nwith an option to edit or change the current information can be valuable to\ninclude in a profile menu depending on the use case.\n\n#### Add icons and links to help guide the user\n\nWhen appropriate, pair icons with related menu items or information to indicate\nthe action that will be performed once it is clicked. Provide links next to\nrelated menu items or information to specify there are additional quick actions\nto take, whether it be upgrading an account plan or changing a location. Only\nadd icons and links to a profile menu if completely necessary in order to not\noverwhelm the user and to reduce visual clutter within the menu.\n\n## Settings and filter menus\n\nSettings and filters follow the disclosure pattern by clicking an icon button\nthat opens a popover. Interactive elements are often found in settings and\nfilters in order to modify or adjust specific content. The disclosure pattern\nallows you to nest interactive elements inside of a popover while still being\naccessible.\n\n### Anatomy\n\n\n\n\n\n\n\n\n\n
Anatomy of a settings menu.
\n\n1. **Icon button:** A trigger to open and close the popover.\n2. **Popover:** Uses the popover component as an underlying layer.\n3. **Content area:** Area to place text and interactive elements.\n4. **Button group:** To cancel or apply changes in settings or filters that\n affect other content on the page.\n\n### Structure\n\nSettings or filter menus are made up of two parts—an icon button and a popover.\nThese types of menus usually contain interactive elements. For example, use\nbuttons to clear filters, use checkboxes, radio buttons, or dropdowns to adjust\ncontent and use sets of buttons to reset or apply changes. Content may vary\ndepending on what is being filtered, sorted, or what settings need to be\ndefined.\n\n\n\n\n\n\n\n\n\n
Example of a filter menu structure
\n\n### Functionality\n\n#### Mouse\n\nClicking the icon button triggers the popover to open. Upon opening the menu,\nthe first interactive element in the menu receives focus. To close the menu\nclick on the icon button again, or anywhere on the page outside of the menu.\n\n\n\n\n\n\n\n\n\n
Example of a closed and opened filter menu.
\n\n#### Keyboard\n\n- `Tab` to the icon button trigger to apply focus.\n- To open the settings or filter menu press `Enter` or `Space`.\n- Upon opening the menu, the first interactive element in the menu receives\n focus.\n- To shift focus to different interactive elements in the menu press the `Tab`\n or `Shift` + `Tab`.\n- To close the settings or filter menu press `Esc`. Pressing `Enter` or `Space`\n on a button can also close the menu.\n\n### Best practices\n\n#### Use a set of buttons to apply all changes\n\nIn some use cases when live filtering is not feasible or the preferred method,\nuse a set of buttons to either reset or apply all selected changes in the\nsettings or filter menu. Once the \"Apply\" button has been selected, the menu\ncloses and the results are updated.\n\n#### Don't overcrowd menus with unnecessary content\n\nOnly include content or interactive elements that are necessary. Overcrowding\ndisclosures with too many options or additional content can be distracting to\nthe user.\n\n#### Include enough space between elements\n\nWhen placing interactive elements, be mindful of the padding between the\ninteractive element and other content in the disclosure. A good rule of thumb is\nto keep at least 16px padding between different elements and content.\n\n## Combo button\n\nA combo button is a type of disclosure pattern and displays a primary default\naction that discloses a list of additional, related actions to choose from in a\npopover.\n\n### Anatomy\n\n\n\n\n\n\n\n\n\n
Anatomy of a combo button.
\n\n1. **Primary button:** A default action.\n2. **Icon button:** A trigger to open and close the popover.\n3. **Content area:** A list of additional actions.\n4. **Menu:** Uses the popover component as an underlying layer.\n\n### Structure\n\nA combo button is made up of three parts—a primary button, an icon button, and a\npopover. Dividers are shown to visually separate different actions that are\nrelated to each other.\n\n\n\n\n\n\n\n\n\n### Functionality\n\n#### Mouse\n\nClicking the primary default action will perform the defaulted action. Clicking\nthe icon button triggers the popover to open and reveals the additional actions\nto choose from in a menu. Clicking on an action in the menu will perform the\naction. To close the menu click on the icon button again, or anywhere on the\npage outside of the menu.\n\n\n\n\n\n\n\n\n\n#### Keyboard\n\nPrimary default button: `Tab` to the primary default button to apply focus.\nTrigger the primary default button by pressing `Enter` or `Space`.\n\nIcon button: `Tab` to the icon button to apply focus. Open the menu by\npressing `Enter`, `Space`, or the `Down` arrow key.\n\nMenu: When the menu is opened, focus will go to the first additional action in\nthe menu list. Move between menu actions by pressing the `Up` and `Down` arrow\nkeys. Close the menu by pressing `Enter` or `Space` to activate the action with\nfocus or `Esc` to cancel.\n\n### Best practices\n\n#### Choose a default action\n\nRemember to choose the default, primary action that will be displayed in the\nprimary button so it is not hidden within the menu of additional actions. The\nprimary default action is typically the most commonly used action there is to\ntake.\n\n#### Use to reduce visual complexity on a page\n\nCombo buttons reduce visual complexity by grouping similar commands together.\nFor example, how navigation menus group together related options to enable\nconceptual understanding of the site information structure.\n\n#### Avoid using extra icons\n\nAvoid using extra icons inside of the default, primary button and the additional\nactions in the menu to reduce visual noise between elements. Keep button labels\nclear and concise.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n## Accessibility\n\n#### Screen readers\n\nVoiceOver: Users can trigger a button to open a disclosure popover by pressing\n`Enter` or `Space` while the trigger has focus.\n\nJAWS: Users can trigger a button to open a disclosure popover by pressing\n`Enter` or `Space` while the trigger has focus.\n\nNVDA: Users can trigger a button to open a disclosure popover by pressing\n`Enter` or `Space` while the trigger has focus.\n\n## Related\n\n#### Button\n\nButtons are clickable interactive elements that are commonly used in disclosures\nas the trigger to open a popover. There are multiple variants of button that\nshould be used for certain use cases. For further guidance, see Carbon's\n[button component](https://www.carbondesignsystem.com/components/button/usage/)\nguidance.\n\n#### Popover\n\nPopovers are frequently used in disclosures to show additional content. Popovers\nare also used in components like tooltips, overflow menus, and dropdown menus.\nFor further guidance of how to use a popover, see Carbon’s\n[popover component](https://v11.carbondesignsystem.com/components/popover/usage/).\n\n#### Toggletip\n\nToggletip uses the disclosure pattern to toggle the visibility of a popover. The\npopover may contain a variety of information, from descriptive text to\ninteractive elements. Toggletips are triggered on click to disclose the\ninformation inside of a popover. For further guidance, see Carbon's\n[toggletip component](https://v11.carbondesignsystem.com/components/toggletip/usage/)\nguidance.\n\n## References\n\nContext menu,\n[Delivering Relevant Tools for Tasks](https://www.nngroup.com/articles/contextual-menus/),(Nielsen\nNorman Group)\n\nSplit\nButtons,[Component definition](https://www.nngroup.com/articles/split-buttons/),(Nielsen\nNorman Group)\n\nPopup,[Component research](https://open-ui.org/components/popup.research#popup),(OpenUI)\n\nEnabling\nPopups,[Initial Explainer](https://open-ui.org/components/popup.research.explainer),(OpenUI)\n\nDisclosure,[W3C WAI-ARIA practices](https://v11.carbondesignsystem.com/components/popover/usage/%5Bhttps://www.w3.org/TR/wai-aria-practices-1.1/#disclosure),(W3C\nWorking Group Note)\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments on\n[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/patterns/disclosures-pattern/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/patterns/empty-states-pattern/page-data.json b/page-data/patterns/empty-states-pattern/page-data.json
index 6b867dcaf5c..9edf9eb8fbf 100644
--- a/page-data/patterns/empty-states-pattern/page-data.json
+++ b/page-data/patterns/empty-states-pattern/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-patterns-empty-states-pattern-index-mdx","path":"/patterns/empty-states-pattern/","result":{"pageContext":{"frontmatter":{"title":"Empty states","description":"Empty states are moments in an app where there is no data to display to the user."},"relativePagePath":"/patterns/empty-states-pattern/index.mdx","titleType":"prepend","MdxNode":{"id":"04f2d2cc-90c1-5934-9a70-c74c57af2f7e","children":[],"parent":"04104eef-d55e-5cab-97a0-79117abee532","internal":{"content":"---\ntitle: Empty states\ndescription:\n Empty states are moments in an app where there is no data to display to the\n user.\n---\n\nimport {\n StructuredListWrapper,\n StructuredListHead,\n StructuredListBody,\n StructuredListRow,\n StructuredListInput,\n StructuredListCell,\n UnorderedList,\n ListItem,\n} from '@carbon/react';\n\n\n\nEmpty states are moments in an app where there is no data to display to the\nuser. They are most commonly seen the first time a user interacts with a product\nor page, but can be used when data has been deleted or is unavailable.\n\n\n\n\n Overview\n Anatomy\n Designing with empty states\n Types of empty states\n In-depth alternatives\n Accessibility\n Related\n References\n Feedback\n\n\n## Overview\n\nEmpty states are a simple yet extremely powerful way to keep a user informed,\nsupported, and on a productive path. They provide opportunities to communicate\nwhat the user would see if they had data, while providing constructive guidance\nabout next steps.\n\nWith just enough contextual guidance, empty states ensure a smoothness of\nexperience, especially when things aren’t working as expected.\n\nMost people are familiar with the basic empty state page that explains what data\nwould normally appear on a page. However, it’s not always a one size fits all.\n\nThis pattern explores the following approaches:\n\n- Basic empty states for first use, user action confirmation, and error\n management\n- In-depth supplements and alternatives for first use empty states, including\n in-line documentation, onboarding, and starter content\n\n## Anatomy\n\n\n\n\n\n\n
Basic empty state with primary action button
\n\n\n\n\n1. **Image (optional):** A non-interactive image that relates to the situation\n (optional).\n1. **Title:** A short and concise explanation. Where possible, write this as a\n positive statement. In this example, \"Start by adding data assets\" feels more\n positive than \"You don’t have any data assets.\" Alternatively, you could say\n \"You don’t have any data assets yet\".\n1. **Body:** Explain clearly the next action to populate the space. You may also\n explain why the space is empty and include the benefit of taking this step.\n There are three options for explaining the primary action:\n - Direct the user to a primary action button positioned underneath the copy\n - Include a primary action link in the copy\n - Direct the user to the UI element—see the example below. This has the\n benefit of teaching the user where elements are and how they will perform\n tasks in the future.\n1. **Primary action—button or link in copy (optional):** The primary call to\n action referenced in the body copy above.\n1. **Secondary call to action (optional):** If there is a secondary action, such\n as referencing documentation for further reading, include it as a link below\n the copy.\n\n\n\n\n\n\n
Basic empty state with instruction to click UI element
\n\n\n\n\n## Designing with empty states\n\nEmpty states are often treated as an afterthought. When designed thoughtfully,\nthey become an essential part of a smooth user experience, providing just enough\ninformation, in context, to allow users to continue working in a productive way.\n\nDuring the design process, ask yourself these questions:\n\n- What will the pages, tiles, data tables, and side panels look like without\n content?\n- What are all of the steps a user can take to address the situation?\n- Is there any useful content that might be available to show?\n- How can I turn this situation into something that is engaging and helpful?\n\nDuring the design phase, explore the full range of options with your team to\nensure that the most appropriate and helpful content is created for each empty\nspace.\n\n### When to use\n\nEmpty states happen for a variety of reasons, and can require different\ntreatments.\n\nStrive for a balance between the situation and the content you’re providing.\nMore content doesn’t necessarily mean it’s a better solution as there is a\ncognitive cost for having more content on the page. This is especially true when\nusers first engage with your product, so save the more involved educational\nmoments for primary features and more complex situations.\n\nThe following table suggests different approaches for empty states to match the\nneeds of the user in different situations.\n\n Basic empty states \n\n| Type | Use cases | Goal of the empty state | When to use |\n| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| No data empty states | First time use, no data yet | User understands what will be available on the page when data has been added or is available. They understand how to add data themselves. | For simpler situations, or for secondary features where bite-sized pieces of information are preferable. |\n| User action empty states | Provides feedback based on some user action. For example:
No results when searchingConfirmation of completion of a process | User understands how to adjust search terms or filters to continue their search.
User understands that they’ve successfully completed a process. | User understands that they’ve successfully completed a process. When you need to provide feedback to the user based on an interaction. |\n| Error management empty states | Permissions issueSystems issueConfiguration required | User understands the problem and if there are corrective actions available, knows what action to take or has options to correct the issue. | When something is amiss or some level of intervention or troubleshooting is required, a higher level of detail and specificity will better support the user. |\n\n### Where to use\n\nEmpty states always appear in the otherwise empty space, in the context of the\ndata that’s missing. They can occur anywhere your app can display data,\nincluding but not limited to dashboards, data tables, tiles, full pages, and\nside panels.\n\nThe approach and layout you choose will depend on the situation, and what is the\nmost appropriate based on the page layout and context.\n\n### Visual guidelines for smaller empty spaces\n\nFor small tiles and side panels, follow these guidelines and use the layouts\nshown below.\n\n#### Alignment of elements\n\nEmpty state elements should be left-aligned as a block. The one exception to\nthis rule is an empty state in a small tile. In this case the image should be\ncentered above the left-aligned text and primary action, as shown in the example\nbelow. This exception was made to prevent the empty state looking too much like\ncontent, where it could be skipped over. The centered image in a smaller space\nhelps to draw attention to a state that may require user action.\n\n#### Image choice considerations\n\n- The image choice should relate to the situation.\n- The size of the space for the empty state should also guide the size of image.\n If space is limited, use just text.\n\n#### Multiple empty states\n\nIn situations where there could be multiple empty states showing at once, we\nrecommend using a tertiary button for the call to action. This avoids scenarios\nwith multiple primary action buttons in the UI.\n\n\n\n\n\n\n
Layout for empty state in a small tile
\n\n\n\n\n\n\n\n\n\n
Layout for empty state in a side panel
\n\n\n\n\n### Visual guidelines for larger empty spaces\n\nFor larger spaces, you have some flexibility with laying out the larger empty\nstates. Follow these guidelines, review the examples, and use your judgment as\nto what is best for the situation.\n\n#### Alignment of elements\n\nEmpty state elements should be left-aligned as a block. Depending on the image\nyou’re using, there are different arrangements available.\n\n\n\n\n\n\n\n\n\n#### Layout/positioning options\n\nYou have two options for positioning the block in the larger empty states:\n\n- Use a wider left margin\n- Block center the left-aligned group in the empty space\n\n#### Image position options\n\nYou have two options for positioning the image in the larger empty states:\n\n- Above the empty state title—generally better for wider images\n- To the left of the element block—generally better for taller images\n\n#### Image choice considerations\n\n- The image choice should relate to the situation.\n- The size of the space for the empty state should also guide the size of image.\n If space is limited, use just text.\n\n\n\n\n\n\n
\n Layout options for empty states in large tiles—wide margin or centered block\n
\n Layout options for full page empty states—wide margin and centered block\n
\n\n\n\n\n#### Best practices\n\n- **Empty states should replace the element that would ordinarily show**. For\n example, an empty state for a table would replace the table and the column\n headers and footer should not be present. This practice avoids having a screen\n reader read the entire table before getting to the message that there is no\n content in the table. Likewise, if you search for something and there are no\n results, any underlying content should be replaced by the empty state message.\n\n- **Consider how many empty states may appear in a space**. If you have a\n dashboard with a number of widgets and there is a failure for multiple widgets\n to load, the repetition of the empty state may not have the same impact if you\n use illustrative icons. In this case, an empty state that uses just text may\n be preferable.\n\n## Types of empty states\n\n### No data empty states\n\nThese are the most recognizable first use empty states, explaining what will be\nin the space once it is populated with data, and providing guidance for the next\nstep the user can take to populate the space.\n\n\n\n\n\n\n
Basic empty state with primary action button
\n\n\n\n\n\n\n\n\n\n
Basic empty state with instruction to click UI element
\n\n\n\n\n#### Do:\n\n- Use basic empty states for simpler situations, or secondary features, where\n bite-sized pieces of information are preferable.\n- Be specific about what will be available in the space when data is there.\n- Keep words to a minimum so they are fast to read and act upon.\n- If there is an actionable next step, include a direct link in your message\n copy or a primary action button to make that action fast. Alternatively, guide\n them to what they need to click.\n\n#### Don’t:\n\n- Don’t cover multiple options in one empty state. If there are multiple things\n a user can do, pick the most important and keep the focus on that action.\n- Don’t use product-specific terms that the user may not yet understand.\n- Don’t include content that is about other areas of the app. Be contextual.\n- As a general rule, don’t lead the user into a dead end. If there are useful\n next steps, include them.\n\n### User action empty states\n\nThese empty states occur as a result of a user action. For example:\n\n- A message showing there are no search results\n- A success confirmation for completion of a process or set of tasks\n\nExplain the reason for seeing the message and providing any follow up steps to\nguide the user. For example, if there are no search results suggest adjusting\nthe search or filters. Links to documentation may also be appropriate as a\nsecondary call to action.\n\n\n\n\n\n\n
A message showing there are no search results
\n\n\n\n\nThere may be situations where next steps are not possible or supplementary text\nis not required, so use your judgment about what is useful to include. For\nexample, if your user has configured alerts and nothing has been triggered, it’s\nnot a case of alerts not being set up but that there is nothing that requires\nthe user’s attention. In this case, supplementary text is not necessary.\n\n\n\n\n\n\n
Basic empty state where next steps are not required
\n\n\n\n\n### Error management empty states\n\nEmpty states can also occur when there is data but it cannot be surfaced for\nsome reason. A higher level of specificity is helpful here, with the aim that\nthe user will be able to address the issue comfortably themselves.\n\nProvide guidance about why there is no data, and either what the user can do to\naddress the lack of data, or the circumstances under which the data would\nappear. And use plain language. Following this fulfills Jakob Nielsen’s ninth\nusability heuristic: _Help users recognize, diagnose, and recover from errors_.\n\n> Error messages should be expressed in plain language (no codes), precisely\n> indicate the problem, and constructively suggest a solution.\n>\n> \n> - 10 Usability Heuristics for User Interface Design, Jakob Nielsen\n> \n\nHere are some error management situations that may be addressed with the basic\nempty state solution.\n\n| Error type | Explain why there is no data | Explain what the user can do |\n| ------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |\n| _Permissions issue_ | The user does not have permission to view the data. | Suggest steps or process to request access. |\n| _Systems issue_ | Problems with a related system are preventing the data from being supplied. | Explain steps the user can take to learn what has happened. For example, viewing an activity log. |\n| _Configuration required_ | Further configuration may be needed to access the data. | Provide an explanation and the first step for the user to take for the required configuration. |\n| _Action not supported_ | For example, the user attempts to upload an unsupported file type. | Explain what file types are supported. |\n\n\n\n\n\n\n
\n Example of an error management empty state for a systems issue\n
\n\n\n\n\n#### Do:\n\n- Consult with your team to explore what information is available.\n- If there are corrective actions, give the user an actionable next step.\n Include a direct link in your message copy or a primary action button to make\n the next action fast. Alternatively, guide them to the element they need to\n click.\n- Use direct, plain language to describe the situation.\n- Be respectful of the user and don’t joke or use flippant language.\n- Any images used should reflect the situation and be sensitive to what could be\n a serious situation.\n\n#### Don’t:\n\n- Don’t include content that is about other areas of the app. Be contextual.\n- Don’t lead the user into a dead end. Always aim to provide a path to a\n solution.\n- If there are multiple things for the user to try, be sure to include a\n hierarchy so that it’s clear which option would be the primary action.\n\nFor more detailed information about writing error messages, see the Nielsen\nNorman group’s\n[Error Message Guidelines](https://www.nngroup.com/articles/error-message-guidelines/).\n\nA pattern providing guidance for error states is currently being planned. If you\nwould like to contribute, please see our\n[guidelines for contributions](/contributing/pattern).\n\n## In-depth alternatives\n\nEducational content that helps users get oriented and started is another option\nfor turning an otherwise empty space into a positive and productive experience\nfor first time users.\n\nWhen deciding on approaches, a good rule of thumb is that a primary resource on\na page could benefit from a more educational approach, while basic empty states\nmay suffice for secondary resources.\n\n Alternative approaches \n\n| Type | Use cases | Goal of the empty state | When to use |\n| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| In-line documentation | First time use (of app or feature)Cleared or deleted dataConfiguration required | Detailed overview of page so the user understands more about the feature and is given at least one call to action to get started. | When introducing a primary feature, there is an opportunity to showcase the benefit of usage. More educational detail could help to drive engagement. |\n| Onboarding | First time use | Starting from an empty state, users have an opportunity to launch a contextual onboarding flow to gain deeper understanding about that area of the app. | When introducing a primary feature that may require more detailed explanation of concepts, a step-through of a workflow sequence, or other information that enhances productivity.
Usually onboarding flows are optional for users, therefore they need to be used in conjunction with basic empty states. |\n| Starter content | First time use | User can interact with data and learn the system by tinkering.
User gets a jumpstart to productivity with basic setup tasks being taken care of for them. | For complex situations, starter content can be a good choice as it saves users a lot of time both in learning and in configuring setups. |\n\n### In-line documentation\n\nIn-line documentation is an extension of the basic empty state for first time\nuse. It can be most helpful when a primary feature is first introduced,\nproviding more detail and highlighting any benefits. Including an image of the\nspace populated with data may help trigger interest and usage. Following a\nprogressive disclosure model, it could provide links out to more detailed\ndocumentation.\n\n#### Considerations for in-line documentation\n\n- If testing results show that users do not understand the feature or concept,\n more detail may encourage usage.\n- This approach may require a higher level of maintenance than a basic empty\n state if using product images as images will need to be kept up to date. If\n your app is translated, there could be extra work in providing localized\n images.\n- Keep the content limited to one feature. Do not talk about other areas of the\n app. If there are multiple things a user could do, pick the most important and\n keep the focus on that.\n\n\n\n\n\n\n\n\n\n### Onboarding\n\nOnboarding services provide various options for contextual in-app guidance that\ncan enhance or direct a user through an empty state.\n\nStepping users through workflows with information that supplements the empty\nstate messages can get the user to a place of comfort quickly. Tours can point\nout the location of features, provide more detail for key tasks, and highlight\nbenefits. Because onboarding flows are optional for users, they need to be used\nin conjunction with basic empty states.\n\n\n\n\n\n\n\n\n\n#### Considerations for onboarding\n\n- If metrics are showing that users are not attempting to use a feature, even\n with an empty state, you may need supplementary information. An empty state\n can be used as a launching point for an onboarding sequence, to help users get\n through a process.\n- When using an onboarding third party service, metrics can be viewed at any\n time, and adjustments to content can be made and deployed immediately.\n- Usually onboarding flows are optional for users, therefore they need to be\n used in conjunction with basic empty states.\n- Another aspect to consider is maintenance and the level of commitment required\n to maintain it.\n\nA pattern providing guidance for onboarding is currently being planned. It will\ninclude a framework for matching user needs with design solutions, tips for\nwriting copy, and general best practices. If you would like to contribute,\nplease see our [guidelines for contributions](/contributing/pattern).\n\n### Starter content\n\nAnother strategy for addressing an otherwise empty space is to provide pre-built\ncontent that allows new users to get started with an app quickly and without any\nconcern.\n\n#### Pre-built content for apps\n\nStarter content can provide the opportunity for users to dive in and learn about\nprimary features and functions with sample data. Users can tinker, examining and\ndeleting content without serious consequences. If it’s possible to include some\npersonalization here, that adds to the positive experience.\n\n\n\n\n\n\n
\n Creating a chatbot is easy when you have a starting place with pre-built\n content.\n
\n\n\n\n\n> When someone feels like she can explore an interface and not suffer dire\n> consequences, she’s likely to learn more—and feel more positive about it—than\n> someone who doesn’t explore. Good software allows people to try something\n> unfamiliar, back out, and try something else, all without stress.\n>\n> \n> -Jenifer Tidwell, Designing Interfaces, (O’Reilly Media, 2011), 9.\n> \n\n#### Pre-configured kits and workflows\n\nOther options for starter content are pre-configured kits and workflows.\nPre-configured kits containing code and API credentials can offer a fast path to\ngetting started.\n\nStarter content can also take the form of pre-configured workflows, where the\nconfiguration of services is automated, saving users from the tedium of a long\nsetup process.\n\n#### Considerations for starter content\n\n- Requires upfront planning with the full product team to determine workflow\n pre-configurations that would most benefit users.\n- If your starter content can be deleted by your user, you will need a basic\n empty state as a back up.\n\n## Accessibility\n\nAs most empty state illustrations are considered decorative, they should be\nskipped by screen readers.\n\nA decorative image is one that does not serve any practical or informational\npurpose, and is included to fill a visual void. Do not include any informational\ncontent in your decorative image.\n\n[Web Content Accessibility Guidelines](https://www.w3.org/WAI/tutorials/images/decorative/)\nrequire that decorative images are given either an empty `alt` tag or their\n`role` is assigned `presentation`. As an empty `alt` tag is more widely\nsupported, we recommend you align with the WCAG guidance and avoid assigning\n`role` to `presentation` until support is more ubiquitous.\n\n## Related\n\n\n\n\n#### Components\n\n- [Button](/components/button/usage)\n- [Data table](/components/data-table/usage)\n- [Tile](/components/tile/usage)\n\n\n\n\n#### Patterns\n\n- Error states (future)\n- Onboarding (future)\n\n\n\n\n## References\n\n- Jakob Nielsen,\n [Error Message Guidelines](https://www.nngroup.com/articles/error-message-guidelines/)\n (Nielsen Norman Group, 2001)\n- Jakob Nielsen and Page Labuheimer,\n [Top 10 Application-Design Mistakes](https://www.nngroup.com/articles/top-10-application-design-mistakes/)\n (Nielsen Norman Group, 2019)\n- Jenifer Tidwell, Designing Interfaces (O’Reilly Media, 2nd edition, 2011)\n- [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/)\n (W3C, 2018)\n- Kathryn Whitenton,\n [3 Guidelines for Search Engine \"No Results\" Pages](https://www.nngroup.com/articles/search-no-results-serp/)\n (Nielsen Norman Group, 2014)\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments on\n[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","type":"Mdx","contentDigest":"87e55bef063119fa05f9082b8eb74640","owner":"gatsby-plugin-mdx","counter":5340},"frontmatter":{"title":"Empty states","description":"Empty states are moments in an app where there is no data to display to the user."},"exports":{},"rawBody":"---\ntitle: Empty states\ndescription:\n Empty states are moments in an app where there is no data to display to the\n user.\n---\n\nimport {\n StructuredListWrapper,\n StructuredListHead,\n StructuredListBody,\n StructuredListRow,\n StructuredListInput,\n StructuredListCell,\n UnorderedList,\n ListItem,\n} from '@carbon/react';\n\n\n\nEmpty states are moments in an app where there is no data to display to the\nuser. They are most commonly seen the first time a user interacts with a product\nor page, but can be used when data has been deleted or is unavailable.\n\n\n\n\n Overview\n Anatomy\n Designing with empty states\n Types of empty states\n In-depth alternatives\n Accessibility\n Related\n References\n Feedback\n\n\n## Overview\n\nEmpty states are a simple yet extremely powerful way to keep a user informed,\nsupported, and on a productive path. They provide opportunities to communicate\nwhat the user would see if they had data, while providing constructive guidance\nabout next steps.\n\nWith just enough contextual guidance, empty states ensure a smoothness of\nexperience, especially when things aren’t working as expected.\n\nMost people are familiar with the basic empty state page that explains what data\nwould normally appear on a page. However, it’s not always a one size fits all.\n\nThis pattern explores the following approaches:\n\n- Basic empty states for first use, user action confirmation, and error\n management\n- In-depth supplements and alternatives for first use empty states, including\n in-line documentation, onboarding, and starter content\n\n## Anatomy\n\n\n\n\n\n\n
Basic empty state with primary action button
\n\n\n\n\n1. **Image (optional):** A non-interactive image that relates to the situation\n (optional).\n1. **Title:** A short and concise explanation. Where possible, write this as a\n positive statement. In this example, \"Start by adding data assets\" feels more\n positive than \"You don’t have any data assets.\" Alternatively, you could say\n \"You don’t have any data assets yet\".\n1. **Body:** Explain clearly the next action to populate the space. You may also\n explain why the space is empty and include the benefit of taking this step.\n There are three options for explaining the primary action:\n - Direct the user to a primary action button positioned underneath the copy\n - Include a primary action link in the copy\n - Direct the user to the UI element—see the example below. This has the\n benefit of teaching the user where elements are and how they will perform\n tasks in the future.\n1. **Primary action—button or link in copy (optional):** The primary call to\n action referenced in the body copy above.\n1. **Secondary call to action (optional):** If there is a secondary action, such\n as referencing documentation for further reading, include it as a link below\n the copy.\n\n\n\n\n\n\n
Basic empty state with instruction to click UI element
\n\n\n\n\n## Designing with empty states\n\nEmpty states are often treated as an afterthought. When designed thoughtfully,\nthey become an essential part of a smooth user experience, providing just enough\ninformation, in context, to allow users to continue working in a productive way.\n\nDuring the design process, ask yourself these questions:\n\n- What will the pages, tiles, data tables, and side panels look like without\n content?\n- What are all of the steps a user can take to address the situation?\n- Is there any useful content that might be available to show?\n- How can I turn this situation into something that is engaging and helpful?\n\nDuring the design phase, explore the full range of options with your team to\nensure that the most appropriate and helpful content is created for each empty\nspace.\n\n### When to use\n\nEmpty states happen for a variety of reasons, and can require different\ntreatments.\n\nStrive for a balance between the situation and the content you’re providing.\nMore content doesn’t necessarily mean it’s a better solution as there is a\ncognitive cost for having more content on the page. This is especially true when\nusers first engage with your product, so save the more involved educational\nmoments for primary features and more complex situations.\n\nThe following table suggests different approaches for empty states to match the\nneeds of the user in different situations.\n\n Basic empty states \n\n| Type | Use cases | Goal of the empty state | When to use |\n| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| No data empty states | First time use, no data yet | User understands what will be available on the page when data has been added or is available. They understand how to add data themselves. | For simpler situations, or for secondary features where bite-sized pieces of information are preferable. |\n| User action empty states | Provides feedback based on some user action. For example:
No results when searchingConfirmation of completion of a process | User understands how to adjust search terms or filters to continue their search.
User understands that they’ve successfully completed a process. | User understands that they’ve successfully completed a process. When you need to provide feedback to the user based on an interaction. |\n| Error management empty states | Permissions issueSystems issueConfiguration required | User understands the problem and if there are corrective actions available, knows what action to take or has options to correct the issue. | When something is amiss or some level of intervention or troubleshooting is required, a higher level of detail and specificity will better support the user. |\n\n### Where to use\n\nEmpty states always appear in the otherwise empty space, in the context of the\ndata that’s missing. They can occur anywhere your app can display data,\nincluding but not limited to dashboards, data tables, tiles, full pages, and\nside panels.\n\nThe approach and layout you choose will depend on the situation, and what is the\nmost appropriate based on the page layout and context.\n\n### Visual guidelines for smaller empty spaces\n\nFor small tiles and side panels, follow these guidelines and use the layouts\nshown below.\n\n#### Alignment of elements\n\nEmpty state elements should be left-aligned as a block. The one exception to\nthis rule is an empty state in a small tile. In this case the image should be\ncentered above the left-aligned text and primary action, as shown in the example\nbelow. This exception was made to prevent the empty state looking too much like\ncontent, where it could be skipped over. The centered image in a smaller space\nhelps to draw attention to a state that may require user action.\n\n#### Image choice considerations\n\n- The image choice should relate to the situation.\n- The size of the space for the empty state should also guide the size of image.\n If space is limited, use just text.\n\n#### Multiple empty states\n\nIn situations where there could be multiple empty states showing at once, we\nrecommend using a tertiary button for the call to action. This avoids scenarios\nwith multiple primary action buttons in the UI.\n\n\n\n\n\n\n
Layout for empty state in a small tile
\n\n\n\n\n\n\n\n\n\n
Layout for empty state in a side panel
\n\n\n\n\n### Visual guidelines for larger empty spaces\n\nFor larger spaces, you have some flexibility with laying out the larger empty\nstates. Follow these guidelines, review the examples, and use your judgment as\nto what is best for the situation.\n\n#### Alignment of elements\n\nEmpty state elements should be left-aligned as a block. Depending on the image\nyou’re using, there are different arrangements available.\n\n\n\n\n\n\n\n\n\n#### Layout/positioning options\n\nYou have two options for positioning the block in the larger empty states:\n\n- Use a wider left margin\n- Block center the left-aligned group in the empty space\n\n#### Image position options\n\nYou have two options for positioning the image in the larger empty states:\n\n- Above the empty state title—generally better for wider images\n- To the left of the element block—generally better for taller images\n\n#### Image choice considerations\n\n- The image choice should relate to the situation.\n- The size of the space for the empty state should also guide the size of image.\n If space is limited, use just text.\n\n\n\n\n\n\n
\n Layout options for empty states in large tiles—wide margin or centered block\n
\n Layout options for full page empty states—wide margin and centered block\n
\n\n\n\n\n#### Best practices\n\n- **Empty states should replace the element that would ordinarily show**. For\n example, an empty state for a table would replace the table and the column\n headers and footer should not be present. This practice avoids having a screen\n reader read the entire table before getting to the message that there is no\n content in the table. Likewise, if you search for something and there are no\n results, any underlying content should be replaced by the empty state message.\n\n- **Consider how many empty states may appear in a space**. If you have a\n dashboard with a number of widgets and there is a failure for multiple widgets\n to load, the repetition of the empty state may not have the same impact if you\n use illustrative icons. In this case, an empty state that uses just text may\n be preferable.\n\n## Types of empty states\n\n### No data empty states\n\nThese are the most recognizable first use empty states, explaining what will be\nin the space once it is populated with data, and providing guidance for the next\nstep the user can take to populate the space.\n\n\n\n\n\n\n
Basic empty state with primary action button
\n\n\n\n\n\n\n\n\n\n
Basic empty state with instruction to click UI element
\n\n\n\n\n#### Do:\n\n- Use basic empty states for simpler situations, or secondary features, where\n bite-sized pieces of information are preferable.\n- Be specific about what will be available in the space when data is there.\n- Keep words to a minimum so they are fast to read and act upon.\n- If there is an actionable next step, include a direct link in your message\n copy or a primary action button to make that action fast. Alternatively, guide\n them to what they need to click.\n\n#### Don’t:\n\n- Don’t cover multiple options in one empty state. If there are multiple things\n a user can do, pick the most important and keep the focus on that action.\n- Don’t use product-specific terms that the user may not yet understand.\n- Don’t include content that is about other areas of the app. Be contextual.\n- As a general rule, don’t lead the user into a dead end. If there are useful\n next steps, include them.\n\n### User action empty states\n\nThese empty states occur as a result of a user action. For example:\n\n- A message showing there are no search results\n- A success confirmation for completion of a process or set of tasks\n\nExplain the reason for seeing the message and providing any follow up steps to\nguide the user. For example, if there are no search results suggest adjusting\nthe search or filters. Links to documentation may also be appropriate as a\nsecondary call to action.\n\n\n\n\n\n\n
A message showing there are no search results
\n\n\n\n\nThere may be situations where next steps are not possible or supplementary text\nis not required, so use your judgment about what is useful to include. For\nexample, if your user has configured alerts and nothing has been triggered, it’s\nnot a case of alerts not being set up but that there is nothing that requires\nthe user’s attention. In this case, supplementary text is not necessary.\n\n\n\n\n\n\n
Basic empty state where next steps are not required
\n\n\n\n\n### Error management empty states\n\nEmpty states can also occur when there is data but it cannot be surfaced for\nsome reason. A higher level of specificity is helpful here, with the aim that\nthe user will be able to address the issue comfortably themselves.\n\nProvide guidance about why there is no data, and either what the user can do to\naddress the lack of data, or the circumstances under which the data would\nappear. And use plain language. Following this fulfills Jakob Nielsen’s ninth\nusability heuristic: _Help users recognize, diagnose, and recover from errors_.\n\n> Error messages should be expressed in plain language (no codes), precisely\n> indicate the problem, and constructively suggest a solution.\n>\n> \n> - 10 Usability Heuristics for User Interface Design, Jakob Nielsen\n> \n\nHere are some error management situations that may be addressed with the basic\nempty state solution.\n\n| Error type | Explain why there is no data | Explain what the user can do |\n| ------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |\n| _Permissions issue_ | The user does not have permission to view the data. | Suggest steps or process to request access. |\n| _Systems issue_ | Problems with a related system are preventing the data from being supplied. | Explain steps the user can take to learn what has happened. For example, viewing an activity log. |\n| _Configuration required_ | Further configuration may be needed to access the data. | Provide an explanation and the first step for the user to take for the required configuration. |\n| _Action not supported_ | For example, the user attempts to upload an unsupported file type. | Explain what file types are supported. |\n\n\n\n\n\n\n
\n Example of an error management empty state for a systems issue\n
\n\n\n\n\n#### Do:\n\n- Consult with your team to explore what information is available.\n- If there are corrective actions, give the user an actionable next step.\n Include a direct link in your message copy or a primary action button to make\n the next action fast. Alternatively, guide them to the element they need to\n click.\n- Use direct, plain language to describe the situation.\n- Be respectful of the user and don’t joke or use flippant language.\n- Any images used should reflect the situation and be sensitive to what could be\n a serious situation.\n\n#### Don’t:\n\n- Don’t include content that is about other areas of the app. Be contextual.\n- Don’t lead the user into a dead end. Always aim to provide a path to a\n solution.\n- If there are multiple things for the user to try, be sure to include a\n hierarchy so that it’s clear which option would be the primary action.\n\nFor more detailed information about writing error messages, see the Nielsen\nNorman group’s\n[Error Message Guidelines](https://www.nngroup.com/articles/error-message-guidelines/).\n\nA pattern providing guidance for error states is currently being planned. If you\nwould like to contribute, please see our\n[guidelines for contributions](/contributing/pattern).\n\n## In-depth alternatives\n\nEducational content that helps users get oriented and started is another option\nfor turning an otherwise empty space into a positive and productive experience\nfor first time users.\n\nWhen deciding on approaches, a good rule of thumb is that a primary resource on\na page could benefit from a more educational approach, while basic empty states\nmay suffice for secondary resources.\n\n Alternative approaches \n\n| Type | Use cases | Goal of the empty state | When to use |\n| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| In-line documentation | First time use (of app or feature)Cleared or deleted dataConfiguration required | Detailed overview of page so the user understands more about the feature and is given at least one call to action to get started. | When introducing a primary feature, there is an opportunity to showcase the benefit of usage. More educational detail could help to drive engagement. |\n| Onboarding | First time use | Starting from an empty state, users have an opportunity to launch a contextual onboarding flow to gain deeper understanding about that area of the app. | When introducing a primary feature that may require more detailed explanation of concepts, a step-through of a workflow sequence, or other information that enhances productivity.
Usually onboarding flows are optional for users, therefore they need to be used in conjunction with basic empty states. |\n| Starter content | First time use | User can interact with data and learn the system by tinkering.
User gets a jumpstart to productivity with basic setup tasks being taken care of for them. | For complex situations, starter content can be a good choice as it saves users a lot of time both in learning and in configuring setups. |\n\n### In-line documentation\n\nIn-line documentation is an extension of the basic empty state for first time\nuse. It can be most helpful when a primary feature is first introduced,\nproviding more detail and highlighting any benefits. Including an image of the\nspace populated with data may help trigger interest and usage. Following a\nprogressive disclosure model, it could provide links out to more detailed\ndocumentation.\n\n#### Considerations for in-line documentation\n\n- If testing results show that users do not understand the feature or concept,\n more detail may encourage usage.\n- This approach may require a higher level of maintenance than a basic empty\n state if using product images as images will need to be kept up to date. If\n your app is translated, there could be extra work in providing localized\n images.\n- Keep the content limited to one feature. Do not talk about other areas of the\n app. If there are multiple things a user could do, pick the most important and\n keep the focus on that.\n\n\n\n\n\n\n\n\n\n### Onboarding\n\nOnboarding services provide various options for contextual in-app guidance that\ncan enhance or direct a user through an empty state.\n\nStepping users through workflows with information that supplements the empty\nstate messages can get the user to a place of comfort quickly. Tours can point\nout the location of features, provide more detail for key tasks, and highlight\nbenefits. Because onboarding flows are optional for users, they need to be used\nin conjunction with basic empty states.\n\n\n\n\n\n\n\n\n\n#### Considerations for onboarding\n\n- If metrics are showing that users are not attempting to use a feature, even\n with an empty state, you may need supplementary information. An empty state\n can be used as a launching point for an onboarding sequence, to help users get\n through a process.\n- When using an onboarding third party service, metrics can be viewed at any\n time, and adjustments to content can be made and deployed immediately.\n- Usually onboarding flows are optional for users, therefore they need to be\n used in conjunction with basic empty states.\n- Another aspect to consider is maintenance and the level of commitment required\n to maintain it.\n\nA pattern providing guidance for onboarding is currently being planned. It will\ninclude a framework for matching user needs with design solutions, tips for\nwriting copy, and general best practices. If you would like to contribute,\nplease see our [guidelines for contributions](/contributing/pattern).\n\n### Starter content\n\nAnother strategy for addressing an otherwise empty space is to provide pre-built\ncontent that allows new users to get started with an app quickly and without any\nconcern.\n\n#### Pre-built content for apps\n\nStarter content can provide the opportunity for users to dive in and learn about\nprimary features and functions with sample data. Users can tinker, examining and\ndeleting content without serious consequences. If it’s possible to include some\npersonalization here, that adds to the positive experience.\n\n\n\n\n\n\n
\n Creating a chatbot is easy when you have a starting place with pre-built\n content.\n
\n\n\n\n\n> When someone feels like she can explore an interface and not suffer dire\n> consequences, she’s likely to learn more—and feel more positive about it—than\n> someone who doesn’t explore. Good software allows people to try something\n> unfamiliar, back out, and try something else, all without stress.\n>\n> \n> -Jenifer Tidwell, Designing Interfaces, (O’Reilly Media, 2011), 9.\n> \n\n#### Pre-configured kits and workflows\n\nOther options for starter content are pre-configured kits and workflows.\nPre-configured kits containing code and API credentials can offer a fast path to\ngetting started.\n\nStarter content can also take the form of pre-configured workflows, where the\nconfiguration of services is automated, saving users from the tedium of a long\nsetup process.\n\n#### Considerations for starter content\n\n- Requires upfront planning with the full product team to determine workflow\n pre-configurations that would most benefit users.\n- If your starter content can be deleted by your user, you will need a basic\n empty state as a back up.\n\n## Accessibility\n\nAs most empty state illustrations are considered decorative, they should be\nskipped by screen readers.\n\nA decorative image is one that does not serve any practical or informational\npurpose, and is included to fill a visual void. Do not include any informational\ncontent in your decorative image.\n\n[Web Content Accessibility Guidelines](https://www.w3.org/WAI/tutorials/images/decorative/)\nrequire that decorative images are given either an empty `alt` tag or their\n`role` is assigned `presentation`. As an empty `alt` tag is more widely\nsupported, we recommend you align with the WCAG guidance and avoid assigning\n`role` to `presentation` until support is more ubiquitous.\n\n## Related\n\n\n\n\n#### Components\n\n- [Button](/components/button/usage)\n- [Data table](/components/data-table/usage)\n- [Tile](/components/tile/usage)\n\n\n\n\n#### Patterns\n\n- Error states (future)\n- Onboarding (future)\n\n\n\n\n## References\n\n- Jakob Nielsen,\n [Error Message Guidelines](https://www.nngroup.com/articles/error-message-guidelines/)\n (Nielsen Norman Group, 2001)\n- Jakob Nielsen and Page Labuheimer,\n [Top 10 Application-Design Mistakes](https://www.nngroup.com/articles/top-10-application-design-mistakes/)\n (Nielsen Norman Group, 2019)\n- Jenifer Tidwell, Designing Interfaces (O’Reilly Media, 2nd edition, 2011)\n- [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/)\n (W3C, 2018)\n- Kathryn Whitenton,\n [3 Guidelines for Search Engine \"No Results\" Pages](https://www.nngroup.com/articles/search-no-results-serp/)\n (Nielsen Norman Group, 2014)\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments on\n[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/patterns/empty-states-pattern/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-patterns-empty-states-pattern-index-mdx","path":"/patterns/empty-states-pattern/","result":{"pageContext":{"frontmatter":{"title":"Empty states","description":"Empty states are moments in an app where there is no data to display to the user."},"relativePagePath":"/patterns/empty-states-pattern/index.mdx","titleType":"prepend","MdxNode":{"id":"04f2d2cc-90c1-5934-9a70-c74c57af2f7e","children":[],"parent":"04104eef-d55e-5cab-97a0-79117abee532","internal":{"content":"---\ntitle: Empty states\ndescription:\n Empty states are moments in an app where there is no data to display to the\n user.\n---\n\nimport {\n StructuredListWrapper,\n StructuredListHead,\n StructuredListBody,\n StructuredListRow,\n StructuredListInput,\n StructuredListCell,\n UnorderedList,\n ListItem,\n} from '@carbon/react';\n\n\n\nEmpty states are moments in an app where there is no data to display to the\nuser. They are most commonly seen the first time a user interacts with a product\nor page, but can be used when data has been deleted or is unavailable.\n\n\n\n\n Overview\n Anatomy\n Designing with empty states\n Types of empty states\n In-depth alternatives\n Accessibility\n Related\n References\n Feedback\n\n\n## Overview\n\nEmpty states are a simple yet extremely powerful way to keep a user informed,\nsupported, and on a productive path. They provide opportunities to communicate\nwhat the user would see if they had data, while providing constructive guidance\nabout next steps.\n\nWith just enough contextual guidance, empty states ensure a smoothness of\nexperience, especially when things aren’t working as expected.\n\nMost people are familiar with the basic empty state page that explains what data\nwould normally appear on a page. However, it’s not always a one size fits all.\n\nThis pattern explores the following approaches:\n\n- Basic empty states for first use, user action confirmation, and error\n management\n- In-depth supplements and alternatives for first use empty states, including\n in-line documentation, onboarding, and starter content\n\n## Anatomy\n\n\n\n\n\n\n
Basic empty state with primary action button
\n\n\n\n\n1. **Image (optional):** A non-interactive image that relates to the situation\n (optional).\n1. **Title:** A short and concise explanation. Where possible, write this as a\n positive statement. In this example, \"Start by adding data assets\" feels more\n positive than \"You don’t have any data assets.\" Alternatively, you could say\n \"You don’t have any data assets yet\".\n1. **Body:** Explain clearly the next action to populate the space. You may also\n explain why the space is empty and include the benefit of taking this step.\n There are three options for explaining the primary action:\n - Direct the user to a primary action button positioned underneath the copy\n - Include a primary action link in the copy\n - Direct the user to the UI element—see the example below. This has the\n benefit of teaching the user where elements are and how they will perform\n tasks in the future.\n1. **Primary action—button or link in copy (optional):** The primary call to\n action referenced in the body copy above.\n1. **Secondary call to action (optional):** If there is a secondary action, such\n as referencing documentation for further reading, include it as a link below\n the copy.\n\n\n\n\n\n\n
Basic empty state with instruction to click UI element
\n\n\n\n\n## Designing with empty states\n\nEmpty states are often treated as an afterthought. When designed thoughtfully,\nthey become an essential part of a smooth user experience, providing just enough\ninformation, in context, to allow users to continue working in a productive way.\n\nDuring the design process, ask yourself these questions:\n\n- What will the pages, tiles, data tables, and side panels look like without\n content?\n- What are all of the steps a user can take to address the situation?\n- Is there any useful content that might be available to show?\n- How can I turn this situation into something that is engaging and helpful?\n\nDuring the design phase, explore the full range of options with your team to\nensure that the most appropriate and helpful content is created for each empty\nspace.\n\n### When to use\n\nEmpty states happen for a variety of reasons, and can require different\ntreatments.\n\nStrive for a balance between the situation and the content you’re providing.\nMore content doesn’t necessarily mean it’s a better solution as there is a\ncognitive cost for having more content on the page. This is especially true when\nusers first engage with your product, so save the more involved educational\nmoments for primary features and more complex situations.\n\nThe following table suggests different approaches for empty states to match the\nneeds of the user in different situations.\n\n Basic empty states \n\n| Type | Use cases | Goal of the empty state | When to use |\n| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| No data empty states | First time use, no data yet | User understands what will be available on the page when data has been added or is available. They understand how to add data themselves. | For simpler situations, or for secondary features where bite-sized pieces of information are preferable. |\n| User action empty states | Provides feedback based on some user action. For example:
No results when searchingConfirmation of completion of a process | User understands how to adjust search terms or filters to continue their search.
User understands that they’ve successfully completed a process. | User understands that they’ve successfully completed a process. When you need to provide feedback to the user based on an interaction. |\n| Error management empty states | Permissions issueSystems issueConfiguration required | User understands the problem and if there are corrective actions available, knows what action to take or has options to correct the issue. | When something is amiss or some level of intervention or troubleshooting is required, a higher level of detail and specificity will better support the user. |\n\n### Where to use\n\nEmpty states always appear in the otherwise empty space, in the context of the\ndata that’s missing. They can occur anywhere your app can display data,\nincluding but not limited to dashboards, data tables, tiles, full pages, and\nside panels.\n\nThe approach and layout you choose will depend on the situation, and what is the\nmost appropriate based on the page layout and context.\n\n### Visual guidelines for smaller empty spaces\n\nFor small tiles and side panels, follow these guidelines and use the layouts\nshown below.\n\n#### Alignment of elements\n\nEmpty state elements should be left-aligned as a block. The one exception to\nthis rule is an empty state in a small tile. In this case the image should be\ncentered above the left-aligned text and primary action, as shown in the example\nbelow. This exception was made to prevent the empty state looking too much like\ncontent, where it could be skipped over. The centered image in a smaller space\nhelps to draw attention to a state that may require user action.\n\n#### Image choice considerations\n\n- The image choice should relate to the situation.\n- The size of the space for the empty state should also guide the size of image.\n If space is limited, use just text.\n\n#### Multiple empty states\n\nIn situations where there could be multiple empty states showing at once, we\nrecommend using a tertiary button for the call to action. This avoids scenarios\nwith multiple primary action buttons in the UI.\n\n\n\n\n\n\n
Layout for empty state in a small tile
\n\n\n\n\n\n\n\n\n\n
Layout for empty state in a side panel
\n\n\n\n\n### Visual guidelines for larger empty spaces\n\nFor larger spaces, you have some flexibility with laying out the larger empty\nstates. Follow these guidelines, review the examples, and use your judgment as\nto what is best for the situation.\n\n#### Alignment of elements\n\nEmpty state elements should be left-aligned as a block. Depending on the image\nyou’re using, there are different arrangements available.\n\n\n\n\n\n\n\n\n\n#### Layout/positioning options\n\nYou have two options for positioning the block in the larger empty states:\n\n- Use a wider left margin\n- Block center the left-aligned group in the empty space\n\n#### Image position options\n\nYou have two options for positioning the image in the larger empty states:\n\n- Above the empty state title—generally better for wider images\n- To the left of the element block—generally better for taller images\n\n#### Image choice considerations\n\n- The image choice should relate to the situation.\n- The size of the space for the empty state should also guide the size of image.\n If space is limited, use just text.\n\n\n\n\n\n\n
\n Layout options for empty states in large tiles—wide margin or centered block\n
\n Layout options for full page empty states—wide margin and centered block\n
\n\n\n\n\n#### Best practices\n\n- **Empty states should replace the element that would ordinarily show**. For\n example, an empty state for a table would replace the table and the column\n headers and footer should not be present. This practice avoids having a screen\n reader read the entire table before getting to the message that there is no\n content in the table. Likewise, if you search for something and there are no\n results, any underlying content should be replaced by the empty state message.\n\n- **Consider how many empty states may appear in a space**. If you have a\n dashboard with a number of widgets and there is a failure for multiple widgets\n to load, the repetition of the empty state may not have the same impact if you\n use illustrative icons. In this case, an empty state that uses just text may\n be preferable.\n\n## Types of empty states\n\n### No data empty states\n\nThese are the most recognizable first use empty states, explaining what will be\nin the space once it is populated with data, and providing guidance for the next\nstep the user can take to populate the space.\n\n\n\n\n\n\n
Basic empty state with primary action button
\n\n\n\n\n\n\n\n\n\n
Basic empty state with instruction to click UI element
\n\n\n\n\n#### Do:\n\n- Use basic empty states for simpler situations, or secondary features, where\n bite-sized pieces of information are preferable.\n- Be specific about what will be available in the space when data is there.\n- Keep words to a minimum so they are fast to read and act upon.\n- If there is an actionable next step, include a direct link in your message\n copy or a primary action button to make that action fast. Alternatively, guide\n them to what they need to click.\n\n#### Don’t:\n\n- Don’t cover multiple options in one empty state. If there are multiple things\n a user can do, pick the most important and keep the focus on that action.\n- Don’t use product-specific terms that the user may not yet understand.\n- Don’t include content that is about other areas of the app. Be contextual.\n- As a general rule, don’t lead the user into a dead end. If there are useful\n next steps, include them.\n\n### User action empty states\n\nThese empty states occur as a result of a user action. For example:\n\n- A message showing there are no search results\n- A success confirmation for completion of a process or set of tasks\n\nExplain the reason for seeing the message and providing any follow up steps to\nguide the user. For example, if there are no search results suggest adjusting\nthe search or filters. Links to documentation may also be appropriate as a\nsecondary call to action.\n\n\n\n\n\n\n
A message showing there are no search results
\n\n\n\n\nThere may be situations where next steps are not possible or supplementary text\nis not required, so use your judgment about what is useful to include. For\nexample, if your user has configured alerts and nothing has been triggered, it’s\nnot a case of alerts not being set up but that there is nothing that requires\nthe user’s attention. In this case, supplementary text is not necessary.\n\n\n\n\n\n\n
Basic empty state where next steps are not required
\n\n\n\n\n### Error management empty states\n\nEmpty states can also occur when there is data but it cannot be surfaced for\nsome reason. A higher level of specificity is helpful here, with the aim that\nthe user will be able to address the issue comfortably themselves.\n\nProvide guidance about why there is no data, and either what the user can do to\naddress the lack of data, or the circumstances under which the data would\nappear. And use plain language. Following this fulfills Jakob Nielsen’s ninth\nusability heuristic: _Help users recognize, diagnose, and recover from errors_.\n\n> Error messages should be expressed in plain language (no codes), precisely\n> indicate the problem, and constructively suggest a solution.\n>\n> \n> - 10 Usability Heuristics for User Interface Design, Jakob Nielsen\n> \n\nHere are some error management situations that may be addressed with the basic\nempty state solution.\n\n| Error type | Explain why there is no data | Explain what the user can do |\n| ------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |\n| _Permissions issue_ | The user does not have permission to view the data. | Suggest steps or process to request access. |\n| _Systems issue_ | Problems with a related system are preventing the data from being supplied. | Explain steps the user can take to learn what has happened. For example, viewing an activity log. |\n| _Configuration required_ | Further configuration may be needed to access the data. | Provide an explanation and the first step for the user to take for the required configuration. |\n| _Action not supported_ | For example, the user attempts to upload an unsupported file type. | Explain what file types are supported. |\n\n\n\n\n\n\n
\n Example of an error management empty state for a systems issue\n
\n\n\n\n\n#### Do:\n\n- Consult with your team to explore what information is available.\n- If there are corrective actions, give the user an actionable next step.\n Include a direct link in your message copy or a primary action button to make\n the next action fast. Alternatively, guide them to the element they need to\n click.\n- Use direct, plain language to describe the situation.\n- Be respectful of the user and don’t joke or use flippant language.\n- Any images used should reflect the situation and be sensitive to what could be\n a serious situation.\n\n#### Don’t:\n\n- Don’t include content that is about other areas of the app. Be contextual.\n- Don’t lead the user into a dead end. Always aim to provide a path to a\n solution.\n- If there are multiple things for the user to try, be sure to include a\n hierarchy so that it’s clear which option would be the primary action.\n\nFor more detailed information about writing error messages, see the Nielsen\nNorman group’s\n[Error Message Guidelines](https://www.nngroup.com/articles/error-message-guidelines/).\n\nA pattern providing guidance for error states is currently being planned. If you\nwould like to contribute, please see our\n[guidelines for contributions](/contributing/pattern).\n\n## In-depth alternatives\n\nEducational content that helps users get oriented and started is another option\nfor turning an otherwise empty space into a positive and productive experience\nfor first time users.\n\nWhen deciding on approaches, a good rule of thumb is that a primary resource on\na page could benefit from a more educational approach, while basic empty states\nmay suffice for secondary resources.\n\n Alternative approaches \n\n| Type | Use cases | Goal of the empty state | When to use |\n| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| In-line documentation | First time use (of app or feature)Cleared or deleted dataConfiguration required | Detailed overview of page so the user understands more about the feature and is given at least one call to action to get started. | When introducing a primary feature, there is an opportunity to showcase the benefit of usage. More educational detail could help to drive engagement. |\n| Onboarding | First time use | Starting from an empty state, users have an opportunity to launch a contextual onboarding flow to gain deeper understanding about that area of the app. | When introducing a primary feature that may require more detailed explanation of concepts, a step-through of a workflow sequence, or other information that enhances productivity.
Usually onboarding flows are optional for users, therefore they need to be used in conjunction with basic empty states. |\n| Starter content | First time use | User can interact with data and learn the system by tinkering.
User gets a jumpstart to productivity with basic setup tasks being taken care of for them. | For complex situations, starter content can be a good choice as it saves users a lot of time both in learning and in configuring setups. |\n\n### In-line documentation\n\nIn-line documentation is an extension of the basic empty state for first time\nuse. It can be most helpful when a primary feature is first introduced,\nproviding more detail and highlighting any benefits. Including an image of the\nspace populated with data may help trigger interest and usage. Following a\nprogressive disclosure model, it could provide links out to more detailed\ndocumentation.\n\n#### Considerations for in-line documentation\n\n- If testing results show that users do not understand the feature or concept,\n more detail may encourage usage.\n- This approach may require a higher level of maintenance than a basic empty\n state if using product images as images will need to be kept up to date. If\n your app is translated, there could be extra work in providing localized\n images.\n- Keep the content limited to one feature. Do not talk about other areas of the\n app. If there are multiple things a user could do, pick the most important and\n keep the focus on that.\n\n\n\n\n\n\n\n\n\n### Onboarding\n\nOnboarding services provide various options for contextual in-app guidance that\ncan enhance or direct a user through an empty state.\n\nStepping users through workflows with information that supplements the empty\nstate messages can get the user to a place of comfort quickly. Tours can point\nout the location of features, provide more detail for key tasks, and highlight\nbenefits. Because onboarding flows are optional for users, they need to be used\nin conjunction with basic empty states.\n\n\n\n\n\n\n\n\n\n#### Considerations for onboarding\n\n- If metrics are showing that users are not attempting to use a feature, even\n with an empty state, you may need supplementary information. An empty state\n can be used as a launching point for an onboarding sequence, to help users get\n through a process.\n- When using an onboarding third party service, metrics can be viewed at any\n time, and adjustments to content can be made and deployed immediately.\n- Usually onboarding flows are optional for users, therefore they need to be\n used in conjunction with basic empty states.\n- Another aspect to consider is maintenance and the level of commitment required\n to maintain it.\n\nA pattern providing guidance for onboarding is currently being planned. It will\ninclude a framework for matching user needs with design solutions, tips for\nwriting copy, and general best practices. If you would like to contribute,\nplease see our [guidelines for contributions](/contributing/pattern).\n\n### Starter content\n\nAnother strategy for addressing an otherwise empty space is to provide pre-built\ncontent that allows new users to get started with an app quickly and without any\nconcern.\n\n#### Pre-built content for apps\n\nStarter content can provide the opportunity for users to dive in and learn about\nprimary features and functions with sample data. Users can tinker, examining and\ndeleting content without serious consequences. If it’s possible to include some\npersonalization here, that adds to the positive experience.\n\n\n\n\n\n\n
\n Creating a chatbot is easy when you have a starting place with pre-built\n content.\n
\n\n\n\n\n> When someone feels like she can explore an interface and not suffer dire\n> consequences, she’s likely to learn more—and feel more positive about it—than\n> someone who doesn’t explore. Good software allows people to try something\n> unfamiliar, back out, and try something else, all without stress.\n>\n> \n> -Jenifer Tidwell, Designing Interfaces, (O’Reilly Media, 2011), 9.\n> \n\n#### Pre-configured kits and workflows\n\nOther options for starter content are pre-configured kits and workflows.\nPre-configured kits containing code and API credentials can offer a fast path to\ngetting started.\n\nStarter content can also take the form of pre-configured workflows, where the\nconfiguration of services is automated, saving users from the tedium of a long\nsetup process.\n\n#### Considerations for starter content\n\n- Requires upfront planning with the full product team to determine workflow\n pre-configurations that would most benefit users.\n- If your starter content can be deleted by your user, you will need a basic\n empty state as a back up.\n\n## Accessibility\n\nAs most empty state illustrations are considered decorative, they should be\nskipped by screen readers.\n\nA decorative image is one that does not serve any practical or informational\npurpose, and is included to fill a visual void. Do not include any informational\ncontent in your decorative image.\n\n[Web Content Accessibility Guidelines](https://www.w3.org/WAI/tutorials/images/decorative/)\nrequire that decorative images are given either an empty `alt` tag or their\n`role` is assigned `presentation`. As an empty `alt` tag is more widely\nsupported, we recommend you align with the WCAG guidance and avoid assigning\n`role` to `presentation` until support is more ubiquitous.\n\n## Related\n\n\n\n\n#### Components\n\n- [Button](/components/button/usage)\n- [Data table](/components/data-table/usage)\n- [Tile](/components/tile/usage)\n\n\n\n\n#### Patterns\n\n- Error states (future)\n- Onboarding (future)\n\n\n\n\n## References\n\n- Jakob Nielsen,\n [Error Message Guidelines](https://www.nngroup.com/articles/error-message-guidelines/)\n (Nielsen Norman Group, 2001)\n- Jakob Nielsen and Page Labuheimer,\n [Top 10 Application-Design Mistakes](https://www.nngroup.com/articles/top-10-application-design-mistakes/)\n (Nielsen Norman Group, 2019)\n- Jenifer Tidwell, Designing Interfaces (O’Reilly Media, 2nd edition, 2011)\n- [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/)\n (W3C, 2018)\n- Kathryn Whitenton,\n [3 Guidelines for Search Engine \"No Results\" Pages](https://www.nngroup.com/articles/search-no-results-serp/)\n (Nielsen Norman Group, 2014)\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments on\n[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","type":"Mdx","contentDigest":"87e55bef063119fa05f9082b8eb74640","owner":"gatsby-plugin-mdx","counter":5336},"frontmatter":{"title":"Empty states","description":"Empty states are moments in an app where there is no data to display to the user."},"exports":{},"rawBody":"---\ntitle: Empty states\ndescription:\n Empty states are moments in an app where there is no data to display to the\n user.\n---\n\nimport {\n StructuredListWrapper,\n StructuredListHead,\n StructuredListBody,\n StructuredListRow,\n StructuredListInput,\n StructuredListCell,\n UnorderedList,\n ListItem,\n} from '@carbon/react';\n\n\n\nEmpty states are moments in an app where there is no data to display to the\nuser. They are most commonly seen the first time a user interacts with a product\nor page, but can be used when data has been deleted or is unavailable.\n\n\n\n\n Overview\n Anatomy\n Designing with empty states\n Types of empty states\n In-depth alternatives\n Accessibility\n Related\n References\n Feedback\n\n\n## Overview\n\nEmpty states are a simple yet extremely powerful way to keep a user informed,\nsupported, and on a productive path. They provide opportunities to communicate\nwhat the user would see if they had data, while providing constructive guidance\nabout next steps.\n\nWith just enough contextual guidance, empty states ensure a smoothness of\nexperience, especially when things aren’t working as expected.\n\nMost people are familiar with the basic empty state page that explains what data\nwould normally appear on a page. However, it’s not always a one size fits all.\n\nThis pattern explores the following approaches:\n\n- Basic empty states for first use, user action confirmation, and error\n management\n- In-depth supplements and alternatives for first use empty states, including\n in-line documentation, onboarding, and starter content\n\n## Anatomy\n\n\n\n\n\n\n
Basic empty state with primary action button
\n\n\n\n\n1. **Image (optional):** A non-interactive image that relates to the situation\n (optional).\n1. **Title:** A short and concise explanation. Where possible, write this as a\n positive statement. In this example, \"Start by adding data assets\" feels more\n positive than \"You don’t have any data assets.\" Alternatively, you could say\n \"You don’t have any data assets yet\".\n1. **Body:** Explain clearly the next action to populate the space. You may also\n explain why the space is empty and include the benefit of taking this step.\n There are three options for explaining the primary action:\n - Direct the user to a primary action button positioned underneath the copy\n - Include a primary action link in the copy\n - Direct the user to the UI element—see the example below. This has the\n benefit of teaching the user where elements are and how they will perform\n tasks in the future.\n1. **Primary action—button or link in copy (optional):** The primary call to\n action referenced in the body copy above.\n1. **Secondary call to action (optional):** If there is a secondary action, such\n as referencing documentation for further reading, include it as a link below\n the copy.\n\n\n\n\n\n\n
Basic empty state with instruction to click UI element
\n\n\n\n\n## Designing with empty states\n\nEmpty states are often treated as an afterthought. When designed thoughtfully,\nthey become an essential part of a smooth user experience, providing just enough\ninformation, in context, to allow users to continue working in a productive way.\n\nDuring the design process, ask yourself these questions:\n\n- What will the pages, tiles, data tables, and side panels look like without\n content?\n- What are all of the steps a user can take to address the situation?\n- Is there any useful content that might be available to show?\n- How can I turn this situation into something that is engaging and helpful?\n\nDuring the design phase, explore the full range of options with your team to\nensure that the most appropriate and helpful content is created for each empty\nspace.\n\n### When to use\n\nEmpty states happen for a variety of reasons, and can require different\ntreatments.\n\nStrive for a balance between the situation and the content you’re providing.\nMore content doesn’t necessarily mean it’s a better solution as there is a\ncognitive cost for having more content on the page. This is especially true when\nusers first engage with your product, so save the more involved educational\nmoments for primary features and more complex situations.\n\nThe following table suggests different approaches for empty states to match the\nneeds of the user in different situations.\n\n Basic empty states \n\n| Type | Use cases | Goal of the empty state | When to use |\n| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| No data empty states | First time use, no data yet | User understands what will be available on the page when data has been added or is available. They understand how to add data themselves. | For simpler situations, or for secondary features where bite-sized pieces of information are preferable. |\n| User action empty states | Provides feedback based on some user action. For example:
No results when searchingConfirmation of completion of a process | User understands how to adjust search terms or filters to continue their search.
User understands that they’ve successfully completed a process. | User understands that they’ve successfully completed a process. When you need to provide feedback to the user based on an interaction. |\n| Error management empty states | Permissions issueSystems issueConfiguration required | User understands the problem and if there are corrective actions available, knows what action to take or has options to correct the issue. | When something is amiss or some level of intervention or troubleshooting is required, a higher level of detail and specificity will better support the user. |\n\n### Where to use\n\nEmpty states always appear in the otherwise empty space, in the context of the\ndata that’s missing. They can occur anywhere your app can display data,\nincluding but not limited to dashboards, data tables, tiles, full pages, and\nside panels.\n\nThe approach and layout you choose will depend on the situation, and what is the\nmost appropriate based on the page layout and context.\n\n### Visual guidelines for smaller empty spaces\n\nFor small tiles and side panels, follow these guidelines and use the layouts\nshown below.\n\n#### Alignment of elements\n\nEmpty state elements should be left-aligned as a block. The one exception to\nthis rule is an empty state in a small tile. In this case the image should be\ncentered above the left-aligned text and primary action, as shown in the example\nbelow. This exception was made to prevent the empty state looking too much like\ncontent, where it could be skipped over. The centered image in a smaller space\nhelps to draw attention to a state that may require user action.\n\n#### Image choice considerations\n\n- The image choice should relate to the situation.\n- The size of the space for the empty state should also guide the size of image.\n If space is limited, use just text.\n\n#### Multiple empty states\n\nIn situations where there could be multiple empty states showing at once, we\nrecommend using a tertiary button for the call to action. This avoids scenarios\nwith multiple primary action buttons in the UI.\n\n\n\n\n\n\n
Layout for empty state in a small tile
\n\n\n\n\n\n\n\n\n\n
Layout for empty state in a side panel
\n\n\n\n\n### Visual guidelines for larger empty spaces\n\nFor larger spaces, you have some flexibility with laying out the larger empty\nstates. Follow these guidelines, review the examples, and use your judgment as\nto what is best for the situation.\n\n#### Alignment of elements\n\nEmpty state elements should be left-aligned as a block. Depending on the image\nyou’re using, there are different arrangements available.\n\n\n\n\n\n\n\n\n\n#### Layout/positioning options\n\nYou have two options for positioning the block in the larger empty states:\n\n- Use a wider left margin\n- Block center the left-aligned group in the empty space\n\n#### Image position options\n\nYou have two options for positioning the image in the larger empty states:\n\n- Above the empty state title—generally better for wider images\n- To the left of the element block—generally better for taller images\n\n#### Image choice considerations\n\n- The image choice should relate to the situation.\n- The size of the space for the empty state should also guide the size of image.\n If space is limited, use just text.\n\n\n\n\n\n\n
\n Layout options for empty states in large tiles—wide margin or centered block\n
\n Layout options for full page empty states—wide margin and centered block\n
\n\n\n\n\n#### Best practices\n\n- **Empty states should replace the element that would ordinarily show**. For\n example, an empty state for a table would replace the table and the column\n headers and footer should not be present. This practice avoids having a screen\n reader read the entire table before getting to the message that there is no\n content in the table. Likewise, if you search for something and there are no\n results, any underlying content should be replaced by the empty state message.\n\n- **Consider how many empty states may appear in a space**. If you have a\n dashboard with a number of widgets and there is a failure for multiple widgets\n to load, the repetition of the empty state may not have the same impact if you\n use illustrative icons. In this case, an empty state that uses just text may\n be preferable.\n\n## Types of empty states\n\n### No data empty states\n\nThese are the most recognizable first use empty states, explaining what will be\nin the space once it is populated with data, and providing guidance for the next\nstep the user can take to populate the space.\n\n\n\n\n\n\n
Basic empty state with primary action button
\n\n\n\n\n\n\n\n\n\n
Basic empty state with instruction to click UI element
\n\n\n\n\n#### Do:\n\n- Use basic empty states for simpler situations, or secondary features, where\n bite-sized pieces of information are preferable.\n- Be specific about what will be available in the space when data is there.\n- Keep words to a minimum so they are fast to read and act upon.\n- If there is an actionable next step, include a direct link in your message\n copy or a primary action button to make that action fast. Alternatively, guide\n them to what they need to click.\n\n#### Don’t:\n\n- Don’t cover multiple options in one empty state. If there are multiple things\n a user can do, pick the most important and keep the focus on that action.\n- Don’t use product-specific terms that the user may not yet understand.\n- Don’t include content that is about other areas of the app. Be contextual.\n- As a general rule, don’t lead the user into a dead end. If there are useful\n next steps, include them.\n\n### User action empty states\n\nThese empty states occur as a result of a user action. For example:\n\n- A message showing there are no search results\n- A success confirmation for completion of a process or set of tasks\n\nExplain the reason for seeing the message and providing any follow up steps to\nguide the user. For example, if there are no search results suggest adjusting\nthe search or filters. Links to documentation may also be appropriate as a\nsecondary call to action.\n\n\n\n\n\n\n
A message showing there are no search results
\n\n\n\n\nThere may be situations where next steps are not possible or supplementary text\nis not required, so use your judgment about what is useful to include. For\nexample, if your user has configured alerts and nothing has been triggered, it’s\nnot a case of alerts not being set up but that there is nothing that requires\nthe user’s attention. In this case, supplementary text is not necessary.\n\n\n\n\n\n\n
Basic empty state where next steps are not required
\n\n\n\n\n### Error management empty states\n\nEmpty states can also occur when there is data but it cannot be surfaced for\nsome reason. A higher level of specificity is helpful here, with the aim that\nthe user will be able to address the issue comfortably themselves.\n\nProvide guidance about why there is no data, and either what the user can do to\naddress the lack of data, or the circumstances under which the data would\nappear. And use plain language. Following this fulfills Jakob Nielsen’s ninth\nusability heuristic: _Help users recognize, diagnose, and recover from errors_.\n\n> Error messages should be expressed in plain language (no codes), precisely\n> indicate the problem, and constructively suggest a solution.\n>\n> \n> - 10 Usability Heuristics for User Interface Design, Jakob Nielsen\n> \n\nHere are some error management situations that may be addressed with the basic\nempty state solution.\n\n| Error type | Explain why there is no data | Explain what the user can do |\n| ------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |\n| _Permissions issue_ | The user does not have permission to view the data. | Suggest steps or process to request access. |\n| _Systems issue_ | Problems with a related system are preventing the data from being supplied. | Explain steps the user can take to learn what has happened. For example, viewing an activity log. |\n| _Configuration required_ | Further configuration may be needed to access the data. | Provide an explanation and the first step for the user to take for the required configuration. |\n| _Action not supported_ | For example, the user attempts to upload an unsupported file type. | Explain what file types are supported. |\n\n\n\n\n\n\n
\n Example of an error management empty state for a systems issue\n
\n\n\n\n\n#### Do:\n\n- Consult with your team to explore what information is available.\n- If there are corrective actions, give the user an actionable next step.\n Include a direct link in your message copy or a primary action button to make\n the next action fast. Alternatively, guide them to the element they need to\n click.\n- Use direct, plain language to describe the situation.\n- Be respectful of the user and don’t joke or use flippant language.\n- Any images used should reflect the situation and be sensitive to what could be\n a serious situation.\n\n#### Don’t:\n\n- Don’t include content that is about other areas of the app. Be contextual.\n- Don’t lead the user into a dead end. Always aim to provide a path to a\n solution.\n- If there are multiple things for the user to try, be sure to include a\n hierarchy so that it’s clear which option would be the primary action.\n\nFor more detailed information about writing error messages, see the Nielsen\nNorman group’s\n[Error Message Guidelines](https://www.nngroup.com/articles/error-message-guidelines/).\n\nA pattern providing guidance for error states is currently being planned. If you\nwould like to contribute, please see our\n[guidelines for contributions](/contributing/pattern).\n\n## In-depth alternatives\n\nEducational content that helps users get oriented and started is another option\nfor turning an otherwise empty space into a positive and productive experience\nfor first time users.\n\nWhen deciding on approaches, a good rule of thumb is that a primary resource on\na page could benefit from a more educational approach, while basic empty states\nmay suffice for secondary resources.\n\n Alternative approaches \n\n| Type | Use cases | Goal of the empty state | When to use |\n| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| In-line documentation | First time use (of app or feature)Cleared or deleted dataConfiguration required | Detailed overview of page so the user understands more about the feature and is given at least one call to action to get started. | When introducing a primary feature, there is an opportunity to showcase the benefit of usage. More educational detail could help to drive engagement. |\n| Onboarding | First time use | Starting from an empty state, users have an opportunity to launch a contextual onboarding flow to gain deeper understanding about that area of the app. | When introducing a primary feature that may require more detailed explanation of concepts, a step-through of a workflow sequence, or other information that enhances productivity.
Usually onboarding flows are optional for users, therefore they need to be used in conjunction with basic empty states. |\n| Starter content | First time use | User can interact with data and learn the system by tinkering.
User gets a jumpstart to productivity with basic setup tasks being taken care of for them. | For complex situations, starter content can be a good choice as it saves users a lot of time both in learning and in configuring setups. |\n\n### In-line documentation\n\nIn-line documentation is an extension of the basic empty state for first time\nuse. It can be most helpful when a primary feature is first introduced,\nproviding more detail and highlighting any benefits. Including an image of the\nspace populated with data may help trigger interest and usage. Following a\nprogressive disclosure model, it could provide links out to more detailed\ndocumentation.\n\n#### Considerations for in-line documentation\n\n- If testing results show that users do not understand the feature or concept,\n more detail may encourage usage.\n- This approach may require a higher level of maintenance than a basic empty\n state if using product images as images will need to be kept up to date. If\n your app is translated, there could be extra work in providing localized\n images.\n- Keep the content limited to one feature. Do not talk about other areas of the\n app. If there are multiple things a user could do, pick the most important and\n keep the focus on that.\n\n\n\n\n\n\n\n\n\n### Onboarding\n\nOnboarding services provide various options for contextual in-app guidance that\ncan enhance or direct a user through an empty state.\n\nStepping users through workflows with information that supplements the empty\nstate messages can get the user to a place of comfort quickly. Tours can point\nout the location of features, provide more detail for key tasks, and highlight\nbenefits. Because onboarding flows are optional for users, they need to be used\nin conjunction with basic empty states.\n\n\n\n\n\n\n\n\n\n#### Considerations for onboarding\n\n- If metrics are showing that users are not attempting to use a feature, even\n with an empty state, you may need supplementary information. An empty state\n can be used as a launching point for an onboarding sequence, to help users get\n through a process.\n- When using an onboarding third party service, metrics can be viewed at any\n time, and adjustments to content can be made and deployed immediately.\n- Usually onboarding flows are optional for users, therefore they need to be\n used in conjunction with basic empty states.\n- Another aspect to consider is maintenance and the level of commitment required\n to maintain it.\n\nA pattern providing guidance for onboarding is currently being planned. It will\ninclude a framework for matching user needs with design solutions, tips for\nwriting copy, and general best practices. If you would like to contribute,\nplease see our [guidelines for contributions](/contributing/pattern).\n\n### Starter content\n\nAnother strategy for addressing an otherwise empty space is to provide pre-built\ncontent that allows new users to get started with an app quickly and without any\nconcern.\n\n#### Pre-built content for apps\n\nStarter content can provide the opportunity for users to dive in and learn about\nprimary features and functions with sample data. Users can tinker, examining and\ndeleting content without serious consequences. If it’s possible to include some\npersonalization here, that adds to the positive experience.\n\n\n\n\n\n\n
\n Creating a chatbot is easy when you have a starting place with pre-built\n content.\n
\n\n\n\n\n> When someone feels like she can explore an interface and not suffer dire\n> consequences, she’s likely to learn more—and feel more positive about it—than\n> someone who doesn’t explore. Good software allows people to try something\n> unfamiliar, back out, and try something else, all without stress.\n>\n> \n> -Jenifer Tidwell, Designing Interfaces, (O’Reilly Media, 2011), 9.\n> \n\n#### Pre-configured kits and workflows\n\nOther options for starter content are pre-configured kits and workflows.\nPre-configured kits containing code and API credentials can offer a fast path to\ngetting started.\n\nStarter content can also take the form of pre-configured workflows, where the\nconfiguration of services is automated, saving users from the tedium of a long\nsetup process.\n\n#### Considerations for starter content\n\n- Requires upfront planning with the full product team to determine workflow\n pre-configurations that would most benefit users.\n- If your starter content can be deleted by your user, you will need a basic\n empty state as a back up.\n\n## Accessibility\n\nAs most empty state illustrations are considered decorative, they should be\nskipped by screen readers.\n\nA decorative image is one that does not serve any practical or informational\npurpose, and is included to fill a visual void. Do not include any informational\ncontent in your decorative image.\n\n[Web Content Accessibility Guidelines](https://www.w3.org/WAI/tutorials/images/decorative/)\nrequire that decorative images are given either an empty `alt` tag or their\n`role` is assigned `presentation`. As an empty `alt` tag is more widely\nsupported, we recommend you align with the WCAG guidance and avoid assigning\n`role` to `presentation` until support is more ubiquitous.\n\n## Related\n\n\n\n\n#### Components\n\n- [Button](/components/button/usage)\n- [Data table](/components/data-table/usage)\n- [Tile](/components/tile/usage)\n\n\n\n\n#### Patterns\n\n- Error states (future)\n- Onboarding (future)\n\n\n\n\n## References\n\n- Jakob Nielsen,\n [Error Message Guidelines](https://www.nngroup.com/articles/error-message-guidelines/)\n (Nielsen Norman Group, 2001)\n- Jakob Nielsen and Page Labuheimer,\n [Top 10 Application-Design Mistakes](https://www.nngroup.com/articles/top-10-application-design-mistakes/)\n (Nielsen Norman Group, 2019)\n- Jenifer Tidwell, Designing Interfaces (O’Reilly Media, 2nd edition, 2011)\n- [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/)\n (W3C, 2018)\n- Kathryn Whitenton,\n [3 Guidelines for Search Engine \"No Results\" Pages](https://www.nngroup.com/articles/search-no-results-serp/)\n (Nielsen Norman Group, 2014)\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments on\n[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/patterns/empty-states-pattern/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/patterns/filtering/page-data.json b/page-data/patterns/filtering/page-data.json
index fafcdcedf08..c81bcb23753 100644
--- a/page-data/patterns/filtering/page-data.json
+++ b/page-data/patterns/filtering/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-patterns-filtering-index-mdx","path":"/patterns/filtering/","result":{"pageContext":{"frontmatter":{"title":"Filtering","description":"Filtering is the mechanism by which a user adds or removes data items from a displayed data set by turning on and off certain predefined attributes."},"relativePagePath":"/patterns/filtering/index.mdx","titleType":"prepend","MdxNode":{"id":"83c7fc47-308b-50c8-ba18-f997a77f25cd","children":[],"parent":"d5a18b91-20b0-51a1-9d5c-b981d35288c4","internal":{"content":"---\ntitle: Filtering\ndescription:\n Filtering is the mechanism by which a user adds or removes data items from a\n displayed data set by turning on and off certain predefined attributes.\n---\n\n\n\nFiltering allows a user to add or remove data items from a displayed data set by\nturning on and off certain predefined attributes.\n\n\n\n\n\nOverview\nSelection methods\nFilter states\nResetting filters\nRelated\nReferences\nFeedback\n\n\n\n## Overview\n\nFiltering allows users to trim down visible items when working through large\ndata sets. Filters can help a user find something they’re looking for, see\navailable options within a certain set of criteria, and make a decision when\nfaced with a large number of options.\n\n## Selection methods\n\nChoosing the right filter selection method will improve usability and user\nefficiency. Carbon supports several selection methods that are appropriate for\ndifferent situations. Consider the data your users are looking at, what they are\ntrying to achieve, and how they might intuitively narrow down the data.\n\n| Selection method | Description |\n| --------------------------------------- | ------------------------------------------------------------------------------------------- |\n| _Single selection_ | The user can pick only one attribute to modify data results. |\n| _Multiselection_ | The user has the option to pick more than one attribute to modify data results. |\n| _Multiple categories_ | The user has the option to select attributes across multiple data categories. |\n| _Multiple filters with batch updates_ | The user selects multiple filters and then takes an additional action to apply the filters. |\n| _Multiple filters with instant updates_ | The data is updated as the user selects each filter. |\n\n### Single selection\n\nUse a single-selection filter when the user can pick only one attribute to\nmodify data results. Under the hood, single selection behaves like a\n[radio button](/components/radio-button/usage). Types of single-selection\nfilters include:\n\n- Basic dropdown\n- Inline dropdown\n- Radio button set (either standalone or within a menu)\n\n\n\n\n\n\n
Example of a single selection filter in an inline dropdown
\n\n\n\n\n### Multiselect\n\nUse a multiselect filter when the user has the option to pick more than one\nattribute to modify the data results. Under the hood, multiselects behave like\n[checkboxes](components/checkbox/usage). Types of multiselect filters include:\n\n- Multiselect dropdown\n- Inline multiselect dropdown\n- Checkbox set (either standalone or within a menu)\n\n\n\n\n\n\n
Example of a multiselect filter in a checkbox set
\n\n\n\n\n### Selecting multiple categories\n\nA category is a set of filter items within the same topic. For example, \"size\"\nis a category and `small`, `medium`, `large`, and `extra large` are its filter\nchoices. Multiple filter categories may be applied to the same data set. For\nexample, the user can filter by size, color, and price range.\n\nMultiple category selection is usually placed vertically on the left side of the\npage or horizontally at the top of the data set. Multiple categories should\nnever be put within a menu or dropdown.\n\n\n\n\n\n\n
Example of multiple filter categories
\n\n\n\n\n### Multiple filters with batch updates\n\nUse a batch filter when all filters are applied together at the end of the\nselection process. The data set only refreshes once at user action. The trigger\nis most commonly an \"Apply filters\" button.\n\nThe batch filter works best when the user is making several filtering selections\nacross different categories that may take a longer time to mentally process.\nBatch filtering is also a good solution for slow data-return speeds. This can\nprevent the user from having to wait for the data to load after every selection.\n\n\n\n\n\n\n
Example of batch filtering
\n\n\n\n\n### Multiple filters with instant updates\n\nThis method returns results after each individual selection is made. The trigger\nis the individual selection and the filter manipulates the data in real time.\nThis is a good solution for when the user is only selecting from one category or\nthe user is expected to only make one filter selection.\n\n## Filter states\n\nFilters within each category should start either as _all unselected_ or _all\nselected_. When using multiple categories, the start state can vary from\ncategory to category. If the user typically wants only one or a few criteria to\nbe excluded from the results, then all filters should be selected at the start.\nIf the user typically wants to see only results related to one particular\ncriteria, then all filters should start as unselected.\n\n\n\n\n\n\n
Example of filter without selections
\n\n\n\n\nIf the filter(s) can be hidden in either a drawer, dropdown, or menu, then there\nshould be an indicator visible on the closed filter state that informs the user\nthat filters have been applied. At a minimum, the indicator should include the\nnumber of filters applied and have the option to clear filters without\nre-opening the filter container.\n\n\n\n\n\n\n
Example of filter with selections
\n\n\n\n\n## Resetting filters\n\nEach category should have a way to clear all applied filters at once without\nhaving to interact with each individual item. Clearing filters returns the\nfilters to their original default starting state.\n\nIf multiple categories have been applied to the same data set then there should\nalso be a way to dismiss all filters across all categories at once.\n\n\n\n\n\n\n
\n\n\n\n\n## Related\n\n\n\n\n#### Components\n\n- [Radio button](/components/radio-button/usage)\n- [Dropdown](/components/dropdown/usage)\n- [Checkbox](/components/checkbox/usage)\n- [Data table](/components/data-table/usage)\n\n\n\n\n#### Patterns\n\n- [Clear](/patterns/common-actions#clear)\n- [Notifications](/patterns/notification-pattern)\n- [Search](/patterns/search-pattern)\n\n\n\n\n## References\n\n- Patternfly,\n [Filters](https://www.patternfly.org/patterns/filters/design-guidelines/)\n (2019)\n- Nick Babich,\n [Best Practices for Search Results](https://uxplanet.org/best-practices-for-search-results-1bbed9d7a311)\n (2017)\n- Think with Google,\n [In-App Search](https://www.thinkwithgoogle.com/marketing-resources/experience-design/chapter-2-in-app-search/)\n (2016)\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments\n[on GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","type":"Mdx","contentDigest":"3f8626c183d30c1f854ee16b56118aa9","owner":"gatsby-plugin-mdx","counter":5338},"frontmatter":{"title":"Filtering","description":"Filtering is the mechanism by which a user adds or removes data items from a displayed data set by turning on and off certain predefined attributes."},"exports":{},"rawBody":"---\ntitle: Filtering\ndescription:\n Filtering is the mechanism by which a user adds or removes data items from a\n displayed data set by turning on and off certain predefined attributes.\n---\n\n\n\nFiltering allows a user to add or remove data items from a displayed data set by\nturning on and off certain predefined attributes.\n\n\n\n\n\nOverview\nSelection methods\nFilter states\nResetting filters\nRelated\nReferences\nFeedback\n\n\n\n## Overview\n\nFiltering allows users to trim down visible items when working through large\ndata sets. Filters can help a user find something they’re looking for, see\navailable options within a certain set of criteria, and make a decision when\nfaced with a large number of options.\n\n## Selection methods\n\nChoosing the right filter selection method will improve usability and user\nefficiency. Carbon supports several selection methods that are appropriate for\ndifferent situations. Consider the data your users are looking at, what they are\ntrying to achieve, and how they might intuitively narrow down the data.\n\n| Selection method | Description |\n| --------------------------------------- | ------------------------------------------------------------------------------------------- |\n| _Single selection_ | The user can pick only one attribute to modify data results. |\n| _Multiselection_ | The user has the option to pick more than one attribute to modify data results. |\n| _Multiple categories_ | The user has the option to select attributes across multiple data categories. |\n| _Multiple filters with batch updates_ | The user selects multiple filters and then takes an additional action to apply the filters. |\n| _Multiple filters with instant updates_ | The data is updated as the user selects each filter. |\n\n### Single selection\n\nUse a single-selection filter when the user can pick only one attribute to\nmodify data results. Under the hood, single selection behaves like a\n[radio button](/components/radio-button/usage). Types of single-selection\nfilters include:\n\n- Basic dropdown\n- Inline dropdown\n- Radio button set (either standalone or within a menu)\n\n\n\n\n\n\n
Example of a single selection filter in an inline dropdown
\n\n\n\n\n### Multiselect\n\nUse a multiselect filter when the user has the option to pick more than one\nattribute to modify the data results. Under the hood, multiselects behave like\n[checkboxes](components/checkbox/usage). Types of multiselect filters include:\n\n- Multiselect dropdown\n- Inline multiselect dropdown\n- Checkbox set (either standalone or within a menu)\n\n\n\n\n\n\n
Example of a multiselect filter in a checkbox set
\n\n\n\n\n### Selecting multiple categories\n\nA category is a set of filter items within the same topic. For example, \"size\"\nis a category and `small`, `medium`, `large`, and `extra large` are its filter\nchoices. Multiple filter categories may be applied to the same data set. For\nexample, the user can filter by size, color, and price range.\n\nMultiple category selection is usually placed vertically on the left side of the\npage or horizontally at the top of the data set. Multiple categories should\nnever be put within a menu or dropdown.\n\n\n\n\n\n\n
Example of multiple filter categories
\n\n\n\n\n### Multiple filters with batch updates\n\nUse a batch filter when all filters are applied together at the end of the\nselection process. The data set only refreshes once at user action. The trigger\nis most commonly an \"Apply filters\" button.\n\nThe batch filter works best when the user is making several filtering selections\nacross different categories that may take a longer time to mentally process.\nBatch filtering is also a good solution for slow data-return speeds. This can\nprevent the user from having to wait for the data to load after every selection.\n\n\n\n\n\n\n
Example of batch filtering
\n\n\n\n\n### Multiple filters with instant updates\n\nThis method returns results after each individual selection is made. The trigger\nis the individual selection and the filter manipulates the data in real time.\nThis is a good solution for when the user is only selecting from one category or\nthe user is expected to only make one filter selection.\n\n## Filter states\n\nFilters within each category should start either as _all unselected_ or _all\nselected_. When using multiple categories, the start state can vary from\ncategory to category. If the user typically wants only one or a few criteria to\nbe excluded from the results, then all filters should be selected at the start.\nIf the user typically wants to see only results related to one particular\ncriteria, then all filters should start as unselected.\n\n\n\n\n\n\n
Example of filter without selections
\n\n\n\n\nIf the filter(s) can be hidden in either a drawer, dropdown, or menu, then there\nshould be an indicator visible on the closed filter state that informs the user\nthat filters have been applied. At a minimum, the indicator should include the\nnumber of filters applied and have the option to clear filters without\nre-opening the filter container.\n\n\n\n\n\n\n
Example of filter with selections
\n\n\n\n\n## Resetting filters\n\nEach category should have a way to clear all applied filters at once without\nhaving to interact with each individual item. Clearing filters returns the\nfilters to their original default starting state.\n\nIf multiple categories have been applied to the same data set then there should\nalso be a way to dismiss all filters across all categories at once.\n\n\n\n\n\n\n
\n\n\n\n\n## Related\n\n\n\n\n#### Components\n\n- [Radio button](/components/radio-button/usage)\n- [Dropdown](/components/dropdown/usage)\n- [Checkbox](/components/checkbox/usage)\n- [Data table](/components/data-table/usage)\n\n\n\n\n#### Patterns\n\n- [Clear](/patterns/common-actions#clear)\n- [Notifications](/patterns/notification-pattern)\n- [Search](/patterns/search-pattern)\n\n\n\n\n## References\n\n- Patternfly,\n [Filters](https://www.patternfly.org/patterns/filters/design-guidelines/)\n (2019)\n- Nick Babich,\n [Best Practices for Search Results](https://uxplanet.org/best-practices-for-search-results-1bbed9d7a311)\n (2017)\n- Think with Google,\n [In-App Search](https://www.thinkwithgoogle.com/marketing-resources/experience-design/chapter-2-in-app-search/)\n (2016)\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments\n[on GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/patterns/filtering/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-patterns-filtering-index-mdx","path":"/patterns/filtering/","result":{"pageContext":{"frontmatter":{"title":"Filtering","description":"Filtering is the mechanism by which a user adds or removes data items from a displayed data set by turning on and off certain predefined attributes."},"relativePagePath":"/patterns/filtering/index.mdx","titleType":"prepend","MdxNode":{"id":"83c7fc47-308b-50c8-ba18-f997a77f25cd","children":[],"parent":"d5a18b91-20b0-51a1-9d5c-b981d35288c4","internal":{"content":"---\ntitle: Filtering\ndescription:\n Filtering is the mechanism by which a user adds or removes data items from a\n displayed data set by turning on and off certain predefined attributes.\n---\n\n\n\nFiltering allows a user to add or remove data items from a displayed data set by\nturning on and off certain predefined attributes.\n\n\n\n\n\nOverview\nSelection methods\nFilter states\nResetting filters\nRelated\nReferences\nFeedback\n\n\n\n## Overview\n\nFiltering allows users to trim down visible items when working through large\ndata sets. Filters can help a user find something they’re looking for, see\navailable options within a certain set of criteria, and make a decision when\nfaced with a large number of options.\n\n## Selection methods\n\nChoosing the right filter selection method will improve usability and user\nefficiency. Carbon supports several selection methods that are appropriate for\ndifferent situations. Consider the data your users are looking at, what they are\ntrying to achieve, and how they might intuitively narrow down the data.\n\n| Selection method | Description |\n| --------------------------------------- | ------------------------------------------------------------------------------------------- |\n| _Single selection_ | The user can pick only one attribute to modify data results. |\n| _Multiselection_ | The user has the option to pick more than one attribute to modify data results. |\n| _Multiple categories_ | The user has the option to select attributes across multiple data categories. |\n| _Multiple filters with batch updates_ | The user selects multiple filters and then takes an additional action to apply the filters. |\n| _Multiple filters with instant updates_ | The data is updated as the user selects each filter. |\n\n### Single selection\n\nUse a single-selection filter when the user can pick only one attribute to\nmodify data results. Under the hood, single selection behaves like a\n[radio button](/components/radio-button/usage). Types of single-selection\nfilters include:\n\n- Basic dropdown\n- Inline dropdown\n- Radio button set (either standalone or within a menu)\n\n\n\n\n\n\n
Example of a single selection filter in an inline dropdown
\n\n\n\n\n### Multiselect\n\nUse a multiselect filter when the user has the option to pick more than one\nattribute to modify the data results. Under the hood, multiselects behave like\n[checkboxes](components/checkbox/usage). Types of multiselect filters include:\n\n- Multiselect dropdown\n- Inline multiselect dropdown\n- Checkbox set (either standalone or within a menu)\n\n\n\n\n\n\n
Example of a multiselect filter in a checkbox set
\n\n\n\n\n### Selecting multiple categories\n\nA category is a set of filter items within the same topic. For example, \"size\"\nis a category and `small`, `medium`, `large`, and `extra large` are its filter\nchoices. Multiple filter categories may be applied to the same data set. For\nexample, the user can filter by size, color, and price range.\n\nMultiple category selection is usually placed vertically on the left side of the\npage or horizontally at the top of the data set. Multiple categories should\nnever be put within a menu or dropdown.\n\n\n\n\n\n\n
Example of multiple filter categories
\n\n\n\n\n### Multiple filters with batch updates\n\nUse a batch filter when all filters are applied together at the end of the\nselection process. The data set only refreshes once at user action. The trigger\nis most commonly an \"Apply filters\" button.\n\nThe batch filter works best when the user is making several filtering selections\nacross different categories that may take a longer time to mentally process.\nBatch filtering is also a good solution for slow data-return speeds. This can\nprevent the user from having to wait for the data to load after every selection.\n\n\n\n\n\n\n
Example of batch filtering
\n\n\n\n\n### Multiple filters with instant updates\n\nThis method returns results after each individual selection is made. The trigger\nis the individual selection and the filter manipulates the data in real time.\nThis is a good solution for when the user is only selecting from one category or\nthe user is expected to only make one filter selection.\n\n## Filter states\n\nFilters within each category should start either as _all unselected_ or _all\nselected_. When using multiple categories, the start state can vary from\ncategory to category. If the user typically wants only one or a few criteria to\nbe excluded from the results, then all filters should be selected at the start.\nIf the user typically wants to see only results related to one particular\ncriteria, then all filters should start as unselected.\n\n\n\n\n\n\n
Example of filter without selections
\n\n\n\n\nIf the filter(s) can be hidden in either a drawer, dropdown, or menu, then there\nshould be an indicator visible on the closed filter state that informs the user\nthat filters have been applied. At a minimum, the indicator should include the\nnumber of filters applied and have the option to clear filters without\nre-opening the filter container.\n\n\n\n\n\n\n
Example of filter with selections
\n\n\n\n\n## Resetting filters\n\nEach category should have a way to clear all applied filters at once without\nhaving to interact with each individual item. Clearing filters returns the\nfilters to their original default starting state.\n\nIf multiple categories have been applied to the same data set then there should\nalso be a way to dismiss all filters across all categories at once.\n\n\n\n\n\n\n
\n\n\n\n\n## Related\n\n\n\n\n#### Components\n\n- [Radio button](/components/radio-button/usage)\n- [Dropdown](/components/dropdown/usage)\n- [Checkbox](/components/checkbox/usage)\n- [Data table](/components/data-table/usage)\n\n\n\n\n#### Patterns\n\n- [Clear](/patterns/common-actions#clear)\n- [Notifications](/patterns/notification-pattern)\n- [Search](/patterns/search-pattern)\n\n\n\n\n## References\n\n- Patternfly,\n [Filters](https://www.patternfly.org/patterns/filters/design-guidelines/)\n (2019)\n- Nick Babich,\n [Best Practices for Search Results](https://uxplanet.org/best-practices-for-search-results-1bbed9d7a311)\n (2017)\n- Think with Google,\n [In-App Search](https://www.thinkwithgoogle.com/marketing-resources/experience-design/chapter-2-in-app-search/)\n (2016)\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments\n[on GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","type":"Mdx","contentDigest":"3f8626c183d30c1f854ee16b56118aa9","owner":"gatsby-plugin-mdx","counter":5337},"frontmatter":{"title":"Filtering","description":"Filtering is the mechanism by which a user adds or removes data items from a displayed data set by turning on and off certain predefined attributes."},"exports":{},"rawBody":"---\ntitle: Filtering\ndescription:\n Filtering is the mechanism by which a user adds or removes data items from a\n displayed data set by turning on and off certain predefined attributes.\n---\n\n\n\nFiltering allows a user to add or remove data items from a displayed data set by\nturning on and off certain predefined attributes.\n\n\n\n\n\nOverview\nSelection methods\nFilter states\nResetting filters\nRelated\nReferences\nFeedback\n\n\n\n## Overview\n\nFiltering allows users to trim down visible items when working through large\ndata sets. Filters can help a user find something they’re looking for, see\navailable options within a certain set of criteria, and make a decision when\nfaced with a large number of options.\n\n## Selection methods\n\nChoosing the right filter selection method will improve usability and user\nefficiency. Carbon supports several selection methods that are appropriate for\ndifferent situations. Consider the data your users are looking at, what they are\ntrying to achieve, and how they might intuitively narrow down the data.\n\n| Selection method | Description |\n| --------------------------------------- | ------------------------------------------------------------------------------------------- |\n| _Single selection_ | The user can pick only one attribute to modify data results. |\n| _Multiselection_ | The user has the option to pick more than one attribute to modify data results. |\n| _Multiple categories_ | The user has the option to select attributes across multiple data categories. |\n| _Multiple filters with batch updates_ | The user selects multiple filters and then takes an additional action to apply the filters. |\n| _Multiple filters with instant updates_ | The data is updated as the user selects each filter. |\n\n### Single selection\n\nUse a single-selection filter when the user can pick only one attribute to\nmodify data results. Under the hood, single selection behaves like a\n[radio button](/components/radio-button/usage). Types of single-selection\nfilters include:\n\n- Basic dropdown\n- Inline dropdown\n- Radio button set (either standalone or within a menu)\n\n\n\n\n\n\n
Example of a single selection filter in an inline dropdown
\n\n\n\n\n### Multiselect\n\nUse a multiselect filter when the user has the option to pick more than one\nattribute to modify the data results. Under the hood, multiselects behave like\n[checkboxes](components/checkbox/usage). Types of multiselect filters include:\n\n- Multiselect dropdown\n- Inline multiselect dropdown\n- Checkbox set (either standalone or within a menu)\n\n\n\n\n\n\n
Example of a multiselect filter in a checkbox set
\n\n\n\n\n### Selecting multiple categories\n\nA category is a set of filter items within the same topic. For example, \"size\"\nis a category and `small`, `medium`, `large`, and `extra large` are its filter\nchoices. Multiple filter categories may be applied to the same data set. For\nexample, the user can filter by size, color, and price range.\n\nMultiple category selection is usually placed vertically on the left side of the\npage or horizontally at the top of the data set. Multiple categories should\nnever be put within a menu or dropdown.\n\n\n\n\n\n\n
Example of multiple filter categories
\n\n\n\n\n### Multiple filters with batch updates\n\nUse a batch filter when all filters are applied together at the end of the\nselection process. The data set only refreshes once at user action. The trigger\nis most commonly an \"Apply filters\" button.\n\nThe batch filter works best when the user is making several filtering selections\nacross different categories that may take a longer time to mentally process.\nBatch filtering is also a good solution for slow data-return speeds. This can\nprevent the user from having to wait for the data to load after every selection.\n\n\n\n\n\n\n
Example of batch filtering
\n\n\n\n\n### Multiple filters with instant updates\n\nThis method returns results after each individual selection is made. The trigger\nis the individual selection and the filter manipulates the data in real time.\nThis is a good solution for when the user is only selecting from one category or\nthe user is expected to only make one filter selection.\n\n## Filter states\n\nFilters within each category should start either as _all unselected_ or _all\nselected_. When using multiple categories, the start state can vary from\ncategory to category. If the user typically wants only one or a few criteria to\nbe excluded from the results, then all filters should be selected at the start.\nIf the user typically wants to see only results related to one particular\ncriteria, then all filters should start as unselected.\n\n\n\n\n\n\n
Example of filter without selections
\n\n\n\n\nIf the filter(s) can be hidden in either a drawer, dropdown, or menu, then there\nshould be an indicator visible on the closed filter state that informs the user\nthat filters have been applied. At a minimum, the indicator should include the\nnumber of filters applied and have the option to clear filters without\nre-opening the filter container.\n\n\n\n\n\n\n
Example of filter with selections
\n\n\n\n\n## Resetting filters\n\nEach category should have a way to clear all applied filters at once without\nhaving to interact with each individual item. Clearing filters returns the\nfilters to their original default starting state.\n\nIf multiple categories have been applied to the same data set then there should\nalso be a way to dismiss all filters across all categories at once.\n\n\n\n\n\n\n
\n\n\n\n\n## Related\n\n\n\n\n#### Components\n\n- [Radio button](/components/radio-button/usage)\n- [Dropdown](/components/dropdown/usage)\n- [Checkbox](/components/checkbox/usage)\n- [Data table](/components/data-table/usage)\n\n\n\n\n#### Patterns\n\n- [Clear](/patterns/common-actions#clear)\n- [Notifications](/patterns/notification-pattern)\n- [Search](/patterns/search-pattern)\n\n\n\n\n## References\n\n- Patternfly,\n [Filters](https://www.patternfly.org/patterns/filters/design-guidelines/)\n (2019)\n- Nick Babich,\n [Best Practices for Search Results](https://uxplanet.org/best-practices-for-search-results-1bbed9d7a311)\n (2017)\n- Think with Google,\n [In-App Search](https://www.thinkwithgoogle.com/marketing-resources/experience-design/chapter-2-in-app-search/)\n (2016)\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments\n[on GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/patterns/filtering/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/patterns/fluid-styles/page-data.json b/page-data/patterns/fluid-styles/page-data.json
index a1c860eaa0b..7820aa1e9a5 100644
--- a/page-data/patterns/fluid-styles/page-data.json
+++ b/page-data/patterns/fluid-styles/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-patterns-fluid-styles-index-mdx","path":"/patterns/fluid-styles/","result":{"pageContext":{"frontmatter":{"title":"Fluid styles","description":"Fluid versions of certain familiar components offer alternative stylistic expressions that differentiate them from their default counterparts."},"relativePagePath":"/patterns/fluid-styles/index.mdx","titleType":"prepend","MdxNode":{"id":"4a84a524-408f-53e3-9641-91873ad6af48","children":[],"parent":"82a32223-f730-5bd2-89f4-558407d4389d","internal":{"content":"---\ntitle: Fluid styles\ndescription:\n Fluid versions of certain familiar components offer alternative stylistic\n expressions that differentiate them from their default counterparts.\n---\n\n\n\nFluid versions of certain familiar components offer alternative stylistic\nexpressions that differentiate them from their default counterparts. The\njuxtaposition of both fluid and default styling in a user interface manifests\nthe expressive and productive duality that is the cornerstone of the IBM brand.\n\n\n\n\n Overview\n Types of fluid components\n Designing with fluid\n Related\n Feedback\n\n\n## Overview\n\nWhen we say that a component is “fluid,” we mean that it becomes a part of a\nlarger, compound component by bleeding to one or more edges of its container.\nFluid components never exist in isolation; they are always part of another\ncomponent or structure, like a modal or form. Fluid is a unique style and\nparticular expression of a component. Alternatively, the more common expression,\nfrequently used in productive spaces, is known as the default style.\n\nDefault and fluid components share the same functionality but look visually\ndifferent and have different alignment rules. The fluid name originates from how\nthese components respond and where they can be placed. Fluid components always\nhug at least one container edge, moving along with the grid as the container\nresizes.\n\n\n\n\n\n\n\n\n\n
\n A fluid text input and fluid buttons inside a fluid modal container using the\n condensed gutter mode.\n
\n\n### Key terms\n\n| Term | Definition |\n| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Fixed width | The width of an element is set to a specific value and does not change as the browser resizes. |\n| Fluid width | The width of an element is responsive, often proportionally changing between breakpoints or is set as a percentage of a container. |\n| Default style | The primary style and behavior of a component that may respond either in a fluid or fixed-width manner depending on layout and responsive strategy. Default styling is more productive in nature and is most commonly used across product UI. |\n| Fluid style | An alternative style and behavior available for certain components that always has a fluid width. Fluid components are percentage-based as they comprise part of a greater whole. Fluid styling is more expressive and is used to create drama and emphasis in an experience. |\n| Productive moment | Experiences that keep the user focused and able to complete complex tasks. Productive elements may appear more conservative, confident, and efficient on the whole. |\n| Expressive moment | Experiences that create a desired impact or pause in a layout. Expressive elements are often employed in long-form, editorial experiences, when users are learning and exploring. Expressive elements may evoke more personality and emotion. |\n\n### When to use fluid styles\n\n- Use in expressive or important moments, to better capture the user’s attention\n and offer a rhythmic break to the productive experience.\n- Use within or attached to compound components.\n- Use in spacious layouts where the fluid variants have space to expand and\n breathe.\n\n### When not to use fluid styles\n\n- Don’t use when white space is needed between input components or in dense\n layouts where smaller components may be preferred.\n- Don’t use in hyper-productive moments like a complex form.\n- Don’t use inside accordions or similarly sectioned containers, where the edge\n of the fluid component aligns to the same edge as the accordion dividers; this\n creates hierarchical confusion.\n\n## Types of fluid components\n\nNot all components come with a fluid style, but each fluid instance has a\ndefault counterpart. The most common types components that have a fluid style\nare inputs, buttons, containers, and forms.\n\n### Fluid inputs\n\nFluid inputs are an alternative input style with the label placed inside the\ninput field, aligning with the user input text. All text is contained inside the\nfield, unlike the default input, where the label and helper text sit above and\nbelow (respectively) outside the field container. Fluid inputs only have one\nheight, at 64px, but have a fluid width that hugs one or more edges of its\ncontainer. See the individual input components for more guidance on each fluid\noption.\n\n\n\n\n\n\n\n\n\n### Fluid buttons\n\nButton alignment determines whether the button is a default or fluid element\nwithin a layout. If it is fluid, its width is defined as a percentage (25%, 50%,\nor 100%) of the container’s width and will often be attached to the bottom of\nthe container. Fluid buttons can never be embedded in the middle of a\nflow/layout. They must hug at least on edge of a container. Use default buttons\nif additional options or actions follow below the primary flow and primary\naction. For more guidance on default versus fluid buttons, see the\n[button component](/components/button/usage/#alignment).\n\n\n\n\n\n\n\n\n\n#### Fluid-width default buttons\n\nA default button can have a fixed or fluid width. A fixed-width button is set to\nthe size of the text label with 64px fixed padding on the right side and 16px\nfixed padding on the left. However, there is a hybrid scenario where a floating\ndefault-style button can span a designated number of columns on the responsive\ncolumn grid, giving it a fluid width. These are called \"fluid-width default\nbuttons.\"\n\nFluid-width default buttons are always preferable to fixed-width default buttons\nin a layout. When possible set the default button container’s relative position\nto the responsive layout grid and match button width to the width of other\nelements on the page. Ideally, when using groups of related buttons (not\nincluding ghost buttons), they should all be the same width.\n\n\n\n\n\n\n\n\n\n### Fluid containers\n\nThough not a formal component, fluid and fixed containers are applied in various\nexisting components. Fluid containers, like a modal, calculate their width based\non column spans or percentages and will fluctuate in size. Fixed containers,\nlike a side panel, maintain a static width, cannot be collapsed and can exist\noutside the responsive grid. For more information on grid responsive containers,\nsee [2x Grid](/guidelines/2x-grid/overview/).\n\n\n\n\n\n\n\n\n\n### Fluid forms\n\nFluid forms are architectural in that they do not allow vertical or horizontal\nspace between inputs. Fluid forms use the condensed or narrow gutter mode and\ncan hang into the gutter without causing label misalignment. Default forms use a\nwide gutter mode and align, flush to the grid columns, prioritizing vertical\nlabel alignment on the grid.\n\nFluid forms should only be used for simple, straightforward tasks, and any\ncomplex or multi-section forms should use the default style instead. For more\nguidance on default versus fluid forms, see the\n[form component](/components/form/usage/).\n\n\n\n\n\n\n\n\n\n
\n An example showing grid alignment for a fluid form (top) and the default form\n (bottom).\n
\n\n## Designing with fluid\n\n### Visual guidance\n\n#### Alignment\n\n- Fluid components are stacked flush to one another with 0px of padding between\n them.\n- Default components are equally stacked with padding separating each component.\n- Fluid components use the condensed or narrow gutter modes while default\n variants use the wide or narrow gutter mode.\n\n\n \n\n\n\n \n \n\n\n\n \n\n\n#### Placement\n\n- Fluid components will always bleed to one or more edges of their container.\n- Fluid components never exist in isolation; they are always part of another\n component or structure.\n\n\n\n\n\n\n\n\n\n
\n Examples of various ways a fluid component may be attached to its container.\n
\n\n#### Sizing\n\n- Fluid component width is dependent on its fluid container size or column span.\n Fluid components can change per breakpoint or according to their defined\n percentage.\n- Default components may have fluid widths to a certain point but will commonly\n have a max or min width to prevent them from continuously growing.\n\n#### Accessibility\n\n- Fluid components need a 3:1 border between them when vertically or\n horizontally stacked.\n\n### Best practices\n\n- Fluid components always appear in a container or as a structural unit. Default\n components may or may not appear within a container and margins will vary\n according to their location on the grid.\n- Together, fluid components comprise fluid containers, whereas default\n components can either sit on the page, without a container, or inside a\n container in with inner margins.\n- Default and fluid components can be used together in certain hybrid scenarios.\n The most common pairing is default input components, with fluid buttons in a\n contained form, like a modal or side panel.\n\n## Related\n\n\n\n\n#### Components\n\n- [Button](/components/button/usage)\n- [Date picker](/components/date-picker/usage/)\n- [Dropdown](/components/dropdown/usage/)\n- [Form](/components/form/usage/)\n- [Number input](/components/number-input/usage/)\n- [Search](/components/search/usage/)\n- [Select](/components/select/usage/)\n- [Text input](/components/text-input/usage/)\n\n\n\n\n#### Patterns\n\n- [Forms](/patterns/forms-pattern/)\n- [Login](/patterns/login-pattern/)\n\n#### Guidelines\n\n- [2x Grid](/guidelines/2x-grid/overview/)\n- [Motion](/guidelines/motion/overview/)\n- [Typography](/guidelines/typography/style-strategies)\n\n\n\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments on\n[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","type":"Mdx","contentDigest":"fd81253880cdf6775f523f140ab045ea","owner":"gatsby-plugin-mdx","counter":5335},"frontmatter":{"title":"Fluid styles","description":"Fluid versions of certain familiar components offer alternative stylistic expressions that differentiate them from their default counterparts."},"exports":{},"rawBody":"---\ntitle: Fluid styles\ndescription:\n Fluid versions of certain familiar components offer alternative stylistic\n expressions that differentiate them from their default counterparts.\n---\n\n\n\nFluid versions of certain familiar components offer alternative stylistic\nexpressions that differentiate them from their default counterparts. The\njuxtaposition of both fluid and default styling in a user interface manifests\nthe expressive and productive duality that is the cornerstone of the IBM brand.\n\n\n\n\n Overview\n Types of fluid components\n Designing with fluid\n Related\n Feedback\n\n\n## Overview\n\nWhen we say that a component is “fluid,” we mean that it becomes a part of a\nlarger, compound component by bleeding to one or more edges of its container.\nFluid components never exist in isolation; they are always part of another\ncomponent or structure, like a modal or form. Fluid is a unique style and\nparticular expression of a component. Alternatively, the more common expression,\nfrequently used in productive spaces, is known as the default style.\n\nDefault and fluid components share the same functionality but look visually\ndifferent and have different alignment rules. The fluid name originates from how\nthese components respond and where they can be placed. Fluid components always\nhug at least one container edge, moving along with the grid as the container\nresizes.\n\n\n\n\n\n\n\n\n\n
\n A fluid text input and fluid buttons inside a fluid modal container using the\n condensed gutter mode.\n
\n\n### Key terms\n\n| Term | Definition |\n| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Fixed width | The width of an element is set to a specific value and does not change as the browser resizes. |\n| Fluid width | The width of an element is responsive, often proportionally changing between breakpoints or is set as a percentage of a container. |\n| Default style | The primary style and behavior of a component that may respond either in a fluid or fixed-width manner depending on layout and responsive strategy. Default styling is more productive in nature and is most commonly used across product UI. |\n| Fluid style | An alternative style and behavior available for certain components that always has a fluid width. Fluid components are percentage-based as they comprise part of a greater whole. Fluid styling is more expressive and is used to create drama and emphasis in an experience. |\n| Productive moment | Experiences that keep the user focused and able to complete complex tasks. Productive elements may appear more conservative, confident, and efficient on the whole. |\n| Expressive moment | Experiences that create a desired impact or pause in a layout. Expressive elements are often employed in long-form, editorial experiences, when users are learning and exploring. Expressive elements may evoke more personality and emotion. |\n\n### When to use fluid styles\n\n- Use in expressive or important moments, to better capture the user’s attention\n and offer a rhythmic break to the productive experience.\n- Use within or attached to compound components.\n- Use in spacious layouts where the fluid variants have space to expand and\n breathe.\n\n### When not to use fluid styles\n\n- Don’t use when white space is needed between input components or in dense\n layouts where smaller components may be preferred.\n- Don’t use in hyper-productive moments like a complex form.\n- Don’t use inside accordions or similarly sectioned containers, where the edge\n of the fluid component aligns to the same edge as the accordion dividers; this\n creates hierarchical confusion.\n\n## Types of fluid components\n\nNot all components come with a fluid style, but each fluid instance has a\ndefault counterpart. The most common types components that have a fluid style\nare inputs, buttons, containers, and forms.\n\n### Fluid inputs\n\nFluid inputs are an alternative input style with the label placed inside the\ninput field, aligning with the user input text. All text is contained inside the\nfield, unlike the default input, where the label and helper text sit above and\nbelow (respectively) outside the field container. Fluid inputs only have one\nheight, at 64px, but have a fluid width that hugs one or more edges of its\ncontainer. See the individual input components for more guidance on each fluid\noption.\n\n\n\n\n\n\n\n\n\n### Fluid buttons\n\nButton alignment determines whether the button is a default or fluid element\nwithin a layout. If it is fluid, its width is defined as a percentage (25%, 50%,\nor 100%) of the container’s width and will often be attached to the bottom of\nthe container. Fluid buttons can never be embedded in the middle of a\nflow/layout. They must hug at least on edge of a container. Use default buttons\nif additional options or actions follow below the primary flow and primary\naction. For more guidance on default versus fluid buttons, see the\n[button component](/components/button/usage/#alignment).\n\n\n\n\n\n\n\n\n\n#### Fluid-width default buttons\n\nA default button can have a fixed or fluid width. A fixed-width button is set to\nthe size of the text label with 64px fixed padding on the right side and 16px\nfixed padding on the left. However, there is a hybrid scenario where a floating\ndefault-style button can span a designated number of columns on the responsive\ncolumn grid, giving it a fluid width. These are called \"fluid-width default\nbuttons.\"\n\nFluid-width default buttons are always preferable to fixed-width default buttons\nin a layout. When possible set the default button container’s relative position\nto the responsive layout grid and match button width to the width of other\nelements on the page. Ideally, when using groups of related buttons (not\nincluding ghost buttons), they should all be the same width.\n\n\n\n\n\n\n\n\n\n### Fluid containers\n\nThough not a formal component, fluid and fixed containers are applied in various\nexisting components. Fluid containers, like a modal, calculate their width based\non column spans or percentages and will fluctuate in size. Fixed containers,\nlike a side panel, maintain a static width, cannot be collapsed and can exist\noutside the responsive grid. For more information on grid responsive containers,\nsee [2x Grid](/guidelines/2x-grid/overview/).\n\n\n\n\n\n\n\n\n\n### Fluid forms\n\nFluid forms are architectural in that they do not allow vertical or horizontal\nspace between inputs. Fluid forms use the condensed or narrow gutter mode and\ncan hang into the gutter without causing label misalignment. Default forms use a\nwide gutter mode and align, flush to the grid columns, prioritizing vertical\nlabel alignment on the grid.\n\nFluid forms should only be used for simple, straightforward tasks, and any\ncomplex or multi-section forms should use the default style instead. For more\nguidance on default versus fluid forms, see the\n[form component](/components/form/usage/).\n\n\n\n\n\n\n\n\n\n
\n An example showing grid alignment for a fluid form (top) and the default form\n (bottom).\n
\n\n## Designing with fluid\n\n### Visual guidance\n\n#### Alignment\n\n- Fluid components are stacked flush to one another with 0px of padding between\n them.\n- Default components are equally stacked with padding separating each component.\n- Fluid components use the condensed or narrow gutter modes while default\n variants use the wide or narrow gutter mode.\n\n\n \n\n\n\n \n \n\n\n\n \n\n\n#### Placement\n\n- Fluid components will always bleed to one or more edges of their container.\n- Fluid components never exist in isolation; they are always part of another\n component or structure.\n\n\n\n\n\n\n\n\n\n
\n Examples of various ways a fluid component may be attached to its container.\n
\n\n#### Sizing\n\n- Fluid component width is dependent on its fluid container size or column span.\n Fluid components can change per breakpoint or according to their defined\n percentage.\n- Default components may have fluid widths to a certain point but will commonly\n have a max or min width to prevent them from continuously growing.\n\n#### Accessibility\n\n- Fluid components need a 3:1 border between them when vertically or\n horizontally stacked.\n\n### Best practices\n\n- Fluid components always appear in a container or as a structural unit. Default\n components may or may not appear within a container and margins will vary\n according to their location on the grid.\n- Together, fluid components comprise fluid containers, whereas default\n components can either sit on the page, without a container, or inside a\n container in with inner margins.\n- Default and fluid components can be used together in certain hybrid scenarios.\n The most common pairing is default input components, with fluid buttons in a\n contained form, like a modal or side panel.\n\n## Related\n\n\n\n\n#### Components\n\n- [Button](/components/button/usage)\n- [Date picker](/components/date-picker/usage/)\n- [Dropdown](/components/dropdown/usage/)\n- [Form](/components/form/usage/)\n- [Number input](/components/number-input/usage/)\n- [Search](/components/search/usage/)\n- [Select](/components/select/usage/)\n- [Text input](/components/text-input/usage/)\n\n\n\n\n#### Patterns\n\n- [Forms](/patterns/forms-pattern/)\n- [Login](/patterns/login-pattern/)\n\n#### Guidelines\n\n- [2x Grid](/guidelines/2x-grid/overview/)\n- [Motion](/guidelines/motion/overview/)\n- [Typography](/guidelines/typography/style-strategies)\n\n\n\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments on\n[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/patterns/fluid-styles/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
+{"componentChunkName":"component---src-pages-patterns-fluid-styles-index-mdx","path":"/patterns/fluid-styles/","result":{"pageContext":{"frontmatter":{"title":"Fluid styles","description":"Fluid versions of certain familiar components offer alternative stylistic expressions that differentiate them from their default counterparts."},"relativePagePath":"/patterns/fluid-styles/index.mdx","titleType":"prepend","MdxNode":{"id":"4a84a524-408f-53e3-9641-91873ad6af48","children":[],"parent":"82a32223-f730-5bd2-89f4-558407d4389d","internal":{"content":"---\ntitle: Fluid styles\ndescription:\n Fluid versions of certain familiar components offer alternative stylistic\n expressions that differentiate them from their default counterparts.\n---\n\n\n\nFluid versions of certain familiar components offer alternative stylistic\nexpressions that differentiate them from their default counterparts. The\njuxtaposition of both fluid and default styling in a user interface manifests\nthe expressive and productive duality that is the cornerstone of the IBM brand.\n\n\n\n\n Overview\n Types of fluid components\n Designing with fluid\n Related\n Feedback\n\n\n## Overview\n\nWhen we say that a component is “fluid,” we mean that it becomes a part of a\nlarger, compound component by bleeding to one or more edges of its container.\nFluid components never exist in isolation; they are always part of another\ncomponent or structure, like a modal or form. Fluid is a unique style and\nparticular expression of a component. Alternatively, the more common expression,\nfrequently used in productive spaces, is known as the default style.\n\nDefault and fluid components share the same functionality but look visually\ndifferent and have different alignment rules. The fluid name originates from how\nthese components respond and where they can be placed. Fluid components always\nhug at least one container edge, moving along with the grid as the container\nresizes.\n\n\n\n\n\n\n\n\n\n
\n A fluid text input and fluid buttons inside a fluid modal container using the\n condensed gutter mode.\n
\n\n### Key terms\n\n| Term | Definition |\n| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Fixed width | The width of an element is set to a specific value and does not change as the browser resizes. |\n| Fluid width | The width of an element is responsive, often proportionally changing between breakpoints or is set as a percentage of a container. |\n| Default style | The primary style and behavior of a component that may respond either in a fluid or fixed-width manner depending on layout and responsive strategy. Default styling is more productive in nature and is most commonly used across product UI. |\n| Fluid style | An alternative style and behavior available for certain components that always has a fluid width. Fluid components are percentage-based as they comprise part of a greater whole. Fluid styling is more expressive and is used to create drama and emphasis in an experience. |\n| Productive moment | Experiences that keep the user focused and able to complete complex tasks. Productive elements may appear more conservative, confident, and efficient on the whole. |\n| Expressive moment | Experiences that create a desired impact or pause in a layout. Expressive elements are often employed in long-form, editorial experiences, when users are learning and exploring. Expressive elements may evoke more personality and emotion. |\n\n### When to use fluid styles\n\n- Use in expressive or important moments, to better capture the user’s attention\n and offer a rhythmic break to the productive experience.\n- Use within or attached to compound components.\n- Use in spacious layouts where the fluid variants have space to expand and\n breathe.\n\n### When not to use fluid styles\n\n- Don’t use when white space is needed between input components or in dense\n layouts where smaller components may be preferred.\n- Don’t use in hyper-productive moments like a complex form.\n- Don’t use inside accordions or similarly sectioned containers, where the edge\n of the fluid component aligns to the same edge as the accordion dividers; this\n creates hierarchical confusion.\n\n## Types of fluid components\n\nNot all components come with a fluid style, but each fluid instance has a\ndefault counterpart. The most common types components that have a fluid style\nare inputs, buttons, containers, and forms.\n\n### Fluid inputs\n\nFluid inputs are an alternative input style with the label placed inside the\ninput field, aligning with the user input text. All text is contained inside the\nfield, unlike the default input, where the label and helper text sit above and\nbelow (respectively) outside the field container. Fluid inputs only have one\nheight, at 64px, but have a fluid width that hugs one or more edges of its\ncontainer. See the individual input components for more guidance on each fluid\noption.\n\n\n\n\n\n\n\n\n\n### Fluid buttons\n\nButton alignment determines whether the button is a default or fluid element\nwithin a layout. If it is fluid, its width is defined as a percentage (25%, 50%,\nor 100%) of the container’s width and will often be attached to the bottom of\nthe container. Fluid buttons can never be embedded in the middle of a\nflow/layout. They must hug at least on edge of a container. Use default buttons\nif additional options or actions follow below the primary flow and primary\naction. For more guidance on default versus fluid buttons, see the\n[button component](/components/button/usage/#alignment).\n\n\n\n\n\n\n\n\n\n#### Fluid-width default buttons\n\nA default button can have a fixed or fluid width. A fixed-width button is set to\nthe size of the text label with 64px fixed padding on the right side and 16px\nfixed padding on the left. However, there is a hybrid scenario where a floating\ndefault-style button can span a designated number of columns on the responsive\ncolumn grid, giving it a fluid width. These are called \"fluid-width default\nbuttons.\"\n\nFluid-width default buttons are always preferable to fixed-width default buttons\nin a layout. When possible set the default button container’s relative position\nto the responsive layout grid and match button width to the width of other\nelements on the page. Ideally, when using groups of related buttons (not\nincluding ghost buttons), they should all be the same width.\n\n\n\n\n\n\n\n\n\n### Fluid containers\n\nThough not a formal component, fluid and fixed containers are applied in various\nexisting components. Fluid containers, like a modal, calculate their width based\non column spans or percentages and will fluctuate in size. Fixed containers,\nlike a side panel, maintain a static width, cannot be collapsed and can exist\noutside the responsive grid. For more information on grid responsive containers,\nsee [2x Grid](/guidelines/2x-grid/overview/).\n\n\n\n\n\n\n\n\n\n### Fluid forms\n\nFluid forms are architectural in that they do not allow vertical or horizontal\nspace between inputs. Fluid forms use the condensed or narrow gutter mode and\ncan hang into the gutter without causing label misalignment. Default forms use a\nwide gutter mode and align, flush to the grid columns, prioritizing vertical\nlabel alignment on the grid.\n\nFluid forms should only be used for simple, straightforward tasks, and any\ncomplex or multi-section forms should use the default style instead. For more\nguidance on default versus fluid forms, see the\n[form component](/components/form/usage/).\n\n\n\n\n\n\n\n\n\n
\n An example showing grid alignment for a fluid form (top) and the default form\n (bottom).\n
\n\n## Designing with fluid\n\n### Visual guidance\n\n#### Alignment\n\n- Fluid components are stacked flush to one another with 0px of padding between\n them.\n- Default components are equally stacked with padding separating each component.\n- Fluid components use the condensed or narrow gutter modes while default\n variants use the wide or narrow gutter mode.\n\n\n \n\n\n\n \n \n\n\n\n \n\n\n#### Placement\n\n- Fluid components will always bleed to one or more edges of their container.\n- Fluid components never exist in isolation; they are always part of another\n component or structure.\n\n\n\n\n\n\n\n\n\n
\n Examples of various ways a fluid component may be attached to its container.\n
\n\n#### Sizing\n\n- Fluid component width is dependent on its fluid container size or column span.\n Fluid components can change per breakpoint or according to their defined\n percentage.\n- Default components may have fluid widths to a certain point but will commonly\n have a max or min width to prevent them from continuously growing.\n\n#### Accessibility\n\n- Fluid components need a 3:1 border between them when vertically or\n horizontally stacked.\n\n### Best practices\n\n- Fluid components always appear in a container or as a structural unit. Default\n components may or may not appear within a container and margins will vary\n according to their location on the grid.\n- Together, fluid components comprise fluid containers, whereas default\n components can either sit on the page, without a container, or inside a\n container in with inner margins.\n- Default and fluid components can be used together in certain hybrid scenarios.\n The most common pairing is default input components, with fluid buttons in a\n contained form, like a modal or side panel.\n\n## Related\n\n\n\n\n#### Components\n\n- [Button](/components/button/usage)\n- [Date picker](/components/date-picker/usage/)\n- [Dropdown](/components/dropdown/usage/)\n- [Form](/components/form/usage/)\n- [Number input](/components/number-input/usage/)\n- [Search](/components/search/usage/)\n- [Select](/components/select/usage/)\n- [Text input](/components/text-input/usage/)\n\n\n\n\n#### Patterns\n\n- [Forms](/patterns/forms-pattern/)\n- [Login](/patterns/login-pattern/)\n\n#### Guidelines\n\n- [2x Grid](/guidelines/2x-grid/overview/)\n- [Motion](/guidelines/motion/overview/)\n- [Typography](/guidelines/typography/style-strategies)\n\n\n\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments on\n[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","type":"Mdx","contentDigest":"fd81253880cdf6775f523f140ab045ea","owner":"gatsby-plugin-mdx","counter":5338},"frontmatter":{"title":"Fluid styles","description":"Fluid versions of certain familiar components offer alternative stylistic expressions that differentiate them from their default counterparts."},"exports":{},"rawBody":"---\ntitle: Fluid styles\ndescription:\n Fluid versions of certain familiar components offer alternative stylistic\n expressions that differentiate them from their default counterparts.\n---\n\n\n\nFluid versions of certain familiar components offer alternative stylistic\nexpressions that differentiate them from their default counterparts. The\njuxtaposition of both fluid and default styling in a user interface manifests\nthe expressive and productive duality that is the cornerstone of the IBM brand.\n\n\n\n\n Overview\n Types of fluid components\n Designing with fluid\n Related\n Feedback\n\n\n## Overview\n\nWhen we say that a component is “fluid,” we mean that it becomes a part of a\nlarger, compound component by bleeding to one or more edges of its container.\nFluid components never exist in isolation; they are always part of another\ncomponent or structure, like a modal or form. Fluid is a unique style and\nparticular expression of a component. Alternatively, the more common expression,\nfrequently used in productive spaces, is known as the default style.\n\nDefault and fluid components share the same functionality but look visually\ndifferent and have different alignment rules. The fluid name originates from how\nthese components respond and where they can be placed. Fluid components always\nhug at least one container edge, moving along with the grid as the container\nresizes.\n\n\n\n\n\n\n\n\n\n
\n A fluid text input and fluid buttons inside a fluid modal container using the\n condensed gutter mode.\n
\n\n### Key terms\n\n| Term | Definition |\n| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Fixed width | The width of an element is set to a specific value and does not change as the browser resizes. |\n| Fluid width | The width of an element is responsive, often proportionally changing between breakpoints or is set as a percentage of a container. |\n| Default style | The primary style and behavior of a component that may respond either in a fluid or fixed-width manner depending on layout and responsive strategy. Default styling is more productive in nature and is most commonly used across product UI. |\n| Fluid style | An alternative style and behavior available for certain components that always has a fluid width. Fluid components are percentage-based as they comprise part of a greater whole. Fluid styling is more expressive and is used to create drama and emphasis in an experience. |\n| Productive moment | Experiences that keep the user focused and able to complete complex tasks. Productive elements may appear more conservative, confident, and efficient on the whole. |\n| Expressive moment | Experiences that create a desired impact or pause in a layout. Expressive elements are often employed in long-form, editorial experiences, when users are learning and exploring. Expressive elements may evoke more personality and emotion. |\n\n### When to use fluid styles\n\n- Use in expressive or important moments, to better capture the user’s attention\n and offer a rhythmic break to the productive experience.\n- Use within or attached to compound components.\n- Use in spacious layouts where the fluid variants have space to expand and\n breathe.\n\n### When not to use fluid styles\n\n- Don’t use when white space is needed between input components or in dense\n layouts where smaller components may be preferred.\n- Don’t use in hyper-productive moments like a complex form.\n- Don’t use inside accordions or similarly sectioned containers, where the edge\n of the fluid component aligns to the same edge as the accordion dividers; this\n creates hierarchical confusion.\n\n## Types of fluid components\n\nNot all components come with a fluid style, but each fluid instance has a\ndefault counterpart. The most common types components that have a fluid style\nare inputs, buttons, containers, and forms.\n\n### Fluid inputs\n\nFluid inputs are an alternative input style with the label placed inside the\ninput field, aligning with the user input text. All text is contained inside the\nfield, unlike the default input, where the label and helper text sit above and\nbelow (respectively) outside the field container. Fluid inputs only have one\nheight, at 64px, but have a fluid width that hugs one or more edges of its\ncontainer. See the individual input components for more guidance on each fluid\noption.\n\n\n\n\n\n\n\n\n\n### Fluid buttons\n\nButton alignment determines whether the button is a default or fluid element\nwithin a layout. If it is fluid, its width is defined as a percentage (25%, 50%,\nor 100%) of the container’s width and will often be attached to the bottom of\nthe container. Fluid buttons can never be embedded in the middle of a\nflow/layout. They must hug at least on edge of a container. Use default buttons\nif additional options or actions follow below the primary flow and primary\naction. For more guidance on default versus fluid buttons, see the\n[button component](/components/button/usage/#alignment).\n\n\n\n\n\n\n\n\n\n#### Fluid-width default buttons\n\nA default button can have a fixed or fluid width. A fixed-width button is set to\nthe size of the text label with 64px fixed padding on the right side and 16px\nfixed padding on the left. However, there is a hybrid scenario where a floating\ndefault-style button can span a designated number of columns on the responsive\ncolumn grid, giving it a fluid width. These are called \"fluid-width default\nbuttons.\"\n\nFluid-width default buttons are always preferable to fixed-width default buttons\nin a layout. When possible set the default button container’s relative position\nto the responsive layout grid and match button width to the width of other\nelements on the page. Ideally, when using groups of related buttons (not\nincluding ghost buttons), they should all be the same width.\n\n\n\n\n\n\n\n\n\n### Fluid containers\n\nThough not a formal component, fluid and fixed containers are applied in various\nexisting components. Fluid containers, like a modal, calculate their width based\non column spans or percentages and will fluctuate in size. Fixed containers,\nlike a side panel, maintain a static width, cannot be collapsed and can exist\noutside the responsive grid. For more information on grid responsive containers,\nsee [2x Grid](/guidelines/2x-grid/overview/).\n\n\n\n\n\n\n\n\n\n### Fluid forms\n\nFluid forms are architectural in that they do not allow vertical or horizontal\nspace between inputs. Fluid forms use the condensed or narrow gutter mode and\ncan hang into the gutter without causing label misalignment. Default forms use a\nwide gutter mode and align, flush to the grid columns, prioritizing vertical\nlabel alignment on the grid.\n\nFluid forms should only be used for simple, straightforward tasks, and any\ncomplex or multi-section forms should use the default style instead. For more\nguidance on default versus fluid forms, see the\n[form component](/components/form/usage/).\n\n\n\n\n\n\n\n\n\n
\n An example showing grid alignment for a fluid form (top) and the default form\n (bottom).\n
\n\n## Designing with fluid\n\n### Visual guidance\n\n#### Alignment\n\n- Fluid components are stacked flush to one another with 0px of padding between\n them.\n- Default components are equally stacked with padding separating each component.\n- Fluid components use the condensed or narrow gutter modes while default\n variants use the wide or narrow gutter mode.\n\n\n \n\n\n\n \n \n\n\n\n \n\n\n#### Placement\n\n- Fluid components will always bleed to one or more edges of their container.\n- Fluid components never exist in isolation; they are always part of another\n component or structure.\n\n\n\n\n\n\n\n\n\n
\n Examples of various ways a fluid component may be attached to its container.\n
\n\n#### Sizing\n\n- Fluid component width is dependent on its fluid container size or column span.\n Fluid components can change per breakpoint or according to their defined\n percentage.\n- Default components may have fluid widths to a certain point but will commonly\n have a max or min width to prevent them from continuously growing.\n\n#### Accessibility\n\n- Fluid components need a 3:1 border between them when vertically or\n horizontally stacked.\n\n### Best practices\n\n- Fluid components always appear in a container or as a structural unit. Default\n components may or may not appear within a container and margins will vary\n according to their location on the grid.\n- Together, fluid components comprise fluid containers, whereas default\n components can either sit on the page, without a container, or inside a\n container in with inner margins.\n- Default and fluid components can be used together in certain hybrid scenarios.\n The most common pairing is default input components, with fluid buttons in a\n contained form, like a modal or side panel.\n\n## Related\n\n\n\n\n#### Components\n\n- [Button](/components/button/usage)\n- [Date picker](/components/date-picker/usage/)\n- [Dropdown](/components/dropdown/usage/)\n- [Form](/components/form/usage/)\n- [Number input](/components/number-input/usage/)\n- [Search](/components/search/usage/)\n- [Select](/components/select/usage/)\n- [Text input](/components/text-input/usage/)\n\n\n\n\n#### Patterns\n\n- [Forms](/patterns/forms-pattern/)\n- [Login](/patterns/login-pattern/)\n\n#### Guidelines\n\n- [2x Grid](/guidelines/2x-grid/overview/)\n- [Motion](/guidelines/motion/overview/)\n- [Typography](/guidelines/typography/style-strategies)\n\n\n\n\n## Feedback\n\nHelp us improve this pattern by providing feedback, asking questions, and\nleaving any other comments on\n[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).\n","fileAbsolutePath":"/home/runner/work/carbon-website/carbon-website/src/pages/patterns/fluid-styles/index.mdx"}}},"staticQueryHashes":["1364590287","137577622","2102389209","2456312558","2746626797","3018647132","3037994772","768070550"]}
\ No newline at end of file
diff --git a/page-data/patterns/forms-pattern/page-data.json b/page-data/patterns/forms-pattern/page-data.json
index 623548d2c29..bec70756aba 100644
--- a/page-data/patterns/forms-pattern/page-data.json
+++ b/page-data/patterns/forms-pattern/page-data.json
@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-patterns-forms-pattern-index-mdx","path":"/patterns/forms-pattern/","result":{"pageContext":{"frontmatter":{"title":"Forms","description":"A form is a group of related input controls that allow users to provide data or configure options."},"relativePagePath":"/patterns/forms-pattern/index.mdx","titleType":"prepend","MdxNode":{"id":"f0c4cc2b-d39b-5fd4-ae04-697bf861b707","children":[],"parent":"798b33dd-b0f1-5af5-9c5c-9adc0e15bd26","internal":{"content":"---\ntitle: Forms\ndescription:\n A form is a group of related input controls that allow users to provide data\n or configure options.\n---\n\n\n\nA form is a group of related input controls that allows users to provide data or\nconfigure options. Forms can be simple or complex, and may be presented as\ndedicated pages, side panels, or dialogs depending on the use case and the\nsituation.\n\n\n\n\n Overview\n Building a form\n Behavior\n Designing a form\n Variants\n Accessibility\n Related\n References\n Feedback\n\n\n## Overview\n\n### When to use\n\nForms are incredibly common in user interfaces and their design and usage\ncontinues to evolve as input methods get smarter and more and more people use\nmobile and tablet devices. You might design a form for a user to:\n\n- Sign up for / log into an account\n- Register for a service\n- Reconfigure settings, (e.g. enabling notifications)\n- Take a survey\n- Purchase a product\n- Provide feedback\n\n### Respect the user\n\nForms are meant to gather information and guide people with as little fuss as\npossible. To allow users to scan and complete the form quickly, forms should:\n\n- Respect the user’s GDPR and other privacy regulations by only asking for\n information that is absolutely necessary.\n- Group related tasks under section titles to provide more context and make the\n interface easier to scan.\n- Follow a logical, predictable order—e.g first name first, last name second.\n- Allow users to stay with a single interaction method for as long as possible\n (i.e. do not make users shift from keyboard to mouse numerous times in a\n single form).\n- When designing be mindful of password managers and browser capabilities that\n populate data for users.\n- Progressively disclose additional inputs only as they become relevant; see the\n [Designing for longer forms](#designing-for-longer-forms) section below.\n\n### Anatomy of a form\n\nForms are comprised of some or all of the following elements.\n\n\n\n\n\n\n\n\n\n1. **Labels:** Input labels helps users understand what the corresponding inputs\n mean.\n1. **Text inputs:** Enable users to input free-form text.\n1. **Data inputs:** Information can be entered through a variety of non-free\n form input fields as well, (e.g. checkboxes, radio buttons, dropdowns and\n selects, file uploader, date pickers, toggles, etc.) Visit the individual\n component pages for in depth details of their specific states and visuals.\n1. **Help:** Provides in-context guidance like tooltips, placeholder text, or\n helper text, to assist the user in providing the right information.\n1. **Buttons:** Allows users to submit or exit a form.\n\n## Building a form\n\n### Labels\n\nConcise labels for text and data inputs help users understand what information\nis being requested of them.\n\n- Use sentence-style capitalization for all text elements, except for product\n names and proper nouns. Sentence-style means only the first word of each\n sentence is capitalized.\n- Although they may be formatted differently, all input components need labels.\n- Labels should clearly state the required input.\n- Do not use colons after label names.\n- Labels are not helper text; be succinct. Use one to three words only.\n\n\n\n\n\n\n\n\n\n#### Top-aligned labels\n\nTop-aligned labels are Carbon’s default (vs. left-aligned labels) and the only\nlabel arrangement currently offered. Top-aligned labels provide a consistent\nleft edge, a close proximity between label and input, and are good for\nscannability and quick form completion.\n\nAdvantages:\n\n- Top-alignment enables quick completion.\n- The label length has room to extend or vary, (e.g. other languages).\n- When users are entering familiar content and are less likely to make data\n entry errors, top-alignment is ideal.\n- This arrangement is best when fewer form fields need to be presented.\n\n### Optional vs. mandatory\n\nForms items can be labeled as either optional or required depending on several\nfactors. A common distinction in IBM products for using required or optional is\nthe forms complexity.\n\n1. **Simple forms** - generally shorter and/or user- or consumer-oriented; such\n as sign-up and contact forms and checkout screens. Most of the fields will\n tend to be required.\n2. **Complex forms** - generally longer and product-oriented; contain properties\n and settings that are used to configure Enterprise software. Although they\n will usually contain at least one required field, the majority of the fields\n will tend to be optional.\n\nNote if the majority of the fields are **required** or **optional**, as the\noverall number of form fields for your entire product should inform your\ntreatment. The pattern used should be consistent throughout your product, or at\nminimum, consistent between all of the same types of form within your product.\n\n- If the majority of the fields are required, mark **only** the optional field\n labels with _(optional)_.\n- If the majority of the fields are optional, mark **only** the required field\n labels with _(required)_.\n\nWhen designing your form, consider the purpose and the use case to reduce visual\nnoise and clutter to allow your user to better complete their task. This will\nalso ensure consistency through and across products.\n\nAn excess of optional fields should be avoided. If it’s necessary to have a\nlarge number of optional fields, we recommend devoting an entire section to\noptional fields to avoid excessive repetition.\n\n\n\n\n\n\n
\n Example of a short user sign-up form using the optional pattern\n
\n\n\n\n\n\n\n\n\n\n
\n Example of product configuration properties using the required pattern\n
\n\n\n\n\n#### When to use\n\n \n\n\n\n\n\n\n\n\n\n\n\n\n\n\n#### Best practices\n\n- Consider the overall number of required and optional fields in the forms for\n your entire product. The pattern used should be consistent throughout your\n product, or at minimum consistent between all of the same type of form within\n your product.\n - For example, if you have 100 types of connections properties forms and the\n fields are optional in 85 of the 100 forms, all 100 should use the required\n pattern.\n- Use the techniques illustrated below in the [Default Values](#default-values)\n and [Designing for Longer Forms](#designing-for-longer-forms) sections in\n order to make your forms easier and more efficient to use.\n\n### Text inputs\n\nFree-form text inputs are the most commonly used components in forms.\n\n\n\n \n\n Deciding what to use \n\n| Control | Usage | Context |\n| -------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Text input](/components/text-input/usage) | To capture several words maximum | Names; phone numbers; addresses |\n| [Password](http://react.carbondesignsystem.com/?path=/story/textinput--toggle-password-visibility) | To collect private data by hiding the characters | Passwords, Social Security Numbers (SSN), PINs, credit card information |\n| [Text area](http://react.carbondesignsystem.com/?path=/story/textarea--default) | To capture multiple lines of text | Feedback; support requests |\n\n#### Best practices\n\n- The field widths should reflect the intended length of the content while still\n aligning to the responsive column or mini unit grid.\n- Make sure users can enter their information at smaller screen sizes.\n- Truncate when an input is too long to be fully displayed in the field.\n- Pre-populate known values when possible, e.g. a default IP address.\n- The first required input field in a form should receive focus on presentation\n to a user.\n\n### Data inputs\n\nThese controls enable users to provide input on forms by selecting from a set of\npre-determined options or a limited range of values. Carbon provides a variety\nof data input components that enable a user to make a selection. Each component\nwas created to serve a specific use case.\n\n#### Selection controls\n\nSelection controls offer users a selection from pre-determined options. When\ndesigning, consider how many options you need to present as well as how many\nitems the user may need to select. These considerations will determine which\ncomponent to use. Common selection controls include: checkboxes, radio buttons,\nfile uploaders, toggles, and select lists (combo box and multiselect).\n\n\n\n \n\n Deciding what to use \n\n| Control | Usage | Context |\n| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------ |\n| [Checkbox](/components/checkbox/usage) | To select or deselect one or more choices | Agree to terms and conditions, add optional items, select all that apply |\n| [Radio button](/components/radio-button/usage) | To select only one option from two or more choices | Pick type, shipping method, etc. |\n| [Toggle](/components/toggle/usage) | To choose one of two or more binary options | Changing user settings; On/off; Show/hide |\n| [File uploader](/components/file-uploader/usage) | To upload/attach a file or multiple files to a form | Attaching SSl certificates; adding config files to support tickets |\n| [Combo box](http://react.carbondesignsystem.com/?path=/story/combobox--default) | To select a single item with type-ahead functionality from a longer list | Choosing a state, country, or language preference |\n| [Multiselect](http://react.carbondesignsystem.com/?path=/story/multiselect--default) | To select multiple items from a longer list | Add a product example for MultiSelect |\n\n#### Radio buttons:\n\n- Pre-select a default option for the user; if the user selects a different\n option the default is deselected.\n- For null options, provide a radio button with the label “None”.\n\n#### Radio buttons and checkboxes:\n\n- Radio buttons and checkbox item text falls to the right of their controls.\n- When possible, arrange the checkbox and radio button groups vertically for\n better scannability.\n\n#### Toggles:\n\n- Always label toggles with the affected attribute due to accessibility\n constraints; color cannot be the only indicator.\n- A standalone toggle or a checkbox can be used for a single option that a user\n can turn on or off.\n- Toggles are very common controls in instantly updating forms, where submission\n is not required.\n\n#### Select lists:\n\n- When you have more than five options to present to the user, use a select list\n (combo box or multiselect), not a checkbox or a radio button.\n\n#### Bound entry controls\n\nBound entry controls allow users to input numeric data, like dates and times\n(e.g. number input, date picker, and slider components). They restrict user\ninput and rely equally on keyboard and mouse interactions. They only allow valid\nentries, so field validation isn’t needed.\n\n\n\n \n\n Deciding what to use \n\n| Control | Usage | Context |\n| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------- |\n| [Number input](/components/number-input/usage) | To increase or decrease incremental values | Order quantities |\n| [Slider](/components/slider/usage) | To select one number from a numerical range | Percentages, volume, timelines, data visualization |\n| [Date picker](/components/date-picker/usage) | To input/select a single localized date or a date range from a calendar | Scheduling trips, meetings, and events |\n| [Time picker](http://react.carbondesignsystem.com/?path=/story/timepicker--default) | To input time in hours/minutes | Scheduling meetings and travel times |\n\n### Offering help\n\n#### Tooltips\n\nTooltips can be very useful for providing additional explanation to users that\nmay be unfamiliar with a particular form field. They can also offer rationale\nfor what may seem like an unusual request. However,\n[research suggests](https://www.nngroup.com/articles/tooltip-guidelines/) that\nusers should not have to dig around for a tooltip to access information that’s\nessential for the completion of their task.\n\nIn Carbon, we use the “i” icon instead of the “?” icon because it indicates\nadditional rather than essential information.\n\n\n\n\n\n\n
\n Tooltip appears on hover (desktop) and on click (tablet and mobile).\n
\n\n\n\n\n#### Do:\n\n- Use tooltips with the outlined “i” (info) icon.\n- Use tooltips for explanatory or added information.\n- Tooltips are microcontent; keep them concise.\n\n#### Don’t:\n\n- Tooltips are not catchalls for content that doesn’t fit elsewhere; they must\n be used intentionally and very sparingly.\n- Never house essential information in a tooltip.\n\n#### Helper text\n\nHelper text appears below the input label and assists the user to provide the\nright information. Helper text is always available, even when the field is\nfocused, that’s why it’s the correct choice for need-to-know information. For\ncontext or background information that is “nice to have”, use placeholder text\nor a tooltip.\n\n\n\n\n\n\n\n\n\n#### Do:\n\n- Think of helper text as crucial information that is secondary to the input\n label.\n- Keep helper text as short and specific as possible.\n- Only use helper text when truly necessary to avoid overloading the user.\n\n#### Don’t:\n\n- Never use helper text in place of field labels.\n- Helper text should not run longer than the input area.\n\n\n\n\n\n\n\n\n\nWhen fields appear side-by-side and one input has helper text while the other\none doesn’t; always top align the input fields, not the labels.\n\n#### Placeholder text\n\nPlaceholder text provides hints or examples of what to enter (e.g. YYYY-MM-DD).\nSince placeholder text disappears once the user begins to input data, it should\nnot contain crucial information. When the requested input may be unfamiliar to\nthe user or formatting is in question, use placeholder text.\n\n\n\n\n\n\n\n\n\n#### Do:\n\n- Keep hints as short as possible and never overrun the input field.\n- Properly anonymize examples rather than using real values.\n\n#### Don’t:\n\n- Use placeholder text to communicate complex and lengthy requirements like\n password requirements. Instead, use an infotip.\n- Provide placeholder text when it isn’t necessary.\n- Ever use placeholder text as a replacement for field labels.\n\n#### Default values\n\nDefault values can be set for for all types of inputs. Ensure that if a default\nvalue is provided, it is something that would commonly be used anyway and would\nnot cause disruption or errors if the user forgets or opts not to make any\nchanges to it before submitting the form. Good default values reduce cognitive\nload.\n\nFor example:\n\n- If you can detect or determine where your users are from, have their country\n pre-selected in a \"Country\" dropdown.\n- If there is a common or minimum value (i.e., a quota or memory limit),\n pre-fill that value.\n- If a text input can be detected or determined in advance (i.e.-company name),\n pre-fill that value.\n- If a start date is required, use the current date as the default.\n\n### Buttons\n\nUse a primary button for the main action, a secondary button for secondary\nactions like Cancel or Discard.\n\n#### Button alignment\n\nAlignment refers to whether the buttons are aligned to the right or the left of\nthe container or layout. Button alignment depends on the type of form that you\nare building. We’ll touch on alignment briefly here as it relates to the button\ncomponent and offer more detailed information about [form variations](#variants)\nbelow.\n\n#### Margins vs. full bleed\n\nIn side panels, dialogs, and any other forms within tiles, the button group\nshould span the width of the container and buttons should bleed to the bottom\nedge. If the button content is too long for this arrangement, stack buttons\nvertically (with primary button on the bottom) and maintain their margin and\npadding. See [button usage guidance](/components/button/usage) for more\ninformation.\n\n| Alignment | Bleed | Use case |\n| ------------- | ----- | ---------------------------------------------------------------------------------------------- |\n| Left-aligned | No | Non-dialog, in-page forms |\n| Right-aligned | No | Multistep forms/wizards when the primary action implies a navigation step forward |\n| Full-width | Yes | All forms that are presented in dialogs and side panels and in some cases, forms within a tile |\n\n#### Button emphasis\n\nEmphasis refers to the position of the primary button in relation to secondary\nand tertiary actions. When using multiple buttons in forms, the position of the\nprimary button can vary according to the\n[button groups](/components/button/usage/#button-groups) guidance. Factors such\nas page layout, form type, and alignment will influence your button emphasis.\n\nThe primary button will be left-aligned and positioned to the left of the\nsecondary/tertiary button on in-page forms or most other form layouts that don’t\nfit the right-aligned criteria. The primary button will be right-aligned and\nappear to the right of the secondary/tertiary button within progressive forms,\nwizards, and forms in structured containers like dialog windows or side panels.\n\n\n\n\n\n\n
Examples of in-page forms with a left-aligned primary button
\n\n\n\n\n\n\n\n\n\n
\n Examples of progressive and dialog forms with a right-aligned primary button\n
\n\n\n\n\n#### Do not top-align buttons\n\nThere is a trend among product teams to pin buttons at the top of a\ndedicated-page form. We want to discourage this arrangement for several reasons.\n\nFirst, we should only be asking the user for essential input and we should\nelicit that information in a concise, deliberate way. So we should assume that\nthe user scrolls through the appropriate inputs before submitting a form.\n\nSecond, the dedicated page form is not a modal and does not prevent the user\nfrom accessing their previous workflow. A back button will be available to them\nas part of the breadcrumb at the top of the page, or via the progress indicator\ncomponent (if your form is part of a multistep flow). The browser back button is\nalso available. In short, back should never be an action on a secondary button.\nThe secondary button is usually reserved for cancelling the task.\n\nThird, and most important, the top-pinned buttons create a very awkward\nrelationship with the content when the user finishes the form and is ready to\nsubmit. If we feel it’s necessary to pursue pinned actions in the future, we\nshould look into a pinned footer or tray to contain button groups.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n#### Naming actions\n\nAbstract terms like “Submit” give the user the impression that the form is\ngeneric. Although brevity is key in buttons, try to tell the user specifically\nwhat action your button will perform.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n## Behavior\n\n### Errors and validation\n\nEffective and immediate error messaging can help the user to understand the\nproblem and how to fix it. First, inform the user what has happened, then\nprovide guidance on next steps or possible resolutions. Always present error\nstates on the form, and use inline errors whenever possible.\n\n#### Client-side validation\n\nWe recommend validating the user’s data before form submission. This type of\nreal-time, inline validation (a.k.a. client-side validation) should happen as\nsoon as the field loses focus. This will help to easily identify the elements\nthat need to be corrected.\n\nThe validation label below the field should be as informative as possible when\ndescribing the issue with the user’s data. For example, if password limitations\nrequire 16 characters, but the user inputs a password with only six characters,\nthe text should read something like, “Password must be at least 16 characters.”\n\nCommon user errors include:\n\n- Incorrectly formatting data\n- Leaving a mandatory field blank\n- Leaving a mandatory field incomplete\n\n\n\n\n\n\n\n\n\n\n\n\n\n#### Server-side validation\n\nInline notifications come into play when server-side errors are involved, i.e.\nthe user tries to submit a form in its entirety and the page is reloaded with\nthe detected errors.\n\nIn these situations, use an inline notification as well as inline error\nmessaging wherever possible to help users make the fix. Inline error messages\nshould disappear when the form criteria is met.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n### Enabling and disabling buttons\n\n- For short forms that require server-side submission before returning errors,\n we recommend disabling primary action buttons until all of the form’s\n requirements are met.\n- For longer forms, do not disable primary action buttons because the error\n messages and the primary action button may not be visible on the screen\n simultaneously.\n- When a user submits a form, disable the primary action button to prevent\n duplicate submissions.\n- If it’s going to take a while to process a form, communicate this to the user\n with feedback messages and progress indicators (e.g. spinners or progress\n bars).\n\n### In-line editing\n\nIn-line editing enables users to edit form text in situ instead of taking users\nto another page to edit their entry. This saves users from having to refresh the\nwhole form in order to make an edit.\n\nCarbon does not have consolidated guidance around inline editing. Since it’s\nsomething a lot of products approach in different ways, we’d like to offer more\nrobust, centralized guidance in the future.\n\n### Designing for longer forms\n\nProduct designers often ask about the appropriate length for web forms.\nUnfortunately, there’s no one-size-fits-all answer. Your audience and their\nintentions, along with the context of your product will determine the solution\nthat’s best for you. Here are several techniques to help make longer forms less\noverwhelming.\n\n#### Progressive disclosure\n\nUse progressive disclosure to reveal any additional content that may arise based\non the user’s previous selection. This kind of show/hide approach allows the\nuser to focus on relevant information while keeping workflows short.\n\n\n\n\n\n\n\n\n\n#### Accordion forms\n\nAccordion forms allow users to dynamically expose and hide sections of related\ninformation. Like progressive disclosure, accordion forms allow users to focus\non relevant information without having to navigate between pages. As a general\nrule, this technique should not be used in dialog forms.\n\n[Research suggests](https://www.lukew.com/ff/entry.asp?1190) that accordion\nforms can greatly enhance completion speed and page load times. However the same\nresearch also suggests that confusion can arise for users when it comes to\nprimary action buttons and whether they apply only to sections vs. the full\nform.\n\nThe IoT team has done some design explorations around accordion forms but more\ndesign iteration and user testing is needed before Carbon solidifies our\nguidance around this interaction. Keep an eye out for refined usage examples in\nthe future.\n\n#### Multistep forms\n\nA multistep form spreads form fields across multiple screens and incorporates a\n[progress indicator](/components/progress-indicator/usage) (vertical or\nhorizontal) to track a user’s status step by step. There should be a logical\nrelationship between the fields on each screen and a linear relationship between\nsections.\n\nThis approach is good for saving form progress along the journey and allows\nusers to return to a previous step to review their submissions.\n\n\n\n\n\n\n
\n A multistep form with a horizontally oriented progress indicator.\n
\n\n\n\n\n\n\n\n\n\n
\n A multistep form with a vertically oriented progress indicator.\n
\n\n\n\n\n## Designing a form\n\n### Layout\n\n#### Form headings\n\nHeadings describe the form. The heading should be the largest type size in the\nform hierarchy. IBM Product UI often uses the `$productive-heading-03` token for\nthis purpose if the form is within a container or a dialog. A larger type size\nshould be used if the form is the only element on the page. The title can also\nbe followed by a short descriptor.\n\n#### Group and section headings\n\nGroup headings describe a group of controls and fields within a form. Their size\nshould also be adjusted depending on context and form heading size (i.e. the\nchosen token should be larger than the field labels but obviously smaller than\nthe form heading). Inputs should be grouped to help users understand what is\nrequired of them in a logical way. Try to make the group heading short and\nprecise, but, you can add a short description of the group if necessary.\n\n### Spacing\n\nUsers will be confused if inputs are too close together. To ensure sufficient\nspacing between single form elements as well as groups of inputs, use margins,\nspacers, gutters, and key alignments to guide you. See the\n[2x Grid](/guidelines/2x-grid/overview) for more information.\n\n#### Form context\n\nForms can appear as dedicated pages or within dialogs, tiles, or side panels.\nThe form’s context affects its layout and vertical spacing. As a general rule\ndedicated-page forms can handle more complexity. See [form variants](#variants)\nbelow for more detailed usage guidance.\n\nOn dedicated page forms, use the responsive grid to drive layout decisions.\nDialogs and side panel forms will revert to a box model so designers will use\nmini units to guide field widths. Consistency of alignments and geometries in\neither scenario is key.\n\nIndividual input fields default to a 40px height in product regardless of\ncontext. On dedicated-page forms, we recommend a 32px spacer between input\nfields. In contained forms, such as side panels or modals, designers can revert\nto 24px or even 16px between inputs.\n\n#### Separating inputs, actions and sections\n\nVertical spacing between form sections also depends on whether the form is a\ndedicated page or a container. Spacing between groups should be adjusted in\nrelationship to spacing between individual items. For instance, if vertical\nspacing between individual inputs is 24px consider a 32px spacer before the\nfirst input and between sections. If the former number is 32px, consider 40px\nfor the latter.\n\nAs a general rule, we recommend a 48px spacer between the last input and the\nbutton or button group. Again, this will vary in mobile and in certain contained\nforms.\n\n\n\n\n\n\n\n\n\n#### Rules\n\nDesigners often use rules to separate groups of information within forms. Carbon\ndoes not have consolidated guidance around rules within forms (i.e. width,\nthickness, vertical margins). We intend to provide more detailed guidance around\ntheir use in the future.\n\n### Columns\n\nBased on research from the\n[Nielsen Norman Group](https://www.nngroup.com/articles/web-form-design/),\nCarbon generally recommends single-column forms, simply because multicolumn\nforms are more prone to misinterpretation. However, when faced with larger\nscreen sizes and a lot of empty space, multicolumn forms may seem like a good\nidea. And in certain situations they are appropriate.\n\nIf you would like to create a multicolumn form, the number of columns should\ndepend on the number of input controls on the page, their relationship to one\nanother, and the screen size of the product window.\n\nAlways use common sense to group related fields horizontally. Two to three\ninputs on a single line will not cause problems if they logically belong\ntogether. Here are some examples:\n\n- [first name][mi] [last name]\n- [credit card number][expiration date] [security code]\n- [city][state/province] [zip code]\n\nAvoid overloading users with too much information, when a multistep form may be\na better choice.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n## Variants\n\nAs mentioned above, forms may be presented as dedicated pages, side panels, or\ndialogs depending on the use case and the situation.\n\n Deciding what to use \n\n| Form variant | Usage | Context\\* |\n| -------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |\n| Dedicated page | For more complex, lengthier or multistep requests for user input | Creating a new service, such as provisioning; more complex order forms etc. |\n| Dialog | For critical, infrequent requests for user input often related to editing and management tasks | User permissions; upgrading a service |\n| Side panel | For repeated requests for user input which require the user needs to reference the affected information | Calibrating row information in a data table |\n\n
\n * We are looking for more input from product teams here. Please connect with\n us about your use cases.\n
\n\n#### Dialog forms:\n\n- Use a dialog form when dealing with less than five inputs.\n- Do not hide information in accordions or tabs.\n- A [dialog pattern](/patterns/dialog-pattern) with more detailed guidance will\n be released shortly.\n\n#### Side panel forms:\n\n- Use a side panel form when dealing with more than five inputs.\n- Do not hide information in accordions or tabs.\n\n## Accessibility\n\nWhen constructing a form, first refer to the specific accessibility guidance for\neach component used. Every text input should have a descriptive and visible\nlabel, along with hard coded instructions for input format. A form must be\nwrapped in a `
