@carbon/element-styles is an experimental styling system for native HTML elements, relying on semantic, attribute-focused selectors instead of class names. There is no 1:1 parity between Carbon element styles and the core React and Web Component implementations of the Carbon Design System. It's use case is targeted more towards simple web pages and editorial content such as styling markdown documents.
npm i @carbon/element-stylesYou can also use any of the prebuilt stylesheets via our CDN:
<!-- specific version (recommended) -->
<link rel="stylesheet" href="https://1.www.s81c.com/common/carbon/element-styles/version/v[x.y.z]/prebuilt/expressive.css" />
<!-- "latest" tag -->
<link rel="stylesheet" href="https://1.www.s81c.com/common/carbon/element-styles/tag/v0/latest/prebuilt/expressive.css" />
<!-- "next" tag -->
<link rel="stylesheet" href="https://1.www.s81c.com/common/carbon/element-styles/tag/v0/next/prebuilt/expressive.css" />To make use of individual elements, import them via @use and include their styles mixin in your Sass stylesheets:
@use '@carbon/element-styles/scss/elements/button';
@include button.styles;Every element has a default selector on which it's styles are emitted. You can configure this selector, but need to make sure the underlying HTML tag and semantics are kept.
The button element for example expects to be emitted on a <button> tag. By default, it's selector is simply button. If you only want to emit these styles on buttons that are explicitly of type button, you can do so via the with syntax of Sass or each time you include the mixin.
@use '@carbon/element-styles/scss/elements/button' with ($config: (
selector: 'button[type="button"]',
));
@include button.styles;@use '@carbon/element-styles/scss/elements/button';
@include button.styles((
selector: 'button[type="button"]',
));Some elements have additional configuration options to adjust their visual appearance. You can configure these options the same way as you can configure the selector: via the with syntax of Sass or each time you include the mixin:
@use '@carbon/element-styles/scss/elements/button' with ($config: (
kind: 'ghost',
));
@include button.styles;@use '@carbon/element-styles/scss/elements/button';
@include button.styles((
kind: 'ghost',
));Combining these options with custom selectors means you can emit multiple variants of the same element depending on their context:
@use '@carbon/element-styles/scss/elements/button';
@include button.styles;
@include button.styles((
selector: 'button[type="submit"]',
kind: 'primary',
));This library offers several prebuilt (opinionated) stylesheets you can use out-of-the-box:
Includes all available elements with their default selectors. Uses a productive style with medium sized elements. Intended for interaction-heavy pages.
| SCSS | /scss/prebuilt/productive/index.scss |
|---|---|
| CSS | /css/prebuilt/productive.css |
| CDN | https://1.www.s81c.com/common/carbon/element-styles/tag/v0/latest/prebuilt/productive.css |
Includes all available elements with their default selectors. Uses an expressive style with large sized elements. Intended for content-heavy pages such as marketing or documentation.
| SCSS | /scss/prebuilt/expressive/index.scss |
|---|---|
| CSS | /css/prebuilt/expressive.css |
| CDN | https://1.www.s81c.com/common/carbon/element-styles/tag/v0/latest/prebuilt/expressive.css |
Only includes non-interactive elements with their default selectors. Uses an expressive style with large elements. Intended for content-only pages such as blogs and styling raw markdown.
| SCSS | /scss/prebuilt/editorial/index.scss |
|---|---|
| CSS | /css/prebuilt/editorial.css |
| CDN | https://1.www.s81c.com/common/carbon/element-styles/tag/v0/latest/prebuilt/editorial.css |
@carbon/element-styles relies on the tokens defined by @carbon/styles. Therefore, it's not meant to be used standalone but in a container that has emitted a Carbon theme.
Important: in order for button styles to work, you must emit the Carbon's component tokens for buttons. If you're using @carbon/styles that's likely already the case. For convenience, this library also provides an emit-carbon-tokens mixin which includes the necessary component tokens.
@use '@carbon/element-styles';
:root {
@include element-styles.emit-carbon-tokens('white');
}To also generate CSS custom properties of all available colors, use the emit-carbon-colors mixin:
@use '@carbon/element-styles';
:root {
@include element-styles.emit-carbon-colors;
}
/**
* ↪ :root {
* --cds-black-100: #000000;
* --cds-blue-10: #edf5ff;
* --cds-blue-20: #d0e2ff;
* …
* }
*/All elements are built on contextual layout tokens that define properties like size and density. You can specify these layout tokens for individual parts of your page.
Density
Controls the density of elements, mostly through inline padding.
condensednormal(default)
$density--padding
@use '@carbon/element-styles/scss/layout';
:root {
@include layout.density('condensed');
}
.callout {
padding: layout.$density--padding;
}Mode
Controls the overall visual impression through font sizes and spacings.
productive(default)expressive
$mode--max-inline-size$mode--margin-block$mode--transition-duration$mode--transition-timing-function
mode--bodymode--body-compactmode--headingmode--heading-compactmode--labelmode--helper-textmode--codemode--quotationmode--heading-level-1mode--heading-level-2mode--heading-level-3mode--heading-level-4mode--heading-level-5mode--heading-level-6
@use '@carbon/element-styles/scss/layout';
:root {
@include layout.mode('expressive');
}
.callout {
margin-block: layout.$mode--margin-block;
}
.callout header {
@include layout.mode--heading-compact;
}Size
Controls the height of elements.
xssmmd(default)lgxl
$size--block-size$size--padding-block-start$size--padding-block-end
@use '@carbon/element-styles/scss/layout';
:root {
@include layout.size('lg');
}
.callout header {
block-size: layout.$size--block-size;
}The goal of this library is to provide opinionated styles for native HTML elements and ARIA patterns. Several components from the core Carbon libraries are intentionally missing from this project due to a lack of matching native counterparts. The intent is to not rely on class names or special attributes.
However, there is one exception to this: the tile element. Tiles are one of the most fundamental and widely used components in Carbon. The default selector for tile styles is [data-tile].
Layout decisions that should be consistent across multiple elements are not the responsibility of those elements. Rather, their parent layout (page or zone) should control aspects like the size, density, and overall apperance.
Not every element in this library is fully compatible with all major browsers yet. This project intentionally uses some of the latest features available to some browsers in order to validate whether they are suitable to support current and upcoming concepts of the Carbon Design System.
Licensed under the Apache 2.0 license.
This package uses IBM Telemetry to collect de-identified and anonymized metrics data. By installing this package as a dependency you are agreeing to telemetry collection. To opt out, see Opting out of IBM Telemetry data collection. For more information on the data being collected, please see the IBM Telemetry documentation.