Skip to content

Commit b80b152

Browse files
joshblackjoshblack
authoredFeb 22, 2022
docs(elements): update v11 migration docs and add Sass API docs (#10624)
* docs(colors): update sass docs * feat(elements): add sass module supports and update sass docs * docs(v11): update colors, elements migration information * docs(colors): update section title to API * docs(v11): update language around sass changes * docs(type): update usage and migration docs for type * docs(themes): update v11 migration guide and usage docs * docs(colors): update sass docs * feat(elements): add sass module supports and update sass docs * docs(v11): update colors, elements migration information * docs(colors): update section title to API * docs(v11): update language around sass changes * docs(type): update usage and migration docs for type * docs(themes): update v11 migration guide and usage docs * docs(type): update usage docs to include type classes * docs(layout): update sass and migration docs * docs(themes): update v11 docs for themes * fix(type): use breakpoint entrypoint * fix(elements): update @forward to hide $prefix
·
v11.95.0v10.54.0-rc.0
1 parent 6ae752c commit b80b152

File tree

14 files changed

+714
-647
lines changed

14 files changed

+714
-647
lines changed
 

‎docs/migration/11.x-color.md‎

Lines changed: 0 additions & 132 deletions
This file was deleted.

‎docs/migration/v11.md‎

Lines changed: 347 additions & 245 deletions
Large diffs are not rendered by default.

‎packages/colors/docs/sass.md‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,11 +32,28 @@ the IBM Design Language using the `$colors` variable.
3232
}
3333
```
3434

35-
Each key in the `$colors` map is the name of a swatch. The value of each entry
36-
is a `Map` where the keys are the grade and the values are the color values for
37-
the swatch at that grade.
35+
Each key in the `$colors` map is the name of a group of colors, also known as a
36+
swatch. The value of each entry is a `Map` where the keys are the color grade
37+
and the values are the hex codes for the color at that grade. For example:
3838

39-
## Exports
39+
```scss
40+
$colors: (
41+
blue: (
42+
10: #edf5ff,
43+
20: #d0e2ff,
44+
30: #a6c8ff,
45+
40: #78a9ff,
46+
50: #4589ff,
47+
60: #0f62fe,
48+
70: #0043ce,
49+
80: #002d9c,
50+
90: #001d6c,
51+
100: #001141,
52+
),
53+
);
54+
```
55+
56+
## API
4057

4158
| Name | Type |
4259
| :--------------------- | :---- |

‎packages/elements/docs/sass.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Sass
2+
3+
> Sass documentation for `@carbon/elements`
4+
5+
## Usage
6+
7+
The `@carbon/elements` package re-exports from other packages that make up the
8+
IBM Design Language. You can import and use this package by writing the
9+
following:
10+
11+
```scss
12+
@use '@carbon/elements';
13+
14+
.selector {
15+
background: elements.$blue-50;
16+
}
17+
```
18+
19+
For more information about what is re-exported, view the documentation for the
20+
individual packages. Each public export from these packages will be available in
21+
`@carbon/elements`.
22+
23+
| Package | README | Sass |
24+
| :--------------- | :----------------------------- | :-------------------------------- |
25+
| `@carbon/colors` | [Link](../../colors/README.md) | [Link](../../colors/docs/sass.md) |
26+
| `@carbon/grid` | [Link](../../grid/README.md) | [Link](../../grid/docs/sass.md) |
27+
| `@carbon/layout` | [Link](../../layout/README.md) | [Link](../../layout/docs/sass.md) |
28+
| `@carbon/motion` | [Link](../../motion/README.md) | [Link](../../motion/docs/sass.md) |
29+
| `@carbon/themes` | [Link](../../themes/README.md) | [Link](../../themes/docs/sass.md) |
30+
| `@carbon/type` | [Link](../../type/README.md) | [Link](../../type/docs/sass.md) |

‎packages/elements/index.scss‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
//
2+
// Copyright IBM Corp. 2018, 2018
3+
//
4+
// This source code is licensed under the Apache-2.0 license found in the
5+
// LICENSE file in the root directory of this source tree.
6+
//
7+
8+
@forward '@carbon/colors';
9+
@forward '@carbon/themes';
10+
@forward '@carbon/layout';
11+
@forward '@carbon/grid' hide $prefix;
12+
@forward '@carbon/type' hide $prefix;
13+
@forward '@carbon/motion';

‎packages/layout/docs/sass.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Sass
2+
3+
> Sass documentation for `@carbon/layout`
4+
5+
## Usage
6+
7+
The `@carbon/layout` package provides spacing tokens and conversion utilities
8+
for the Carbon Design System. You can access these tokens and helpers by writing
9+
the following:
10+
11+
```scss
12+
@use '@carbon/layout';
13+
14+
.selector {
15+
margin-bottom: layout.$spacing-05;
16+
width: layout.rem(24px);
17+
height: layout.rem(24px);
18+
}
19+
```
20+
21+
## API
22+
23+
| Export | Description | !default |
24+
| :------------------ | :---------- | :------- |
25+
| `$spacing-01` | | ✅ |
26+
| `$spacing-02` | | ✅ |
27+
| `$spacing-03` | | ✅ |
28+
| `$spacing-04` | | ✅ |
29+
| `$spacing-05` | | ✅ |
30+
| `$spacing-06` | | ✅ |
31+
| `$spacing-07` | | ✅ |
32+
| `$spacing-08` | | ✅ |
33+
| `$spacing-09` | | ✅ |
34+
| `$spacing-10` | | ✅ |
35+
| `$spacing-11` | | ✅ |
36+
| `$spacing-12` | | ✅ |
37+
| `$spacing-13` | | ✅ |
38+
| `$spacing ` | | |
39+
| `$fluid-spacing-01` | | ✅ |
40+
| `$fluid-spacing-02` | | ✅ |
41+
| `$fluid-spacing-03` | | ✅ |
42+
| `$fluid-spacing-04` | | ✅ |
43+
| `$fluid-spacing ` | | |
44+
| `@function em` | | |
45+
| `@function rem` | | |
46+
| `$base-font-size` | | ✅ |
47+
48+
### Configuration
49+
50+
You can configure parts of the `@carbon/layout` package that are `!default` with
51+
Sass Modules. For example, you can change the `$base-font-size` by writing the
52+
following:
53+
54+
```scss
55+
@use '@carbon/layout' with (
56+
$base-font-size: 18px
57+
);
58+
```

‎packages/layout/index.scss‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,5 @@
55
// LICENSE file in the root directory of this source tree.
66
//
77

8-
@forward 'scss/modules/breakpoint';
98
@forward 'scss/modules/convert';
109
@forward 'scss/modules/spacing';
11-
// TODO: should these be public?
12-
@forward 'scss/modules/utilities';

‎packages/layout/scss/modules/_breakpoint.scss‎

Lines changed: 0 additions & 232 deletions
This file was deleted.

‎packages/motion/docs/sass.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ from the package by writing the following:
2323
}
2424
```
2525

26-
## Exports
26+
## API
2727

2828
| Name | Type |
2929
| :---------------------- | :------- |
@@ -33,6 +33,6 @@ from the package by writing the following:
3333
| `$duration-moderate-02` | Duration |
3434
| `$duration-slow-01` | Duration |
3535
| `$duration-slow-02` | Duration |
36-
| `$easings` | Duration |
36+
| `$easings` | Map |
3737
| `@mixin motion` | Mixin |
3838
| `@function motion` | Mixin |

‎packages/themes/docs/sass.md‎

Lines changed: 110 additions & 15 deletions
Large diffs are not rendered by default.

‎packages/type/docs/sass.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Sass
2+
3+
> Sass documentation for `@carbon/type`
4+
5+
## Usage
6+
7+
The `@carbon/type` package enables you to use typography from the IBM Design
8+
Language, including the type scale and fonts, along with typography design
9+
tokens from the Carbon Design System. It also comes with opinionated defaults
10+
for type styles on common elements like `h1`, `h2`, `p`, etc.
11+
12+
You can use this package by writing the following:
13+
14+
```scss
15+
@use '@carbon/type';
16+
17+
// Include type reset
18+
@include type.reset();
19+
20+
// Include default type styles, targets h1, h2, h3, etc
21+
@include type.default-type();
22+
23+
// Include utility classes for type-related properties
24+
@include type.type-classes();
25+
26+
.selector {
27+
// Include a type style
28+
@include type.style('productive-heading-01');
29+
}
30+
```
31+
32+
### Type classes
33+
34+
The `type-classes` mixin will output a collection of utility CSS that you can
35+
use to style a given HTML element with type-related styles.
36+
37+
In particular, you can use the following classes:
38+
39+
| Class | Description |
40+
| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
41+
| `.cds--type-{font-family}` | Set the `font-family` property for the given font. This can include `mono`, `sans`, `sans-condensed`, `sans-arabic`, `sans-devanagari`, `sans-hebrew`, `sans-jp`, `sans-kr`, `sans-thai-looped`, `sans-thai`, `serif` |
42+
| `.cds--type-{font-weight}` | Set the `font-weight` property |
43+
| `.cds--type-italic` | Set the `font-style` property to `italic` |
44+
| `.cds--type-{token}` | Style the HTML element with the given type token |
45+
46+
## API
47+
48+
| Export | Description | Link | !default |
49+
| :------------------------- | :---------------------------------------------------------------- | :--- | :------- |
50+
| `@mixin type-classes` | A mixin used to emit utility type classes in CSS | | |
51+
| `@mixin reset` | A mixin used to emit base styles for the Carbon Design System | | |
52+
| `@mixin default-type` | A mixin used to emit default styles for typographic HTML elements | | |
53+
| `@mixin type-style` | A mixin used to emit all declarations for a type token | | |
54+
| `$label-01` | | | ✅ |
55+
| `$legal-02` | | | ✅ |
56+
| `$helper-text-01` | | | ✅ |
57+
| `$body-short-01` | | | ✅ |
58+
| `$body-compact-01` | | | ✅ |
59+
| `$body-long-01` | | | ✅ |
60+
| `$body-01` | | | ✅ |
61+
| `$body-short-02` | | | ✅ |
62+
| `$body-compact-02` | | | ✅ |
63+
| `$body-long-02` | | | ✅ |
64+
| `$body-02` | | | ✅ |
65+
| `$code-01` | | | ✅ |
66+
| `$code-02` | | | ✅ |
67+
| `$heading-01` | | | ✅ |
68+
| `$productive-heading-01` | | | ✅ |
69+
| `$heading-compact-01` | | | ✅ |
70+
| `$heading-02` | | | ✅ |
71+
| `$productive-heading-02` | | | ✅ |
72+
| `$heading-compact-02` | | | ✅ |
73+
| `$productive-heading-03` | | | ✅ |
74+
| `$heading-03` | | | ✅ |
75+
| `$productive-heading-04` | | | ✅ |
76+
| `$heading-04` | | | ✅ |
77+
| `$productive-heading-05` | | | ✅ |
78+
| `$heading-05` | | | ✅ |
79+
| `$productive-heading-06` | | | ✅ |
80+
| `$heading-06` | | | ✅ |
81+
| `$productive-heading-07` | | | ✅ |
82+
| `$heading-07` | | | ✅ |
83+
| `$expressive-heading-01` | | | ✅ |
84+
| `$expressive-heading-02` | | | ✅ |
85+
| `$expressive-heading-03` | | | ✅ |
86+
| `$fluid-heading-03` | | | ✅ |
87+
| `$expressive-heading-04` | | | ✅ |
88+
| `$fluid-heading-04` | | | ✅ |
89+
| `$expressive-heading-05` | | | ✅ |
90+
| `$fluid-heading-05` | | | ✅ |
91+
| `$expressive-heading-06` | | | ✅ |
92+
| `$fluid-heading-06` | | | ✅ |
93+
| `$expressive-paragraph-01` | | | ✅ |
94+
| `$fluid-paragraph-01` | | | ✅ |
95+
| `$quotation-01` | | | ✅ |
96+
| `$fluid-quotation-01` | | | ✅ |
97+
| `$quotation-02` | | | ✅ |
98+
| `$fluid-quotation-02` | | | ✅ |
99+
| `$display-01` | | | ✅ |
100+
| `$fluid-display-01` | | | ✅ |
101+
| `$display-02` | | | ✅ |
102+
| `$fluid-display-02` | | | ✅ |
103+
| `$display-03` | | | ✅ |
104+
| `$fluid-display-03` | | | ✅ |
105+
| `$display-04` | | | ✅ |
106+
| `$fluid-display-04` | | | ✅ |
107+
108+
### Configuration
109+
110+
You can configure parts of the `@carbon/type` package with Sass Modules. For
111+
example, you can change the `$prefix` used by writing the following:
112+
113+
```scss
114+
@use '@carbon/type' with (
115+
$prefix: 'custom-prefix',
116+
);
117+
```
118+
119+
For a full list of options that you can configure, check out the table below.
120+
121+
| Option | Description | Default |
122+
| :-------- | :---------------------------------------------------------------- | :------ |
123+
| `$prefix` | The prefix that is used in selectors, CSS Custom Properties, etc. | `'cds'` |

‎packages/type/package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,8 @@
3737
"clean": "rimraf css es lib umd scss/_inlined scss/vendor"
3838
},
3939
"dependencies": {
40-
"@carbon/import-once": "^10.6.0",
41-
"@carbon/layout": "^10.36.0"
40+
"@carbon/grid": "^10.41.0",
41+
"@carbon/import-once": "^10.6.0"
4242
},
4343
"devDependencies": {
4444
"@carbon/cli": "^10.33.0",

‎packages/type/scss/modules/_styles.scss‎

Lines changed: 7 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99

1010
@use 'sass:map';
1111
@use 'sass:math';
12-
@use '@carbon/layout';
12+
@use '@carbon/grid/scss/modules/breakpoint' as grid;
1313
@use 'font-family';
1414
@use 'scale';
1515

@@ -716,7 +716,7 @@ $tokens: (
716716
/// @param {Map} $breakpoints [$grid-breakpoints] - Custom breakpoints to use
717717
/// @access public
718718
/// @group @carbon/type
719-
@mixin fluid-type($type-styles, $breakpoints: layout.$grid-breakpoints) {
719+
@mixin fluid-type($type-styles, $breakpoints: grid.$grid-breakpoints) {
720720
// Include the initial styles for the given token by default without any
721721
// media query guard. This includes `font-size` as a fallback in the case
722722
// that a browser does not support `calc()`
@@ -729,7 +729,7 @@ $tokens: (
729729
// token and apply the properties and fluid type size for that given
730730
// breakpoint
731731
@each $name, $values in map.get($type-styles, breakpoints) {
732-
@include layout.breakpoint($name) {
732+
@include grid.breakpoint($name) {
733733
@include properties($values);
734734
@include fluid-type-size($type-styles, $name, $breakpoints);
735735
}
@@ -745,7 +745,7 @@ $tokens: (
745745
@mixin fluid-type-size(
746746
$type-styles,
747747
$name,
748-
$breakpoints: layout.$grid-breakpoints
748+
$breakpoints: grid.$grid-breakpoints
749749
) {
750750
// Get the information about the breakpoint we're currently working in. Useful
751751
// for getting initial width information
@@ -776,7 +776,7 @@ $tokens: (
776776

777777
// We can use `breakpoint-next` to see if there is another breakpoint we can
778778
// use to update `max-font-size` and `max-vw` with larger values
779-
$next-breakpoint-available: layout.breakpoint-next($name, $breakpoints);
779+
$next-breakpoint-available: grid.breakpoint-next($name, $breakpoints);
780780
$next-fluid-breakpoint-name: null;
781781

782782
// We need to figure out what the next available fluid breakpoint is for our
@@ -788,7 +788,7 @@ $tokens: (
788788
$next-fluid-breakpoint-name: $next-breakpoint-available;
789789
$next-breakpoint-available: null;
790790
} @else {
791-
$next-breakpoint-available: layout.breakpoint-next(
791+
$next-breakpoint-available: grid.breakpoint-next(
792792
$next-breakpoint-available,
793793
$breakpoints
794794
);
@@ -846,11 +846,7 @@ $custom-property-prefix: 'cds' !default;
846846
/// @param {Map} $breakpoints [$grid-breakpoints] - Provide a custom breakpoint map to use
847847
/// @access public
848848
/// @group @carbon/type
849-
@mixin type-style(
850-
$name,
851-
$fluid: false,
852-
$breakpoints: layout.$grid-breakpoints
853-
) {
849+
@mixin type-style($name, $fluid: false, $breakpoints: grid.$grid-breakpoints) {
854850
@if not map.has-key($tokens, $name) {
855851
@error 'Unable to find a token with the name: `#{$name}`';
856852
}

‎yarn.lock‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2258,8 +2258,8 @@ __metadata:
22582258
resolution: "@carbon/type@workspace:packages/type"
22592259
dependencies:
22602260
"@carbon/cli": ^10.33.0
2261+
"@carbon/grid": ^10.41.0
22612262
"@carbon/import-once": ^10.6.0
2262-
"@carbon/layout": ^10.36.0
22632263
"@carbon/test-utils": ^10.21.0
22642264
change-case: ^4.1.1
22652265
rimraf: ^3.0.0

0 commit comments

Comments
 (0)
Please sign in to comment.