docs: column layout (#795)

* write introduction

* write overview and guidelines

* adjust examples

* make all textfields required

---------

Co-authored-by: Marie Jünke <m.juenke@mittwald.de>

packages/docs/src/content/03-components/structure/column-layout/examples/custom-values.tsx

@@ -3,10 +3,10 @@ import TextField from "@mittwald/flow-react-components/TextField";
 import Label from "@mittwald/flow-react-components/Label";
 
 <ColumnLayout m={[2, 1]}>
-  <TextField>
+  <TextField isRequired>
     <Label>Straße</Label>
   </TextField>
-  <TextField>
+  <TextField isRequired>
     <Label>Hausnummer</Label>
   </TextField>
 </ColumnLayout>;

packages/docs/src/content/03-components/structure/column-layout/examples/default.tsx

@@ -2,17 +2,17 @@ import ColumnLayout from "@mittwald/flow-react-components/ColumnLayout";
 import TextField from "@mittwald/flow-react-components/TextField";
 import Label from "@mittwald/flow-react-components/Label";
 
-<ColumnLayout>
-  <TextField>
+<ColumnLayout rowGap="s" columnGap="l">
+  <TextField isRequired>
     <Label>Vorname</Label>
   </TextField>
-  <TextField>
+  <TextField isRequired>
     <Label>Nachname</Label>
   </TextField>
-  <TextField>
+  <TextField isRequired>
     <Label>Straße</Label>
   </TextField>
-  <TextField>
+  <TextField isRequired>
     <Label>Hausnummer</Label>
   </TextField>
 </ColumnLayout>;

packages/docs/src/content/03-components/structure/column-layout/examples/gaps.tsx

@@ -2,17 +2,22 @@ import ColumnLayout from "@mittwald/flow-react-components/ColumnLayout";
 import TextField from "@mittwald/flow-react-components/TextField";
 import Label from "@mittwald/flow-react-components/Label";
 
-<ColumnLayout rowGap="s" columnGap="l">
-  <TextField>
+<ColumnLayout m={[1, 1]} rowGap="s" columnGap="l">
+  <TextField isRequired>
     <Label>Vorname</Label>
   </TextField>
-  <TextField>
+  <TextField isRequired>
     <Label>Nachname</Label>
   </TextField>
-  <TextField>
-    <Label>Straße</Label>
-  </TextField>
-  <TextField>
-    <Label>Hausnummer</Label>
+  <ColumnLayout s={[2, 1]} columnGap="m">
+    <TextField isRequired>
+      <Label>Straße</Label>
+    </TextField>
+    <TextField isRequired>
+      <Label>Hausnummer</Label>
+    </TextField>
+  </ColumnLayout>
+  <TextField isRequired>
+    <Label>Ort</Label>
   </TextField>
 </ColumnLayout>;

packages/docs/src/content/03-components/structure/column-layout/examples/main.tsx

@@ -3,10 +3,10 @@ import TextField from "@mittwald/flow-react-components/TextField";
 import Label from "@mittwald/flow-react-components/Label";
 
 <ColumnLayout s={[1, 1]}>
-  <TextField>
+  <TextField isRequired>
     <Label>Vorname</Label>
   </TextField>
-  <TextField>
+  <TextField isRequired>
     <Label>Nachname</Label>
   </TextField>
 </ColumnLayout>;

packages/docs/src/content/03-components/structure/column-layout/guidelines.mdx

@@ -0,0 +1,41 @@
+# Grundlagen
+
+## Best practices
+
+- Zu viele Spalten können den Content überladen und unübersichtlich machen. In
+  der Regel reichen maximal 4 Spalten aus.
+- Integriere bei Bedarf mehrere ColumnLayouts ineinander, um Inhalte optisch zu
+  gruppieren.
+- Wähle die Spaltenbreiten bewusst: Einheitliche Breiten schaffen ein
+  harmonisches Layout, während unterschiedliche Breiten den Fokus des Users auf
+  breitere Inhalte lenken.
+- Verwende das ColumnLayout in Kombination mit der
+  [Section](/03-components/structure/section), um einfach übersichtliche Layouts
+  zu erstellen.
+
+# Verwendung
+
+Verwende ein ColumnLayout, um ...
+
+- das Layout eines Dashboards festzulegen.
+- Formularfeldern eine klare Struktur zu geben.
+- Inhalte auf unterschiedlichen Geräten übersichtlich darzustellen.
+
+---
+
+# Verhalten
+
+## Responsive layout
+
+Das ColumnLayout folgt folgenden Breakpoints:
+
+- Größe `s` bis 550 Pixel Breite: `[1]`
+- Größe `m` bis 850 Pixel Breite: `[1, 1]`
+- Größe `l` ab 851 Pixel Breite: `[1, 1, 1]`
+
+Beachte, dass die Breakpoints sich nicht auf die Bildschirmgröße des Endgeräts
+beziehen. Sie beziehen sich auf die Breite des Containers, in dem das
+ColumnLayout verwendet wird. Für jeden Breakpoint kann sowohl die Anzahl der
+Spalten als auch deren Größenverteilung individuell festgelegt werden (siehe
+Overview). So bricht das Layout automatisch um, wenn es eine bestimmte Breite
+unterschreitet.

packages/docs/src/content/03-components/structure/column-layout/index.mdx

@@ -1,6 +1,9 @@
 ---
 component: ColumnLayout
-description: Mit dem ColumnLayout kann Inhalt in Spalten unterteilt werden.
+description:
+  Das ColumnLayout organisiert Inhalte in Spalten. Sowohl die Anzahl der Spalten
+  als auch deren Größe lassen sich flexibel für verschiedene Breakpoints
+  definieren
 ---
 
 <LiveCodeEditor editorDisabled example="main" />

packages/docs/src/content/03-components/structure/column-layout/overview.mdx

@@ -1,31 +1,57 @@
-# Beispiel
+# Playground
 
-Im Default werden die Spalten folgendermaßen gesetzt:
-
-- s: `[1]`
-- m: `[1, 1]`
-- l: `[1, 1, 1]`
+Verwende `<ColumnLayout />`, um ein ColumnLayout darzustellen.
 
 <LiveCodeEditor />
 
+Das ColumnLayout erzeugt ein flexibles Spalten-Layout, das für die Breakpoints
+s, m und l individuell angepasst werden kann. Diese Breakpoints beziehen sich
+nicht auf die Bildschirmgröße, sondern auf die Breite des Containers, in dem das
+ColumnLayout verwendet wird. Standardmäßig sind die Spalten wie folgt definiert:
+
+- Größe `s` bis 550 Pixel Breite: `[1]`
+- Größe `m` bis 850 Pixel Breite: `[1, 1]`
+- Größe `l` ab 851 Pixel Breite: `[1, 1, 1]`
+
+In der Definition der Spalten-Breiten werden sowohl die Anzahl der Spalten als
+auch ihr Größenverhältnis festgelegt. Eine Aufteilung wie [1, 2, 1] erzeugt zum
+Beispiel drei Spalten, wobei die mittlere Spalte doppelt so breit ist wie die
+beiden äußeren.
+
 ---
 
-# Benutzerdefinierte Values
+# Benutzerdefinierte Werte
 
-Größere Größen erben von kleineren größen, sofern sie nicht gesetzt sind:
+Für jeden Breakpoint können eigene Werte für die Spaltenanzahl und deren
+Größenverhältnis festgelegt werden. Wenn für einen größeren Breakpoint keine
+eigenen Werte definiert sind, übernimmt er automatisch die Werte des
+nächstkleineren Breakpoints. Standardwerte werden nur verwendet, wenn bei keinem
+kleineren Breakpoint benutzerdefinierte Werte angegeben sind. Beispiel:
 
-- s: `[1]` (default)
-- m: `[2, 1]`
-- l: `[2, 1]` (inherited)
+- Größe `s` bis 550 Pixel Breite: `[1]` (Default-Wert)
+- Größe `m` bis 850 Pixel Breite: `[2, 1]` (benutzerdefinierter Wert)
+- Größe `l` ab 851 Pixel Breite: `[2, 1]` (Wert von m geerbt)
+
+In diesem Beispiel wurde für den Breakpoint `m` eine benutzerdefinierte
+Spaltenaufteilung festgelegt. Der Breakpoint `l` übernimmt diese Aufteilung von
+`m`, anstatt auf den Standardwert von `[1, 1, 1]` zurückzufallen. Da für den
+Breakpoint `s` kein benutzerdefinierter Wert angegeben wurde, bleibt er beim
+Standardwert von `[1]`.
 
 <LiveCodeEditor example="custom-values" editorCollapsed />
 
 ---
 
-# Abstände konfigurieren
+# Abstände
+
+Die Abstände des ColumnLayout können in drei Stufen angepasst werden:
+
+- s = 8px
+- m = 16px
+- l = 24px
 
-- `rowGap`: Setzt Reihenabstände (s, m, l)
-- `columnGap`: Setzt Spaltenabstände (s, m, l)
-- `gap`: Setzt beide Abstände gleichzeitig (s, m, l)
+Die property `rowGap` steuert die Abstände zwischen den Zeilen (oben und unten),
+`columnGap` die Abstände zwischen den Spalten (rechts und links) und `gap` setzt
+alle Abstände gleichzeitig (oben, unten, rechts und links).
 
 <LiveCodeEditor example="gaps" editorCollapsed />