Skip to content

x-container.md

Latest commit

 

History

History
537 lines (357 loc) · 8.83 KB

x-container.md

File metadata and controls

537 lines (357 loc) · 8.83 KB

x-container

Overview

x-container is an accessible, themeable layout container web component for constraining content width, centering page content, and applying consistent responsive spacing.

It is a passive layout primitive:

  • no custom events
  • no internal interaction model
  • no focus management
  • no child behavior orchestration

The component is framework-agnostic and works with plain HTML, React, Reagent, or any framework that supports custom elements.

Tag

<x-container>

Purpose

Provide a low-level layout primitive that can:

  • constrain content width
  • center content horizontally
  • apply consistent inline padding
  • expose a semantic root element
  • support light and dark mode theming
  • expose surface and spacing tokens for consumers

Attributes

Attribute Type Description
as enum Semantic root element rendered inside shadow DOM
size enum Max-width preset
padding enum Inline padding preset
center boolean-like Controls horizontal centering
fluid boolean Removes width constraint and stretches full width
label string Accessible label applied to the internal semantic root

Attribute values

as

Supported values:

  • div
  • section
  • article
  • main
  • aside
  • header
  • footer
  • nav

Default:

div

Invalid values normalize to div.

size

Supported values:

  • xs
  • sm
  • md
  • lg
  • xl
  • full

Default:

lg

Invalid values normalize to lg.

padding

Supported values:

  • none
  • sm
  • md
  • lg

Default:

md

Invalid values normalize to md.

center

center is a default-true boolean-style option.

Behavior:

  • absent attribute → centered
  • center="false" → not centered

This is exposed as a property for easier programmatic control.

Default:

true

fluid

Boolean attribute.

Behavior:

  • absent → normal max-width behavior
  • present → max-width: none; width: 100%

Default:

false

label

Optional string. When provided, it becomes:

aria-label

on the internal semantic root element.

Properties

Property Type Description
center boolean Reflects layout centering
fluid boolean Reflects full-width fluid mode

Notes

center

center is implemented as a default-true property:

  • el.center returns true by default
  • setting el.center = false writes center="false"
  • setting el.center = true removes the attribute again

fluid

fluid is a standard reflected boolean property.

Events

x-container emits no custom events.

This is intentional. It is a layout primitive only.

Slots

Default slot

x-container provides a single default slot for arbitrary content.

Example:

<x-container>
  <h1>Hello world</h1>
  <p>Content goes here.</p>
</x-container>

No named slots are supported.

Semantic root behavior

The host element is always:

<x-container>

But inside shadow DOM, the component renders a semantic root element based on as.

Examples:

Default

<div part="base">
  <slot></slot>
</div>

With as="section"

<section part="base">
  <slot></slot>
</section>

With as="main"

<main part="base" aria-label="Main content">
  <slot></slot>
</main>

This allows the component to provide semantic landmarks without changing the host tag.

Accessibility

x-container is intentionally simple.

It guarantees:

  • semantic internal root selected from as
  • aria-label support via label
  • preservation of slotted child semantics
  • no keyboard behavior
  • no focus management
  • no ARIA role overrides

Examples:

<x-container as="main" label="Main content"></x-container>
<x-container as="nav" label="Primary navigation"></x-container>

Styling

The internal semantic root exposes one stable part:

base

Example:

x-container::part(base) {
  background: white;
}

CSS Custom Properties

Width tokens

Variable Description
--x-container-max-width-xs Width for size="xs"
--x-container-max-width-sm Width for size="sm"
--x-container-max-width-md Width for size="md"
--x-container-max-width-lg Width for size="lg"
--x-container-max-width-xl Width for size="xl"

Default values:

  • xs → 480px
  • sm → 640px
  • md → 768px
  • lg → 1024px
  • xl → 1280px

size="full" removes max-width entirely.

Padding tokens

Variable Description
--x-container-padding-sm Padding for padding="sm"
--x-container-padding-md Padding for padding="md"
--x-container-padding-lg Padding for padding="lg"
--x-container-padding-block Block padding applied to the base element

Defaults:

  • sm → 0.5rem
  • md → 1rem
  • lg → 1.5rem
  • block padding → 0

Layout and surface tokens

Variable Description
--x-container-margin-inline Margin used for centering
--x-container-bg Background
--x-container-color Foreground text color
--x-container-border Border color
--x-container-radius Border radius
--x-container-shadow Box shadow

Defaults:

  • background → transparent
  • border → transparent
  • radius → 0
  • shadow → none

So by default, x-container is layout-first, not card-like.

Light / Dark mode

x-container supports automatic theme adaptation using:

color-scheme: light dark;
@media (prefers-color-scheme: dark) { ... }

Default text tokens:

Light mode

  • --x-container-color: #0f172a

Dark mode

  • --x-container-color: #e5e7eb

Background remains transparent by default in both modes.

Motion

x-container has no required animated behavior.

It still includes reduced-motion-safe behavior:

@media (prefers-reduced-motion: reduce) {
  [part='base'] {
    transition: none;
  }
}

Since the component does not animate by default, this is mostly defensive.

Internal rendering behavior

The component:

  1. reads host attributes
  2. normalizes them through the model
  3. ensures the correct semantic root exists
  4. writes normalized state to internal data-* attributes on the base part

Internal data attributes include:

  • data-size
  • data-padding
  • data-center
  • data-fluid

This internal projection avoids rewriting host attributes during render.

Default behavior summary

Default rendered state is effectively:

  • as = div
  • size = lg
  • padding = md
  • center = true
  • fluid = false

So a plain container:

<x-container></x-container>

renders as a centered large-width container with medium inline padding.

Examples

Basic

<x-container>
  <p>Hello world</p>
</x-container>

Narrow reading width

<x-container size="sm">
  <article>
    <h1>Article title</h1>
    <p>Readable narrow content width.</p>
  </article>
</x-container>

Full width section

<x-container size="full" padding="lg">
  <section>
    <h2>Full width layout</h2>
  </section>
</x-container>

Semantic main region

<x-container as="main" label="Main content">
  <h1>Dashboard</h1>
</x-container>

Programmatic property usage

const el = document.querySelector("x-container");

el.center = false;
el.fluid = true;

Integration with Reagent

Example usage with the helper wrapper used in the demo app:

[wc/wc
 :x-container
 {:size "lg"
  :padding "lg"
  :center true
  :class "page-container"}
 [:section.hero-card
  [:h1 "Hello world"]
  [:p "Content inside a container."]]]

Design philosophy

x-container is intentionally minimal.

It owns:

  • width constraints
  • inline spacing
  • semantic wrapper selection
  • theme-aware layout tokens

It does not own:

  • cards
  • grids
  • sections with internal spacing rules
  • interactions
  • events
  • responsive behavior beyond container width presets

That makes it a strong base primitive for larger layout systems.