feat(docs): Box primitive

.changeset/curly-snakes-relate.md

@@ -0,0 +1,5 @@
+---
+"docs": patch
+---
+
+feat(docs): add documentation for Box primitive

docs/content/components/box.mdx

@@ -2,7 +2,49 @@
 title: Box
 ---
 
-# Box-Component
+# Box
+
+## Properties
+
+| Property                    | Type                                  | Default |
+| :-------------------------- | :------------------------------------ | :------ |
+| `as` (optional)             | `HTMLElement`                         | `div`   |
+| `display` (optional)        | `ResponsiveStyleValue<string>`        |         |
+| `height` (optional)         | `ResponsiveStyleValue<number⎮string>` |         |
+| `width` (optional)          | `ResponsiveStyleValue<number⎮string>` |         |
+| `minWidth` (optional)       | `ResponsiveStyleValue<number⎮string>` |         |
+| `maxWidth` (optional)       | `ResponsiveStyleValue<number⎮string>` |         |
+| `position` (optional)       | `ResponsiveStyleValue<string>`        |         |
+| `top` (optional)            | `ResponsiveStyleValue<number⎮string>` |         |
+| `bottom` (optional)         | `ResponsiveStyleValue<number⎮string>` |         |
+| `right` (optional)          | `ResponsiveStyleValue<number⎮string>` |         |
+| `left` (optional)           | `ResponsiveStyleValue<number⎮string>` |         |
+| `zIndex` (optional)         | `ResponsiveStyleValue<number⎮string>` |         |
+| `p` (optional)              | `ResponsiveStyleValue<number⎮string>` |         |
+| `px` (optional)             | `ResponsiveStyleValue<number⎮string>` |         |
+| `py` (optional)             | `ResponsiveStyleValue<number⎮string>` |         |
+| `pt` (optional)             | `ResponsiveStyleValue<number⎮string>` |         |
+| `pb` (optional)             | `ResponsiveStyleValue<number⎮string>` |         |
+| `pl` (optional)             | `ResponsiveStyleValue<number⎮string>` |         |
+| `pr` (optional)             | `ResponsiveStyleValue<number⎮string>` |         |
+| `m` (optional)              | `ResponsiveStyleValue<number⎮string>` |         |
+| `mx` (optional)             | `ResponsiveStyleValue<number⎮string>` |         |
+| `my` (optional)             | `ResponsiveStyleValue<number⎮string>` |         |
+| `ml` (optional)             | `ResponsiveStyleValue<number⎮string>` |         |
+| `mr` (optional)             | `ResponsiveStyleValue<number⎮string>` |         |
+| `flexDirection` (optional)  | `ResponsiveStyleValue<string>`        |         |
+| `flexWrap` (optional)       | `ResponsiveStyleValue<string>`        |         |
+| `flexShrink` (optional)     | `ResponsiveStyleValue<number⎮string>` |         |
+| `flexGrow` (optional)       | `ResponsiveStyleValue<number⎮string>` |         |
+| `alignItems` (optional)     | `ResponsiveStyleValue<string>`        |         |
+| `justifyContent` (optional) | `ResponsiveStyleValue<string>`        |         |
+| `bg` (optional)             | `ResponsiveStyleValue<number⎮string>` |         |
+| `border` (optional)         | `ResponsiveStyleValue<number⎮string>` |         |
+| `borderRadius` (optional)   | `ResponsiveStyleValue<number⎮string>` |         |
+| `boxShadow` (optional)      | `ResponsiveStyleValue<number⎮string>` |         |
+| `opacity` (optional)        | `ResponsiveStyleValue<number⎮string>` |         |
+| `overflow` (optional)       | `ResponsiveStyleValue<string>`        |         |
+| `transition` (optional)     | `ResponsiveStyleValue<number⎮string>` |         |
 
 ## Import
 

docs/content/components/link.mdx

@@ -10,11 +10,11 @@ Element to style links.
 
 ## Properties
 
-| Property              | Type                  | Default |
-| :-------------------- | :-------------------- | :------ |
-| `as` (optional)       | string \| `Component` | `a`     |
-| `variant` (optional)  | string \| string[]    | `link`  |
-| `disabled` (optional) | boolean               |         |
+| Property              | Type                 | Default |
+| :-------------------- | :------------------- | :------ |
+| `as` (optional)       | `string ⎮ Component` | `a`     |
+| `variant` (optional)  | `string ⎮ string[]`  | `link`  |
+| `disabled` (optional) | boolean              |         |
 
 ## Import
 

docs/content/components/stack.mdx

@@ -10,10 +10,10 @@ Layout component to stack elements. This component uses the spaces from the give
 
 ## Properties
 
-| Property | Type                                           | Default |
-| :------- | :--------------------------------------------- | :------ |
-| `space`  | `ResponsiveStyleValue<number `&#124;` string>` | `0`     |
-| `align`  | `left, right, center`                          | `left`  |
+| Property | Type                                  | Default |
+| :------- | :------------------------------------ | :------ |
+| `space`  | `ResponsiveStyleValue<number⎮string>` | `0`     |
+| `align`  | `left, right, center`                 | `left`  |
 
 ## Import
 

docs/content/components/text.mdx

@@ -11,15 +11,15 @@ By adding the `as` prop you can alternatively render a `p` element.
 
 ## Properties
 
-| Property                | Type                  | Default |
-| :---------------------- | :-------------------- | :------ |
-| `as` (optional)         | string \| `Component` | `span`  |
-| `variant` (optional)    | string \| string[]    | `body`  |
-| `align` (optional)      | string                |         |
-| `color` (optional)      | string                |         |
-| `cursor` (optional)     | string                |         |
-| `outline` (optional)    | string                |         |
-| `userSelect` (optional) | string                |         |
+| Property                | Type                 | Default |
+| :---------------------- | :------------------- | :------ |
+| `as` (optional)         | `string ⎮ Component` | `span`  |
+| `variant` (optional)    | `string ⎮ string[]`  | `body`  |
+| `align` (optional)      | `string`             |         |
+| `color` (optional)      | `string`             |         |
+| `cursor` (optional)     | `string`             |         |
+| `outline` (optional)    | `string`             |         |
+| `userSelect` (optional) | `string`             |         |
 
 ## Import
 

docs/content/foundation/box-primitive.mdx

@@ -0,0 +1,75 @@
+---
+title: Box Primitive
+---
+
+import Link from 'gatsby-link';
+import { useStyles } from '@marigold/system';
+
+# Box Primitive
+
+## Box as Layout Component
+
+As the basis of all our components, we use the `<Box>`. It is a versatile layout component that
+can be modified with layout props as listed in the <Link to="../../components/box">Box component</Link> description.
+Additionally, use the `variant` prop to define custom styles in your themes. With the `as` prop, you
+determine the rendered HTML element. Instead of exposing the underlying tools that will create CSS, the `<Box>` component
+wraps them and exposes an API for applying styling to a component while respecting the rules and constraints of our design
+system.
+
+```tsx code
+import { Box } from '@marigold/components';
+import { useStyles } from '@marigold/system';
+```
+
+```tsx live
+<Box as="button" bg="orange" p="8px">
+  Button box with backgroundcolor and padding!
+</Box>
+```
+
+## Building a custom Component with the Box
+
+In case you want to build your own custom component, use the `Box` as the underlying layout component and add
+the styles accordingly. You can stack and nest multiple Box instances and build your complex component like this.
+By default, the `Box` component will render a `<div />`. This might be fine most of the times, but sometimes you would
+rather render a `<button>` or an `<input>` etc. To allow this, the `Box` takes the special prop called `as`, accepting
+all HTML tag names as input. Don't forget to define variants in your theme.
+
+```tsx code
+export type ButtonProps = {
+  variant?: string;
+} & ComponentPropsWithRef<'button'>;
+
+export const Button: React.FC<ButtonProps> = ({
+  variant = 'primary.large',
+  children,
+  ...props
+}) => {
+  return (
+    <Box as="button" {...props} variant={`button.${variant}`}>
+      <Box as="span" display="inline-flex" alignItems="center">
+        {children}
+      </Box>
+    </Box>
+  );
+};
+```
+
+## Custom CSS
+
+Staying inside the boundaries of the design system and its contraints should be the norm. But as limiting styling only
+to allowed values defined by the system can be very restrictive, you can use the `className` prop and generate custom
+styles with the <Link to="../../guides/usestyles">`useStyles` hook</Link>.
+
+```tsx code
+...
+    <Box
+      as="button"
+      className={useStyles({ css: { fontSize: '11pt' } })}
+      {...props}
+      variant={`button.${variant}`}
+    >
+      ...
+    </Box>
+...
+```

docs/content/foundation/themes-variants.mdx

@@ -1,10 +1,10 @@
 ---
-title: Theming
+title: Theme & Variants
 ---
 
 import Link from 'gatsby-link';
 
-# Theming
+# Theme & Variants
 
 Marigold uses a theme for its base styles.
 

docs/content/guides/installation.mdx

@@ -1,7 +1,9 @@
 ---
-title: Installation
+title: Getting Started
 ---
 
+import Link from 'gatsby-link';
+
 # Getting Started
 
 ## Installation
@@ -21,7 +23,7 @@ Add the package `@marigold/icons` if you want to use icons in Marigold.
 ## Usage
 
 Marigold components don't come with a theme by default. In order to add a theme to your application, use the `ThemeProvider`
-component and thereby provide a theme in context. You can use one of the following themes: <Link to="themes/b2b">B2B Theme</Link> or <Link to="themes/unicorn">Unicorn Theme</Link>.
+component and thereby provide a theme in context. You can use one of the following themes: <Link to="../../themes/b2b">B2B theme</Link> or <Link to="../../themes/unicorn">Unicorn theme</Link>.
 
 ```bash code
 # with npm

docs/src/components/Layout.tsx

@@ -6,6 +6,7 @@ import { Link } from './Link';
 import { Logo } from './Logo';
 import { Navigation } from './Navigation';
 import { ThemeSelect } from './ThemeSelect';
+import { useStyles } from 'packages/system/src/useStyles';
 
 export const Layout: React.FC = ({ children }) => {
   return (
@@ -19,7 +20,12 @@ export const Layout: React.FC = ({ children }) => {
         <title>Marigold Design System</title>
       </Helmet>
       <Columns space={8}>
-        <Column width={2}>
+        <Column
+          width={3}
+          className={useStyles({
+            css: { position: 'fixed', top: 0, left: 0, overflowX: 'hidden', height: '100%' },
+          })}
+        >
           <Stack space={16}>
             <Link to="/">
               <Logo />
@@ -28,7 +34,7 @@ export const Layout: React.FC = ({ children }) => {
             <Navigation />
           </Stack>
         </Column>
-        <Column width={10}>{children}</Column>
+        <Column width={9}>{children}</Column>
       </Columns>
     </>
   );

docs/src/components/Logo/Logo.tsx

@@ -2,5 +2,5 @@ import React from 'react';
 import { StaticImage } from 'gatsby-plugin-image';
 
 export const Logo: React.FC = () => (
-  <StaticImage src="./logo.png" alt="Marigold Logo" />
+  <StaticImage src="./logo.png" alt="Marigold Logo" width={180} />
 );

docs/src/components/Navigation/Navigation.tsx

@@ -49,7 +49,7 @@ const NavigationSection = ({ name, children }: NavigationSectionProps) => {
 
 export const Navigation: React.FC = () => {
   const tree = useNavigation();
-  console.log(tree);
+  // console.log(tree);
 
   return (
     <Box