Container CSS

The Philosophy

This library exists because:

1. Large applications are messy - Trying to retrofit a design system into a massive codebase is painful
2. Consistency matters - Property-based styling enforces patterns that CSS classes cannot
3. Simple is better - With the combination of Flex and Box you can create solid designs used every day in most applications
4. Anything fancier is showing off - If you need more than layout containers and styled boxes, you're probably overengineering

What This Library Does

Container CSS provides layout containers (Flex) and styled containers (Box). That's it.

• No margins - We don't allow margins. Use padding and gap instead.
• No custom CSS - All styling is done via properties. No classes, no inline styles.
• Responsive by default - Every property has breakpoint variants (sm, md, lg, xl, 2xl)
• Flexbox-based - Flexbox is the building block. Layer these containers to create any layout.
• No Box-in-Box - A Box should never be a direct child of another Box. Flex must live between them to control spacing with gap.

The Golden Rule

Box padding is for internal spacing. Flex gap is for layout spacing.

If you find yourself using padding properties (p, pt, pb, etc.) to create space between elements, you're doing it wrong. That spacing should be controlled by a parent Flex container using the gap property.

On that note make sure you normalize and remove any default margins/padding from your styles. This is for the best.

Correct Pattern

<container-flex gap="2">
  <container-box p="2" bg="blue">Item 1</container-box>
  <container-box p="2" bg="red">Item 2</container-box>
</container-flex>

Incorrect Pattern

<!-- WRONG: Using padding for spacing between elements -->
<container-box pb="2" bg="blue">Item 1</container-box>
<container-box pt="2" bg="red">Item 2</container-box>

<!-- WRONG: Box as direct child of Box -->
<container-box p="2">
  <container-box p="2">Content</container-box>
</container-box>

Companion Library

This library has an accompanying ContentCSS library that handles internal styling of actual content (like <p>, <img>, and other content items). These libraries can be used separately if you wish.

Available Components

Layout Components

• <container-flex> - Flexible layout container with dynamic direction
• <container-flexrow> - Opinionated horizontal flex container
• <container-flexcol> - Opinionated vertical flex container

Styling Components

• <container-box> - Styled container with padding, borders, and backgrounds

Quick Example

<container-flexcol gap="2">
  <container-box p="2" bg="lightgray">Header</container-box>
  
  <container-flexrow gap="2">
    <container-box p="2" bg="lightblue" flex="1">Sidebar</container-box>
    <container-box p="3" bg="white" flex="3">Main Content</container-box>
  </container-flexrow>
  
  <container-box p="2" bg="lightgray">Footer</container-box>
</container-flexcol>

That's a complete layout. No CSS files. No class names. Just properties.

Responsive Design

Every property supports breakpoint variants:

<container-box 
  p="2" 
  bg="orange"
  md-p="4" 
  md-bg="blue"
  lg-p="6"
  lg-bg="purple">
  Mobile: 2rem padding, orange
  MD: 4rem padding, blue
  LG: 6rem padding, purple
</container-box>

Breakpoints:

• sm - 30rem (~480px)
• md - 48rem (~768px)
• lg - 62rem (~992px)
• xl - 80rem (~1280px)
• 2xl - 96rem (~1536px)

Why Web Components?

Web Components work everywhere. Use them in React, Vue, Angular, Svelte, or vanilla HTML. They don't care about your framework wars.