Background goal

As part of T340535: [EPIC] Responsive layout approach we are going to implement a Container component. We will need both fluid and fixed containers.

• Fixed containers have a max width (like article max width)
• Fluid containers expand as the viewport gets bigger (but they still have padding or margins at the edges)
• Containers may need different margin/padding tokens at different breakpoint sizes

Assuming that this goes well, we will adopt a component-based approach to responsive layout in Codex, and we will plan to introduce a series of more complex Layout components (exact members TBD, but will likely include Columns, Grid, etc).

Description

A Container is a flexible layout wrapper that adapts across the different breakpoints and screen sizes.

User stories

• As an engineer, I need a flexible Container component that allows me to easily set min-width, max-width, and fluid behavior to create consistent layouts across all breakpoints and screen sizes.

---

Codex implementation

Component task owners

• Designer: @bmartinezcalvo
• Developer: @Volker_E

Design spec

• Width: 100% by default, ensuring a fluid and flexible layout.
• Min-Width: @size-1600 (equivalent to 256px) by default to avoid content to be too narrow, but it can be customizable to a smaller or larger width.
• Max-Width: some predefined max-widths and then customizable to other widths. Predefined max-widths will be:
  • x-large 1596px (new token needed)
  • large 944px (new token needed)
  • medium 640px (@size-4000)
  • small 448px (@size-2800)
  • x-small 256px (@size-1600) 2025-03-10: We decided for the WIP implementation to only roll-out larger containers startign with medium, as the use case of the small ones is questionable under premise of underlying Grid and container supposedly being just most outer layout helper
• Breakpoint Mobile: at breakpoint mobile (320px - 639px screens) the Container will be full-width, and it will reset to 100% even if the min or max width is different at other breakpoints.
• Paddings: by default, paddings in container will be 0, although they can be customized with other system paddings if needed.
• Alignment: horizontally center-aligned in LTR/RTL by default, but they will be customizable to other placements.

Guidelines

Open questions

• Is this going to be a "normal" Codex component, and live in the sidebar of the https://doc.wikimedia.org/codex/latest/components/overview.html page?
  • VE: From my POV it makes most sense to have it as specific entry in the sidebar, as it fits into the 'Content & data' section and it seems important enough to feature it for general documentation.
• [design] Should the Containers always be centered in their container – HTML body/main/section or div?
  • VE: I think an opinionated default could be more problematic when feature teams have to override it too often. An alternative could be to
• [engineering] Clarify (tbd if in MVP) HTML5 sectioning character feature for Container? Should dev teams be able to also choose between semantic sectioning elements like section, main, nav or aside as well instead of an meaningless wrapper div? This would also need to feature a heading or an ARIA label.

---

Acceptance criteria

• Define the container specifications and guidelines
• T386997: Implement a new WIP Container component
• T387387: Container: create a prototype to test it with real content
• Write an ADR documenting the approach we will follow for responsive layout components in Codex based on what we learn here