# Panel
## Overview
To make sure all designers on all projects build views consistently, it is important that we use Roma layout components. By doing so, we ensure the consistency, sustainability, and scalability of our designs, and we facilitate the onboarding of new designers into the team.
Panels can be composed of the following components that can only be children of the main panel.
* [Panel Header](#panel-header)
* [Panel Content](#panel-content)
* [SubContentWrapper](#subcontentwrapper)
* [Panel Link](#panel-link)
* [Panel Separator](#panel-separator)
* [Panel Tabs](#panel-tabs)
* [Panel Footer](#panel-footer)
You cannot nest these elements inside each other; if you want a panel separator, you have to place it within the main panel, not the panel content component.
## Guidelines
### Panel header
As its name states, Panel Header is the first element that appears within the panel structure. It is not mandatory but highly recommended. As an example, if the [Page Title](https://design.mirakl.com/design/components/navigation/page-title) is clear enough, you may remove it.
{% hint style="info" %}
For accessibility reasons, if there is no `Panel Header` in the `Panel`, you should specify an ``(to be added in the code). It will not be visible in the interface but it will help screen readers to read the page while reassuring users who are navigating it.
{% endhint %}
Panel Header has several options, such as [Button group](https://design.mirakl.com/design/components/actions/button-group), [Background Icon](https://design.mirakl.com/design/components/structure/broken-reference), and [Badges](https://design.mirakl.com/design/components/feedback/badge-status) (2 maximum).
### Panel content
Panel Content is used to contain anything that has to go inside a panel (text, image, datatable, datalist, etc.).
Panel has 3 options:
* Classic
* Expandable : its content is hidden until user triggers it to reveal content.
* Scrollable : user can navigate content by scrolling it
{% tabs %}
{% tab title="Expandable" %}
This layout helps declutter a page and hide information that might not be useful at first to users. You can choose to expand or collapse it by default.
{% endtab %}
{% tab title="Scrollable" %}
This layout allows putting long-form content within a panel in which the user can scroll. You can define a max height.
{% endtab %}
{% endtabs %}
All elements contained within a panel are separated by a 16px margin in all directions, as follows:
#### SubContentWrapper
***SubContentWrapper*** is a structural container used exclusively within Panel Content to express visual hierarchy and dependency between content blocks. It adds a semi-transparent vertical indentation bar and consistent spacing to communicate "this section belongs to the preceding element."
{% hint style="success" %}
**When to use**
* To visually group content that is structurally dependent on a parent element (checkbox, radio, select, or toggle)
* When the nested content represents a sub-element or sub-configuration of its trigger, not merely a conditional choice
* To maintain clear visual hierarchy within complex panel layouts
{% endhint %}
{% hint style="danger" %}
**When not to use**
* For generic spacing or indentation without a true dependency relationship
* To reveal content that only depends on a form choice but is not a sub-element of that choice (use standard [progressive disclosure](https://design.mirakl.com/design/patterns/progressive-disclosure) instead)
* Key distinction: SubContentWrapper is for parent-child relationships (e.g., "Configure shipping method" → "Express shipping options"), not simple conditional visibility (e.g., "Enable notifications" → "Email address field"). If the revealed content is a peer requirement rather than a nested configuration, do not use SubContentWrapper.
{% endhint %}
**Options**
Collapsible: Can expand/collapse when controlled by an external trigger (button, checkbox, toggle). The wrapper itself is non-interactive; state is managed by the controlling element using aria-expanded and aria-controls.\
Spacing: Bottom spacing can be removed when multiple wrappers are stacked consecutively.\
Nesting: Supports up to 2 levels maximum. Keep nesting shallow to avoid overwhelming users.
**Accessibility**
* The wrapper is purely presentational (no role, no form behavior)
* When collapsible, the controlling element must be focusable and reflect state with aria-expanded
* Use aria-controls to connect the trigger to the wrapper region by ID
* Ensure keyboard users can reach all interactive elements within the wrapper when expanded
**Relationship to Progressive Disclosure**
SubContentWrapper pairs naturally with the [Progressive Disclosure pattern](https://design.mirakl.com/design/patterns/progressive-disclosure). When content is conditionally revealed based on a prior choice, wrap it in a SubContentWrapper only if it represents a sub-element or nested configuration of the trigger. Place the wrapper immediately after its controlling element to keep the cause → effect relationship obvious. For simple conditional visibility without hierarchical dependency, use standard progressive disclosure techniques without SubContentWrapper.
### Panel link
Panel link creates a vertical visual narrative between different panel elements. You may also add text within the link.
### Panel separator
Panel Separator can help you structure your panel visually and make a difference between 2 panel content components. It is never mandatory.
Two options are available: classic and full-width. You may also add text within the separator.
### Panel footer
Panel footer is really useful when you wish to display a fixed element after a Panel Content, especially a scrollable one.
