# Box


## Examples

### Default

```html
<m-box
      border=${args.border}
      ?shadow=${args.shadow}
      spacing=${args.spacing}
      ?borderRadius=${args.borderRadius}
      width=${args.width}
      background=${args.background}
    >
      <div>Slot</div>
    </m-box>
```

### PaddingVariants

```html
<div style="display: grid; gap: 10px;">
      ${["none", "xxs", "xs", "s", "m", "l", "xl", "xxl"].map(
        (spacing) => html`
          <m-box spacing=${spacing} border>
            <div>Spacing: ${spacing}</div>
          </m-box>
        `
      )}
    </div>
```

### WidthVariants

```html
<div style="display: grid; gap: 10px;">
      ${["default", "narrow", "medium", "wide"].map(
        (width) => html`
          <m-box width=${width} border>
            <div>Width: ${width}</div>
          </m-box>
        `
      )}
    </div>
```

### BackgroundVariants

```html
<div style="display: grid; gap: 10px;">
      ${["default", "raised", "transparent"].map(
        (background) => html`
          <m-box background=${background} border>
            <div>Background: ${background}</div>
          </m-box>
        `
      )}
    </div>
```

## Usage

**Use Box to:**

- Encapsulate content to provide a structured and consistent layout.
- Ensure padding around enclosed content.
- Create reusable layout components, such as cards, containers, and wrappers.
- Enhance visual clarity by applying background colors, borders, or padding.
- Maintain consistent responsiveness by adapting to its content or parent layout constraints.

**Do not use Box to:**

- Apply arbitrary styling that should be handled by higher-level layout components.
- Replace more semantic HTML elements like `<section>`, `<article>`, or `<aside>`, unless necessary for styling consistency.
- Define specific spacing between elements (use component like Stack instead).
- Apply inconsistent padding or margin logic that deviates from the design system’s layout structure.

## Other Considerations

- Padding is introspective and should be used to create space inside the Box around its content.
- Margin should be used for spacing between Boxes or other elements.
- Borders should be applied symmetrically (on all sides) or not at all. If an element needs a contextual border (e.g., separating items in a list), it should be handled by the parent component.
- Background colors should be applied to visually distinguish a Box, but should also ensure sufficient contrast for accessibility.
- Ensure sufficient contrast between background and text to meet WCAG compliance.
- The Box should adapt its width and height dynamically, either:
    - Intrinsic to its content (e.g., expanding based on text).
    - Defined by a parent layout system (e.g., flexbox, grid, or fixed dimensions).
    - Avoid explicitly setting widths and heights unless absolutely necessary.

## Design Rationale

- **Separation of Concerns:** The Box should only handle styling intrinsic to itself. Any layout-based spacing (margins) should be managed by parent components like Stack. This ensures predictable behavior when composing layouts.
- **Padding as a Controlled Property:** Allowing padding inside the Box makes sense since it affects the enclosed content, unlike margin which affects external spacing.
- **Consistent Aesthetic without Overstepping:** The Box should only provide a structural and layout function, leaving branding-related styles (such as typography and color) to higher-level stylesheets or components.
- **Scalability & Reusability:** The Box should serve as a foundation for more complex layout components like Cards, Modals, and Panels, promoting modular design.