docs: add some more docs

.storybook/preview.js

@@ -15,7 +15,12 @@ const preview = {
     },
     options: {
       storySort: {
-        order: ["Introduction", "Components", "*"],
+        order: [
+          "Introduction",
+          ["Installation", "Usage", "Theme", "Contributing"],
+          "Components",
+          "*",
+        ],
       },
     },
     viewport: {

README.md

@@ -95,73 +95,6 @@ To build a production version of Storybook, run
 npm run storybook:build
 ```
 
-## Create a new component
-
-To create a starting point for a new component, run
-
-```bash
-./scripts/generate-component/generate.js
-```
-
-Running it with `--help` will show you all available options.
-
-## Development guidelines
-
-A few rules are necessary when developing a component library. The following conventions and guidelines should be followed when new features are implemented.
-
-At the same time they're not set in stone. If the there is a good reason to change them open a pull request.
-
-### Naming
-
-Every element or custom property that will be globally available has to be prefixed with `leu`.
-
-```js
-/* Custom elements */
-class LeuRadio extends LeuElement {
-  ...
-}
-
-window.customElements.define("leu-input", LeuInput)
-```
-
-```css
-/* CSS custom property of the theme */
-:root {
-  --leu-color-black-0: #000;
-}
-```
-
-### Scoped styles
-
-All CSS declarations have to live inside a custom element. This way we ensure that the styles won't interfere with the environment they're loaded into.
-Styles that are shared between components should be defined as global custom properties inside the `styles/custom-properties.css`.
-When a global custom property is used inside a component it could be a good practice to assign them to a local custom property with a semantic naming.
-This only make a sense when the component has a certain complexity and the global custom property are used multiple times.
-
-```css
-:host {
-  --radio-color-disabled: var(--leu-color-black-20);
-}
-```
-
-### Value property
-
-All custom elements that contain a value of some sort have to implement a `value` property.
-Everytime the value of the `value` property changes a `input` event has to be dispatched.
-This behaviour matches the way [Observable](https://observablehq.com) handles and observes changes of values that are contained in arbitrary elements. We decided to take over this pattern as it is usable in every other environment too.
-
-### Custom events
-
-In case of a custom event that is meant to be catched by an other component of this library, the name of this event has to be prefixed too.
-
-```js
-this.dispatchEvent(new Event("leu:select", { bubbles: true, composed: true }))
-```
-
-### Dependencies
-
-Use as little dependencies as possible and as many as needed.
-
 ## Contributors
 
 Thanks to the following people who have contributed to this project

src/docs/contributing.mdx

@@ -4,7 +4,115 @@ import { Meta, Markdown } from "@storybook/blocks"
 
 # Contributing
 
-- How to write a new component
-- How to start the development server
-- Guidelines
+Contributing to this project is highly appreciated. We are happy to receive feedback, bug reports, feature requests, and pull requests.
+
+
 - Custom Elements / Lit
+
+
+## Create a new component
+
+To create a starting point for a new component, run
+
+```bash
+./scripts/generate-component/generate.js
+```
+
+Running it with `--help` will show you all available options.
+
+It creates a basic structure for a new component in the `src/components` directory.
+
+
+## Linting and formatting
+
+To scan the project for linting and formatting errors, run
+
+```bash
+npm run lint
+```
+
+To automatically fix linting and formatting errors, run
+
+```bash
+npm run format
+```
+
+## Testing with Web Test Runner
+
+To execute a single test run:
+
+```bash
+npm run test
+```
+
+To run the tests in interactive watch mode run:
+
+```bash
+npm run test:watch
+```
+
+## Demoing with Storybook
+
+To run a local instance of Storybook for your component, run
+
+```bash
+npm run storybook
+```
+
+
+## Development guidelines
+
+A few rules are necessary when developing a component library. The following conventions and guidelines should be followed when new features are implemented.
+
+At the same time they're not set in stone. If the there is a good reason to change them open a pull request.
+
+### Naming
+
+Every element or custom property that will be globally available has to be prefixed with `leu`.
+
+```js
+/* Custom elements */
+class LeuRadio extends LeuElement {
+  ...
+}
+
+window.customElements.define("leu-input", LeuInput)
+```
+
+```css
+/* CSS custom property of the theme */
+:root {
+  --leu-color-black-0: #000;
+}
+```
+
+### Scoped styles
+
+All CSS declarations have to live inside a custom element. This way we ensure that the styles won't interfere with the environment they're loaded into.
+Styles that are shared between components should be defined as global custom properties inside the `styles/custom-properties.css`.
+When a global custom property is used inside a component it could be a good practice to assign them to a local custom property with a semantic naming.
+This only make a sense when the component has a certain complexity and the global custom property are used multiple times.
+
+```css
+:host {
+  --radio-color-disabled: var(--leu-color-black-20);
+}
+```
+
+### Value property
+
+All custom elements that contain a value of some sort have to implement a `value` property.
+Everytime the value of the `value` property changes a `input` event has to be dispatched.
+This behaviour matches the way [Observable](https://observablehq.com) handles and observes changes of values that are contained in arbitrary elements. We decided to take over this pattern as it is usable in every other environment too.
+
+### Custom events
+
+In case of a custom event that is meant to be catched by an other component of this library, the name of this event has to be prefixed too.
+
+```js
+this.dispatchEvent(new Event("leu:select", { bubbles: true, composed: true }))
+```
+
+### Dependencies
+
+Use as little dependencies as possible and as many as needed.

src/docs/theme.mdx

@@ -43,6 +43,19 @@ export const ColorTable = ({ prefix, shades }) => {
 
 # Theme
 
+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" />
+```
+
+If you're "only" using the components then that's all you need to do.
+
+The rest of the document explains what the theme contains and how it's structured.
+This is helpful if you want to use the it to style your application or to build new components.
+
+
 ## Table of Contents
 
 - [Design System](#design-system)
@@ -52,19 +65,10 @@ export const ColorTable = ({ prefix, shades }) => {
 - [Box Shadows](#box-shadows)
 - [z-index](#z-index)
 - [Typography](#typography)
-- [Grid](#grid)
+- [Layout](#layout)
 
 ---
 
-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.
@@ -83,7 +87,7 @@ The theme contains custom properties for:
 
 ## Custom property naming
 
-All custom properties are prefixed with `--leu-` to avoid conflicts with other custom properties.
+All custom properties of this theme are prefixed with `--leu`.
 
 ```css
 :root {
@@ -177,7 +181,7 @@ The font files and the font face declaration are not part of the package. You ne
 
 ## Font family naming
 
-Each weight has a unique font family name. The @font-face declaration has to match this naming.
+Each weight has a unique font family name. The `@font-face` declaration has to match this naming.
 
 <table>
   <tr>
@@ -190,11 +194,30 @@ Each weight has a unique font family name. The @font-face declaration has to mat
   </tr>
 </table>
 
+In the theme those two definitions including fallbacks are defined as custom properties.
+
+```css
+h1 {
+  font-family: var(--leu-font-family-black);
+}
+
+p {
+  font-family: var(--leu-font-family-regular);
+}
+```
+
+### OpenType features
+
+Inter has a lot of OpenType features and the design system makes use of that.
+To have the correct features applied, you need to set the `font-feature-settings` property.
+
 ```css
---leu-font-family-black
---leu-font-family-regular
+h1 {
+  font-feature-settings: var(--leu-t-font-feature-settings);
+}
 ```
 
+
 ### Font styles
 
 The ["Typografie" page of the figma file](https://www.figma.com/design/d6Pv21UVUbnBs3AdcZijHmbN/KTZH-Design-System?node-id=17336-82304&t=dL03yolQ7l8e6eow-11) lists all the font style definitions that are used in the design system.
@@ -262,7 +285,22 @@ h1 {
 }
 ```
 
-## Grid
+#### Responsive scaling
+
+There are cases where an element keeps the same font size on all breakpoints. Most of the times this is not a desireable behaviour.
+The design system defines this, with what they call "curves". They are a definition of which font style should be applied on which breakpoint.
+
+Every "curve" is defined as a custom property. They automatically change its value depending on the current breakpoint.
+
+They can be accessed with the same properties like the font styles mentioned above.
+
+```css
+h1 {
+  font: var(--leu-t-curve-large-black-font);
+}
+```
+
+## Layout
 
 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.