Skip to content

Commit 10b478c

Browse files
committed
docs(guides): create Guides docs, starting by Design Tokens and Cascade Layers
1 parent 63bc656 commit 10b478c

File tree

6 files changed

+240
-0
lines changed

6 files changed

+240
-0
lines changed

packages/next-docs/pages/_meta.json

+4
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@
33
"title": "Home",
44
"type": "page"
55
},
6+
"guides": {
7+
"title": "Guides",
8+
"type": "page"
9+
},
610
"components": {
711
"title": "Components",
812
"type": "page"
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"styling": "Styling"
3+
}
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"introduction": "Introduction",
3+
"design-tokens": "Design Tokens",
4+
"cascade-layers": "Cascade Layers"
5+
}
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Cascade Layers
2+
3+
Rules within a [cascade layer cascade together](<(https://developer.mozilla.org/en-US/docs/Web/CSS/@layer)>), giving more control over the cascade to web developers. Any styles not in a layer are gathered together and placed into a single anonymous layer that comes after all the declared layers, named and anonymous. This means that any styles declared outside of a layer will override styles declared in a layer, regardless of specificity.
4+
5+
## Core layers
6+
7+
Shoreline has four layers: reset, base, tokens, and components.
8+
9+
### reset
10+
11+
Reserved for CSS resets.
12+
13+
```css
14+
@layer sl-reset {
15+
*,
16+
*::before,
17+
*::after {
18+
box-sizing: border-box;
19+
}
20+
21+
body {
22+
line-height: 1.5;
23+
-webkit-font-smoothing: antialiased;
24+
}
25+
/* ... */
26+
}
27+
```
28+
29+
### base
30+
31+
Reserved for global styles.
32+
33+
```css
34+
@layer sl-base {
35+
body {
36+
font-family: system-ui;
37+
}
38+
/* ... */
39+
}
40+
```
41+
42+
### tokens
43+
44+
Declare both tokens and semantic tokens.
45+
46+
```css
47+
@layer sl-tokens {
48+
:root {
49+
--sl-bg-primary: black;
50+
}
51+
/* ... */
52+
}
53+
```
54+
55+
### components
56+
57+
Components exported by Shoreline.
58+
59+
```css
60+
@layer sl-components {
61+
[data-sl-button] {
62+
cursor: pointer;
63+
background: var(--sl-bg-action-primary);
64+
65+
& :hover {
66+
background: var(--sl-bg-action-primary-hover);
67+
}
68+
}
69+
/* ... */
70+
}
71+
```
72+
73+
## Priority
74+
75+
The layers follow the priority:
76+
77+
- `sl-components` (Highest)
78+
- `sl-tokens`
79+
- `sl-base`
80+
- `sl-reset` (Lowest)
81+
82+
The CSS style is:
83+
84+
```css
85+
@layer sl-reset, sl-base, sl-tokens, sl-components;
86+
```
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
import { Tab, Tabs } from 'nextra-theme-docs'
2+
3+
# Design Tokens
4+
5+
Design tokens abstract and organize design-related values, such as colors, typography, spacing, and other styles, exporting them as reusable variables. They serve as the single source of truth for design properties in a design system. By defining design tokens, designers and developers can ensure consistency across various platforms, applications, and devices.
6+
7+
They are a common language for designers and developers, facilitating seamless collaboration and maintaining a cohesive visual identity throughout a project or organization. By making changes to design tokens, designers can update the entire design system, ensuring a consistent look and feel across all products and interfaces.
8+
9+
## Understanding tokens
10+
11+
### Vendor and Prefix
12+
13+
The vendor is a company or organization that ships a design token specification, in the case of Shoreline, VTEX. The prefix is assigned to avoid conflicts with other tools of libraries that the application can be using. In Shoreline, we adopt the prefix `sl`. This means that every className or design token exported by Shoreline starts with `sl`.
14+
15+
### Token type
16+
17+
A classification is applied to the value of a token. For example:
18+
19+
- color
20+
- radii
21+
- font-size
22+
23+
### Token name
24+
25+
A label assigned to a design decision. For example:
26+
27+
- space-1
28+
- color-blue-100
29+
- border-container
30+
31+
### Token value
32+
33+
A context-specific value is assigned to a design token name.
34+
35+
- `1rem`
36+
- `rgb(142, 142, 142)`
37+
- `1px solid black`
38+
39+
### Variable
40+
41+
Describes the most common way (but not the only way) a design token is formatted and used in code. It can be a CSS custom property, javascript variable, etc. In Shoreline, we rely on [CSS custom properties (aka CSS variables)](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).
42+
43+
CSS variables are declared using the pattern:
44+
45+
```css
46+
--{vendor}-{token-type}-{token-name}
47+
```
48+
49+
And are reused (called) using the pattern:
50+
51+
```css
52+
var({css-variable})
53+
```
54+
55+
So, an example of declaration and usage is:
56+
57+
<Tabs items={['declaration.css', 'usage.css', 'usage.tsx']}>
58+
59+
<Tab>
60+
61+
> We cover `@layer` in detail on the [Cascade Layers](./cascade-layers) page.
62+
63+
```css
64+
@layer sl-tokens {
65+
:root {
66+
--sl-color-blue-100: #b0d7ff;
67+
}
68+
}
69+
```
70+
71+
</Tab>
72+
73+
<Tab>
74+
75+
```css
76+
.my-component {
77+
background-color: 'var(--sl-color-blue-100)',
78+
}
79+
```
80+
81+
</Tab>
82+
83+
<Tab>
84+
85+
```tsx
86+
<div
87+
style={{
88+
backgroundColor: 'var(--sl-color-blue-100)',
89+
}}
90+
/>
91+
```
92+
93+
</Tab>
94+
95+
</Tabs>
96+
97+
### Token alias
98+
99+
Aliases are token values that reference another token. In this example, we alias a color shade of the palette as a semantic background:
100+
101+
```css
102+
:root {
103+
--sl-color-blue-100: #b0d7ff;
104+
--sl-bg-primary: var(--sl-color-blue-100);
105+
}
106+
```
107+
108+
### Composite tokens
109+
110+
Composite design tokens contain values that represent more than one design decision. One example is a border, composed of color, width, and style:
111+
112+
```css
113+
:root {
114+
--sl-color-blue-100: #b0d7ff;
115+
--sl-border-size-1: 0.0625rem;
116+
--sl-border-1: var(--sl-border-size-1) solid var(--sl-color-blue-100);
117+
}
118+
```
119+
120+
Another classic example of composite tokens is typography. In the following example, the token `$text-body` is composed of font size, weight, family, and line-height:
121+
122+
```css
123+
:root {
124+
--sl-font-family: system-ui;
125+
--sl-font-size: 1rem;
126+
--sl-line-height: 1.5;
127+
--sl-font-weight: 400;
128+
129+
--sl-text-body: var(--sl-font-weight) var(--sl-font-size) / var(
130+
--sl-line-height
131+
)
132+
var(--sl-font-family);
133+
}
134+
```
135+
136+
## References
137+
138+
- [Design Tokens Format Model](https://tr.designtokens.org/format/)
139+
- [Design Tokens Glossary](https://www.designtokens.org/glossary/)
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Introduction
2+
3+
🚧

0 commit comments

Comments
 (0)