From ba2287ffa2d6eba1816e6871e7c1418b001541f4 Mon Sep 17 00:00:00 2001
From: Parimal Satyal <88370597+psatyal@users.noreply.github.com>
Date: Fri, 30 Aug 2024 16:31:31 +0200
Subject: [PATCH] Added documentation concerning forms

---
 lookbook/docs/patterns/02-forms.md.erb        | 47 +++++++++++++++++++
 .../docs/patterns/16-settings-pages.md.erb    |  1 +
 2 files changed, 48 insertions(+)
 create mode 100644 lookbook/docs/patterns/02-forms.md.erb
 create mode 100644 lookbook/docs/patterns/16-settings-pages.md.erb

diff --git a/lookbook/docs/patterns/02-forms.md.erb b/lookbook/docs/patterns/02-forms.md.erb
new file mode 100644
index 000000000000..6b5732f9b0cd
--- /dev/null
+++ b/lookbook/docs/patterns/02-forms.md.erb
@@ -0,0 +1,47 @@
+A form is a series of components that require user input that will then be submitted. Forms are notably common in settings pages but are also present elsewhere like in individual modals (edit project attribute section, edit meeting details) and the filter panel.
+
+## Form elements
+
+A form may be composed of these elements:
+
+- Text input
+- Text area
+- Select
+- Toggle switch
+- Checkbox
+- Checkbox group
+- Radio button
+- Radio groups
+
+Additional elements like Banners might also be used.
+
+## Grouping and hierarchy
+
+Form elements are related need to be grouped together. For this, use a form group. 
+
+If a form is particularly long, split it into different form groups and use a `Subhead` at the start of each to give it a title. When using Subheads, we recommend implementing individual Save buttons for each section (using the <em>Secondary</em> style). If a section only contains `Toggle switch` elements, a separate Save button is not necessarily (since the Toggle sends its own server request on interaction).
+
+If a form does not use Subhead sections, then there should be a single 'Save' (using the <em>Primary</em> style) button at the end.
+
+## Form width
+
+In Primer, form elements automatically take the width of the container. In certain cases (especially Settings pages), full-width input fields will look strange. In this case, form inputs will need to have a smaller width.
+
+In OpenProject, each form element has its own container. It is thus possible to define the container width for each input. This width will define both the visual width of the field but also the max width of the caption field (where the line breaks).
+
+The options are:
+
+- <strong>:auto</strong> => width: auto
+- <strong>:small</strong> => max-width: min(256px, 100vw - 2rem)
+- <strong>:medium</strong> =>  max-width: min(320px, 100vw - 2rem)
+- <strong>:large</strong> => max-width: min(480px, 100vw - 2rem)
+- <strong>:xlarge</strong> => max-width: min(640px, 100vw - 2rem)
+- <strong>:xxlarge</strong> => max-width: min(960px, 100vw - 2rem)
+
+## Vertical spacing
+
+By default, form elements do not have proper vertical spacing in Primer. We recommend a 16px (`stack/gap/normal`) vertical separate between individual elements. There is an [open issue in Primer's GitHub](https://github.com/primer/view_components/issues/3042) to fix this.
+
+Until this is fixed at a component level, please do not manually apply form padding.
+
+An alternative approach is to wrap individual form elements using `Form group`. Please only use this sparingly and only when it is absolutely necessarily.
diff --git a/lookbook/docs/patterns/16-settings-pages.md.erb b/lookbook/docs/patterns/16-settings-pages.md.erb
new file mode 100644
index 000000000000..f975a73b9026
--- /dev/null
+++ b/lookbook/docs/patterns/16-settings-pages.md.erb
@@ -0,0 +1 @@
+When working on Settings pages, please refer to the Forms pattern for information on how to implement form elements.
\ No newline at end of file