Skip to content

Commit

Permalink
docs(project): update to reflect v10 end of support (#17615)
Browse files Browse the repository at this point in the history 
* 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 <[email protected]>

---------

Co-authored-by: Alison Joseph <[email protected]>
  • Loading branch information
@tay1orjones @alisonjoseph
tay1orjones and alisonjoseph authored Sep 30, 2024
1 parent 75001eb commit e5f0b88
Show file tree
Hide file tree
Showing 10 changed files with 192 additions and 148 deletions.
7 changes: 4 additions & 3 deletions .github/CODE_OF_CONDUCT.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
28 changes: 13 additions & 15 deletions .github/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand All @@ -346,22 +347,21 @@ 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.
### 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?
Expand All @@ -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
208 changes: 102 additions & 106 deletions docs/guides/sass.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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/<path-to-file>';

# With webpack
@import '~carbon-components/scss/<path-to-file>';

# With sass config setup to include `node_modules` in paths
@import 'carbon-components/scss/<path-to-file>';
```
> [!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 `<body>` 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 `<body>` 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/<path-to-file>';
```

> [!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
Expand Down Expand Up @@ -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 <ul className={`${prefix}--accordion`}>{props.children}</ul>;
}
```

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
Loading

0 comments on commit e5f0b88

Please sign in to comment.