carbon-design-system · tay1orjones · Sep 25, 2025 · Sep 26, 2025 · Sep 26, 2025 · Sep 26, 2025
@@ -1,9 +1,13 @@
+<!-- NOTE: This file is used in the generation of storybook docs page(s). -->
+
 ## About feature flags
 
 Carbon packages ship with a collection of feature flags that enable new behavior
 and styling. They're a way for consumers to opt-in incrementally to
 [preview](https://github.com/carbon-design-system/carbon/blob/main/docs/preview-code.md)
-changes while still using the current version.
+changes while still using the current version. When a new feature flag is
+introduced it is marked `false` or "off" by default to ensure backwards
+compatibility.
 
 A feature flag can be available in react, web components, sass, or any mix of
 these. Flags may also have a related codemod to help migration faster and
@@ -16,9 +20,10 @@ test and give us feedback on. They're generally stable and unlikely to change
 but can change based on your feedback.
 
 Flags prefixed with `enable-v12-*` are stable and won't change. They will be
-marked as `true` or "on" by default in the next major version, v12. For more
-details on this approach, see the
-[preview code documentation](https://github.com/carbon-design-system/carbon/blob/main/docs/preview-code.md).
+marked as `true` or "on" by default in the next major version, v12.
+
+For more details on this naming convention, see the
+[section below](#feature-flag-naming-convention).
 
 Unless otherwise specified, flags are `false` by default.
 
@@ -40,6 +45,13 @@ Unless otherwise specified, flags are `false` by default.
 | `enable-experimental-tile-contrast`                | Deprecated, use `enable-tile-contrast` instead                                       | Sass         |                                                                                                                                                                |
 | `enable-experimental-focus-wrap-without-sentinels` | Deprecated, use `enable-focus-wrap-without-sentinels` instead                        | React        |                                                                                                                                                                |
 
+## Documentation
+
+In addition to this document, within each storybook there are "Feature flags"
+folders for some components. Docs page(s) within this folder cover the flag
+specifics and usage. The stories within in the folder showcase the impact of
+when the flag(s) are turned on.
+
 ## Using Codemods for Migration
 
 Codemods are code modification scripts that automate the necessary changes when
@@ -76,3 +88,43 @@ Changes can be reviewed by looking at your local unstaged file changes in git.
 For more information on available codemods, see the
 [@carbon/upgrade](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade/README.md)
 documentation.
+
+## Feature flag naming convention
+
+All feature flags follow a prefix naming convention that indicate status.
+
+### Flags prefixed with `enable-*`
+
+- Contain new features that we'd like consuming projects to test
+- Are generally stable and unlikely to change but may change based on user
+  feedback
+- May require some manual migration or code changes within your project
+- Are documented in storybook
+- May not be documented on https://www.carbondesignsystem.com
+- Need user feedback to ensure we've met all concerns relating to this feature
+
+If you use these flags, make sure to check our release notes where we'll outline
+any changes to them across our regularly scheduled minor version releases.
+
+### Flags prefixed with `enable-v#-*`
+
+As usage of an existing flag increases or we determine a feature to be of high
+importance, we'll "commit" it to a future major release and rename it to use the
+`enable-v#-*` prefix. At this point the API or functionality behind this flag is
+now fixed and won't change. We intend to ship this flag as "on by default" in
+the major version indicated in the name. e.g. `enable-v12-some-feature`
+
+All breaking changes will be shipped as `enable-v12-*` flags within the current
+major release (v11). This enables projects to opt-in to breaking changes earlier
+and at their own pace avoiding one huge changeset when upgrading to the next
+major release. In theory, if all `enable-v12-*` flags are enabled within your
+project before the v12 release, no changes should need to be made to the
+affected components when updating to v12.
+
+For a flag to be committed to a release and renamed to `enable-v#-*` it must:
+
+- Be tested with early adopters
+- Be fully covered in tests (Unit, AVT, and VRT)
+- Be documented in storybook
+- Be documented on https://carbondesignsystem.com
+- Have an automated migration script (codemod) available, where possible
@@ -1,23 +1,35 @@
+<!-- NOTE: This file is used in the generation of storybook docs page(s). -->
+
 # Preview code
 
-The team occasionally will author code, or accept contributions, that is not yet
-considered stable. The goal for this code is to ship it as a "preview" for teams
-to begin using in production. During this time, the Carbon team can get feedback
-around what is working and what does not work so that potential changes can be
-made before an official release.
+The team occasionally will author code, or accept contributions, that is shipped
+as a "preview" for teams to begin using in production. During this phase, the
+goal is to get feedback from consumers and their end users around what is
+working well and what could be improved. This feedback informs if, how, and why
+changes should be made before the official stable release. Using preview code in
+your project helps Carbon continue to be buided by real-world usage of
+components and patterns.
+
+Previously referred to as "experimental" or "unstable", the new "preview" status
+is part of the larger
+[Product Development Lifecycle (PDLC)](https://carbondesignsystem.com/contributing/product-development-lifecycle/)
+process framework that Carbon follows.
+
+## Preview documentation
+
+Within the `Preview` section of storybook, there are individual entries for each
+preview export. These contain stories and written documentation outlining the
+functionality of these components and exports.
+
+## Preview usage
 
 Preview code is made available in the following ways:
 
 - Components and exports prefixed with `preview_`
 - Feature flags
 - Expanding existing APIs
 
-Previously referred to as "experimental" or "unstable", the new "preview" status
-is part of the larger
-[Product Development Lifecycle (PDLC)](https://carbondesignsystem.com/contributing/product-development-lifecycle/)
-process framework that Carbon follows.
-
-## Components and exports prefixed with `preview_`
+### Prefixed exports
 
 For exports in the preview phase, we use the `preview_` prefix. For example:
 
@@ -40,7 +52,7 @@ function ComponentName(props) {
 
 // However, when we export the component we will export it with the `preview_`
 // prefix.
-export { default as preview_ComponentName } from './components/ComponentName';
+export { ComponentName as preview_ComponentName } from './components/ComponentName';
 ```
 
 For teams using these features, they will need to import the functionality by
@@ -50,81 +62,15 @@ using the `preview_` prefix. For example:
 import { preview_ComponentName as ComponentName } from '@carbon/react';
 ```
 
-<!-- prettier-ignore-start -->
-> [!TIP]
-> Exports prefixed with `preview_` are ready for production use.
-<!-- prettier-ignore-end -->
-
-### Documenting components and exports prefixed with `preview_`
-
-Within the preview section of the `@carbon/react` storybook, there are
-individual entries for each preview export. These contain stories and written
-documentation outlining the functionality of these components and exports.
-
-## Feature flags
-
-Some Carbon packages ship with available feature flags. These feature flags
-enable new behavior and styling, allowing you to opt-in to new breaking changes
-while remaining on the current major version. When a new feature flag is
-introduced it is marked `false` or "off" by default to ensure backwards
-compatibility. A feature flag may be configured in javascript, sass, or both.
-
-All the currently available feature flags, as well as how to enable them, is
-documented in the
-[`@carbon/react` storybook](https://react.carbondesignsystem.com/).
-
-### Feature flag naming convention
-
-All feature flags follow a prefix naming convention that indicate status.
-
-#### Flags prefixed with `enable-*`
-
-- Contain new features that we'd like consuming projects to test
-- Are generally stable and unlikely to change but may change based on user
-  feedback
-- May require some manual migration or code changes within your project
-- Are documented in storybook
-- May not be documented on https://www.carbondesignsystem.com
-- Need user feedback to ensure we've met all concerns relating to this feature
-
-If you use these flags, make sure to check our release notes where we'll outline
-any changes to them across our regularly scheduled minor version releases.
-
-#### Flags prefixed with `enable-v#-*`
-
-As usage of an existing flag increases or we determine a feature to be of high
-importance, we'll "commit" it to a future major release and rename it to use the
-`enable-v#-*` prefix. At this point the API or functionality behind this flag is
-now fixed and won't change. We intend to ship this flag as "on by default" in
-the major version indicated in the name. e.g. `enable-v12-some-feature`
-
-All breaking changes will be shipped as `enable-v12-*` flags within the current
-major release (v11). This enables projects to opt-in to breaking changes earlier
-and at their own pace avoiding one huge changeset when upgrading to the next
-major release. In theory, if all `enable-v12-*` flags are enabled within your
-project before the v12 release, no changes should need to be made to the
-affected components when updating to v12.
-
-For a flag to be committed to a release and renamed to `enable-v#-*` it must:
-
-- Be tested with early adopters
-- Be fully covered in tests (Unit, AVT, and VRT)
-- Be documented in storybook
-- Be documented on https://carbondesignsystem.com
-- Have an automated migration script (codemod) available, where possible
-
-### Documenting feature flags
-
-Within the the `@carbon/react` storybook, there is a "Feature Flags" docs page.
-This contains stories and written documentation covering every available flag
-and how to configure them. "Feature flags" folders and stories in storybook show
-components with all feature flags turned on.
+### Feature flags
 
 All the currently available feature flags, as well as how to enable them, is
 documented in the
-[`@carbon/react` storybook](https://react.carbondesignsystem.com/).
+[`@carbon/react` storybook](https://react.carbondesignsystem.com/?path=/docs/getting-started-feature-flags--overview)
+and
+[`@carbon/web-components` storybook](https://web-components.carbondesignsystem.com/?path=/docs/introduction-feature-flags--overview).
 
-## Expanding existing APIs
+### Expanding existing APIs
 
 New preview functionality can sometimes be added without the need of an
 `preview_` export or a feature flag. Oftentimes this ends up being a new prop on

@@ -0,0 +1,6 @@
+import { Meta, Markdown } from '@storybook/addon-docs/blocks';
+import PreviewCode from '../../../../docs/preview-code.md?raw';
+
+<Meta title="Preview/About preview" name="About preview" />
+
+<Markdown>{PreviewCode}</Markdown>
@@ -27,6 +27,7 @@ const storyGlobs = [
   '../src/**/next/**/*.stories.js',
   '../src/**/next/*.mdx',
   '../src/**/*-story.js',
+  './Preview/Preview.mdx',
 ];
 
 const stories = glob.sync(storyGlobs, {

@@ -0,0 +1,6 @@
+import { Meta, Markdown } from '@storybook/addon-docs/blocks';
+import PreviewCode from '../../../docs/preview-code.md?raw';
+
+<Meta title="Preview/About preview" name="About preview" />
+
+<Markdown>{PreviewCode}</Markdown>