From e5f0b8818861519be16064f2303a0f9563496647 Mon Sep 17 00:00:00 2001 From: Taylor Jones Date: Mon, 30 Sep 2024 16:38:33 -0500 Subject: [PATCH] docs(project): update to reflect v10 end of support (#17615) * docs(project): update to reflect v10 end of support * docs(storybook): update welcome page links * chore: update blockquote formatting * Apply suggestions from code review Co-authored-by: Alison Joseph --------- Co-authored-by: Alison Joseph --- .github/CODE_OF_CONDUCT.md | 7 +- .github/CONTRIBUTING.md | 28 ++- docs/guides/sass.md | 208 +++++++++--------- docs/migration/v11.md | 48 +++- docs/release.md | 11 +- packages/carbon-components-react/README.md | 6 + packages/carbon-components-react/package.json | 2 +- packages/carbon-components/README.md | 6 + packages/carbon-components/package.json | 6 +- packages/react/.storybook/Welcome/Welcome.js | 18 +- 10 files changed, 192 insertions(+), 148 deletions(-) diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index 73c9da00d2e2..1740af75b250 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -89,9 +89,10 @@ members of the project's leadership. with the same questions can benefit. 4. If you have a pressing bug fix, it is best to make a PR directly to get your issues addressed. -5. `#carbon-components`: This channel is for questions about Carbon Components - only. It is not the place to ask general coding questions. Instead, use a - dev community like [StackOverflow](https://stackoverflow.com/). +5. `#carbon-react`, `#carbon-web-components`: These channels are for questions + about Carbon Components only. They are not the place to ask general coding + questions. Instead, use a dev community like + [StackOverflow](https://stackoverflow.com/). 6. `#carbon-design-system`: Please post any design questions with an in-context screen shot (i.e. screen shot of the whole UI you are designing) with background as to what you are trying to accomplish in this flow. We welcome diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index fc943453562f..c4b3ea0bad12 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -317,20 +317,21 @@ Here are some contribution quick tips: ### What projects can I contribute to? -- [`carbon-components`](https://github.com/carbon-design-system/carbon/tree/main/packages/components) -- [`carbon-components-react`](https://github.com/carbon-design-system/carbon/tree/main/packages/react) +- [`@carbon/styles`](https://github.com/carbon-design-system/carbon/tree/main/packages/styles) +- [`@carbon/react`](https://github.com/carbon-design-system/carbon/tree/main/packages/react) +- [`@carbon/web-components`](https://github.com/carbon-design-system/carbon/tree/main/packages/web-components) - [`carbon-website`](https://github.com/carbon-design-system/carbon-website) - [`gatsby-theme-carbon`](https://github.com/carbon-design-system/gatsby-theme-carbon) - [`carbon-design-kit`](https://github.com/carbon-design-system/carbon-design-kit) - [`@carbon/elements`](https://github.com/carbon-design-system/carbon/tree/main/packages/elements) -- [`@carbon/type`](https://github.com/carbon-design-system/carbon/tree/main/packages/type) - [`@carbon/colors`](https://github.com/carbon-design-system/carbon/tree/main/packages/colors) - [`@carbon/grid`](https://github.com/carbon-design-system/carbon/tree/main/packages/grid) - [`@carbon/icons`](https://github.com/carbon-design-system/carbon/tree/main/packages/icons) +- [`@carbon/icons-react`](https://github.com/carbon-design-system/carbon/tree/main/packages/icons-react) - [`@carbon/layout`](https://github.com/carbon-design-system/carbon/tree/main/packages/layout) - [`@carbon/motion`](https://github.com/carbon-design-system/carbon/tree/main/packages/motion) - [`@carbon/themes`](https://github.com/carbon-design-system/carbon/tree/main/packages/themes) -- [`@carbon/icons-react`](https://github.com/carbon-design-system/carbon/tree/main/packages/icons-react) +- [`@carbon/type`](https://github.com/carbon-design-system/carbon/tree/main/packages/type) And more! You can view a complete list of our packages [here](https://github.com/carbon-design-system/carbon/tree/main/packages). @@ -346,9 +347,8 @@ work: best to answer questions on slack, it's not always possible to answer everything. One of the easiest ways to help us it to jump in on slack conversations if there's something you know the answer to! Some of our most - popular slack channels include `#carbon-components`, `#carbon-react`, - `#carbon-design-system`, `#carbon-ng`, `#carbon-vue`, `#carbon-announcements`, - `#carbon-community-components`. + popular slack channels include `#carbon-react`, `#carbon-web-components`, + `#carbon-design-system`, `#carbon-ng`, `#carbon-vue`, `#carbon-announcements`. - **Report bugs.** Even if you don't have the time to contribute a bug fix, opening an issue alone makes a big difference! Be sure to completely fill out the issue template to best help us understand what is going wrong. @@ -356,12 +356,12 @@ work: ### If I'm contributing code, am I required to contribute it for all frameworks? If you've been working with Carbon for a while, you know that we have code -assets in multiple frameworks. While the core team only maintains the React -components, we work closely with the other framework teams to maintain parity. -If you're contributing a bug fix in a framework other than React for a component -which also exists in the React version, you can either contribute a fix for the -React version as well or open an issue so that we can update the React component -accordingly. +assets in multiple frameworks. While the core team only maintains the React and +Web Component implementations, we work closely with the other framework teams to +maintain parity. If you're contributing a bug fix in a framework other than +React for a component which also exists in the React and Web Components version, +you can either contribute a fix for the that version as well or open an issue so +that we can update the component accordingly. ### How can I test-drive components or provide a bug reproduction? @@ -382,5 +382,3 @@ services: - [`@carbon/react` template](https://codesandbox.io/s/github/carbon-design-system/carbon/tree/v11.2.0/examples/codesandbox) - [`@carbon/styles` template](https://codesandbox.io/s/github/carbon-design-system/carbon/tree/v11.2.0/examples/codesandbox-styles) -- [`carbon-components-react` template](https://codesandbox.io/s/github/carbon-design-system/carbon/tree/v10/packages/react/examples/codesandbox), - configured to use v10.x assets diff --git a/docs/guides/sass.md b/docs/guides/sass.md index 55e70cdab6eb..c816b1a282f7 100644 --- a/docs/guides/sass.md +++ b/docs/guides/sass.md @@ -16,113 +16,135 @@ ## Overview -The `carbon-components` package ships all of the styles for the Carbon Design -System as Sass files in the `scss` folder. You can import this file directly -through either of the following paths: +The `@carbon/styles` package ships all of the styles for the Carbon Design +System. -```scss -# Specifying node_modules directly -@import 'node_modules/carbon-components/scss/'; - -# With webpack -@import '~carbon-components/scss/'; - -# With sass config setup to include `node_modules` in paths -@import 'carbon-components/scss/'; -``` +> [!IMPORTANT] +> You probably don't need to install this package. Framework variant packages +> such as `@carbon/react` re-export all of `@carbon/styles`. For the examples +> below `@carbon/styles` paths can be switched out for `@carbon/react` without +> issue. -There are two folders in this `scss` folder: +`@carbon/styles` uses the sass module system. We recommend taking a look through +the [announcement](https://sass-lang.com/blog/the-module-system-is-launched/) +and [documentation](https://sass-lang.com/documentation/at-rules/use/) to +familiarize yourself with this. `@use` is quite +[different than `@import`](https://sass-lang.com/documentation/at-rules/use/#differences-from-import), +particularly as it relates to the previous concept of `globals` in the v10.x +styles. -- `components`: which contain component-specific styles and mixins -- `globals`: which contain files that effect global settings like color, type, - grid, and more - -To quickly get started, you can import `styles.scss` which contains all of the -styles for the Carbon Design System. You can import this using the following -path: +To get started, just `@use` the package. ```scss -@import 'carbon-components/scss/globals/scss/styles.scss'; +@use '@carbon/styles'; ``` -_Note: the `styles.scss` will include all styles for the Carbon Design System, -even if you are not using all of its components, to learn how to optimize this -import check out [Optimizing your Sass builds](#optimizing-your-sass-builds)._ +This will include all the styles for the Carbon Design System, even if you're +not using all of it's components. If desired, you can +[optimize your Sass builds](#optimizing-your-sass-builds) to include only the +relevant modules you need. If you would like to a see a full overview of the functionality we ship in Sass, in particular our public API, you should checkout our published -[SassDoc](../../packages/components/docs/sass.md). +[SassDoc](../../packages/styles/docs/sass.md). -## Global flags +## Config variables -The Carbon Design System sass setup specifies a number of global flags that you -can configure before importing Carbon's sass files to enable or disable -different behaviors. To enable these flags, you will need to set them before -importing any styles from Carbon. For example: +The Carbon Design System sass setup specifies a number of config variables +(previously called "global flags") that you can configure via the `with` syntax. +For example: ```scss -$css--reset: false; -@import 'carbon-components/scss/globals/scss/styles.scss'; +@use '@carbon/styles' with ( + $font-path: '@ibm/plex' +); ``` -For a full reference of flags, see the table below. - -| Global flag | Description | Default value | -| ----------------- | -------------------------------------------------------------------- | ------------- | -| `$css--font-face` | Includes the font-face mixins for the current font family (IBM Plex) | `true` | -| `$css--helpers` | Includes classes and utilities that are commonly used by components | `true` | -| `$css--body` | Sets a top-level reset, type style, and color for the `` tag | `true` | -| `$css--use-layer` | Enables use of box-shadow in `layer()` helpers | `true` | -| `$css--reset` | Includes a top-level CSS Reset | `true` | +For a full reference of config variables, see the table below. + +| Global flag | Description | Default value | +| -------------------- | ------------------------------------------------------------------------------------ | ------------- | +| `$css--body` | Sets a top-level reset, type style, and color for the `` tag | `true` | +| `$css--font-face` | Includes the font-face mixins for IBM Plex | `true` | +| `$css--reset` | Includes a top-level CSS Reset | `true` | +| `$css--default-type` | Includes default type styles for a handful of elements (`h1`, etc) | `true` | +| `$font-display` | Specify the default value for the `font-display` property used for fonts | `swap` | +| `$font-path` | Specify the base path for loading IBM Plex. When using Vite, set this to `@ibm/plex` | `~@ibm/plex` | +| `$use-akamai-cdn` | Specify if IBM Plex should be provided by the IBM Akamai CDN | `false` | +| `$prefix` | Specify the value used to prefix all selectors and CSS Custom Properties | `cds` | +| `$use-flexbox-grid` | Specify if the flexbox grid styles should be emitted | `false` | +| `$flex-grid-columns` | Specify the total columns to be used in the flex grid | `16` | ## Feature flags The Carbon Design System takes advantage of feature flags to conditionally -enable or disable new features that are being introduced to the system. To -configure feature flags, you will need to update the `$feature-flags` map before -importing any sass files from Carbon. For example: +enable or disable new features that are being introduced to the system. You can +enable feature flags in any of your stylesheets. Most often this is done at the +root/entrypoint stylesheet. ```scss -$feature-flags: ( - grid-columns-16: true, +@use '@carbon/styles/scss/feature-flags' with ( + $feature-flags: ( + 'enable-experimental-tile-contrast': true, + ) ); -@import 'carbon-components/scss/globals/scss/styles.scss'; +@use '@carbon/styles'; +``` + +Feature flags can also be enabled via the provided `enable()` mixin + +```scss +@use '@carbon/styles/scss/feature-flags'; +@use '@carbon/styles'; + +@include feature-flags.enable('enable-experimental-tile-contrast'); ``` ## Optimizing your Sass builds If you are looking to optimize the CSS that is output by including the Carbon -Design System, you can take advantage of the fact that every partial in Carbon's -package can be compiled independently. Using this feature, you can mirror the -structure of the default `styles.scss` file to include only the component styles -that you need. +Design System, you can take advantage of the fact that every module in +`@carbon/styles` package can be compiled independently. Using the sass module +system, when `@use`ing a single file, all required dependent modules will be +included as well. -At a high-level, this would look like: +To use only a specific module, include the full path. ```scss -// Your entrypoint for including sass files from Carbon -$css--font-face: true; -$css--helpers: true; -$css--body: true; -$css--use-layer: true; -$css--reset: true; -$css--default-type: true; -$css--plex: true; - -// Include defaults typically provided through the `styles.scss` entrypoint -@import 'carbon-components/scss/globals/scss/_css--reset.scss'; -@import 'carbon-components/scss/globals/scss/_css--font-face.scss'; -@import 'carbon-components/scss/globals/scss/_css--helpers.scss'; -@import 'carbon-components/scss/globals/scss/_css--body.scss'; - -// Optionally include the grid -@import 'carbon-components/scss/globals/grid/_grid.scss'; +@use '@carbon/styles/scss/'; +``` + +> [!NOTE] +> Sass modules can only ever be configured once. Bringing in this module and +> configuring it should be one of the first things you do in your project. +> +> As such, when configuring or using multiple modules, `@use '@carbon/styles';` +> should always come last in the `@use` order. + +More broadly, you can mirror the default entrypoint configuration to include +only the component styles that you need. At a high-level, this would look like: + +```scss +// Use the config module to set config variables +@use '@carbon/styles/scss/config' with ( + $prefix: 'cds' +); + +// Include prerequisite modules typically provided through the main entrypoint +@use '@carbon/styles/scss/reset'; +@use '@carbon/styles/scss/grid'; +@use '@carbon/styles/scss/layer'; +@use '@carbon/styles/scss/themes'; +@use '@carbon/styles/scss/theme'; // Optionally include components that you need -@import 'carbon-components/scss/components/button/button'; -@import 'carbon-components/scss/components/file-uploader/file-uploader'; +@use '@carbon/styles/scss/components/button'; ``` +In this example, because `button` relies on +[a number of additional modules](https://github.com/carbon-design-system/carbon/blob/main/packages/styles/scss/components/button/_button.scss#L8-L22), +all of these will be included in the final compiled output. + ## Prefixes Style selectors that are a part of the sass files for Carbon are built using a @@ -150,44 +172,18 @@ the future if this value changes or if the prefix is overridden. ### Overriding `$prefix` In order to override `$prefix` to your own custom prefix, you will need to set -`$prefix` before importing any styles from Carbon. For example: +`$prefix`. For example: ```scss -// Custom prefix -$prefix: 'ibm'; - -// Import Carbon -@import 'path-to-carbon'; +@use '@carbon/styles' with ( + $prefix: 'my-prefix' +); ``` In addition, if you're using any of the JavaScript packages that Carbon ships, -you'll want to update the `prefix` setting available in `carbon-components`. -This setting is used in JavaScript files to make sure that components use the -correct prefix for class names. For example: - -```jsx -import { settings } from 'carbon-components'; -import React from 'react'; - -const { prefix } = settings; - -function Accordion(props) { - return
    {props.children}
; -} -``` - -Settings from Carbon are available from the `settings` named export. You can -mutate this value before including any references to other packages (like -`carbon-components-react`) in order to change `prefix` across - -```js -import { settings } from 'carbon-components'; -// Set custom prefix, should match what is set in Sass -settings.prefix = 'cds'; -``` - -**Note:** it's important that this is included as one of the first modules -initialized in your project. We recommend having this be one of the first -imports in your entrypoint as a result. +you'll want to update the `prefix` there as well. For instance, in +`@carbon/react` the +[ClassPrefix](https://react.carbondesignsystem.com/?path=/docs/components-classprefix--overview) +component is available for this use. ## FAQ diff --git a/docs/migration/v11.md b/docs/migration/v11.md index 4173c4074679..cfc63f448f73 100644 --- a/docs/migration/v11.md +++ b/docs/migration/v11.md @@ -26,14 +26,22 @@ migration. ## carbon-components -In v10, the `carbon-components` package ships Sass styles and Vanilla JavaScript -for components in our Design System. Starting in v11, we will split our styles -into a dedicated package: `@carbon/styles`. In addition, we will no longer -support the Vanilla JavaScript for our components. +`carbon-components` reached it's end of support on September 30, 2024. This +package will no longer receive updates. + +`carbon-components` is replaced by `@carbon/styles`, but most projects don't +need to install `@carbon/styles` directly. + +If you're using `@carbon/react` or `@carbon/web-components`, you do not need to +install `@carbon/styles`. All `@carbon/styles` assets are already available to +you through those framework-specific packages. + +Library authors should use `@carbon/styles` if they do not already rely on a +framework-variant package such as `@carbon/react`. ### Changing from `node-sass` to `sass` -Along with this change, the styles of Carbon have been completely updated to use +The styles of Carbon have been completely updated to use [Sass Modules](https://css-tricks.com/introducing-sass-modules/). This change requires that teams use the [Dart Sass](https://npmjs.com/package/sass) package. Support for `node-sass` has been dropped starting in v11. @@ -643,12 +651,11 @@ and we can help you migrate from the following list of files: ## carbon-components-react The `carbon-components-react` package has been replaced by the `@carbon/react` -package in v11. While you can still use `carbon-components-react` along with -v11, it has been deprecated and will stop receiving updates when v12 is -released. +package in v11. `carbon-components-react` reached it's end of support on +September 30, 2024. This package will no longer receive updates. -In addition, this release contains updates to React components in the package. -These updates include: +In addition, v11 contains updates to React components in the package. These +updates include: - Changing components from class components to functional components - Creating consistent prop names and types across components @@ -1550,6 +1557,9 @@ const iconTypes = { ## @carbon/colors +The v10.x versions of this package reached end of support on September 30, 2024 +and will not receive any more updates. + **Breaking changes** - This package now requires Dart Sass and uses Sass Modules @@ -1594,6 +1604,9 @@ For full Sass API documentation, visit the ## @carbon/elements +The v10.x versions of this package reached end of support on September 30, 2024 +and will not receive any more updates. + **Breaking changes** - This package now requires Dart Sass and uses Sass Modules @@ -1625,6 +1638,9 @@ For full Sass API documentation, visit the ## @carbon/grid +The v10.x versions of this package reached end of support on September 30, 2024 +and will not receive any more updates. + | v10 | v11 | | :---------------------------------- | :--------------------------------- | | `@import '@carbon/grid/scss/grid';` | `@use '@carbon/grid';` | @@ -1659,6 +1675,9 @@ For full documentation, visit the ## @carbon/layout +The v10.x versions of this package reached end of support on September 30, 2024 +and will not receive any more updates. + **Breaking changes** - This package now requires Dart Sass and uses Sass Modules @@ -1764,6 +1783,9 @@ For full documentation, visit the ## @carbon/motion +The v10.x versions of this package reached end of support on September 30, 2024 +and will not receive any more updates. + **Breaking changes** - This package now requires Dart Sass and uses Sass Modules @@ -1802,6 +1824,9 @@ For full documentation, visit the ## @carbon/themes +The v10.x versions of this package reached end of support on September 30, 2024 +and will not receive any more updates. + **Breaking changes** - This package now requires Dart Sass and uses Sass Modules @@ -2038,6 +2063,9 @@ compatibility theme for `$g100` as the `$fallback. ## @carbon/type +The v10.x versions of this package reached end of support on September 30, 2024 +and will not receive any more updates. + **Breaking changes** - This package now requires Dart Sass and uses Sass Modules diff --git a/docs/release.md b/docs/release.md index 009ad26822ab..87988cad4710 100644 --- a/docs/release.md +++ b/docs/release.md @@ -341,10 +341,13 @@ cases, follow these steps below to ensure a proper patch release: ## Previous releases (v10) -We currently support the current and previous major version of the Design -System. While the current major version will receive features and bug fixes, the -previous major version will only receive bug fixes along with any critical -security updates. +From the initial v11 release in March 2022 until September 30, 2024 we supported +the previous major version of the Design System (v10). During this time v10 only +received bug fixes when requested, and critical security updates. All v10 code +and assets reached end of support on September 30, 2024. + +The content below relating to the v10 release process is only kept here for +posterity and should be removed from this document in the next major release. ### How to determine if the previous major version needs to be released diff --git a/packages/carbon-components-react/README.md b/packages/carbon-components-react/README.md index 9e706a92c0df..4064107a0201 100644 --- a/packages/carbon-components-react/README.md +++ b/packages/carbon-components-react/README.md @@ -2,6 +2,12 @@ > React components for the Carbon Design System +> [!CAUTION] +> `carbon-components-react` is deprecated and will not receive any more updates. +> +> More information is available on our +> [website](https://www.carbondesignsystem.com/deprecations) + ## Getting started To install `carbon-components-react` in your project, you will need to run the diff --git a/packages/carbon-components-react/package.json b/packages/carbon-components-react/package.json index cddf76a2a277..ed3051e6f5a6 100644 --- a/packages/carbon-components-react/package.json +++ b/packages/carbon-components-react/package.json @@ -1,6 +1,6 @@ { "name": "carbon-components-react", - "description": "The Carbon Design System is IBM’s open-source design system for products and experiences.", + "description": "The Carbon Design System is IBM’s open-source design system for products and experiences. This package reached end of support on September 30, 2024 and will not receive any more updates.", "version": "8.67.0", "license": "Apache-2.0", "main": "lib/index.js", diff --git a/packages/carbon-components/README.md b/packages/carbon-components/README.md index b92f7fb21bef..4997a9029c62 100644 --- a/packages/carbon-components/README.md +++ b/packages/carbon-components/README.md @@ -2,6 +2,12 @@ > Styles for the Carbon Design System +> [!CAUTION] +> `carbon-components` is deprecated and will not receive any more updates. +> +> More information is available on our +> [website](https://www.carbondesignsystem.com/deprecations) + ## Getting started To install `carbon-components` in your project, you will need to run the diff --git a/packages/carbon-components/package.json b/packages/carbon-components/package.json index a012478d07d8..0706a30e6a70 100644 --- a/packages/carbon-components/package.json +++ b/packages/carbon-components/package.json @@ -1,6 +1,6 @@ { "name": "carbon-components", - "description": "The Carbon Design System is IBM’s open-source design system for products and experiences.", + "description": "The Carbon Design System is IBM’s open-source design system for products and experiences. This package reached end of support on September 30, 2024 and will not receive any more updates.", "version": "11.66.0", "license": "Apache-2.0", "repository": { @@ -8,8 +8,8 @@ "url": "https://github.com/carbon-design-system/carbon.git", "directory": "packages/components" }, - "bugs": "https://github.com/carbon-design-system/carbon/issues", - "homepage": "https://www.carbondesignsystem.com/", + "bugs": "https://www.carbondesignsystem.com/deprecated", + "homepage": "https://www.carbondesignsystem.com/deprecated", "files": [ "scss/**/*", "index.scss", diff --git a/packages/react/.storybook/Welcome/Welcome.js b/packages/react/.storybook/Welcome/Welcome.js index 49ced6ee6d5d..2726da3271d3 100644 --- a/packages/react/.storybook/Welcome/Welcome.js +++ b/packages/react/.storybook/Welcome/Welcome.js @@ -25,22 +25,28 @@ export const Welcome = () => {

{`v${PackageInfo.version}`}

- v10 Storybook + Website - v10 website + GitHub repo - GitHub repo + Release schedule + + + Security policy