docs(Overview & FAQs page) Feature flag update (#4259)

* Adding feature flag to Overview & FAQs pages * feat: add Tag * chore: oops wrong PR - revert * Updating in the data/components.json * chore: update classname and add tokens * Copy fixes * link shortened * Anna's feedback * fix(checklist): extra % --------- Co-authored-by: Alison Joseph <[email protected]> Co-authored-by: Scott Strubberg <[email protected]>
carbon-design-system · Oct 10, 2024 · 803f54c · 803f54c
1 parent b8fd3ac
commit 803f54c
Show file tree

Hide file tree

Showing 9 changed files with 137 additions and 12 deletions.
diff --git a/src/components/ComponentOverview/ComponentOverview.js b/src/components/ComponentOverview/ComponentOverview.js
@@ -2,14 +2,16 @@
 import React from 'react';
 import { Link } from 'gatsby';
 import componentList from '../../data/components.json';
+import { Tag } from '@carbon/react';
 
 // only display components where overview is true in the data
 const filteredComponentList = componentList.components.filter(
   (item) => item.overview !== false
 );
+
 class ComponentOverview extends React.Component {
   renderItems = (currentItem) => {
-    const { component } = currentItem;
+    const { component, featureFlag } = currentItem;
     let componentUrl;
     if (component === 'Multiselect') {
       componentUrl = '/components/dropdown/usage';
@@ -39,7 +41,12 @@ class ComponentOverview extends React.Component {
                 alt={component}
                 className="component-item__img"
               />
-              <p className="component-name">{component}</p>
+              <p className="component-name">{component}</p>{' '}
+              {featureFlag ? (
+                <Tag type="blue" className="component-tag--feature-flag">
+                  Feature flag
+                </Tag>
+              ) : null}
             </Link>
           </div>
         </div>

diff --git a/src/components/ComponentOverview/component-overview.scss b/src/components/ComponentOverview/component-overview.scss
@@ -117,6 +117,13 @@ $hover-ui: #e5e5e5;
   text-align: left;
   display: flex;
   position: absolute;
-  top: 1rem;
-  left: 1rem;
+  top: $spacing-05;
+  left: $spacing-05;
+}
+
+.component-tag--feature-flag {
+  position: absolute;
+  bottom: $spacing-05;
+  left: $spacing-05;
+  margin: 0;
 }
diff --git a/src/data/components.json b/src/data/components.json
@@ -298,12 +298,14 @@
     },
     {
       "component": "Menu buttons",
+      "featureFlag": true,
       "testing": {
         "screenreader": "manual"
       }
     },
     {
       "component": "Modal",
+      "featureFlag": true,
       "testing": {
         "screenreader": "manual"
       }
@@ -317,6 +319,7 @@
     },
     {
       "component": "Notification",
+      "featureFlag": true,
       "testing": {
         "screenreader": "manual"
       }
@@ -408,6 +411,7 @@
     },
     {
       "component": "Structured list",
+      "featureFlag": true,
       "testing": {
         "screenreader": "manual"
       }
@@ -447,6 +451,7 @@
     },
     {
       "component": "Tile",
+      "featureFlag": true,
       "testing": {
         "screenreader": "manual"
       }
@@ -479,6 +484,7 @@
     },
     {
       "component": "Treeview",
+      "featureFlag": true,
       "testing": {
         "screenreader": "manual"
       }

diff --git a/src/pages/components/overview/accessibility-status.mdx b/src/pages/components/overview/accessibility-status.mdx
@@ -3,7 +3,7 @@ title: Overview
 description:
   Components are one of the key building blocks of the design system. Each
   component has been designed and coded to solve a specific UI problem.
-tabs: ['Components', 'Accessibility status']
+tabs: ['Components', 'Accessibility status', 'Feature flags']
 ---
 
 import A11yStatus from 'components/A11yStatus';

diff --git a/src/pages/components/overview/components.mdx b/src/pages/components/overview/components.mdx
@@ -3,7 +3,7 @@ title: Overview
 description:
   Components are one of the key building blocks of the design system. Each
   component has been designed and coded to solve a specific UI problem.
-tabs: ['Components', 'Accessibility status']
+tabs: ['Components', 'Accessibility status', 'Feature flags']
 ---
 
 import ComponentOverview from 'components/ComponentOverview';

diff --git a/src/pages/components/overview/feature-flags.mdx b/src/pages/components/overview/feature-flags.mdx
@@ -0,0 +1,87 @@
+---
+title: Overview
+description:
+  Components are one of the key building blocks of the design system. Each
+  component has been designed and coded to solve a specific UI problem.
+tabs: ['Components', 'Accessibility status', 'Feature flags']
+---
+
+import { Launch } from '@carbon/icons-react';
+import { Link } from '@carbon/react';
+
+<PageDescription>
+
+Feature flags enable new behaviors and styling, allowing users to opt-in to new
+breaking changes while staying on the current major version.
+
+</PageDescription>
+
+<AnchorLinks>
+
+<AnchorLink>Overview</AnchorLink>
+<AnchorLink>Components with feature flags</AnchorLink>
+<AnchorLink>How to implement</AnchorLink>
+
+</AnchorLinks>
+
+## Overview
+
+When a new feature flag is introduced, it is set to false or "off" by default to
+ensure backward compatibility. We are not deprecating the current components but
+encourage all teams to use the new feature flag-enabled components in their
+products moving forward.
+
+## Components with feature flags
+
+The following components have feature flags, with changes related to either
+design or development.
+
+| Component                    | Design change                                                                    | Code change                                                                                                                                                                                  |
+| ---------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Menu buttons (Overflow menu) | No design change                                                                 | <Link href={"https://react.carbondesignsystem.com/?path=/docs/experimental-feature-flags-overflowmenu--overview"} renderIcon={() => <Launch aria-label="Launch" />}>React</Link>             |
+| Modal                        | No design change                                                                 | <Link href={"https://react.carbondesignsystem.com/?path=/docs/experimental-feature-flags-modal--overview"} renderIcon={() => <Launch aria-label="Launch" />}>React</Link>                    |
+| Notification                 | No design change                                                                 | <Link href={"https://react.carbondesignsystem.com/?path=/docs/experimental-feature-flags-notifications-actionable--overview"} renderIcon={() => <Launch aria-label="Launch" />}>React</Link> |
+| Structured list              | <Link href={"/components/structured-list/usage/#feature-flags"}>Usage tab</Link> | <Link href={"https://react.carbondesignsystem.com/?path=/docs/experimental-feature-flags-structuredlist--overview"} renderIcon={() => <Launch aria-label="Launch" />}>React</Link>           |
+| Tile                         | <Link href={"/components/tile/usage/#feature-flags"}>Usage tab</Link>            | <Link href={"https://react.carbondesignsystem.com/?path=/docs/experimental-feature-flags-tile--overview"} renderIcon={() => <Launch aria-label="Launch" />}>React</Link>                     |
+| Tree view                    | No design change                                                                 | <Link href={"https://react.carbondesignsystem.com/?path=/docs/experimental-feature-flags-treeview--overview"} renderIcon={() => <Launch aria-label="Launch" />}>React</Link>                 |
+
+## How to implement
+
+### Code
+
+Each framework handles feature flags differently. At the moment, only React has
+available feature flags. This may change in the future, check back later for
+updates related to all available feature flags.
+
+<Title>React</Title>
+
+The development specifics for feature flags in React can be found in the
+[@carbon/react](https://react.carbondesignsystem.com/?path=/docs/experimental-feature-flags--overview)
+framework.
+
+### Design
+
+Inside a design file, click on the component with a feature flag (A). In the
+properties panel, locate the **Feature flag** boolean property (B). By default,
+this feature is turned off, but can be toggled on to enable the feature flag.
+
+<Row>
+<Column colLg={8}>
+
+![Feature flag implementation in Figma](images/feature-flag-implementation-1.png)
+
+</Column>
+</Row>
+
+Additionally, when clicking on the **components details** (C) in the properties
+panel, a description of the feature flag, and a link to the component's usage
+guidance is provided for more information in the **Component documentation**
+window (D).
+
+<Row>
+<Column colLg={8}>
+
+![Feature flag implementation in Figma](images/feature-flag-implementation-2.png)
+
+</Column>
+</Row>
diff --git a/src/pages/components/overview/images/feature-flag-implementation-1.png b/src/pages/components/overview/images/feature-flag-implementation-1.png
diff --git a/src/pages/components/overview/images/feature-flag-implementation-2.png b/src/pages/components/overview/images/feature-flag-implementation-2.png
diff --git a/src/pages/help/faq/index.mdx b/src/pages/help/faq/index.mdx
@@ -121,12 +121,30 @@ The Carbon Native mobile Figma kit is available on the
 [Other resources](https://carbondesignsystem.com/designing/design-resources/#native-mobile)
 page.
 
-### Where do I find the Experimental components and patterns?
-
-The patterns and components that were in Experimental are now in the
-[Community assets](/community/overview) section. Community assets include work
-developed and maintained by the individuals and teams who use Carbon. You can
-help elevate these resources by contributing feedback, code, and design.
+### What are feature flags? Where do I find them?
+
+Feature flags enable new behaviors and styling, allowing users to opt-in to new
+breaking changes while staying on the current major version. A list of
+components with available feature flags can be found on the Component Overview
+page under the [Feature flags](/components/overview/feature-flags/) tab.
+
+### What are experimental components? Where do I find them?
+
+The team occasionally will author code, or accept contributions, that is
+considered experimental or unstable. The goal for this code is to ship it as
+unstable for sponsor groups to leverage. During this time, the team can get
+feedback around what is working and what does not work so that changes can be
+made before an official release. They are available on the storybook under the
+[Experimental](https://react.carbondesignsystem.com/?path=/docs/experimental-feature-flags--overview)
+tab.
+
+### Where do I find the community assets?
+
+The patterns and components that were in Experimental are now in
+the [Community assets](https://carbondesignsystem.com/community/overview/) section.
+Community assets include work developed and maintained by the individuals and
+teams who use Carbon. You can help elevate these resources by contributing
+feedback, code, and design.
 
 Note that some of the content in Community assets is hosted on internal IBM
 sites and is only accessible to IBMers.