Ceate Guides docs, starting by Design Tokens and Cascade Layers

packages/next-docs/pages/_meta.json

@@ -3,6 +3,10 @@
     "title": "Home",
     "type": "page"
   },
+  "guides": {
+    "title": "Guides",
+    "type": "page"
+  },
   "components": {
     "title": "Components",
     "type": "page"

packages/next-docs/pages/guides/_meta.json

@@ -0,0 +1,3 @@
+{
+  "styling": "Styling"
+}

packages/next-docs/pages/guides/styling/_meta.json

@@ -0,0 +1,5 @@
+{
+  "introduction": "Introduction",
+  "design-tokens": "Design Tokens",
+  "cascade-layers": "Cascade Layers"
+}

packages/next-docs/pages/guides/styling/cascade-layers.mdx

@@ -0,0 +1,86 @@
+# Cascade Layers
+
+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.
+
+## Core layers
+
+Shoreline has four layers: reset, base, tokens, and components.
+
+### reset
+
+Reserved for CSS resets.
+
+```css
+@layer sl-reset {
+  *,
+  *::before,
+  *::after {
+    box-sizing: border-box;
+  }
+
+  body {
+    line-height: 1.5;
+    -webkit-font-smoothing: antialiased;
+  }
+  /* ... */
+}
+```
+
+### base
+
+Reserved for global styles.
+
+```css
+@layer sl-base {
+  body {
+    font-family: system-ui;
+  }
+  /* ... */
+}
+```
+
+### tokens
+
+Declare both tokens and semantic tokens.
+
+```css
+@layer sl-tokens {
+  :root {
+    --sl-bg-primary: black;
+  }
+  /* ... */
+}
+```
+
+### components
+
+Components exported by Shoreline.
+
+```css
+@layer sl-components {
+  [data-sl-button] {
+    cursor: pointer;
+    background: var(--sl-bg-action-primary);
+
+    & :hover {
+      background: var(--sl-bg-action-primary-hover);
+    }
+  }
+  /* ... */
+}
+```
+
+## Priority
+
+The layers follow the priority:
+
+- `sl-components` (Highest)
+- `sl-tokens`
+- `sl-base`
+- `sl-reset` (Lowest)
+
+The CSS style is:
+
+```css
+@layer sl-reset, sl-base, sl-tokens, sl-components;
+```

packages/next-docs/pages/guides/styling/design-tokens.mdx

@@ -0,0 +1,139 @@
+import { Tab, Tabs } from 'nextra-theme-docs'
+
+# Design Tokens
+
+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.
+
+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.
+
+## Understanding tokens
+
+### Vendor and Prefix
+
+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`.
+
+### Token type
+
+A classification is applied to the value of a token. For example:
+
+- color
+- radii
+- font-size
+
+### Token name
+
+A label assigned to a design decision. For example:
+
+- space-1
+- color-blue-100
+- border-container
+
+### Token value
+
+A context-specific value is assigned to a design token name.
+
+- `1rem`
+- `rgb(142, 142, 142)`
+- `1px solid black`
+
+### Variable
+
+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).
+
+CSS variables are declared using the pattern:
+
+```css
+--{vendor}-{token-type}-{token-name}
+```
+
+And are reused (called) using the pattern:
+
+```css
+var({css-variable})
+```
+
+So, an example of declaration and usage is:
+
+<Tabs items={['declaration.css', 'usage.css', 'usage.tsx']}>
+
+<Tab>
+
+> We cover `@layer` in detail on the [Cascade Layers](./cascade-layers) page.
+
+```css
+@layer sl-tokens {
+  :root {
+    --sl-color-blue-100: #b0d7ff;
+  }
+}
+```
+
+</Tab>
+
+<Tab>
+
+```css
+.my-component {
+  background-color: 'var(--sl-color-blue-100)',
+}
+```
+
+</Tab>
+
+<Tab>
+
+```tsx
+<div
+  style={{
+    backgroundColor: 'var(--sl-color-blue-100)',
+  }}
+/>
+```
+
+</Tab>
+
+</Tabs>
+
+### Token alias
+
+Aliases are token values that reference another token. In this example, we alias a color shade of the palette as a semantic background:
+
+```css
+:root {
+  --sl-color-blue-100: #b0d7ff;
+  --sl-bg-primary: var(--sl-color-blue-100);
+}
+```
+
+### Composite tokens
+
+Composite design tokens contain values that represent more than one design decision. One example is a border, composed of color, width, and style:
+
+```css
+:root {
+  --sl-color-blue-100: #b0d7ff;
+  --sl-border-size-1: 0.0625rem;
+  --sl-border-1: var(--sl-border-size-1) solid var(--sl-color-blue-100);
+}
+```
+
+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:
+
+```css
+:root {
+  --sl-font-family: system-ui;
+  --sl-font-size: 1rem;
+  --sl-line-height: 1.5;
+  --sl-font-weight: 400;
+
+  --sl-text-body: var(--sl-font-weight) var(--sl-font-size) / var(
+      --sl-line-height
+    )
+    var(--sl-font-family);
+}
+```
+
+## References
+
+- [Design Tokens Format Model](https://tr.designtokens.org/format/)
+- [Design Tokens Glossary](https://www.designtokens.org/glossary/)

packages/next-docs/pages/guides/styling/introduction.mdx

@@ -0,0 +1,3 @@
+# Introduction
+
+🚧