Merge branch 'main' into 8764-font-family

docs/migration/v11.x.md

@@ -8,9 +8,10 @@
 ## Table of Contents
 
 - [Timeline](#timeline)
-- [Previewing the release](#previewing-the-release)
-  - [Feature flags](#feature-flags)
-
+- [Updates](#updates)
+  - [Single-entrypoint packages](#single-entrypoint-packages)
+  - [`carbon-icons`](#carbon-icons)
+  - [Vanilla JS components](#vanilla-js-components)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 <!-- prettier-ignore-end -->
@@ -19,12 +20,12 @@
 
 **Note: all dates are an estimate and can be changed**
 
-| Date                        | Release          | Status            |
-| --------------------------- | ---------------- | ----------------- |
-| Alpha release               | April 15th, 2021 | Published         |
-| Beta release                | May 13th, 2021   | Under development |
-| Release Candidate 0 release | June 10th, 2021  | Not published     |
-| Stable release              | July 1st, 2021   | Not published     |
+| Date                        | Release             | Status            |
+| --------------------------- | ------------------- | ----------------- |
+| Alpha release               | April 15th, 2021    | Published         |
+| Beta release                | July 22nd, 2021     | Under development |
+| Release Candidate 0 release | ~1 month after beta | Not published     |
+| Stable release              | ~1 month after rc.0 | Not published     |
 
 We are breaking up our v11 release into several iterations to get feedback from
 teams before our stable release. If you're interested in helping us out with
@@ -40,68 +41,54 @@ publishing.
 During each release stage, we're looking to get feedback from teams in our
 [Release Partner Program](https://github.com/carbon-design-system/carbon/wiki/Release-Partner-Program).
 
-## Previewing the release
-
-There are two ways to try out the v11 release of Carbon:
-
-- Feature flags along with the `carbon-components` and `carbon-components-react`
-  packages
-- Using the new packages directly, like `@carbon/react` or `@carbon/styles`
-
-As we near the v11 release, the preference will be to use the `@carbon/react`
-package. However, for the alpha and beta release, full compatibility will not be
-available, so we recommend trying out new features using feature flags.
-
-### Feature flags
-
-Our team makes use of
-[feature flags](https://martinfowler.com/articles/feature-toggles.html) to ship
-new code in our v10 release without breaking existing usage.
-
-To try out features related to the v11 release, you will use the
-`enable-v11-release` flag in both Sass and JavaScript.
+## Updates
 
-To enable this flag in `carbon-components`, you will need to set
-`$feature-flags` before importing `carbon-components`. For example:
+### Single-entrypoint packages
 
-```scss
-$feature-flags: (
-  enable-v11-release: true,
-);
+Starting in v11, we will prefix many of the packages we ship with the `@carbon`
+scope. We will also try and consolidate packages where possible to get as close
+to a one-package, one-install experience.
 
-@import 'path/to/carbon';
-```
+- `carbon-components`
+- `carbon-components-react`
+- `carbon-icons`
 
-To enable this flag in `carbon-components-react`, you can either set flags
-directly using the `@carbon/feature-flags` package or use the `FeatureFlags`
-component.
+In v11, you will only need to install one package: `@carbon/react`. This package
+will contain components, styles, and icons all bundled up in one package.
 
-**`FeatureFlags`**
+This does not mean that all packages are now developed in the `@carbon/react`
+package. Instead, we re-export packages like `@carbon/icons-react` or the new
+`@carbon/styles` for you to use.
 
-```jsx
-import { unstable_FeatureFlags as FeatureFlags } from 'carbon-components-react';
+For teams using the `carbon-components` package for styles, you can update to
+`@carbon/styles` which is our standalone styles package for Sass.
 
-render(
-  <FeatureFlags flags={{ 'enable-v11-release': true }}>
-    <MyComponent />
-  </FeatureFlags>
-);
-```
+Both `carbon-components` and `carbon-components-react` will continue to work in
+v11, however they are only re-exporting from `@carbon/styles` and
+`@carbon/react` respectively.
 
-**`@carbon/feature-flags`**
+### `carbon-icons`
 
-First, create a file called `feature-flags.js` and include the following:
+The `carbon-icons` package has been archived and is no longer supported. To use
+icons from the Carbon Design System, you should install the appropriate library
+to use with your framework:
 
-```js
-import * as FeatureFlags from '@carbon/feature-flags';
+- `@carbon/icons`: Vanilla JavaScript
+- `@carbon/icons-react`: React
+- `@carbon/icons-vue`: Vue
+- `@carbon/icons-angular`: Angular
+- `carbon-icons-svelte`: Svelte
 
-FeatureFlags.enable('enable-v11-release');
-```
+### Vanilla JS components
 
-Next, bring in this file as the first import in your project:
+For a long time now, the `carbon-components` package has shipped Vanilla
+JavaScript version of components for teams to use. Starting in v11, these
+components will be split out from the main package and into a
+community-supported package. The Carbon team will no longer directly support
+these components.
 
-```js
-import './feature-flags';
+You can continue to use the v10.x version of `carbon-components`, or use the
+`TODO` package to access the Vanilla JS components.
 
-// Import feature flags before any of your application code
-```
+If you're interested in helping to maintain this package, we're currently
+looking for maintainers! Please reach out to us over at: TODO.

packages/carbon-react/.storybook/styles.scss

@@ -9,19 +9,13 @@ $feature-flags: (
   enable-v11-release: true,
 );
 
-@use "~@ibm/plex/default" as sans;
-@use "~@ibm/plex/mono";
-@use "~@ibm/plex/arabic";
-
-@use '../index.scss' as styles;
+@use '../index.scss' as styles with (
+  $css--font-face: true,
+  $css--plex-arabic: true,
+);
 @use '../scss/components/button';
 @use '../scss/components/tag';
 
-// For now, including all weights for testing
-@include arabic.all;
-@include sans.all;
-@include mono.all;
-
 :root {
   @include styles.theme(styles.$white, button.$white, tag.$white);
 }

packages/carbon-react/.storybook/theme.js

@@ -33,8 +33,9 @@ export default create({
   appBorderRadius: 0,
 
   // Typography
-  fontBase: '"IBM Plex Sans", sans-serif',
-  fontCode: '"IBM Plex Mono", monospace',
+  fontBase: "'IBM Plex Sans', 'Helvetica Neue', Arial, sans-serif",
+  fontCode:
+    "'IBM Plex Mono', Menlo, 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', Courier, monospace",
 
   // Text colors
   textColor: text01,

packages/carbon-react/README.md

@@ -18,14 +18,30 @@ instead:
 yarn add @carbon/react
 ```
 
-## Usage
+This package requires [Dart Sass](http://npmjs.com/package/sass) in order to
+compile styles.
+
+If you're new to Sass, or are wondering how to configure Sass for your project,
+we recommend checking out the following resources and links:
+
+- [Sass Basics](https://sass-lang.com/guide)
+- [Webpack with Sass](https://webpack.js.org/loaders/sass-loader/)
+- [Next.js with Sass](https://nextjs.org/docs/basic-features/built-in-css-support#sass-support)
+- [Create React App with Sass](https://create-react-app.dev/docs/adding-a-sass-stylesheet/)
+- [Parcel with Sass](https://v2.parceljs.org/languages/sass/)
+- [Vite with Sass](https://vitejs.dev/guide/features.html#css-pre-processors)
+- [Snowpack with Sass](https://www.snowpack.dev/guides/sass/)
 
-**Note: this package is unstable and will change before it's 1.0 release**
+Once you get Sass up and running in your project, configure Sass to include
+`node_modules` in its `includePaths` option. For more information, checkout the
+[configuration](../styles/docs/sass.md#configuration) section in our Sass docs.
+
+## Usage
 
-You can use the `@carbon/react` to bring in components, icons, and styles from
-the Carbon Design System.
+The `@carbon/react` package provides components and icons for the Carbon Design
+System.
 
-To include a component, you can import it:
+To use a component, you can import it directly from the package:
 
 ```jsx
 import { Button } from '@carbon/react';
@@ -35,8 +51,25 @@ function MyComponent() {
 }
 ```
 
-To include an icon, use the `@carbon/react/icons` entrypoint and import it the
-same way you would import a component:
+To include the styles for a specific component, you can either import all the
+styles from the project or include the styles for a specific component:
+
+```scss
+// Bring in all the styles for Carbon
+@use '@carbon/react';
+
+// Preferred: bring in the styles for one component
+@use '@carbon/react/scss/components/button';
+```
+
+For a full list of components available, checkout our
+[Storybook](https://carbon-react-next.netlify.app/).
+
+### Icons
+
+The `@carbon/react` package also provides icon components that you can include
+in your project. You can import these icon components from the
+`@carbon/react/icons` entrypoint:
 
 ```jsx
 import { Add } from '@carbon/react/icons';
@@ -46,21 +79,15 @@ function MyComponent() {
 }
 ```
 
-For styles, you can bring them in using Sass Modules:
-
-```jsx
-@use '@carbon/react';
-```
-
-Note: you will need to configure Sass in order to correctly find modules in your
-`node_modules`. Follow [this guide](./docs/sass.md#configuration) to make sure
-your project is setup correctly.
+For a full list of icons available, checkout our
+[website](https://www.carbondesignsystem.com/guidelines/icons/library/).
 
 ## 📖 API Documentation
 
 If you're looking for `@carbon/react` API documentation, check out:
 
-- [Sass](./docs/sass.md)
+- [Storybook](https://carbon-react-next.netlify.app/)
+- [Icon Library](https://www.carbondesignsystem.com/guidelines/icons/library/).
 
 ## 🙌 Contributing
 

packages/carbon-react/index.scss

@@ -5,7 +5,4 @@
 // LICENSE file in the root directory of this source tree.
 //
 
-@forward '@carbon/styles' with (
-  $css--font-face: false,
-  $css--default-type: false,
-);
+@forward '@carbon/styles';