Skip to content

OpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub

add documentation

Behrokh Satarnejad9b694546e2a0
diff --git a/lookbook/docs/components/inset-box.md.erb b/lookbook/docs/components/inset-box.md.erb
new file mode 100644
index 00000000000..ab4b9cc9f5d
--- /dev/null
+++ b/lookbook/docs/components/inset-box.md.erb
@@ -0,0 +1,63 @@
+The Inset Box element is used to visually group content inside a container with a subtle inset background and optional border.
+
+<%= embed OpPrimer::InsetBoxComponentPreview, :default %>
+
+## Anatomy
+
+The Inset Box is made up of:
+
+1. The **container**, which provides consistent padding and background.
+2. The **content slot**, which renders any inner content (text, forms, tables, etc.).
+3. An optional **border**, which can be toggled off when not needed.
+
+## Default rendering
+
+- **Border:** enabled by default
+- **Border radius:** 2
+- **Background:** `:inset` (light grey)
+- **Padding:** 3 (all sides, unless overridden)
+
+<%= embed OpPrimer::InsetBoxComponentPreview, :default %>
+
+## Customization
+
+The Inset Box supports the following options:
+
+- **Border** – can be disabled with `border: false`.
+- **Padding** – defaults to `p: 3`, but can be overridden (`p`, `pt`, `pb`, `pl`, `pr`).
+- **Background** – defaults to `:inset`, but can be set to `:muted` or other Primer colors.
+- **Other system arguments** – all `Primer::Box` arguments are passed through.
+
+<%= embed OpPrimer::InsetBoxComponentPreview, :default %>
+
+## Uses
+
+Some places where we already use the Inset Box:
+
+- in project forms (copy form, new project, source project select, template select)
+- in `ProjectQueries::PublicFlagComponent`
+- in meeting agenda items and outcomes
+
+It is useful whenever content should stand out from the page background while staying lightweight.
+
+If content needs more structure (e.g., with headers, actions, or multiple items), consider using the [Border Box](./border_box) component instead.
+
+## Best practices
+
+**Do**
+
+- Use the Inset Box to provide a consistent background for related content.
+- Adjust padding only when necessary to match surrounding layout.
+- Keep its usage lightweight and minimal for clarity.
+
+**Don't**
+
+- Don’t apply arbitrary custom background colors in CSS — use the component’s options.
+- Don’t duplicate "grey box" styles manually; always use the Inset Box.
+- Don’t use Inset Box if a more structured component (like Border Box) is better suited.
+
+## Technical notes
+
+<%= embed OpPrimer::InsetBoxComponentPreview, :default %>
+
+The Inset Box is implemented as a wrapper around `Primer::Box` with opinionated defaults for border, padding, border radius, and background. It passes through all other `system_arguments` to `Primer::Box`.