docs: extend the docs

src/docs/contributing.mdx

@@ -0,0 +1,10 @@
+import { Meta, Markdown } from "@storybook/blocks"
+
+<Meta title="Introduction/Contributing" />
+
+# Contributing
+
+- How to write a new component
+- How to start the development server
+- Guidelines
+- Custom Elements / Lit

src/docs/theme.mdx

@@ -1,11 +1,210 @@
-import { Meta, Markdown } from '@storybook/blocks';
+import { Meta, Markdown, Canvas } from "@storybook/blocks"
+
+import * as GridStories from "../styles/style.stories.js"
 
 <Meta title="Introduction/Theme" />
 
+export const ColorTable = ({ prefix, shades }) => {
+  return (
+    <table>
+      <thead>
+        <tr>
+          <th>Color</th>
+          <th>Property</th>
+        </tr>
+      </thead>
+      <tbody>
+        {shades.map((shade) => {
+          return (
+            <tr>
+              <td
+                style={{
+                  background:
+                    "repeating-conic-gradient(var(--leu-color-black-10) 0% 25%, transparent 0% 50%) 50% / 20px 20px, white",
+                }}
+              >
+                <div
+                  style={{
+                    background: `var(--leu-color-${prefix}-${shade})`,
+                    height: "1.5rem",
+                  }}
+                ></div>
+              </td>
+              <td>
+                --leu-color-{prefix}-{shade}
+              </td>
+            </tr>
+          )
+        })}
+      </tbody>
+    </table>
+  )
+}
+
 # Theme
 
-- Structure of the file
-- Typography (Font faces and settings)
+The styling of all the components rely on the theme stylesheet and its definitions. In order for the components to work and look right, you need to load the theme stylesheet globally.
+The theme is a single stylesheet that just defines custom properties. It doesn't contain any global classes.
+
+```html
+<link rel="stylesheet" href="@statistikzh/leu/dist/theme.css" />
+```
+
+The theme itself can also be used for the styling of the rest of your application. The custom properties can be accessed in every stylesheet as they're defined on the root element (`:root`) .
+
+## Design system
+
+The theme is based on the official [design system](https://www.zh.ch/de/webangebote-entwickeln-und-gestalten.html). Every single custom property relates to a specific design token defined in the design system.
+Currently there is no automatic workflow that generates the theme from the design system. The theme is manually updated when the design system changes.
+If you spot any inconsistencies between the theme and the design system, please open an issue.
+
+## Structure of the file
+
+The theme contains custom properties for:
+
 - Colors
-- Box shadows
+- Box Shadows
+- z-index
+- Typography
 - Grid
+
+## Custom property naming
+
+All custom properties are prefixed with `--leu-` to avoid conflicts with other custom properties.
+
+```css
+:root {
+  --leu-color-black-100: #000;
+}
+```
+
+## Colors
+
+The colors are split into different categories (black, white, accent, functional).
+Each of the categories have a specific prefix.
+
+An overview of all the colors can be found in the [figma file](https://www.figma.com/design/d6Pv21UVUbnBs3AdcZijHmbN/KTZH-Design-System?node-id=278-297&p=f&t=9QQZarLNjSn1og6x-11).
+
+### Shades of black
+
+The design system uses two different kind of black shades. One with transparency and one without.
+Consult the figma file to find out when to use which.
+
+<ColorTable prefix="black" shades={[100, 80, 60, 40, 20, 10, 5, 0]} />
+
+#### Shades with transparency
+
+<ColorTable prefix="black-transp" shades={[80, 60, 40, 20, 10, 5]} />
+
+### Shaeds of white
+
+<ColorTable prefix="white-transp" shades={[90, 70, 40, 10]} />
+
+### Accent colors
+
+<ColorTable
+  prefix="accent"
+  shades={[
+    "blue",
+    "darkblue",
+    "turquoise",
+    "green",
+    "bordeaux",
+    "magenta",
+    "violet",
+    "gray",
+  ]}
+/>
+<ColorTable
+  prefix="accent"
+  shades={[
+    "blue-soft",
+    "darkblue-soft",
+    "turquoise-soft",
+    "green-soft",
+    "bordeaux-soft",
+    "magenta-soft",
+    "violet-soft",
+    "gray-soft",
+  ]}
+/>
+
+### Functional colors
+
+<ColorTable prefix="func" shades={["cyan", "red", "green"]} />
+
+## Box Shadows
+
+The three different box shadow styles can directly be applied to the `box-shadow` property.
+
+```css
+box-shadow: var(--leu-box-shadow-short);
+```
+
+<div style={{ display: "flex", gap: "1rem", flexWrap: "wrap" }}>
+  {["short", "regular", "long"].map((shadow) => (
+    <div
+      style={{
+        boxShadow: `var(--leu-box-shadow-${shadow})`,
+        padding: "1rem",
+        flex: 1,
+      }}
+    >
+      --leu-box-shadow-{shadow}
+    </div>
+  ))}
+</div>
+
+## z-index
+
+## Typography
+
+## Grid
+
+As the theme only consist of custom properties, it isn't possible to provide a full set of grid classes.
+Instead the theme contains just five necessary values that can be applied directly.
+Most components don't need a grid anyway and those who do mostly have a very simple configuration.
+Alternatively you can use to build your own classes for your application.
+This aproach helps us to keep the css footprint small.
+
+The official design system uses a 6 columns system on smaller screens.
+For simplicity we use a 12 column grid for all breakpoints.
+
+<table>
+  <thead>
+    <tr>
+      <th>Property</th>
+      <th>Definition</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`--leu-grid-gap`</td>
+      <td>The gap between the columns (responsive)</td>
+    </tr>
+    <tr>
+      <td>`--leu-grid-max-width`</td>
+      <td>Maximum width of the grid container</td>
+    </tr>
+    <tr>
+      <td>`--leu-grid-template-columns`</td>
+      <td>Defines 12 equal sized columns</td>
+    </tr>
+    <tr>
+      <td>`--leu-grid-columns-full`</td>
+      <td>
+        Preset for a cell that takes up the whole width of it's container
+        (responsive)
+      </td>
+    </tr>
+    <tr>
+      <td>`--leu-grid-columns-offset`</td>
+      <td>
+        Preset for offset cells. This configuration is used a lot on zh.ch
+        content pages.
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<Canvas of={GridStories.Regular} />